Package com.snowflake.ingest.streaming

Interface SuccessDetail

public interface SuccessDetail
The payload handed to an elastic-channel success handler (registered via SnowflakeStreamingIngestElasticChannel.setSuccessHandler(java.util.function.Consumer<com.snowflake.ingest.streaming.SuccessDetail>)) when appends are acknowledged by Snowflake.

Delivered once per successful acknowledgement batch and carries the caller-supplied append tokens of every append acknowledged together — a whole server-ack success batch. A success carries no error, only the tokens and the requestId that acknowledged them.

Implemented by the SDK, never by callers: handlers only read this type, so new accessors can be added over time without breaking them.

  • Method Summary

    Modifier and Type
    Method
    Description
    Iterable<Object>
    getAppendTokens()
    The opaque, caller-supplied append tokens of the appends that were acknowledged.
    String
    getRequestId()
    The Snowflake requestId of the acknowledged request.
    int
    getRetryCount()
    How many retries the acknowledged request took: 0 when the first attempt was acknowledged, N when the SDK retried N times before Snowflake accepted it.

  • Method Details

    • getAppendTokens

      Iterable<Object> getAppendTokens()
      The opaque, caller-supplied append tokens of the appends that were acknowledged. Never empty; a token reused across appends appears once per acknowledged append (not deduplicated). Read-only — the returned iterable must not be modified.
      Returns:
      the acknowledged append tokens

    • getRequestId

      String getRequestId()
      The Snowflake requestId of the acknowledged request. Useful for correlating an acknowledgement with Snowflake-side telemetry.

      A support-escalation aid — do not key application logic off it.

      Returns:
      the requestId, never null

    • getRetryCount

      int getRetryCount()
      How many retries the acknowledged request took: 0 when the first attempt was acknowledged, N when the SDK retried N times before Snowflake accepted it.

      Use this to decide whether these rows may be duplicated in the table. A retry re-sends the same rowset, and the SDK retries whenever it cannot tell that the previous attempt failed -- a timeout or a 5xx may mean the rows were never processed, or that they were processed and only the response was lost. So:

      • 0 -- the SDK sent this rowset once and Snowflake acknowledged that one send. It did not introduce a duplicate.
      • > 0 -- the SDK sent it more than once before getting this acknowledgement, and an earlier attempt may also have been applied. These rows may appear in the table more than once. Reconcile or de-duplicate downstream if you need exactly-once.

      The signal is deliberately conservative: it counts every re-send, 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 for this.

      Read this only when getRequestId() is non-null. An acknowledgement that no single request produced reports 0, which is indistinguishable from a first attempt that succeeded; the requestId is the one signal for "this came from a request at all".

      A steadily non-zero count also means the SDK is absorbing retries on your behalf; it is worth reporting alongside the requestId when escalating throughput concerns to Snowflake support.

      Returns:
      the number of retries, 0 when there was no retry or no originating request