openapi: 3.1.0 info: title: Snowflake SQL REST API version: 2.0.0 description: >- The Snowflake SQL REST API is a REST API that you can use to access and update data in a Snowflake database. You can use this API to submit SQL statements for execution, check the status of statement execution, and retrieve results. The API supports synchronous and asynchronous execution, multi-statement requests, and bind variables. contact: name: Snowflake, Inc. url: https://snowflake.com email: support@snowflake.com license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0 servers: - description: Snowflake SQL API V2 url: https://{account}.snowflakecomputing.com variables: account: default: org-account description: >- Your Snowflake account identifier in the format org-account_name or account_locator.region.cloud. 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: 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' 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 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 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 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' 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' 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 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 parameters: 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. 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. 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 result set including null. If the parameter is set to false, the result set value null will be replaced with the string 'null'. statementHandle: name: statementHandle in: path schema: type: string format: uuid required: true 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 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. accept: name: Accept in: header schema: type: string default: application/json required: false description: >- The response payload format. The schema should be specified in resultSetMetaData in the request payload. snowflakeAuthorizationTokenType: name: X-Snowflake-Authorization-Token-Type in: header schema: type: string enum: - KEYPAIR_JWT - OAUTH - PROGRAMMATIC_ACCESS_TOKEN required: false description: >- Specify the authorization token type for the Authorization header. KEYPAIR_JWT is for Keypair JWT, OAUTH for oAuth token, or PROGRAMMATIC_ACCESS_TOKEN for programmatic access tokens. If not specified, OAUTH is assumed. securitySchemes: keyPair: type: http scheme: bearer bearerFormat: JWT description: >- Key pair authentication using a JWT token. Set X-Snowflake-Authorization-Token-Type to KEYPAIR_JWT. externalOAuth: type: http scheme: bearer bearerFormat: JWT description: >- External OAuth authentication. Configure External OAuth with Snowflake and set X-Snowflake-Authorization-Token-Type to OAUTH. Set the Token to the auth token received from the external Auth server. snowflakeOAuth: type: oauth2 description: Snowflake OAuth authentication flow. flows: authorizationCode: authorizationUrl: https://org-account.snowflakecomputing.com/oauth/authorize tokenUrl: https://org-account.snowflakecomputing.com/oauth/token-request scopes: session:role:PUBLIC: Default public role access responses: 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. 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. 403Forbidden: description: >- Forbidden. The request is forbidden. This can happen if the request is made even though the API is not enabled. 404NotFound: description: >- Not Found. The request endpoint is not valid. This happens if the API endpoint is wrong. 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. 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. 429LimitExceeded: description: >- Limit Exceeded. The number of requests hit the rate limit. The application must slow down the frequency of hitting the API endpoints. 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. 503ServiceUnavailable: description: >- Service Unavailable. The request was not processed due to server side timeouts. The application may retry with backoff. Jittered backoff is recommended. 504GatewayTimeout: description: >- Gateway Timeout. The request was not processed due to server side timeouts. The application may retry with backoff. Jittered backoff is recommended. 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). security: - keyPair: [] - externalOAuth: [] - snowflakeOAuth: [] externalDocs: description: Snowflake SQL API documentation url: https://docs.snowflake.com/en/developer-guide/sql-api/index