Snowflake SQL API

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