Snowflake SQL API
The Snowflake SQL API is a REST API that you can use to access and update data in a Snowflake database.
OpenAPI Specification
openapi: 3.0.0
servers:
- description: Snowflake SQL API V2
url: https://org-account.snowflakecomputing.com
info:
version: 2.0.0
title: Snowflake SQL API
description: 'The Snowflake SQL API is a REST API that you can use to access and update data in a Snowflake database. '
contact:
name: Snowflake, Inc.
url: https://snowflake.com
email: support@snowflake.com
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: Submits a Sql Statement for Execution.
description: Submits one or more statements for execution. You can specify that the statement should be executed asynchronously.
tags:
- statements
security:
- keyPair: []
- ExternalOAuth: []
- snowflakeOAuth: []
requestBody:
required: true
description: Specifies the SQL statement to execute and the statement context.
content:
application/json:
schema:
type: object
properties:
statement:
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.'
type: string
timeout:
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.
type: integer
format: int64
minimum: 0
example: 10
database:
description: Database in which the statement should be executed. The value in this field is case-sensitive.
type: string
example: TESTDB
schema:
description: Schema in which the statement should be executed. The value in this field is case-sensitive.
type: string
example: TESTSCHEMA
warehouse:
description: Warehouse to use when executing the statement. The value in this field is case-sensitive.
type: string
example: TESTWH
role:
description: Role to use when executing the statement. The value in this field is case-sensitive.
type: string
example: TESTROLE
bindings:
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.
type: object
properties: {}
example:
'1':
type: FIXED
value: '123'
'2':
type: TEXT
value: teststring
parameters:
description: Session parameters that should be set before executing the statement.
type: object
properties:
timezone:
description: Time zone to use when executing the statement.
type: string
example: america/los_angeles
query_tag:
description: Query tag that you want to associate with the SQL statement.
type: string
example: tag-1234
binary_output_format:
description: Output format for binary values.
type: string
example: HEX
date_output_format:
description: Output format for DATE values.
type: string
example: YYYY-MM-DD
time_output_format:
description: Output format for TIME values.
type: string
example: HH24:MI:SS.FF6
timestamp_output_format:
description: Output format for TIMESTAMP values.
type: string
example: YYYY-MM-DDTHH24:MI:SS.FF6
timestamp_ltz_output_format:
description: Output format for TIMESTAMP_LTZ values.
type: string
example: YYYY-MM-DDTHH24:MI:SS.FF6
timestamp_ntz_output_format:
description: Output format for TIMESTAMP_NTZ values.
type: string
example: YYYY-MM-DDTHH24:MI:SS.FF6
timestamp_tz_output_format:
description: Output format for TIMESTAMP_TZ values.
type: string
example: YYYY-MM-DDTHH24:MI:SS.FF6 TZHTZM
multi_statement_count:
description: Number of statements to execute when using multi-statement capability. 0 implies variable number of statements. Negative numbers are not allowed.
type: integer
example: 4
default: 1
example:
statement: select * from T where c1=?
timeout: 10
database: TESTDB
schema: TESTSCHEMA
warehouse: TESTWH
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:
- name: Example Title
type: example_value
length: 10
precision: 10
scale: 10
nullable: true
partitionInfo:
- rowCount: 10
compressedSize: 10
uncompressedSize: 10
nullable: true
parameters:
binary_output_format: example_value
date_output_format: example_value
time_output_format: example_value
timestamp_output_format: example_value
timestamp_ltz_output_format: example_value
timestamp_ntz_output_format: example_value
timestamp_tz_output_format: example_value
multi_statement_count: 10
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#/resultMetaData.statementHandle
CancelStatement:
operationId: CancelStatement
parameters:
statementHandle: $response.body#/resultMetaData.statementHandle
'202':
description: The execution of the statement is still in progress. Use GET /statements/ and specify the statement handle 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: Checks 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:
- name: Example Title
type: example_value
length: 10
precision: 10
scale: 10
nullable: true
partitionInfo:
- rowCount: 10
compressedSize: 10
uncompressedSize: 10
nullable: true
parameters:
binary_output_format: example_value
date_output_format: example_value
time_output_format: example_value
timestamp_output_format: example_value
timestamp_ltz_output_format: example_value
timestamp_ntz_output_format: example_value
timestamp_tz_output_format: example_value
multi_statement_count: 10
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: Cancels the Execution of a Statement.
security:
- keyPair: []
- ExternalOAuth: []
- snowflakeOAuth: []
description: Cancels the execution of the statement with the specified statement handle.
tags:
- statements
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:
QueryStatus:
type: object
properties:
code:
type: string
example: example_value
sqlState:
type: string
example: example_value
message:
type: string
example: example_value
statementHandle:
type: string
format: uuid
example: example_value
createdOn:
type: integer
format: int64
description: Timestamp that specifies when the statement execution started. The timestamp is expressed in milliseconds since the epoch.
example: 1597090533987
statementStatusUrl:
type: string
format: uri
description: URL that you can use to check the status of the execution of the statement and the result set.
example: https://www.example.com
required:
- statementHandle
example:
code: '000000'
sqlState: '00000'
message: successfully executed
statementHandle: e4ce975e-f7ff-4b5e-b15e-bf25f59371ae
createdOn: 1597090533987
QueryFailureStatus:
type: object
properties:
code:
type: string
example: example_value
sqlState:
type: string
example: example_value
message:
type: string
example: example_value
statementHandle:
type: string
format: uuid
example: example_value
createdOn:
type: integer
format: int64
description: "Timestamp that specifies when the statement execution started. The timestamp is expressed in milliseconds since the epoch."
example: 1597090533987
statementStatusUrl:
type: string
format: uri
example: https://www.example.com
required:
- message
- statementHandle
example:
code: '000123'
sqlState: '42601'
message: SQL compilation error
statementHandle: e4ce975e-f7ff-4b5e-b15e-bf25f59371ae
createdOn: 1597090533987
CancelStatus:
type: object
properties:
code:
type: string
example: example_value
sqlState:
type: string
example: example_value
message:
type: string
example: example_value
statementHandle:
type: string
format: uuid
example: example_value
statementStatusUrl:
type: string
format: uri
example: https://www.example.com
required:
- statementHandle
example:
message: successfully canceled
statementHandle: 536fad38-b564-4dc5-9892-a4543504df6c
ResultSet:
type: object
properties:
code:
type: string
example: '000123'
sqlState:
type: string
example: '42601'
message:
type: string
example: successfully executed
statementHandle:
type: string
format: uuid
example: 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."
example: 1597090533987
statementStatusUrl:
type: string
format: uri
example: https://www.example.com
resultSetMetaData:
type: object
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.
example: 100
rowType:
type: array
minItems: 1
items:
type: object
properties:
name:
type: string
type:
type: string
length:
type: integer
format: int64
minimum: 0
precision:
type: integer
format: int64
minimum: 0
scale:
type: integer
format: int64
minimum: 0
nullable:
type: boolean
example:
- name: ROWNUM
type: FIXED
length: 0
precision: 38
scale: 0
nullable: false
- name: ACCOUNT_ID
type: FIXED
length: 0
precision: 38
scale: 0
nullable: false
- name: ACCOUNT_NAME
type: TEXT
length: 1024
precision: 0
scale: 0
nullable: false
- name: ADDRESS
type: TEXT
length: 16777216
precision: 0
scale: 0
nullable: true
- name: ZIP
type: TEXT
length: 100
precision: 0
scale: 0
nullable: true
- name: CREATED_ON
type: TIMESTAMP_NTZ
length: 0
precision: 0
scale: 3
nullable: false
partitionInfo:
description: Partition information
type: array
minItems: 0
items:
type: object
properties:
rowCount:
type: integer
format: int64
description: Number of rows in the partition.
minimum: 0
example: 1324
compressedSize:
type: integer
format: int64
description: the partition size before the decompression. This may or may not be present in the partitionInfo. Uncompressed size would always be there.
minimum: 0
example: 37436824
uncompressedSize:
type: integer
format: int64
description: the partition size after the decompression
minimum: 0
example: 1343787384
nullable:
description: false if null is replaced with a string 'null' otherwise false
type: boolean
parameters:
type: object
properties:
binary_output_format:
type: string
example: HEX
date_output_format:
type: string
example: YYYY-MM-DD
time_output_format:
type: string
example: HH24:MI:SS
timestamp_output_format:
type: string
example: YYYY-MM-DD HH24:MI:SS.FF6
timestamp_ltz_output_format:
type: string
example: YYYY-MM-DD HH24:MI:SS.FF6
timestamp_ntz_output_format:
type: string
example: YYYY-MM-DD HH24:MI:SS.FF6
timestamp_tz_output_format:
type: string
example: YYYY-MM-DDTHH24:MI:SS.FF6 TZHTZM
multi_statement_count:
type: integer
example: 4
example: example_value
data:
description: Result set data.
type: array
minItems: 0
items:
type: array
minItems: 0
items:
type: string
nullable: true
minItems: 0
example:
- - customer1
- 1234 A Avenue
- '98765'
- '2019-08-10 23:56:34.123'
- - customer2
- 987 B Street
- '98765'
- '2019-08-11 09:45:12.890'
- - customer3
- 8777 C Blvd
- '98765'
- '2019-08-12 10:23:51.999'
- - customer4
- 64646 D Circle
- '98765'
- '2019-08-13 01:54:32.000'
stats:
type: object
description: these stats might not be available for each request.
properties:
numRowsInserted:
type: integer
format: int64
description: Number of rows that were inserted.
minimum: 0
example: 12
numRowsUpdated:
type: integer
format: int64
description: Number of rows that were updated.
minimum: 0
example: 9
numRowsDeleted:
type: integer
format: int64
description: Number of rows that were deleted.
minimum: 0
example: 8
numDuplicateRowsUpdated:
type: integer
format: int64
description: Number of duplicate rows that were updated.
minimum: 0
example: 20
example: example_value
parameters:
requestId:
name: requestId
in: query
schema:
type: string
format: uuid
required: false
allowEmptyValue: 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.
async:
name: async
in: query
schema:
type: boolean
example: true
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.
partition:
name: partition
in: query
schema:
type: integer
format: int64
minimum: 0
example: 2
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
example: true
required: false
description: Set to true to execute the statement to generate the result set including null. If the parameter is set to false, the result set value null will be replaced with a string 'null'.
statementHandle:
name: statementHandle
in: path
schema:
type: string
format: uuid
example: e4ce975e-f7ff-4b5e-b15e-bf25f59371ae
required: true
allowEmptyValue: false
description: The handle of the statement that you want to use (e.g. to fetch the result set or cancel execution).
userAgent:
name: User-Agent
in: header
schema:
type: string
example: myApplication/1.0
required: true
allowEmptyValue: false
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."
accept:
name: Accept
in: header
schema:
type: string
example: application/json
required: false
allowEmptyValue: false
description: The response payload format. The schema should be specified in resultSetMetaData in the request payload.
acceptEncoding:
name: Accept-Encoding
in: header
schema:
type: string
example: gzip
required: false
allowEmptyValue: false
description: The response payload encoding. Optional.
snowflakeAuthorizationTokenType:
name: X-Snowflake-Authorization-Token-Type
in: header
schema:
type: string
example: KEYPAIR_JWT
required: false
allowEmptyValue: true
description: Specify the authorization token type for the Authorization header. KEYPAIR_JWT is for Keypair JWT or OAUTH for oAuth token. If not specified, OAUTH is assumed.
securitySchemes:
keyPair:
type: http
scheme: bearer
bearerFormat: JWT
description: Set X
# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/snowflake/refs/heads/main/openapi/sqlapi.yaml