{
  "components": {
    "parameters": {
      "chunkIndex": {
        "in": "path",
        "name": "chunk_index",
        "required": true,
        "schema": {
          "format": "int32",
          "type": "integer"
        }
      },
      "statementId": {
        "in": "path",
        "name": "statement_id",
        "required": true,
        "schema": {
          "description": "Statement ID is returned upon successfully submitting a SQL statement, and is a required reference for all\nsubsequent calls.\n",
          "type": "string"
        }
      }
    },
    "responses": {
      "CancelStatementResponse": {
        "content": {
          "application/json": {
            "schema": {
              "type": "object"
            }
          }
        }
      },
      "ErrorResponse": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ServiceError"
            }
          }
        }
      },
      "StatementResponse": {
        "content": {
          "application/json": {
            "examples": {
              "statement_response_ext_links_succeeded": {
                "summary": "Large result sets with EXTERNAL_LINKS + ARROW_STREAM",
                "value": {
                  "manifest": {
                    "chunks": [
                      {
                        "chunk_index": 0,
                        "row_count": 100,
                        "row_offset": 0
                      }
                    ],
                    "format": "ARROW_STREAM",
                    "schema": {
                      "column_count": 1,
                      "columns": [
                        {
                          "name": "id",
                          "position": 0,
                          "type_name": "LONG",
                          "type_text": "BIGINT"
                        }
                      ]
                    },
                    "total_byte_count": 16160,
                    "total_chunk_count": 1,
                    "total_row_count": 100
                  },
                  "result": {
                    "external_links": [
                      {
                        "chunk_index": 0,
                        "expiration": "2023-01-30T22:23:23.140Z",
                        "external_link": "https://someplace.s3.us-west-2.amazonaws.com/very/long/path/...",
                        "row_count": 100,
                        "row_offset": 0
                      }
                    ]
                  },
                  "statement_id": "01eda0ea-9b4b-15ce-b8bb-a7d4114cb5ed",
                  "status": {
                    "state": "SUCCEEDED"
                  }
                }
              },
              "statement_response_inline_succeeded": {
                "summary": "JSON_ARRAY formatted data returned INLINE",
                "value": {
                  "manifest": {
                    "format": "JSON_ARRAY",
                    "schema": {
                      "column_count": 1,
                      "columns": [
                        {
                          "name": "id",
                          "position": 0,
                          "type_name": "LONG",
                          "type_text": "BIGINT"
                        }
                      ]
                    }
                  },
                  "result": {
                    "chunk_index": 0,
                    "data_array": [
                      [
                        "0"
                      ],
                      [
                        "1"
                      ],
                      [
                        "2"
                      ]
                    ],
                    "row_count": 3,
                    "row_offset": 0
                  },
                  "statement_id": "01eda0e7-e315-1846-84e2-79a963ffad44",
                  "status": {
                    "state": "SUCCEEDED"
                  }
                }
              },
              "statement_response_running": {
                "summary": "Call mode: asynchronous. Submission is accepted",
                "value": {
                  "statement_id": "01ed9db9-24c4-1cb6-a320-fb6ebbe7410d",
                  "status": {
                    "state": "RUNNING"
                  }
                }
              }
            },
            "schema": {
              "properties": {
                "manifest": {
                  "$ref": "#/components/schemas/ResultManifest"
                },
                "result": {
                  "$ref": "#/components/schemas/ResultData"
                },
                "statement_id": {
                  "$ref": "#/components/schemas/StatementId"
                },
                "status": {
                  "$ref": "#/components/schemas/StatementStatus"
                }
              },
              "type": "object"
            }
          }
        }
      }
    },
    "schemas": {
      "Chunk": {
        "properties": {
          "byte_count": {
            "description": "Number of bytes in the result chunk.",
            "format": "int64",
            "type": "integer"
          },
          "chunk_index": {
            "description": "Position within the sequence of result set chunks.",
            "type": "integer"
          },
          "data_array": {
            "$ref": "#/components/schemas/JsonArray"
          },
          "next_chunk_index": {
            "description": "When fetching, gives `chunk_index` for the _next_ chunk; if absent, indicates there are no more chunks.",
            "type": "integer"
          },
          "next_chunk_internal_link": {
            "description": "When fetching, gives `internal_link` for the _next_ chunk; if absent, indicates there are no more chunks.",
            "type": "string"
          },
          "row_count": {
            "description": "Number of rows within the result chunk.",
            "format": "int64",
            "type": "integer"
          },
          "row_offset": {
            "description": "Starting row offset within the result set.",
            "format": "int64",
            "type": "integer"
          }
        },
        "type": "object"
      },
      "ChunkInfo": {
        "description": "Describes metadata for a particular chunk, within a result set; this structure is used both within a manifest,\nand when fetching individual chunk data or links.\n",
        "properties": {
          "byte_count": {
            "description": "Number of bytes in the result chunk.",
            "format": "int64",
            "type": "integer"
          },
          "chunk_index": {
            "description": "Position within the sequence of result set chunks.",
            "type": "integer"
          },
          "next_chunk_index": {
            "description": "When fetching, gives `chunk_index` for the _next_ chunk; if absent, indicates there are no more chunks.",
            "type": "integer"
          },
          "next_chunk_internal_link": {
            "description": "When fetching, gives `internal_link` for the _next_ chunk; if absent, indicates there are no more chunks.",
            "type": "string"
          },
          "row_count": {
            "description": "Number of rows within the result chunk.",
            "format": "int64",
            "type": "integer"
          },
          "row_offset": {
            "description": "Starting row offset within the result set.",
            "format": "int64",
            "type": "integer"
          }
        },
        "type": "object"
      },
      "ColumnInfo": {
        "properties": {
          "name": {
            "description": "Name of Column.",
            "type": "string"
          },
          "position": {
            "description": "Ordinal position of column (starting at position 0).",
            "format": "int32",
            "type": "integer"
          },
          "type_interval_type": {
            "description": "Format of interval type.",
            "type": "string"
          },
          "type_name": {
            "description": "Name of type (INT, STRUCT, MAP, and so on)",
            "enum": [
              "BOOLEAN",
              "BYTE",
              "SHORT",
              "INT",
              "LONG",
              "FLOAT",
              "DOUBLE",
              "DATE",
              "TIMESTAMP",
              "STRING",
              "BINARY",
              "DECIMAL",
              "INTERVAL",
              "ARRAY",
              "STRUCT",
              "MAP",
              "CHAR",
              "NULL",
              "USER_DEFINED_TYPE"
            ],
            "type": "string"
          },
          "type_precision": {
            "description": "Digits of precision.",
            "format": "int32",
            "type": "integer"
          },
          "type_scale": {
            "description": "Digits to right of decimal.",
            "format": "int32",
            "type": "integer"
          },
          "type_text": {
            "description": "Full data type spec, SQL/catalogString text.",
            "type": "string"
          }
        },
        "type": "object"
      },
      "Disposition": {
        "description": "The fetch disposition provides two modes of fetching results: `INLINE` and `EXTERNAL_LINKS`.\n\nStatements executed with `INLINE` disposition will return result data inline, in `JSON_ARRAY` format, in a series\nof chunks. If a given statement produces a result set with a size larger than 16 MiB,\nthat statement execution is aborted, and no result set will be available.\n\n**NOTE**\nByte limits are computed based upon internal representations of the result set data, and may not match the\nsizes visible in JSON responses.\n\nStatements executed with `EXTERNAL_LINKS` disposition will return result data as external links: URLs that point\nto cloud storage internal to the workspace. Using `EXTERNAL_LINKS` disposition allows statements to\ngenerate arbitrarily sized result sets for fetching up to 100 GiB. The resulting links\nhave two important properties:\n\n1. They point to resources _external_ to the Databricks compute; therefore any associated authentication\n   information (typically a personal access token, OAuth token, or similar) _must be removed_ when fetching from these links.\n\n2. These are presigned URLs with a specific expiration, indicated in the response. The behavior when attempting to use an expired link is cloud specific.\n",
        "enum": [
          "INLINE",
          "EXTERNAL_LINKS"
        ],
        "type": "string"
      },
      "ExecuteStatementRequest": {
        "properties": {
          "byte_limit": {
            "description": "Applies the given byte limit to the statement's result size. Byte counts are based on internal representations and may\nnot match measurable sizes in the requested `format`.\n",
            "format": "int64",
            "type": "integer"
          },
          "catalog": {
            "description": "Sets default catalog for statement execution, similar to [`USE CATALOG`](https://docs.microsoft.com/azure/databricks/sql/language-manual/sql-ref-syntax-ddl-use-catalog.html) in SQL.\n",
            "type": "string"
          },
          "disposition": {
            "$ref": "#/components/schemas/Disposition"
          },
          "format": {
            "$ref": "#/components/schemas/Format"
          },
          "on_wait_timeout": {
            "$ref": "#/components/schemas/TimeoutAction"
          },
          "schema": {
            "description": "Sets default schema for statement execution, similar to [`USE SCHEMA`](https://docs.microsoft.com/azure/databricks/sql/language-manual/sql-ref-syntax-ddl-use-schema.html) in SQL.\n",
            "type": "string"
          },
          "statement": {
            "description": "SQL statement to execute",
            "example": "SELECT * FROM range(10)",
            "type": "string"
          },
          "wait_timeout": {
            "description": "The time in seconds the API service will wait for the statement's result set as `Ns`, where `N` can be set to 0 or to a value between 5 and 50.\nWhen set to '0s' the statement will execute in asynchronous mode.\"\n",
            "type": "string"
          },
          "warehouse_id": {
            "$ref": "#/components/schemas/WarehouseId"
          }
        },
        "type": "object"
      },
      "ExternalLink": {
        "properties": {
          "byte_count": {
            "description": "Number of bytes in the result chunk.",
            "format": "int64",
            "type": "integer"
          },
          "chunk_index": {
            "description": "Position within the sequence of result set chunks.",
            "type": "integer"
          },
          "expiration": {
            "description": "Indicates date-time that the given external link will expire and become invalid, after which point a new\n`external_link` must be requested.\n",
            "format": "date-time",
            "type": "string"
          },
          "external_link": {
            "description": "Pre-signed URL pointing to a chunk of result data, hosted by an external service, with a short expiration\ntime (< 1 hour).\n",
            "type": "string"
          },
          "next_chunk_index": {
            "description": "When fetching, gives `chunk_index` for the _next_ chunk; if absent, indicates there are no more chunks.",
            "type": "integer"
          },
          "next_chunk_internal_link": {
            "description": "When fetching, gives `internal_link` for the _next_ chunk; if absent, indicates there are no more chunks.",
            "type": "string"
          },
          "row_count": {
            "description": "Number of rows within the result chunk.",
            "format": "int64",
            "type": "integer"
          },
          "row_offset": {
            "description": "Starting row offset within the result set.",
            "format": "int64",
            "type": "integer"
          }
        },
        "type": "object"
      },
      "Format": {
        "description": "Statement execution supports two result formats: `JSON_ARRAY` (default), and `ARROW_STREAM`.\n\n**NOTE**\n\nCurrently `JSON_ARRAY` is only available for requests with `disposition=INLINE`, and `ARROW_STREAM` is only\navailable for requests with `disposition=EXTERNAL_LINKS`.\n\nWhen specifying `format=JSON_ARRAY`, result data will be formatted as an array of arrays of values, where each\nvalue is either the *string representation* of a value, or `null`. For example, the output of `SELECT\nconcat('id-', id) AS strId, id AS intId FROM range(3)` would look like this:\n\n```\n[\n  [ \"id-1\", \"1\" ],\n  [ \"id-2\", \"2\" ],\n  [ \"id-3\", \"3\" ],\n]\n```\n\n`INLINE` `JSON_ARRAY` data can be found within `StatementResponse.result.chunk.data_array` or\n`ResultData.chunk.data_array`.\n\nWhen specifying `format=ARROW_STREAM`, results fetched through `external_links` will be chunks of\nresult data, formatted as Apache Arrow Stream. See\n[Apache Arrow Streaming Format](https://arrow.apache.org/docs/format/Columnar.html#ipc-streaming-format) for more details.\n",
        "enum": [
          "JSON_ARRAY",
          "ARROW_STREAM"
        ],
        "type": "string"
      },
      "JsonArray": {
        "description": "`JSON_ARRAY` format is an array of arrays of values, where each non-null value is formatted as a string. Null\nvalues are encoded as JSON `null`.\n",
        "items": {
          "items": {
            "description": "Non-null values are string encoded, null values are encoded as `null`.",
            "nullable": true,
            "type": "string"
          },
          "nullable": false,
          "type": "array"
        },
        "type": "array"
      },
      "ResultData": {
        "description": "Result data chunks are delivered in either the `chunk` field when using `INLINE` disposition,\nor in the `external_link` field when using `EXTERNAL_LINKS` disposition. Exactly one of these\nwill be set.\n",
        "properties": {
          "byte_count": {
            "description": "Number of bytes in the result chunk.",
            "format": "int64",
            "type": "integer"
          },
          "chunk_index": {
            "description": "Position within the sequence of result set chunks.",
            "type": "integer"
          },
          "data_array": {
            "$ref": "#/components/schemas/JsonArray"
          },
          "external_links": {
            "items": {
              "$ref": "#/components/schemas/ExternalLink"
            },
            "type": "array"
          },
          "next_chunk_index": {
            "description": "When fetching, gives `chunk_index` for the _next_ chunk; if absent, indicates there are no more chunks.",
            "type": "integer"
          },
          "next_chunk_internal_link": {
            "description": "When fetching, gives `internal_link` for the _next_ chunk; if absent, indicates there are no more chunks.",
            "type": "string"
          },
          "row_count": {
            "description": "Number of rows within the result chunk.",
            "format": "int64",
            "type": "integer"
          },
          "row_offset": {
            "description": "Starting row offset within the result set.",
            "format": "int64",
            "type": "integer"
          }
        },
        "type": "object"
      },
      "ResultManifest": {
        "description": "The result manifest provides schema and metadata for the result set.",
        "properties": {
          "chunks": {
            "description": "Array of result set chunk metadata.",
            "items": {
              "$ref": "#/components/schemas/ChunkInfo"
            },
            "type": "array"
          },
          "format": {
            "$ref": "#/components/schemas/Format"
          },
          "schema": {
            "$ref": "#/components/schemas/ResultSchema"
          },
          "total_byte_count": {
            "description": "Total number of bytes in the result set.",
            "format": "int64",
            "type": "integer"
          },
          "total_chunk_count": {
            "description": "Total number of chunks that the result set has been divided into.",
            "type": "integer"
          },
          "total_row_count": {
            "description": "Total number of rows in the result set.",
            "format": "int64",
            "type": "integer"
          }
        },
        "type": "object"
      },
      "ResultSchema": {
        "description": "Schema is an ordered list of column descriptions.",
        "properties": {
          "column_count": {
            "type": "integer"
          },
          "columns": {
            "items": {
              "$ref": "#/components/schemas/ColumnInfo"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "ServiceError": {
        "properties": {
          "error_code": {
            "$ref": "#/components/schemas/ServiceErrorCode"
          },
          "message": {
            "description": "Brief summary of error condition.",
            "type": "string"
          }
        },
        "type": "object"
      },
      "ServiceErrorCode": {
        "enum": [
          "UNKNOWN",
          "INTERNAL_ERROR",
          "TEMPORARILY_UNAVAILABLE",
          "IO_ERROR",
          "BAD_REQUEST",
          "SERVICE_UNDER_MAINTENANCE",
          "WORKSPACE_TEMPORARILY_UNAVAILABLE",
          "DEADLINE_EXCEEDED",
          "CANCELLED",
          "RESOURCE_EXHAUSTED",
          "ABORTED",
          "NOT_FOUND",
          "ALREADY_EXISTS",
          "UNAUTHENTICATED"
        ],
        "type": "string"
      },
      "StatementId": {
        "description": "Statement ID is returned upon successfully submitting a SQL statement, and is a required reference for all\nsubsequent calls.\n",
        "type": "string"
      },
      "StatementState": {
        "description": "Statement execution state:\n- `PENDING`: waiting for warehouse\n- `RUNNING`: running\n- `SUCCEEDED`: execution was successful, result data available for fetch\n- `FAILED`: execution failed; reason for failure described in accomanying error message\n- `CANCELED`: user canceled; can come from explicit cancel call, or timeout with `on_wait_timeout=CANCEL`\n- `CLOSED`: execution successful, and statement closed; result no longer available for fetch\n",
        "enum": [
          "PENDING",
          "RUNNING",
          "SUCCEEDED",
          "FAILED",
          "CANCELED",
          "CLOSED"
        ],
        "type": "string"
      },
      "StatementStatus": {
        "description": "Status response includes execution state and if relevant, error information.",
        "properties": {
          "error": {
            "$ref": "#/components/schemas/ServiceError"
          },
          "state": {
            "$ref": "#/components/schemas/StatementState"
          }
        },
        "type": "object"
      },
      "TimeoutAction": {
        "description": "When in synchronous mode with `wait_timeout > 0s` it determines the action taken when the timeout is reached:\n\n`CONTINUE` → the statement execution continues asynchronously and the call returns a statement ID immediately.\n\n`CANCEL` → the statement execution is canceled and the call returns immediately with a `CANCELED` state.\n",
        "enum": [
          "CONTINUE",
          "CANCEL"
        ],
        "type": "string"
      },
      "WarehouseId": {
        "description": "Warehouse upon which to execute a statement. See also [What are SQL warehouses?](https://docs.microsoft.com/azure/databricks/sql/admin/warehouse-type.html)\n",
        "type": "string"
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "bearerFormat": "String",
        "description": "Authenticate with a Databricks personal access token (PAT).",
        "in": "header",
        "name": "Token",
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "info": {
    "description": "This feature is in [Public Preview](https://docs.microsoft.com/azure/databricks/release-notes/release-types.html).\n\nThe SQL Statement Execution API manages the execution of arbitrary SQL statements and the fetching of result data.\n",
    "title": "SQL Statement Execution API",
    "version": "2.0.0"
  },
  "openapi": "3.0.0",
  "paths": {
    "/api/2.0/sql/statements/": {
      "post": {
        "description": "Execute a SQL statement, and if flagged as such, await its result for a specified time.\n",
        "operationId": "executeStatement",
        "requestBody": {
          "content": {
            "application/json": {
              "examples": {
                "execute_statement_async": {
                  "summary": "Call mode: asynchronous",
                  "value": {
                    "statement": "SELECT * FROM range(100)",
                    "wait_timeout": "0s",
                    "warehouse_id": "abcdef0123456789"
                  }
                },
                "execute_statement_sync_cancel": {
                  "summary": "Call mode: synchronous. Cancel on timeout",
                  "value": {
                    "on_wait_timeout": "CANCEL",
                    "statement": "SELECT * FROM range(100)",
                    "wait_timeout": "30s",
                    "warehouse_id": "abcdef0123456789"
                  }
                },
                "execute_statement_sync_continue": {
                  "summary": "Call mode: synchronous. Continue on timeout",
                  "value": {
                    "on_wait_timeout": "CONTINUE",
                    "statement": "SELECT * FROM range(100)",
                    "wait_timeout": "30s",
                    "warehouse_id": "abcdef0123456789"
                  }
                },
                "execute_statement_sync_ext_links": {
                  "summary": "Large result sets with EXTERNAL_LINKS + ARROW_STREAM",
                  "value": {
                    "disposition": "EXTERNAL_LINKS",
                    "format": "ARROW_STREAM",
                    "statement": "SELECT * FROM range(100)",
                    "warehouse_id": "abcdef0123456789"
                  }
                },
                "execute_statement_with_defaults": {
                  "summary": "Call mode: synchronous. Deafult parameters",
                  "value": {
                    "statement": "SELECT * FROM range(3)",
                    "warehouse_id": "abcdef0123456789"
                  }
                }
              },
              "schema": {
                "$ref": "#/components/schemas/ExecuteStatementRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/StatementResponse",
            "description": "StatementResponse will contain `statement_id` and `status`; other fields may be absent or\npresent depending on context. See each field for its description.\n"
          },
          "default": {
            "$ref": "#/components/responses/ErrorResponse"
          }
        },
        "summary": "Execute a SQL statement",
        "tags": [
          "Statement Execution"
        ]
      }
    },
    "/api/2.0/sql/statements/{statement_id}": {
      "get": {
        "description": "This request can be used to poll for the statement's status. When the `status.state` field is `SUCCEEDED` it will also\nreturn the result manifest and the first chunk of the result data. When the statement is in the terminal states `CANCELED`,\n`CLOSED` or `FAILED`, it returns HTTP 200 with the state set. After at least 12 hours in terminal state, the statement is\nremoved from the warehouse and further calls will receive an HTTP 404 response.\n\n**NOTE**\nThis call currently may take up to 5 seconds to get the latest status and result.\n",
        "operationId": "getStatement",
        "responses": {
          "200": {
            "$ref": "#/components/responses/StatementResponse",
            "description": "StatementResponse will contain `statement_id` and `status`; other fields may be absent or\npresent depending on context. See each field for its description.\n"
          },
          "default": {
            "$ref": "#/components/responses/ErrorResponse"
          }
        },
        "summary": "Get status, manifest, and result first chunk",
        "tags": [
          "Statement Execution"
        ]
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/statementId"
        }
      ]
    },
    "/api/2.0/sql/statements/{statement_id}/cancel": {
      "parameters": [
        {
          "$ref": "#/components/parameters/statementId"
        }
      ],
      "post": {
        "description": "Requests that an executing statement be canceled. Callers must poll for status to see the terminal state.\n",
        "operationId": "cancelExecution",
        "responses": {
          "200": {
            "description": "Cancel response is empty; receiving response indicates successful receipt."
          },
          "default": {
            "$ref": "#/components/responses/ErrorResponse"
          }
        },
        "summary": "Cancel statement execution",
        "tags": [
          "Statement Execution"
        ]
      }
    },
    "/api/2.0/sql/statements/{statement_id}/result/chunks/{chunk_index}": {
      "get": {
        "description": "After the statement execution has `SUCCEEDED`, the result data can be fetched by chunks. Whereas\nthe first chuck with `chunk_index=0` is typically fetched through a `get status` request,\nsubsequent chunks can be fetched using a `get result` request. The response structure is identical\nto the nested `result` element described in the `get status` request, and similarly includes the\n`next_chunk_index` and `next_chunk_internal_link` fields for simple iteration through the result set.\n",
        "operationId": "getStatementResultChunkN",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "get_result_chunk_inline_next": {
                    "summary": "Small result sets with INLINE + JSON_ARRAY",
                    "value": {
                      "chunk_index": 0,
                      "data_array": [
                        [
                          "0-54-0.8256375429534709"
                        ],
                        [
                          "// ... 139799 more rows"
                        ]
                      ],
                      "next_chunk_index": 1,
                      "next_chunk_internal_link": "/api/2.0/sql/statements/01eda0ed-9149-1648-bb5d-46d635ab7d74/result/chunks/1?row_offset=139800",
                      "row_count": 139800,
                      "row_offset": 0
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ResultData"
                }
              }
            },
            "description": "Successful return; depending on `disposition` returns chunks of data either inline, or as links."
          },
          "default": {
            "$ref": "#/components/responses/ErrorResponse"
          }
        },
        "summary": "Get result chunk by index",
        "tags": [
          "Statement Execution"
        ]
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/statementId"
        },
        {
          "$ref": "#/components/parameters/chunkIndex"
        }
      ]
    }
  },
  "security": [
    {
      "bearerAuth": []
    },
    {}
  ],
  "servers": [
    {
      "description": "Substitute `$DATABRICKS_HOST` with the `adb-{workspace-id}.{random-number}.azuredatabricks.net` domain name of your Azure Databricks deployment.",
      "url": "https://$DATABRICKS_HOST"
    }
  ],
  "tags": [
    {
      "description": "The SQL Statement Execution API manages the execution of arbitrary SQL statements and the fetching of result data.\n\n**Release status**\n\nThis feature is in [Public Preview](/release-notes/release-types.html).\n\n**Getting started**\n\nWe suggest beginning with the [SQL Statement Execution API tutorial](https://learn.microsoft.com/azure/databricks/sql/api/sql-execution-tutorial).\n\n**Overview of statement execution and result fetching**\n\nStatement execution begins by issuing a `POST https://$DATABRICKS_HOST/api/2.0/sql/statements/` request with a valid\nSQL statement and warehouse ID, along with optional parameters such as the data catalog and output format.\n\nWhen submitting the statement, the call can behave synchronously or asynchronously, based on the `wait_timeout`\nsetting. When set between 5-50 seconds (default:\n10) the call behaves synchronously and waits for results up to the specified timeout; when set to `0s`, the call is asynchronous and responds\nimmediately with a statement ID that can be used to poll for status or fetch the results in a separate call.\n\n**Call mode: synchronous**\n\nIn synchronous mode, when statement execution completes within the `wait timeout`,\nthe result data is returned directly in the response. This response will contain `statement_id`, `status`, `manifest`, and\n`result` fields. The `status` field confirms success whereas the `manifest` field contains the result data column schema and\nmetadata about the result set. The `result` field contains the first chunk of result data according to the specified\n`disposition`, and links to fetch any remaining chunks.\n\nIf the execution does not complete before `wait_timeout`, the setting\n`on_wait_timeout` determines how the system responds.\n\nBy default, `on_wait_timeout=CONTINUE`, and after reaching `wait_timeout`, a response is returned and statement execution\ncontinues asynchronously. The response will contain only `statement_id` and `status` fields, and the caller must now\nfollow the flow described for asynchronous call mode to poll and fetch the result.\n\nAlternatively, `on_wait_timeout` can also be set to `CANCEL`; in this case if the timeout is reached before\nexecution completes, the underlying statement execution is canceled, and a `CANCELED` status is returned in the\nresponse.\n\n**Call mode: asynchronous**\n\nIn asynchronous mode, or after a timed-out synchronous request continues, a `statement_id` and `status` will be\nreturned. In this case polling `GET https://$DATABRICKS_HOST/api/2.0/sql/statements/{statement_id}` calls are required to fetch the result and metadata.\n\nNext, a caller must poll until execution completes (`SUCCEEDED`, `FAILED`, etc.) by issuing `GET https://$DATABRICKS_HOST/api/2.0/sql/statements/{statement_id}`\nrequests for the given `statement_id`.\n\nWhen execution has succeeded, the response will contain `status`, `manifest`, and `result` fields. These fields\nand the structure are identical to those in the response to a successful synchronous submission. The `result` field will\ncontain the first chunk of result data, either `INLINE` or as `EXTERNAL_LINKS` depending on `disposition`. Additional\nchunks of result data can be fetched by checking for the presence of the `next_chunk_internal_link` field, and\niteratively `GET` those paths until that field is unset: `GET https://$DATABRICKS_HOST/{next_chunk_internal_link}`.\n\n**Fetching result data: format and disposition**\n\nResult data from statement execution is available in two formats: JSON, and\n[Apache Arrow Columnar](https://arrow.apache.org/overview/). Statements producing a result set smaller than\n16 MiB can be fetched as `format=JSON_ARRAY`, using the `disposition=INLINE`. When a\nstatement executed in `INLINE` disposition exceeds this limit, the execution is aborted, and no result can be fetched.\nUsing `format=ARROW_STREAM` and `disposition=EXTERNAL_LINKS` allows large result sets, and with\nhigher throughput.\n\nThe API uses defaults of `format=JSON_ARRAY` and `disposition=INLINE`. `We advise explicitly setting format and\ndisposition in all production use cases.\n\n**Statement response: statement_id, status, manifest, and result**\n\nThe base call `GET https://$DATABRICKS_HOST/api/2.0/sql/statements/{statement_id}` returns a single response combining `statement_id`, `status`, a\nresult `manifest`, and a `result` data chunk or link, depending on the `disposition`. The `manifest` contains the result schema definition and the result\nsummary metadata. When using `disposition=EXTERNAL_LINKS`, it also contains a full listing of all chunks and\ntheir summary metadata.\n\n**Use case: small result sets with INLINE + JSON_ARRAY**\n\nFor flows that generate small and predictable result sets (<= 16 MiB), `INLINE`\ndownloads of `JSON_ARRAY` result data are typically the simplest way to execute and fetch result data.\n\nWhen the result set with `disposition=INLINE` is larger, the result can be transferred in chunks. After receiving the initial chunk with `POST https://$DATABRICKS_HOST/api/2.0/sql/statements/` or `GET https://$DATABRICKS_HOST/api/2.0/sql/statements/{statement_id}` subsequent calls are\nrequired to iteratively fetch each chunk. Each result response contains a link to the next chunk, when there are\nadditional chunks to fetch; it can be found in the field `.next_chunk_internal_link`. This link is an absolute\n`path` to be joined with your `$DATABRICKS_HOST`, and of the form\n`/api/2.0/sql/statements/{statement_id}/result/chunks/{chunk_index}`. The next chunk can be fetched by issuing a `GET https://$DATABRICKS_HOST/api/2.0/sql/statements/{statement_id}/result/chunks/{chunk_index}` request.\n\nWhen using this mode, each chunk may be fetched once, and in order. A chunk without a field\n`next_chunk_internal_link` indicates the last chunk was reached and all chunks have been fetched from the\nresult set.\n\n**Use case: large result sets with EXTERNAL_LINKS + ARROW_STREAM**\n\nUsing `EXTERNAL_LINKS` to fetch result data in Arrow format allows you to fetch large result sets efficiently.\nThe primary difference from using `INLINE` disposition is that fetched result chunks contain resolved\n`external_links` URLs, which can be fetched with standard HTTP.\n\n**Presigned URLs**\n\nExternal links point to data stored within your workspace's internal DBFS, in the form of a presigned URL. The\nURLs are valid for only a short period, <= 15 minutes. Alongside each `external_link` is an expiration field\nindicating the time at which the URL is no longer valid. In `EXTERNAL_LINKS` mode, chunks can be resolved and\nfetched multiple times and in parallel.\n\n----\n\n### **Warning: We recommend you protect the URLs in the EXTERNAL_LINKS.**\n\nWhen using the EXTERNAL_LINKS disposition, a short-lived pre-signed URL is generated, which the client\ncan use to download the result chunk directly from cloud storage. As the short-lived credential is embedded in a pre-signed URL,\nthis URL should be protected.\n\nSince pre-signed URLs are generated with embedded temporary credentials, you need to remove the authorization header from the fetch requests.\n\n----\n\nSimilar to `INLINE` mode, callers can iterate through the result set, by using the\n`next_chunk_internal_link` field. Each internal link response will contain an external link to the raw chunk data,\nand additionally contain the `next_chunk_internal_link` if there are more chunks.\n\nUnlike `INLINE` mode, when using `EXTERNAL_LINKS`, chunks may be fetched out of order, and in parallel to\nachieve higher throughput.\n\n**Limits and limitations**\n\nNote: All byte limits are calculated based on internal storage metrics and will not match byte counts of actual payloads.\n\n- Statements with `disposition=INLINE` are limited to 16 MiB and will abort when this limit is\n  exceeded.\n- Statements with `disposition=EXTERNAL_LINKS` are limited to 100 GiB.\n- The maximum query text size is 16 MiB.\n- Cancelation may silently fail. A successful response from a cancel request indicates that the cancel request\n  was successfully received and sent to the processing engine. However, for example, an outstanding statement\n  may complete execution during signal delivery, with the cancel signal arriving too late to be meaningful. Polling\n  for status until a terminal state is reached is a reliable way to determine the final state.\n- Wait timeouts are approximate, occur server-side, and cannot account for caller delays, network latency from\n  caller to service, and similarly.\n- After a statement has been submitted and a statement_id is returned, that statement's status and result will\n  automatically close after either of 2 conditions:\n  - The last result chunk is fetched (or resolved to an external link).\n  - One hour passes with no calls to get the status or fetch the result.\n    Best practice: in asynchronous clients, poll for status regularly (and with backoff) to keep the statement\n    open and alive.\n- After fetching the last result chunk (including chunk_index=0) the statement is automatically closed.\n\n",
      "name": "Statement Execution"
    }
  ]
}
