snowflake.ingest.streaming¶

API Reference¶

class ChannelStatus(database_name: str, schema_name: str, pipe_name: str, channel_name: str, status_code: str, latest_committed_offset_token: str | None, created_on_ms: int, rows_inserted: int, rows_parsed: int, rows_error_count: int, last_error_offset_upper_bound: str | None, last_error_message: str | None, last_error_timestamp_ms: int | None, snowflake_avg_processing_latency_ms: int | None, last_refreshed_on_ms: int)¶

Channel status information returned to users.

Provides access to channel status information including the channel name, status code, and latest committed offset token from Snowflake server.

classmethod from_py_status(status: object) → ChannelStatus¶

Create a ChannelStatus from a PyO3 status object.

Parameters:

status – A PyO3 status object with matching attribute names.

Returns:

A new ChannelStatus instance.

property database_name: str¶

Get the database name.

property schema_name: str¶

Get the schema name.

property pipe_name: str¶

Get the pipe name.

property channel_name: str¶

Get the channel name.

Returns:

The name of the channel

Return type:

str

property status_code: str¶

Get the status code for the channel.

Returns:

The status code from Snowflake server

Return type:

str

property latest_committed_offset_token: str | None¶

Get the latest committed offset token for the channel.

Returns:

The latest committed offset token, or None if no commits yet

Return type:

Optional[str]

property latest_offset_token: str | None¶

Get the latest committed offset token for the channel.

Deprecated: Use latest_committed_offset_token instead.

Returns:

The latest committed offset token, or None if no commits yet

Return type:

Optional[str]

property created_on: datetime.datetime¶

Get the created on timestamp for the channel.

property rows_inserted_count: int¶

Get the rows inserted for the channel.

property rows_parsed_count: int¶

Get the rows parsed for the channel.

property rows_error_count: int¶

Get the rows error count for the channel.

property last_error_offset_token_upper_bound: str | None¶

Get the last error offset token upper bound for the channel.

property last_error_message: str | None¶

Get the last error message for the channel.

property last_error_timestamp: datetime.datetime | None¶

Get the last error timestamp for the channel.

property server_avg_processing_latency: datetime.timedelta | None¶

Get the snowflake avg processing latency for the channel.

property last_refreshed_on: datetime.datetime¶

Get the last refreshed on timestamp for the channel.

class ErrorDetail¶

The payload handed to an elastic-channel error handler when appends fail asynchronously.

Delivered once per failure event, carrying 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.

The SDK constructs this; handlers only read it.

append_tokens¶

The opaque, caller-supplied tokens of the appends that failed with error, as an immutable tuple. Never empty; a token reused across appends appears once per failed append (not deduplicated).

error¶

The error that completed those appends exceptionally.

request_id¶

The Snowflake requestId of the request that failed, for correlating this failure with server-side logs. None when the failure did not originate from a single request – channel invalidation or close, which fail every tracked in-flight append at once.

retry_count¶

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.

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. 0 means the SDK sent this rowset once and introduced no duplicate; > 0 means it sent it more than once and an earlier attempt may already have been applied, so the rows may appear more than once. Reconcile or de-duplicate downstream if you need exactly-once. The signal is conservative: it counts every re-send, including an authentication refresh, which is rejected before the rows are processed and so cannot have duplicated anything – > 0 means “a duplicate is possible”, not “a duplicate happened”. 0 means the SDK introduced no duplicate of its own, not that the rows are absent from the table.

Whenever ``request_id`` is None, neither field tells you whether the rows arrived. A None id means the SDK failed this append itself rather than relaying a server response – channel or client invalidation, a close or drop, or an internal fault – and all of those fail every append still in flight, locally and immediately. That includes appends whose request had already gone to Snowflake and may still be applied after this handler runs. The accompanying retry_count=0 says only that the SDK sent the rowset once; it is not a statement that Snowflake rejected it. The SDK cannot resolve this for you: the append has to be failed when the channel goes away, and the in-flight request’s outcome is not known at that point. Reconcile against the table if you need to know. Some None-id failures never reached the network at all – a payload the SDK could not serialize, for instance – so a None id spans both “definitely not applied” and “possibly applied”, which is why it cannot answer the question.

