Snowpipe Streaming API REST endpoints¶
The following request headers apply to all the endpoints for the Snowpipe Streaming REST API:
Header |
Description |
---|---|
|
auth token |
|
JWT/OAuth |
Get Hostname¶
The Get Hostname
returns the hostname used to interact with the Snowpipe Streaming REST API. Each account has a unique hostname.
GET /v2/streaming/hostname
Response:
Field |
Type |
Description |
---|---|---|
status_code |
int |
Status code that customers can use to map internal errors with public documentation. |
message |
string |
Descriptive error message that explains the error when the response code is not 200 (Success). Otherwise, it’s empty for response code 200. |
hostname |
string |
The rowset hostname of the account. |
Exchange Rowset Scoped Token¶
The Exchange Rowset Scoped Token
returns a security token that can be used to access only the Snowpipe Streaming API-related service. This provides security protection for the customer.
POST /oauth/token
Request:
Attribute |
Required |
Component |
Description |
---|---|---|---|
content_type |
Yes |
Header |
“application/x-www-form-urlencoded” |
grant_type |
Yes |
payload |
|
scope |
Yes |
payload |
The rowset hostname of the account |
Response:
Field |
Type |
Description |
---|---|---|
status_code |
int |
Status code that customers can use to map internal errors with public documentation. |
message |
string |
Descriptive error message that explains the error when the response code is not 200 (Success). Otherwise, it’s empty for response code 200. |
token |
string |
The rowset scoped token. |
Open Channel¶
The Open Channel
operation creates or opens a new channel against a pipe or table. If the channel already exists, Snowflake bumps the client sequencer of the channel and returns the last committed offset token.
PUT /v2/streaming/databases/{databaseName}/schemas/{schemaName}/pipes/{pipeName}/channels/{channelName}
Request:
Attribute |
Required |
Component |
Description |
---|---|---|---|
databaseName |
Yes |
URI |
Database name, case-insensitive |
schemaName |
Yes |
URI |
Schema name, case-insensitive |
pipeName |
Yes |
URI |
Pipe name, case-insensitive |
channelName |
Yes |
URI |
The name of the channel that you create or re-open, case-insensitive |
offset_token |
No |
payload |
String used to set an offset token when opening a channel. |
requestId |
No |
Query parameter |
UUID used to track requests through the system |
Response:
Field |
Type |
Description |
---|---|---|
channel_status_code |
String |
Indicating the status of the channel. |
last_committed_offset_token |
String |
Latest committed offset token |
database_name |
String |
The name of the database that the channel belongs to. |
schema_name |
String |
The name of the schema that the channel belongs to. |
pipe_name |
String |
The name of the pipe that the channel belongs to. |
channel_name |
String |
The name of the channel. |
rows_inserted |
int |
A count of all rows inserted into this channel. |
rows_parsed |
int |
A count of all rows parsed, but not necessarily inserted into this channel. |
rows_errors |
int |
A count of all rows that experienced errors when inserting into this channel and were therefore rejected. |
last_error_offset_upper_bound |
String |
Upper bound for the latest offset token of the inserted row set that has the last corresponding to an error. The real offset token of the row set with the last error is either this one or strictly before it in the channel ingestion order. |
last_error_message |
String |
A human readable message corresponding to the latest error code for that channel, with sensitive customer data redacted. |
last_error_timestamp |
timestamp_utc |
Timestamp at which the last error occured. |
snowflake_avg_processing_latency_ms |
int |
Average e2e processing time for this channel. |
Insert Row(s)¶
The Insert Rows
operation inserts a batch of rows to the given channel.
POST /v2/streaming/data/databases/{databaseName}/schemas/{schemaName}/pipes/{pipeName}/channels/{channelName}/rows
Request:
Attribute |
Required |
Component |
Description |
---|---|---|---|
databaseName |
Yes |
URI |
Database name, case-insensitive |
schemaName |
Yes |
URI |
Schema name, case-insensitive |
pipeName |
Yes |
URI |
Pipe, case-insensitive |
channelName |
Yes |
URI |
Channel name, case-insensitive |
continuationToken |
Yes for stateful clients, but not required for stateless clients |
Query parameter |
Continuation token from Snowflake, encapsulates both client and row sequencers |
offsetToken |
No |
Query parameter |
String used to set an offset token per batch. |
rows |
Yes |
payload |
Actual data payload that will be ingested in NDJSON format. |
requestId |
No |
Query parameter |
A UUID used to track requests through the system. |
Response:
Field |
Type |
Description |
---|---|---|
status_code |
int |
Status code that customers can use to map internal errors with public documentation |
next_continuation_token |
string |
The next continuation token from Snowflake, which encapsulates both client and row sequencers. It should be used for inserting the next batch. |
message |
string |
Descriptive error message that explains the error when the response code is not 200 (Success). Otherwise, it’s empty for response code 200. |
Drop Channel¶
The Drop Channel
operation drops a channel at server side along with its metadata.
DELETE /v2/streaming/databases/{databaseName}/schemas/{schemaName}/pipes/{pipeName}/channels/{channelName}
Request:
Attribute |
Required |
Component |
Description |
---|---|---|---|
databaseName |
Yes |
URI |
Database name, case-insensitive |
schemaName |
Yes |
URI |
Schema name, case-insensitive |
pipeOrTableName |
Yes |
URI |
Pipe or table name, case-insensitive |
channelName |
Yes |
URI |
Channel name, case-insensitive |
continuationToken |
No |
payload |
Continuation token from Snowflake, which encapsulates both client and row sequencers. If it’s not provided, then we will delete the channel with the latest client sequencer. |
requestId |
No |
Query parameter |
A UUID used to track requests through the system |
Response:
Field |
Type |
Description |
---|---|---|
status_code |
int |
Status code that customers can use to map internal errors with public documentation |
message |
string |
Descriptive error message that explains the error when the response code is not 200 (Success). Otherwise, it’s empty for response code 200. |
Bulk Get Channel Status¶
The Bulk Get Channel Status
operation returns the status of a channel for a specific client sequencer.
POST /v2/streaming/databases/{databaseName}/schemas/{schemaName}/pipes/{pipeName}:bulk-channel-status
Request:
Attribute |
Required |
Component |
Description |
---|---|---|---|
databaseName |
Yes |
URI |
Database name, case-insensitive |
schemaName |
Yes |
URI |
Schema name, case-insensitive |
pipeName |
Yes |
URI |
Pipe name, case-insensitive |
channelName |
Yes |
Payload |
An array of String channel names that the customer wants to get status for, case-sensitive. |
Response:
Field |
Type |
Description |
---|---|---|
channel_status_code |
String |
Indicating the status of the channel. |
last_committed_offset_token |
String |
Latest committed offset token |
database_name |
String |
The name of the database that the channel belongs to. |
schema_name |
String |
The name of the schema that the channel belongs to. |
pipe_name |
String |
The name of the pipe that the channel belongs to. |
channel_name |
String |
The name of the channel. |
rows_inserted |
int |
A count of all rows inserted into this channel. |
rows_parsed |
int |
A count of all rows parsed, but not necessarily inserted into this channel. |
rows_errors |
int |
A count of all rows that experienced errors when inserting into this channel and were therefore rejected. |
last_error_offset_upper_bound |
String |
Upper bound for the latest offset token of the inserted row set that has the last corresponding to an error. The real offset token of the row set with the last error is either this one or strictly before it in the channel ingestion order. |
last_error_message |
String |
A human readable message corresponding to the latest error code for that channel, with sensitive customer data redacted. |
last_error_timestamp |
timestamp_utc |
Timestamp at which the last error occured. |
snowflake_avg_processing_latency_ms |
int |
Average e2e processing time for this channel. |