Snowflake statements API

openapi: 3.2.0
info:
  title: Snowflake Statements API
  version: 2.0.0
  contact:
    name: Snowflake, Inc.
    url: https://snowflake.com
    email: support@snowflake.com
  description: 'Operations tagged statements across 3 of this provider''s published API definitions: snowflake-sql-rest-api.yaml, sqlapi.yaml, sqlapi.yaml. Each path carries the servers of the definition it was published in.'
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.
- description: Snowflake SQL API V2
  url: https://org-account.snowflakecomputing.com
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
    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.
  /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
    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.
  /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
    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.
components:
  parameters:
    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.
    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.
    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'.
    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.
    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).
    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.
    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_2:
      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.
    partition_2:
      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.
    async_2:
      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.
    nullable_2:
      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'.
    snowflakeAuthorizationTokenType_2:
      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.
    statementHandle_2:
      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).
    accept_2:
      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.
    requestId_2:
      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.
    userAgent_3:
      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.
    partition_3:
      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.
    async_3:
      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.
    nullable_3:
      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'.
    snowflakeAuthorizationTokenType_3:
      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.
    statementHandle_3:
      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).
    accept_3:
      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.
    requestId_3:
      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.
  schemas:
    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
    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
    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'
    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
    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

# --- truncated at 32 KB (64 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/snowflake/refs/heads/main/openapi/snowflake-statements-api-openapi.yml