Read it only when request_id is not None: a failure with no originating request reports 0 as well. Together with request_id this names the exact attempt server-side – the SDK sends both as query params on every request.

append_tokens: tuple¶

error: StreamingIngestError¶

request_id: str | None¶

retry_count: int¶

class StreamingIngestChannel(channel: snowflake.ingest.streaming._python_ffi.PyChannel, callback: snowflake.ingest.streaming._mark_complete_callback.MarkCompleteCallback, *, binary_input_format: snowflake.ingest.streaming._python_ffi.PyBinaryInputFormat = PyBinaryInputFormat.BASE64, _internal: bool = False)¶

A channel for streaming data ingestion into Snowflake using the Snowflake Ingest SDK.

The channel is used to ingest data into Snowflake tables in a streaming fashion. Each channel is associated with a specific account/database/schema/pipe combination and is created by calling open_channel() and closed by calling close().

The channel provides methods for appending single rows or batches of rows into Snowflake, with support for offset tokens to track ingestion progress and enable replay capabilities in case of failures.

Note

This class should not be instantiated directly. Use open_channel() to create channel instances.

initiate_flush() → None¶

Initiate a flush of the channel.

Initiates a flush of all buffered data maintained for this Channel but does not wait for the flush to complete. Calls to append_rows are still allowed on the Channel after invoking this API.

This method triggers an immediate flush of all currently buffered data in this specific channel, similar to the client-level initiate_flush() but scoped to only this channel. The flush operation will occur asynchronously and this method returns immediately.

This method is useful when you want to force immediate transmission of buffered data without waiting for automatic flush triggers (time-based or size-based). It provides fine-grained control over when data gets sent to Snowflake on a per-channel basis. However, calling initiate_flush at a high rate will lead to a drop in overall throughput, potential increase in costs, and could lead to higher incidence of throttling by the Snowflake Service.

Raises:

StreamingIngestError – If initiating the flush fails

wait_for_flush(timeout_seconds: int | None = None) → None¶

Wait for the channel to flush all buffered data.

Waits for all buffered data in this channel to be flushed to the Snowflake server side. This method triggers a flush of all pending data and waits for the flush operation to complete. If the timeout is reached, a TimeoutError is raised.

Parameters:

timeout_seconds – Optional timeout in seconds for the flush operation. Defaults to None if no timeout is desired.

Raises:

• ValueError – If timeout_seconds is negative

• TimeoutError – If the timeout is reached

• StreamingIngestError – If waiting for the flush fails

wait_for_commit(token_checker: Callable[[str], bool], timeout_seconds: int | None = None) → None¶

Wait for the channel to commit all buffered data.

Waits for offset token to be committed in the snowflake sever side by checking whether the latest committed offset token meets the commit condition provided by the token_checker. Note that snowflake commits offset token in batch, so the token_checker should be able to handle the case where the latest committed offset token passed the expected ones. That said, the token_checker usually does a range check whether the provided token is greater or equal to the expected one, not a exact match.

Parameters:

• token_checker – A callable that tests whether the current committed offset token from the server meets the desired condition. The callable receives the latest committed offset token (which may be None) and should return True when the wait condition is satisfied.

• timeout_seconds – Optional timeout in seconds for the commit operation. Defaults to None if no timeout is desired.

Raises:

• ValueError – If token_checker is not callable or timeout_seconds is negative

• StreamingIngestError – If waiting for the commit fails

• TimeoutError – If the timeout is reached

append_row(row: Dict[str, Any], offset_token: str | None = None) → None¶

Append a single row into the channel.

Parameters:

