snowflake.ingest.streaming.StreamingIngestClient

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)

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.

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.