Package com.snowflake.ingest.streaming

Interface SnowflakeStreamingIngestElasticChannel

public interface SnowflakeStreamingIngestElasticChannel
Elastic channel for Snowflake Streaming Ingest. Unlike regular channels, elastic channels have no offset token concepts and their lifecycle is tied to the client (no close method). The same instance is returned on repeated calls to SnowflakeStreamingIngestClient.getElasticChannel().

  • Method Details

    • appendRow

      void appendRow(@Nonnull Map<String,Object> row, Object appendToken)
      Insert one row into the elastic channel without waiting for acknowledgement (fire-and-forget): returns as soon as the row is buffered. The append is still tracked for the error handler and the success handler — the outcome is surfaced through whichever is registered, keyed by appendToken, just not through a future. Use appendRowWithWait(java.util.Map<java.lang.String, java.lang.Object>, java.lang.Object) when you need a future to await.
      Parameters:
      row - the row data to insert
      appendToken - caller-supplied opaque append token, delivered in the ErrorDetail to a registered error handler if this append fails asynchronously, or in the SuccessDetail to a registered success handler once it is acknowledged. If appendToken is null, neither handler is invoked — and, with no future either (fire-and-forget), the outcome is not reported at all. The token is retained in memory until the append is acknowledged by the service, so attaching a large object raises the client's memory footprint — prefer a small id.

    • appendRows

      void appendRows(@Nonnull Iterable<Map<String,Object>> rows, Object appendToken)
      Insert a batch of rows into the elastic channel without waiting for acknowledgement (fire-and-forget): returns as soon as the rows are buffered. The append is still tracked for the error handler and the success handler — the outcome is surfaced through whichever is registered, keyed by appendToken, just not through a future. Use appendRowsWithWait(java.lang.Iterable<java.util.Map<java.lang.String, java.lang.Object>>, java.lang.Object) when you need a future to await.
      Parameters:
      rows - the rows to insert
      appendToken - caller-supplied opaque append token, delivered in the ErrorDetail to a registered error handler if this append fails asynchronously, or in the SuccessDetail to a registered success handler once it is acknowledged. If appendToken is null, neither handler is invoked — and, with no future either (fire-and-forget), the outcome is not reported at all. The token is retained in memory until the append is acknowledged by the service, so attaching a large object raises the client's memory footprint — prefer a small id.

    • appendRowWithWait

      CompletableFuture<Void> appendRowWithWait(@Nonnull Map<String,Object> row, Object appendToken)
      Insert one row into the elastic channel and return a future that completes when Snowflake acknowledges the row (or completes exceptionally if the append fails). A registered error handler also fires on failure, and a registered success handler on acknowledgement — dual delivery either way.
      Parameters:
      row - the row data to insert
      appendToken - caller-supplied opaque append token, delivered in the ErrorDetail to a registered error handler if this append fails asynchronously, or in the SuccessDetail to a registered success handler once it is acknowledged. If appendToken is null, neither handler is invoked; the returned future is then the only signal. The token is retained in memory until the append is acknowledged by the service, so attaching a large object raises the client's memory footprint — prefer a small id.
      Returns:
      a future that completes when the row is acknowledged by Snowflake

    • appendRowsWithWait

      CompletableFuture<Void> appendRowsWithWait(@Nonnull Iterable<Map<String,Object>> rows, Object appendToken)
      Insert a batch of rows into the elastic channel and return a future that completes when Snowflake acknowledges the batch (or completes exceptionally if the append fails). A registered error handler also fires on failure, and a registered success handler on acknowledgement — dual delivery either way.
      Parameters:
      rows - the rows to insert
      appendToken - caller-supplied opaque append token, delivered in the ErrorDetail to a registered error handler if this append fails asynchronously, or in the SuccessDetail to a registered success handler once it is acknowledged. If appendToken is null, neither handler is invoked; the returned future is then the only signal. The token is retained in memory until the append is acknowledged by the service, so attaching a large object raises the client's memory footprint — prefer a small id.
      Returns:
      a future that completes when the rows are acknowledged by Snowflake

    • setErrorHandler

      void setErrorHandler(@Nonnull Consumer<ErrorDetail> handler)
      Register a handler for appends that fail asynchronously, after appendRow/ appendRows has returned. The handler is invoked once per failure event with an ErrorDetail carrying the append tokens that failed together under a common error. Optional, and replaceable (last one set wins) — set it before appending for full coverage. Failed futures still complete exceptionally either way.

      The handler is only invoked for appends made with a non-null appendToken; an append given a null token still fails its future but is never reported to the handler.

      The handler runs inline on this channel's internal acknowledgement task. It must therefore return quickly and do no heavy or thread-blocking work: no blocking I/O, no network or disk calls, no waiting on locks or futures, and no synchronous re-entry into the SDK. Do only cheap bookkeeping inline (for example, record the failed tokens) and hand any real work to your own executor or queue. Blocking delays this channel's own acknowledgements — and therefore its append and flush completion — and, because every channel's acknowledgement task shares one process-wide worker pool, enough blocked handlers can starve acknowledgements elsewhere too. The SDK logs a warning when a handler runs slowly. A thrown exception is caught and logged so one bad handler cannot poison the acknowledgement path.

      Parameters:
      handler - the error handler to register. Must not be null.

    • setSuccessHandler

      void setSuccessHandler(@Nonnull Consumer<SuccessDetail> handler)
      Register a handler for appends that are acknowledged by Snowflake, after appendRow/appendRows has returned. The handler is invoked once per successful acknowledgement batch with a SuccessDetail carrying the append tokens that were acknowledged together. Optional, and replaceable (last one set wins) — set it before appending for full coverage. Independent of the error handler: either can be registered without the other, and a given append is reported to exactly one of them. Successful futures still complete either way.

      The handler runs inline on this channel's internal acknowledgement task. It must therefore return quickly and do no heavy or thread-blocking work: no blocking I/O, no network or disk calls, no waiting on locks or futures, and no synchronous re-entry into the SDK. Do only cheap bookkeeping inline (for example, record the tokens) and hand any real work to your own executor or queue. Blocking delays this channel's own acknowledgements — and therefore its append and flush completion — and, because every channel's acknowledgement task shares one process-wide worker pool, enough blocked handlers can starve acknowledgements elsewhere too. The SDK logs a warning when a handler runs slowly. A thrown exception is caught and logged so one bad handler cannot poison the acknowledgement path.

      Parameters:
      handler - the success handler to register. Must not be null.

    • initiateFlush

      void initiateFlush()
      Initiates a flush of all buffered data in this channel without waiting for completion.

    • waitForFlush

      CompletableFuture<Void> waitForFlush(@Nullable Duration timeoutDuration)
      Asynchronously waits for all buffered data in this channel to be flushed to the Snowflake server side. This triggers a flush of all pending data and completes when the flush operation finishes.
      Parameters:
      timeoutDuration - The maximum time to wait for the flush to complete. If null, the operation waits indefinitely.
      Returns:
      A CompletableFuture<Void> that completes successfully when the flush completes within the timeout. It completes exceptionally with a TimeoutException if the timeout is reached, or an SFException if the channel is closed or the flush fails.
      Throws:
      IllegalArgumentException - if timeoutDuration is negative

    • getChannelStatus

      ChannelStatus getChannelStatus()
      Get the channel status from Snowflake.
      Returns:
      the channel status

    • isClosed

      boolean isClosed()
      Check if the elastic channel is closed (because the client was closed).
      Returns:
      true if the channel is closed

    • getChannelName

      String getChannelName()
      Get the channel name (always "ELASTIC").
      Returns:
      the channel name

    • getDBName

      String getDBName()
      Get the database name.
      Returns:
      name of the database

    • getSchemaName

      String getSchemaName()
      Get the schema name.
      Returns:
      name of the schema

    • getPipeName

      String getPipeName()
      Get the pipe name.
      Returns:
      name of the pipe

    • getFullyQualifiedPipeName

      String getFullyQualifiedPipeName()
      Get the fully qualified pipe name.
      Returns:
      fully qualified pipe name

    • getFullyQualifiedChannelName

      String getFullyQualifiedChannelName()
      Get the fully qualified channel name.
      Returns:
      fully qualified channel name