• row –

  Dictionary representing the row data to append with keys as column names and values as column values. Values can be of the following types:

  • None: null values

  • bool: boolean values (True, False)

  • int: integer values

  • float: floating-point values

  • str: string values

  • bytes: byte strings

  • bytearray: mutable byte arrays

  • tuple: tuples of values

  • list: lists of values

  • dict: nested dictionaries

  • set: sets of values

  • frozenset: immutable sets of values

  • datetime.datetime: datetime objects

  • datetime.date: date objects

  • datetime.time: time objects

  • decimal.Decimal: decimal values for precise numeric operations

• offset_token – Optional offset token, used to track the ingestion progress and replay ingestion in case of failures. It could be null if user don’t plan on replaying or can’t replay.

Raises:

• ValueError, TypeError – If the row cannot be serialized to JSON

• StreamingIngestError – If the row appending fails

append_rows(rows: List[Dict[str, Any]], start_offset_token: str | None = None, end_offset_token: str | None = None) → None¶

Append multiple rows into the channel.

Parameters:

• rows –

  List of dictionaries representing the row data to append. Each dictionary’s values can be of the following types:

  • None: null values

  • bool: boolean values (True, False)

  • int: integer values

  • float: floating-point values

  • str: string values

  • bytes: byte strings

  • bytearray: mutable byte arrays

  • tuple: tuples of values

  • list: lists of values

  • dict: nested dictionaries

  • set: sets of values

  • frozenset: immutable sets of values

  • datetime.datetime: datetime objects

  • datetime.date: date objects

  • datetime.time: time objects

  • decimal.Decimal: decimal values for precise numeric operations

• start_offset_token – Optional start offset token of the batch/row-set.

• end_offset_token – Optional end offset token of the batch/row-set.

Raises:

• ValueError, TypeError – If the rows cannot be serialized to JSON

• StreamingIngestError – If the rows appending fails

get_latest_committed_offset_token() → str | None¶

Get the latest committed offset token for the channel.

Returns:

The latest committed offset token for the channel, or None if the channel is brand new.

Return type:

Optional[str]

Raises:

StreamingIngestError – If getting the latest committed offset token fails

get_channel_status() → ChannelStatus¶

Get the status of the channel.

Returns:

The status of the channel.

Return type:

ChannelStatus

Raises:

StreamingIngestError – If getting the channel status fails

close(drop: bool = False, wait_for_flush: bool = True, timeout_seconds: int | None = None) → None¶

Close the channel.

Parameters:

• drop – Whether to drop the channel, defaults to False

• wait_for_flush – Whether to wait for the flush to complete. Default is True.

• timeout_seconds – The timeout in seconds for the flush, None means no timeout. Default is None.

Raises:

• ValueError – If timeout_seconds is negative

• StreamingIngestError – If closing the channel fails

is_closed() → bool¶

Check if the channel is closed.

Returns:

True if the channel is closed, False otherwise

Return type:

bool

property db_name: str¶

Get the database name.

property channel_name: str¶

Get the channel name.

property schema_name: str¶

Get the schema name.

property pipe_name: str¶

Get the pipe name.

class StreamingIngestClient(client_name: str, db_name: str, schema_name: str, pipe_name: str, profile_json: str | None = None, properties: Dict[str, Any] | None = None, _is_table_mode: bool = False)¶

A client that is the starting point for using the Streaming Ingest client APIs.

A single client maps to exactly one account/database/schema/pipe in Snowflake; however, multiple clients can point to the same account/database/schema/pipe. Each client contains information for Snowflake authentication and authorization, and it is used to create one or more StreamingIngestChannel instances for data ingestion.

The client manages the lifecycle of streaming ingest channels and handles the underlying communication with Snowflake services for authentication, channel management, and data transmission.

classmethod from_table(client_name: str, db_name: str, schema_name: str, table_name: str, profile_json: str | None = None, properties: Dict[str, Any] | None = None) → StreamingIngestClient¶

Create a table-mode client. The pipe name is derived from table_name + “-STREAMING”.

Parameters:

• client_name – A unique name to identify this client instance.

• db_name – The name of the Snowflake database.

• schema_name – The name of the schema within the database.

