snowflake::ingest::streaming::ErrorDetail Class Referencefinal
The payload handed to an elastic-channel error handler (registered via StreamingIngestElasticChannel::SetErrorHandler()) when appends fail asynchronously.
More...
#include <snowflake/ingest/streaming/elastic_channel.h>
Public Member Functions | |
| ErrorDetail (std::vector<AppendToken> append_tokens,StreamingIngestError error,std::optional<std::string> request_id,uint16_t retry_count) | |
| const std:: | append_tokens () const noexcept |
The opaque, caller-supplied append tokens of the appends that failed with error(). | |
| const StreamingIngestError & | error () const noexcept |
| The error that failed the appends. | |
| const std:: | request_id () const noexcept |
The Snowflake request ID of the request whose failure is being reported, or std::nullopt if this failure did not originate from a single identifiable request, e.g. channel invalidation or close. | |
| uint16_t | retry_count () const noexcept |
| How many retries the failing request had already made: 0 when the first attempt failed, N when the SDK retried N times before giving up. | |
Detailed Description
The payload handed to an elastic-channel error handler (registered via StreamingIngestElasticChannel::SetErrorHandler()) when appends fail asynchronously.
Delivered once per failure event and carries the caller-supplied append tokens of every append that failed together under a common error() — a whole server-ack error batch, or every tracked in-flight append on channel invalidation.
Member Function Documentation
append_tokens¶
|
const std::vector<AppendToken> & ErrorDetail::append_tokens() const
|
inlinenoexcept |
The opaque, caller-supplied append tokens of the appends that failed with error().
Never empty; a token reused across appends appears once per failed append (not deduplicated). Read-only — the returned vector must not be modified.
- Returns
- the failing append tokens
error¶
|
const StreamingIngestError & ErrorDetail::error() const
|
inlinenoexcept |
The error that failed the appends.
- Returns
- the error
request_id¶
|
const std::optional<std::string> & ErrorDetail::request_id() const
|
inlinenoexcept |
The Snowflake request ID of the request whose failure is being reported, or std::nullopt if this failure did not originate from a single identifiable request, e.g. channel invalidation or close.
Useful when escalating a failure to Snowflake support.
Treat std::nullopt as "not available" rather than as information: one request ID covers a logical request and every retry of it (attempts are told apart by a retry count the SDK sends), so do not key application logic off this value. It is a support-escalation aid only.
- Returns
- the request ID, or
std::nullopt
retry_count¶
|
uint16_t ErrorDetail::retry_count() const
|
inlinenoexcept |
How many retries the failing request had already made: 0 when the first attempt failed, N when the SDK retried N times before giving up.
This answers one question: could the SDK have applied this rowset more than once? It does not answer whether the rows reached the table at all. A retry re-sends the same rowset, and the SDK retries any failure it cannot prove the server rejected: a timeout, a transport error or a 5xx may mean the rows were never processed, or that they were processed and only the response was lost.
0: the SDK sent this rowset at most once, so it cannot have duplicated it.> 0: the SDK sent it more than once and an earlier attempt may already have been applied, so the rows may appear in the table more than once even though the append is being reported as failed. Reconcile or de-duplicate downstream if you need exactly-once.
Conservative by design: every re-send counts, including an authentication refresh, which is rejected before the rows are processed and so cannot have duplicated anything. A non-zero count therefore means "a duplicate is possible", not "a duplicate happened"; the SDK does not distinguish the two, and over-reporting is the safe direction here.
0 is not a statement that the rows are absent. Two ways a failed append can have landed anyway while reporting 0:
- The SDK sent it once and failed only on the response (a body it could not parse, say) after Snowflake had already accepted the rows.
- The failure did not come from a request at all. When
request_id()is absent the SDK failed the append itself: channel or client invalidation, a close, or an internal fault. Invalidation and close fail every append still in flight, including one whose request had already gone to Snowflake and may still be applied after this handler returns. Such a failure reports 0 because there was no attempt to count, not because anything was rejected.
The SDK cannot resolve either case for you: an append has to be failed when the channel goes away, and an in-flight request's outcome is not known at that point. Reconcile against the table if you need to know whether the rows landed.
Together with the request ID this identifies the exact attempt server-side: the SDK sends both as the requestId and retryCount query params on every request.
- Returns
- the number of retries, 0 when there was no retry or no originating request