openapi: 3.0.0
info:
version: 0.0.1
title: Snowflake account statements API
description: The Snowflake Account API is a REST API that you can use to access, update, and perform certain actions on Account resource in Snowflake.
contact:
name: Snowflake, Inc.
url: https://snowflake.com
email: support@snowflake.com
servers:
- description: Snowflake Account API
url: https://org-account.snowflakecomputing.com
security:
- KeyPair: []
- ExternalOAuth: []
- SnowflakeOAuth: []
tags:
- name: statements
paths:
/api/v2/statements:
parameters:
- $ref: '#/components/parameters/requestId'
- $ref: '#/components/parameters/async'
- $ref: '#/components/parameters/nullable'
- $ref: '#/components/parameters/accept'
- $ref: '#/components/parameters/userAgent'
- $ref: '#/components/parameters/snowflakeAuthorizationTokenType'
post:
operationId: submitStatement
summary: Submit a Sql Statement for Execution.
description: 'Submits one or more SQL statements for execution. You can specify that the statement should be executed asynchronously. The following statement types are not supported: PUT, GET, USE, ALTER SESSION, BEGIN, COMMIT, ROLLBACK, statements that set session variables, and statements that create temporary tables and stages.'
tags:
- statements
security:
- keyPair: []
- externalOAuth: []
- snowflakeOAuth: []
requestBody:
required: true
description: Specifies the SQL statement to execute and the statement context.
content:
application/json:
schema:
$ref: '#/components/schemas/StatementRequest'
example:
statement: select * from T where c1=?
timeout: 10
database: TESTDB
schema: TESTSCHEMA
warehouse: TESTWH
role: TESTROLE
bindings:
'1':
type: FIXED
value: '123'
responses:
'200':
description: The statement was executed successfully, and the response includes any data requested.
content:
application/json:
schema:
$ref: '#/components/schemas/ResultSet'
examples:
Submitstatement200Example:
summary: Default submitStatement 200 response
x-microcks-default: true
value:
code: example_value
sqlState: example_value
message: example_value
statementHandle: example_value
createdOn: 10
statementStatusUrl: https://www.example.com
resultSetMetaData:
format: jsonv2
numRows: 10
rowType:
- {}
partitionInfo:
- {}
nullable: true
data:
- - example_value
stats:
numRowsInserted: 10
numRowsUpdated: 10
numRowsDeleted: 10
numDuplicateRowsUpdated: 10
headers:
Link:
$ref: '#/components/headers/Link'
links:
GetStatementStatus:
operationId: getStatementStatus
parameters:
statementHandle: $response.body#/statementHandle
CancelStatement:
operationId: cancelStatement
parameters:
statementHandle: $response.body#/statementHandle
'202':
description: The execution of the statement is still in progress. Use GET /api/v2/statements/{statementHandle} to check the status of the statement execution.
content:
application/json:
schema:
$ref: '#/components/schemas/QueryStatus'
examples:
Submitstatement202Example:
summary: Default submitStatement 202 response
x-microcks-default: true
value:
code: example_value
sqlState: example_value
message: example_value
statementHandle: example_value
createdOn: 10
statementStatusUrl: https://www.example.com
'400':
$ref: '#/components/responses/400BadRequest'
'401':
$ref: '#/components/responses/401Unauthorized'
'403':
$ref: '#/components/responses/403Forbidden'
'404':
$ref: '#/components/responses/404NotFound'
'405':
$ref: '#/components/responses/405MethodNotAllowed'
'408':
description: The execution of the statement exceeded the timeout period. The execution of the statement was cancelled.
content:
application/json:
schema:
$ref: '#/components/schemas/QueryStatus'
examples:
Submitstatement408Example:
summary: Default submitStatement 408 response
x-microcks-default: true
value:
code: example_value
sqlState: example_value
message: example_value
statementHandle: example_value
createdOn: 10
statementStatusUrl: https://www.example.com
'415':
$ref: '#/components/responses/415UnsupportedMediaType'
'422':
description: An error occurred when executing the statement. Check the error code and error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/QueryFailureStatus'
examples:
Submitstatement422Example:
summary: Default submitStatement 422 response
x-microcks-default: true
value:
code: example_value
sqlState: example_value
message: example_value
statementHandle: example_value
createdOn: 10
statementStatusUrl: https://www.example.com
'429':
$ref: '#/components/responses/429LimitExceeded'
'500':
$ref: '#/components/responses/500InternalServerError'
'503':
$ref: '#/components/responses/503ServiceUnavailable'
'504':
$ref: '#/components/responses/504GatewayTimeout'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/v2/statements/{statementHandle}:
parameters:
- $ref: '#/components/parameters/statementHandle'
- $ref: '#/components/parameters/requestId'
- $ref: '#/components/parameters/partition'
- $ref: '#/components/parameters/accept'
- $ref: '#/components/parameters/userAgent'
- $ref: '#/components/parameters/snowflakeAuthorizationTokenType'
get:
operationId: getStatementStatus
summary: Check the Status of the Execution of a Statement.
description: Checks the status of the execution of the statement with the specified statement handle. If the statement was executed successfully, the operation returns the requested partition of the result set.
tags:
- statements
security:
- keyPair: []
- externalOAuth: []
- snowflakeOAuth: []
responses:
'200':
description: The statement was executed successfully, and the response includes any data requested.
headers:
Link:
$ref: '#/components/headers/Link'
content:
application/json:
schema:
$ref: '#/components/schemas/ResultSet'
examples:
Getstatementstatus200Example:
summary: Default getStatementStatus 200 response
x-microcks-default: true
value:
code: example_value
sqlState: example_value
message: example_value
statementHandle: example_value
createdOn: 10
statementStatusUrl: https://www.example.com
resultSetMetaData:
format: jsonv2
numRows: 10
rowType:
- {}
partitionInfo:
- {}
nullable: true
data:
- - example_value
stats:
numRowsInserted: 10
numRowsUpdated: 10
numRowsDeleted: 10
numDuplicateRowsUpdated: 10
'202':
description: The execution of the statement is still in progress. Use this method again to check the status of the statement execution.
content:
application/json:
schema:
$ref: '#/components/schemas/QueryStatus'
examples:
Getstatementstatus202Example:
summary: Default getStatementStatus 202 response
x-microcks-default: true
value:
code: example_value
sqlState: example_value
message: example_value
statementHandle: example_value
createdOn: 10
statementStatusUrl: https://www.example.com
'400':
$ref: '#/components/responses/400BadRequest'
'401':
$ref: '#/components/responses/401Unauthorized'
'403':
$ref: '#/components/responses/403Forbidden'
'404':
$ref: '#/components/responses/404NotFound'
'405':
$ref: '#/components/responses/405MethodNotAllowed'
'415':
$ref: '#/components/responses/415UnsupportedMediaType'
'422':
description: An error occurred when executing the statement. Check the error code and error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/QueryFailureStatus'
examples:
Getstatementstatus422Example:
summary: Default getStatementStatus 422 response
x-microcks-default: true
value:
code: example_value
sqlState: example_value
message: example_value
statementHandle: example_value
createdOn: 10
statementStatusUrl: https://www.example.com
'429':
$ref: '#/components/responses/429LimitExceeded'
'500':
$ref: '#/components/responses/500InternalServerError'
'503':
$ref: '#/components/responses/503ServiceUnavailable'
'504':
$ref: '#/components/responses/504GatewayTimeout'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/v2/statements/{statementHandle}/cancel:
parameters:
- $ref: '#/components/parameters/statementHandle'
- $ref: '#/components/parameters/requestId'
- $ref: '#/components/parameters/accept'
- $ref: '#/components/parameters/userAgent'
- $ref: '#/components/parameters/snowflakeAuthorizationTokenType'
post:
operationId: cancelStatement
summary: Cancel the Execution of a Statement.
description: Cancels the execution of the statement with the specified statement handle.
tags:
- statements
security:
- keyPair: []
- externalOAuth: []
- snowflakeOAuth: []
responses:
'200':
description: The execution of the statement was successfully canceled.
content:
application/json:
schema:
$ref: '#/components/schemas/CancelStatus'
examples:
Cancelstatement200Example:
summary: Default cancelStatement 200 response
x-microcks-default: true
value:
code: example_value
sqlState: example_value
message: example_value
statementHandle: example_value
statementStatusUrl: https://www.example.com
'400':
$ref: '#/components/responses/400BadRequest'
'401':
$ref: '#/components/responses/401Unauthorized'
'403':
$ref: '#/components/responses/403Forbidden'
'404':
$ref: '#/components/responses/404NotFound'
'405':
$ref: '#/components/responses/405MethodNotAllowed'
'422':
description: An error occurred when cancelling the execution of the statement. Check the error code and error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/CancelStatus'
examples:
Cancelstatement422Example:
summary: Default cancelStatement 422 response
x-microcks-default: true
value:
code: example_value
sqlState: example_value
message: example_value
statementHandle: example_value
statementStatusUrl: https://www.example.com
'500':
$ref: '#/components/responses/500InternalServerError'
'503':
$ref: '#/components/responses/503ServiceUnavailable'
'504':
$ref: '#/components/responses/504GatewayTimeout'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
schemas:
QueryFailureStatus:
type: object
description: Status returned when a query execution fails.
properties:
code:
type: string
description: Error code for the query failure.
examples:
- '000123'
sqlState:
type: string
description: SQL state code indicating the error category.
examples:
- '42601'
message:
type: string
description: Error message describing the failure.
examples:
- SQL compilation error
statementHandle:
type: string
format: uuid
description: Handle that uniquely identifies the failed statement.
examples:
- e4ce975e-f7ff-4b5e-b15e-bf25f59371ae
createdOn:
type: integer
format: int64
description: Timestamp that specifies when the statement execution started. The timestamp is expressed in milliseconds since the epoch.
examples:
- 1597090533987
statementStatusUrl:
type: string
format: uri
description: URL for checking the status of the failed statement.
example: https://www.example.com
required:
- message
- statementHandle
BindVariable:
type: object
description: A bind variable value with its Snowflake data type.
properties:
type:
type: string
description: The Snowflake data type of the bind variable (e.g. FIXED, TEXT, BOOLEAN, DATE, TIMESTAMP_LTZ, TIMESTAMP_NTZ, TIMESTAMP_TZ).
examples:
- FIXED
- TEXT
value:
type: string
description: The value of the bind variable as a string.
examples:
- '123'
- teststring
required:
- type
- value
ColumnDefinition:
type: object
description: Describes a column in the result set.
properties:
name:
type: string
description: Name of the column.
example: Example Title
type:
type: string
description: Snowflake data type of the column (e.g. FIXED, TEXT, BOOLEAN, DATE, TIMESTAMP_NTZ, VARIANT, ARRAY, OBJECT).
example: example_value
length:
type: integer
format: int64
minimum: 0
description: Maximum length of the column data.
example: 10
precision:
type: integer
format: int64
minimum: 0
description: Precision of numeric data.
example: 10
scale:
type: integer
format: int64
minimum: 0
description: Scale of numeric data.
example: 10
nullable:
type: boolean
description: Whether the column allows null values.
example: true
PartitionInfo:
type: object
description: Information about a partition of the result set.
properties:
rowCount:
type: integer
format: int64
minimum: 0
description: Number of rows in the partition.
examples:
- 1324
compressedSize:
type: integer
format: int64
minimum: 0
description: The partition size before decompression. This may not be present in every partition.
examples:
- 37436824
uncompressedSize:
type: integer
format: int64
minimum: 0
description: The partition size after decompression.
examples:
- 1343787384
ResultSetMetaData:
type: object
description: Metadata about the result set including column definitions.
properties:
format:
type: string
enum:
- jsonv2
description: For v2 endpoints the only possible value for this field is jsonv2.
example: jsonv2
numRows:
type: integer
format: int64
description: The total number of rows of results.
examples:
- 100
rowType:
type: array
description: Array of column descriptors for the result set.
minItems: 1
items:
$ref: '#/components/schemas/ColumnDefinition'
example: []
partitionInfo:
type: array
description: Information about result set partitions for large results.
items:
$ref: '#/components/schemas/PartitionInfo'
example: []
nullable:
type: boolean
description: If false, null values are replaced with the string 'null' in the result set.
example: true
parameters:
$ref: '#/components/schemas/SessionParameters'
CancelStatus:
type: object
description: Status returned when a statement cancellation is requested.
properties:
code:
type: string
description: Status code for the cancellation.
example: example_value
sqlState:
type: string
description: SQL state code.
example: example_value
message:
type: string
description: Message describing the cancellation status.
examples:
- successfully canceled
statementHandle:
type: string
format: uuid
description: Handle of the canceled statement.
examples:
- 536fad38-b564-4dc5-9892-a4543504df6c
statementStatusUrl:
type: string
format: uri
description: URL for checking the status of the canceled statement.
example: https://www.example.com
required:
- statementHandle
ResultSet:
type: object
description: The result set returned from a successfully executed SQL statement, including metadata, row data, and execution statistics.
properties:
code:
type: string
description: Status code for the query.
examples:
- 090001
sqlState:
type: string
description: SQL state code.
examples:
- '00000'
message:
type: string
description: Message describing the execution status.
examples:
- successfully executed
statementHandle:
type: string
format: uuid
description: Handle that uniquely identifies the executed statement.
examples:
- 536fad38-b564-4dc5-9892-a4543504df6c
createdOn:
type: integer
format: int64
description: Timestamp that specifies when the statement execution started. The timestamp is expressed in milliseconds since the epoch.
examples:
- 1597090533987
statementStatusUrl:
type: string
format: uri
description: URL for checking the status of the statement.
example: https://www.example.com
resultSetMetaData:
$ref: '#/components/schemas/ResultSetMetaData'
data:
type: array
description: Result set data. Each element in the outer array represents a row. Each element in the inner array represents a column value as a string.
items:
type: array
items:
type:
- string
- 'null'
example: []
stats:
$ref: '#/components/schemas/ExecutionStats'
SessionParameters:
type: object
description: Session parameters that should be set before executing the statement.
properties:
timezone:
type: string
description: Time zone to use when executing the statement.
examples:
- america/los_angeles
query_tag:
type: string
description: Query tag that you want to associate with the SQL statement.
examples:
- tag-1234
binary_output_format:
type: string
description: Output format for binary values.
examples:
- HEX
date_output_format:
type: string
description: Output format for DATE values.
examples:
- YYYY-MM-DD
time_output_format:
type: string
description: Output format for TIME values.
examples:
- HH24:MI:SS.FF6
timestamp_output_format:
type: string
description: Output format for TIMESTAMP values.
examples:
- YYYY-MM-DDTHH24:MI:SS.FF6
timestamp_ltz_output_format:
type: string
description: Output format for TIMESTAMP_LTZ values.
examples:
- YYYY-MM-DDTHH24:MI:SS.FF6
timestamp_ntz_output_format:
type: string
description: Output format for TIMESTAMP_NTZ values.
examples:
- YYYY-MM-DDTHH24:MI:SS.FF6
timestamp_tz_output_format:
type: string
description: Output format for TIMESTAMP_TZ values.
examples:
- YYYY-MM-DDTHH24:MI:SS.FF6 TZHTZM
multi_statement_count:
type: integer
description: Number of statements to execute when using multi-statement capability. 0 implies variable number of statements. Negative numbers are not allowed.
default: 1
examples:
- 4
client_result_chunk_size:
type: integer
description: Maximum size of each set (chunk) of query results to download.
examples:
- 160
rows_per_resultset:
type: integer
description: Maximum number of rows returned in a result set.
examples:
- 10000
use_cached_result:
type: boolean
description: Whether to use a previously-cached result set for a query whose result set is still in the cache.
examples:
- true
QueryStatus:
type: object
description: Status of a query that is in progress or has completed successfully.
properties:
code:
type: string
description: Status code for the query execution.
examples:
- 090001
sqlState:
type: string
description: SQL state code.
examples:
- '00000'
message:
type: string
description: Message describing the status of the query.
examples:
- successfully executed
statementHandle:
type: string
format: uuid
description: Handle that uniquely identifies the statement. You can use this handle to check the status of the statement and retrieve the result set.
examples:
- e4ce975e-f7ff-4b5e-b15e-bf25f59371ae
createdOn:
type: integer
format: int64
description: Timestamp that specifies when the statement execution started. The timestamp is expressed in milliseconds since the epoch.
examples:
- 1597090533987
statementStatusUrl:
type: string
format: uri
description: URL that you can use to check the status of the execution of the statement and retrieve the result set.
examples:
- /api/v2/statements/e4ce975e-f7ff-4b5e-b15e-bf25f59371ae
required:
- statementHandle
ExecutionStats:
type: object
description: Statistics about the execution of the statement. These stats might not be available for each request.
properties:
numRowsInserted:
type: integer
format: int64
minimum: 0
description: Number of rows that were inserted.
examples:
- 12
numRowsUpdated:
type: integer
format: int64
minimum: 0
description: Number of rows that were updated.
examples:
- 9
numRowsDeleted:
type: integer
format: int64
minimum: 0
description: Number of rows that were deleted.
examples:
- 8
numDuplicateRowsUpdated:
type: integer
format: int64
minimum: 0
description: Number of duplicate rows that were updated.
examples:
- 20
StatementRequest:
type: object
description: Request body for submitting a SQL statement for execution.
properties:
statement:
type: string
description: 'SQL statement or batch of SQL statements to execute. You can specify query, DML and DDL statements. The following statements are not supported: PUT, GET, USE, ALTER SESSION, BEGIN, COMMIT, ROLLBACK, statements that set session variables, and statements that create temporary tables and stages.'
examples:
- select * from T where c1=?
- CREATE TABLE test_table (id INTEGER, name VARCHAR)
timeout:
type: integer
format: int64
minimum: 0
description: Timeout in seconds for statement execution. If the execution of a statement takes longer than the specified timeout, the execution is automatically canceled. To set the timeout to the maximum value (604800 seconds), set timeout to 0.
examples:
- 10
- 60
database:
type: string
description: Database in which the statement should be executed. The value in this field is case-sensitive.
examples:
- TESTDB
schema:
type: string
description: Schema in which the statement should be executed. The value in this field is case-sensitive.
examples:
- TESTSCHEMA
warehouse:
type: string
description: Warehouse to use when executing the statement. The value in this field is case-sensitive.
examples:
- TESTWH
role:
type: string
description: Role to use when executing the statement. The value in this field is case-sensitive.
examples:
- TESTROLE
bindings:
type: object
description: Values of bind variables in the SQL statement. When executing the statement, Snowflake replaces placeholders (? and :name) in the statement with these specified values.
additionalProperties:
$ref: '#/components/schemas/BindVariable'
example: example_value
parameters:
$ref: '#/components/schemas/SessionParameters'
headers:
Link:
schema:
type: string
description: Links to the partition of results (e.g. the first partition, the last partition, etc.). The header can include multiple URL entries with different rel attribute values that specify the partition to return (first, next, prev, and last).
responses:
403Forbidden:
description: Forbidden. The request is forbidden. This can happen if the request is made even though the API is not enabled.
500InternalServerError:
description: Internal Server Error. The server hit an unrecoverable system error. The response body may include the error code and message for further guidance. The application owner may need to reach out to customer support.
401Unauthorized:
description: Unauthorized. The request is not authorized. This happens if the attached access token is invalid or missing. The response body may include the error code and message indicating the actual cause, e.g., expired, invalid token. The application must obtain a new access token for retry.
405MethodNotAllowed:
description: Method Not Allowed. The request method does not match the supported API. This happens, for example, if the application calls the API with GET method but the endpoint accepts only POST.
429LimitExceeded:
description: Limit Exceeded. The number of requests hit the rate limit. The application must slow down the frequency of hitting the API endpoints.
400BadRequest:
description: Bad Request. The request payload is invalid or malformed. This happens if the application did not send the correct request payload. The response body may include the error code and message indicating the actual cause. The application must reconstruct the request body for retry.
415UnsupportedMediaType:
description: The request header Content-Type includes an unsupported media type. The API supports application/json only. If none is specified, the request payload is taken as JSON, but if any other media type is specified, this error is returned.
503ServiceUnavailable:
description: Service Unavailable. The request was not processed due to server side timeouts. The application may retry with backoff. Jittered backoff is recommended.
404NotFound:
description: Not Found. The request endpoint is not valid. This happens if the API endpoint is wrong.
504GatewayTimeout:
description: Gateway Timeout. The request was not processed due to server side timeouts. The application may retry with backoff. Jittered backoff is recommended.
parameters:
async:
name: async
in: query
schema:
type: boolean
required: false
description: Set to true to execute the statement asynchronously and return the statement handle. If the parameter is not specified or is set to false, a statement is executed and the first result is returned if the execution is completed in 45 seconds. If the statement execution takes longer to complete, the statement handle is returned.
requestId:
name: requestId
in: query
schema:
type: string
format: uuid
required: false
description: Unique ID of the API request. This ensures that the execution is idempotent. If not specified, a new UUID is generated and assigned.
userAgent:
name: User-Agent
in: header
schema:
type: string
required: true
description: Set this to the name and version of your application (e.g. applicationName/applicationVersion). You must use a value that complies with RFC 7231.
partition:
name: partition
in: query
schema:
type: integer
format: int64
minimum: 0
required: false
description: Number of the partition of results to return. The number can range from 0 to the total number of partitions minus 1.
nullable:
name: nullable
in: query
schema:
type: boolean
required: false
description: Set to true to execute the statement to generate the
# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/snowflake/refs/heads/main/openapi/snowflake-statements-api-openapi.yml