• table_name – The table name (pipe name will be table_name + “-STREAMING”).

• profile_json – Optional path to a JSON profile file.

• properties – Optional dictionary of connection properties.

Returns:

A new StreamingIngestClient in table mode.

Raises:

StreamingIngestError – If client initialization fails.

get_elastic_channel() → StreamingIngestElasticChannel¶

Get the elastic channel for this client.

Returns the singleton elastic channel. On first call, opens the elastic channel. Subsequent calls return the cached instance.

Returns:

The elastic channel.

Return type:

StreamingIngestElasticChannel

Raises:

StreamingIngestError – If the client is closed or the channel cannot be opened.

open_channel(channel_name: str, offset_token: str | None = None) → Tuple[StreamingIngestChannel, ChannelStatus]¶

Open a channel with the given name.

Parameters:

• channel_name – Name of the channel to open

• offset_token – Optional offset token

Returns:

(StreamingIngestChannel, ChannelStatus)

Return type:

tuple

Raises:

StreamingIngestError – If opening the channel fails

close(wait_for_flush: bool = True, timeout_seconds: int | None = None) → None¶

Close the client.

Parameters:

• wait_for_flush – Whether to wait for the flush to complete, defaults to True

• timeout_seconds – Optional timeout in seconds for the flush operation, defaults to 60 seconds

Raises:

• ValueError – If timeout_seconds is negative

• TimeoutError – If the timeout is reached

• StreamingIngestError – If closing the client fails

is_closed() → bool¶

Check if the client is closed.

Raises:

StreamingIngestError – If checking the client status fails

get_latest_committed_offset_tokens(channel_names: List[str]) → Dict[str, str | None]¶

Get the latest committed offset tokens for a list of channels.

Parameters:

channel_names – List of channel names

Returns:

A dictionary mapping channel names to their latest committed offset tokens.

Value is None if the channel is brand new or does not exist.

Return type:

Dict[str, Optional[str]]

Raises:

StreamingIngestError – If getting the latest committed offset tokens fails

get_channel_statuses(channel_names: List[str]) → Dict[str, ChannelStatus]¶

Get the statuses of a list of channels.

Parameters:

channel_names – List of channel names

Returns:

A dictionary mapping channel names to their statuses.

Return type:

Dict[str, ChannelStatus]

Raises:

StreamingIngestError – If getting the channel statuses fails

drop_channel(channel_name: str) → None¶

Drop a channel.

Parameters:

channel_name – Name of the channel to drop

Raises:

StreamingIngestError – If dropping the channel fails

initiate_flush() → None¶

Initiate a flush of the client.

Initiates a flush by the Client which causes all outstanding buffered data to be flushed to Snowflake. Note that data can still be accepted by the Client - this is an asynchronous call and will return after flush is initiated for all Channels opened by this Client

Raises:

StreamingIngestError – If initiating the flush fails

wait_for_flush(timeout_seconds: int | None = None) → None¶

Wait for the client to flush all buffered data.

Waits for all buffered data in all channels managed by this client to be flushed to the Snowflake server side. This method triggers a flush of all pending data across all channels and waits for the flush operations to complete. If the timeout is reached, a StreamingIngestError is raised.

Parameters:

timeout_seconds – Optional timeout in seconds for the flush operation. Defaults to None if no timeout is desired.

Raises:

• ValueError – If timeout_seconds is negative

• TimeoutError – If the timeout is reached

• StreamingIngestError – If waiting for the flush fails

property client_name: str¶

Get the client name.

property db_name: str¶

Get the database name.

property schema_name: str¶

Get the schema name.

property pipe_name: str¶

Get the pipe name.

ChannelErrorHandler¶

ChannelSuccessHandler¶

class StreamingIngestElasticChannel(channel: snowflake.ingest.streaming._python_ffi.PyChannel, callback: snowflake.ingest.streaming._mark_complete_callback.MarkCompleteCallback, *, binary_input_format: snowflake.ingest.streaming._python_ffi.PyBinaryInputFormat, _internal: bool = False)¶

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 get_elastic_channel().

Note

This class should not be instantiated directly. Use get_elastic_channel() to obtain the elastic channel instance.

set_error_handler(handler: ChannelErrorHandler) → None¶

Register a handler invoked when appends fail asynchronously.

Optional and replaceable (last one set wins); set it before appending for full coverage. This is the only asynchronous-failure signal for the fire-and-forget append_row/ append_rows; the Futures returned by append_row_with_wait/append_rows_with_wait still complete exceptionally as well. See ChannelErrorHandler for the threading contract.

Parameters:

handler – Callable taking the ErrorDetail for the failure event, which bundles the failing append tokens with the StreamingIngestError.

Raises:

ValueError – If handler is None.

set_success_handler(handler: ChannelSuccessHandler) → None¶

Register a handler invoked when appends are acknowledged successfully.

Optional and replaceable (last one set wins); set it before appending for full coverage. This is the only success signal for the fire-and-forget append_row/append_rows; the Futures returned by append_row_with_wait/append_rows_with_wait still complete successfully as well. Independent of set_error_handler() – registering one does not require the other. See ChannelSuccessHandler for the threading contract.

Parameters:

handler – Callable taking the SuccessDetail for the acknowledgement batch, which carries the acknowledged append tokens.

Raises:

ValueError – If handler is None.

append_row(row: Dict[str, Any], append_token: object) → None¶

Append a single row into the elastic channel without waiting for acknowledgement.

Fire-and-forget: returns as soon as the row is handed to the SDK, with no Future to await. The append is still tracked for the handler registered via set_error_handler(), so an asynchronous failure is still reported there, keyed by append_token – that handler is the only way to learn about one. Use append_row_with_wait() when you need a Future.

Parameters:

• row – Dictionary representing the row data to append.

• append_token – Required caller-supplied opaque token (any object) echoed back in the ErrorDetail handed to the handler registered via set_error_handler() if the append fails asynchronously, or in the SuccessDetail handed to the handler registered via set_success_handler() once it is acknowledged. Required but nullable: pass None explicitly to opt out, which leaves this append untracked for either handler. The token is retained in memory until the append is acknowledged, so a large object raises the SDK’s memory footprint – prefer a small id.

Raises:

• ValueError, TypeError – If the row cannot be serialized to JSON.

• StreamingIngestError – If the row appending fails.

append_rows(rows: List[Dict[str, Any]], append_token: object) → None¶

Append multiple rows into the elastic channel without waiting for acknowledgement.

Fire-and-forget: returns as soon as the rows are handed to the SDK, with no Future to await. The append is still tracked for the handler registered via set_error_handler(), so an asynchronous failure is still reported there, keyed by append_token – that handler is the only way to learn about one. Use append_rows_with_wait() when you need a Future.

Parameters:

• rows – List of dictionaries representing the row data to append.

• append_token – Required caller-supplied opaque token (any object) echoed back in the ErrorDetail handed to the handler registered via set_error_handler() if the append fails asynchronously, or in the SuccessDetail handed to the handler registered via set_success_handler() once it is acknowledged. Required but nullable: pass None explicitly to opt out, which leaves this append untracked for either handler. The token is retained in memory until the append is acknowledged, so a large object raises the SDK’s memory footprint – prefer a small id.

Raises:

• ValueError, TypeError – If the rows cannot be serialized to JSON.

• StreamingIngestError – If the rows appending fails.

append_row_with_wait(row: Dict[str, Any], append_token: object) → concurrent.futures.Future¶

Append a single row into the elastic channel and return a Future to await.

Parameters:

• row – Dictionary representing the row data to append.

• append_token – Required caller-supplied opaque token (any object) echoed back in the ErrorDetail handed to the handler registered via set_error_handler() if the append fails asynchronously, or in the SuccessDetail handed to the handler registered via set_success_handler() once it is acknowledged. Required but nullable: pass None explicitly to opt out, which leaves this append untracked for either handler. The token is retained in memory until the append is acknowledged, so a large object raises the SDK’s memory footprint – prefer a small id.

Returns:

Completes when the row is acknowledged by Snowflake, or completes exceptionally if it fails. A registered error handler also fires on failure.

Return type:

Future

Raises:

• ValueError, TypeError – If the row cannot be serialized to JSON.

• StreamingIngestError – If the row appending fails.

append_rows_with_wait(rows: List[Dict[str, Any]], append_token: object) → concurrent.futures.Future¶

Append multiple rows into the elastic channel and return a Future to await.

Parameters:

• rows – List of dictionaries representing the row data to append.

• append_token – Required caller-supplied opaque token (any object) echoed back in the ErrorDetail handed to the handler registered via set_error_handler() if the append fails asynchronously, or in the SuccessDetail handed to the handler registered via set_success_handler() once it is acknowledged. Required but nullable: pass None explicitly to opt out, which leaves this append untracked for either handler. The token is retained in memory until the append is acknowledged, so a large object raises the SDK’s memory footprint – prefer a small id.

Returns:

Completes when the rows are acknowledged by Snowflake, or completes exceptionally if they fail. A registered error handler also fires on failure.

Return type:

Future

Raises:

• ValueError, TypeError – If the rows cannot be serialized to JSON.

• StreamingIngestError – If the rows appending fails.

initiate_flush() → None¶

Initiate a flush of all buffered data in this channel without waiting for completion.

Raises:

StreamingIngestError – If initiating the flush fails.

wait_for_flush(timeout_seconds: int | None = None) → None¶

Wait for the elastic channel to flush all buffered data.

Waits for all buffered data in this channel to be flushed to the Snowflake server side. This method triggers a flush of all pending data and waits for the flush operation to complete. If the timeout is reached, a TimeoutError is raised.

Parameters:

timeout_seconds – Optional timeout in seconds for the flush operation. Defaults to None if no timeout is desired.

Raises:

• ValueError – If timeout_seconds is negative

• TimeoutError – If the timeout is reached

• StreamingIngestError – If waiting for the flush fails

get_channel_status() → ChannelStatus¶

Get the status of the elastic channel.

Returns:

The status of the channel.

Return type:

ChannelStatus

Raises:

StreamingIngestError – If getting the channel status fails.

is_closed() → bool¶

Check if the elastic channel is closed (because the client was closed).

Returns:

True if the channel is closed, False otherwise.

Return type:

bool

property channel_name: str¶

Get the channel name (always “ELASTIC”).

property db_name: str¶

Get the database name.

property schema_name: str¶

Get the schema name.

property pipe_name: str¶

Get the pipe name.

exception StreamingIngestError(error_code: StreamingIngestErrorCode, message: str, http_status_code: int, http_status_name: str)¶

Bases: Exception

A class for all streaming ingest errors.

property error_code: StreamingIngestErrorCode¶

The error code of the error.

property message: str¶

The message of the error.

property http_status_code: int¶

The HTTP status code of the error.

property http_status_name: str¶

The HTTP status name of the error.

class StreamingIngestErrorCode(*args, **kwds)¶

Bases: enum.Enum

Enumeration of all possible streaming ingest error codes.

These error codes correspond to the IngestError variants in the Rust implementation and provide type-safe error handling.

CONFIG_ERROR = 'ConfigError'¶

INVALID_REQUEST = 'InvalidRequest'¶

INVALID_ARGUMENT = 'InvalidArgument'¶

SF_API_USER_ERROR = 'SfApiUserError'¶

NOT_IMPLEMENTED = 'NotImplemented'¶

HTTP_CLIENT_NON_RETRYABLE_ERROR = 'HttpClientNonRetryableError'¶

SF_API_PIPE_FAILED_OVER_ERROR = 'SfApiPipeFailedOverError'¶

CHANNEL_ALREADY_EXISTS = 'ChannelAlreadyExists'¶

ELASTIC_CHANNEL_RESERVED_NAME = 'ElasticChannelReservedName'¶

CANNOT_DROP_ELASTIC_CHANNEL = 'CannotDropElasticChannel'¶

AUTH_TOKEN_ERROR = 'AuthTokenError'¶

SF_API_AUTH_ERROR = 'SfApiAuthError'¶

CHANNEL_NOT_FOUND = 'ChannelNotFound'¶

CHANNEL_WAIT_FOR_FLUSH_TIMEOUT = 'ChannelWaitForFlushTimeout'¶

CLIENT_WAIT_FOR_FLUSH_TIMEOUT = 'ClientWaitForFlushTimeout'¶

CLOSED_CHANNEL_ERROR = 'ClosedChannelError'¶

CLOSED_ELASTIC_CHANNEL_ERROR = 'ClosedElasticChannelError'¶

CLOSED_CLIENT_ERROR = 'ClosedClientError'¶

CHANNEL_CLOSED_BY_USER = 'ChannelClosedByUser'¶

INVALID_CHANNEL_ERROR = 'InvalidChannelError'¶

INVALID_CLIENT_ERROR = 'InvalidClientError'¶

INPUT_CHANNEL_CLOSED = 'InputChannelClosed'¶

OUTPUT_CHANNEL_CLOSED = 'OutputChannelClosed'¶

RECEIVER_SATURATED = 'ReceiverSaturated'¶

MEMORY_THRESHOLD_EXCEEDED = 'MemoryThresholdExceeded'¶

MEMORY_THRESHOLD_EXCEEDED_IN_CONTAINER = 'MemoryThresholdExceededInContainer'¶

FATAL = 'Fatal'¶

NON_FATAL = 'NonFatal'¶

MUTEX_LOCK_FAILED = 'MutexLockFailed'¶

SF_API_UNEXPECTED_BEHAVIOR_ERROR = 'SfApiUnexpectedBehaviorError'¶

SF_API_INTERNAL_SERVER_ERROR = 'SfApiInternalServerError'¶

FILE_UPLOAD_ERROR = 'FileUploadError'¶

HTTP_RETRIES_EXHAUSTED_ERROR = 'HttpRetriesExhaustedError'¶

CLOSE_ALL_CHANNELS_FAILED_ERROR = 'CloseAllChannelsFailedError'¶

HTTP_RETRYABLE_CLIENT_ERROR = 'HttpRetryableClientError'¶

classmethod from_string(error_code_str: str) → StreamingIngestErrorCode | None¶

Convert a string error code to enum value if it exists.

Parameters:

error_code_str – The error code string to convert

Raises:

ValueError – If the error code string is invalid

Returns:

The matching StreamingIngestErrorCode enum value, or None if not found

class SuccessDetail¶

The payload handed to an elastic-channel success handler when appends are acknowledged.

Delivered once per successful acknowledgement batch, carrying the caller-supplied append tokens of every append the server acknowledged together. There is no error counterpart field: this payload only ever describes appends that succeeded.

The SDK constructs this; handlers only read it.

append_tokens¶

The opaque, caller-supplied tokens of the appends that were acknowledged successfully, as an immutable tuple. Never empty; a token reused across appends appears once per acknowledged append (not deduplicated).

request_id¶

The Snowflake requestId of the request that acknowledged these appends, for correlating them with server-side logs.

retry_count¶

How many retries that 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. 0 means the SDK sent this rowset once and introduced no duplicate; > 0 means it sent it more than once and an earlier attempt may already have been applied, so the rows may appear more than once. Reconcile or de-duplicate downstream if you need exactly-once. The signal is conservative: it counts every re-send, including an authentication refresh, which is rejected before the rows are processed and so cannot have duplicated anything – > 0 means “a duplicate is possible”, not “a duplicate happened”.

Read it only when request_id is not None: an acknowledgement with no originating request reports 0 as well. A steadily non-zero count also means the SDK is absorbing retries on your behalf.

append_tokens: tuple¶

request_id: str¶

retry_count: int¶