# Execute Statement

Launch stage: GA

`POST /api/2.0/sql/statements`

Execute a SQL statement and optionally await its results for a specified time.

 **Use case: small result sets with INLINE + JSON_ARRAY**

 For flows that generate small and predictable result sets (<= 25 MiB), `INLINE` responses of `JSON_ARRAY` result
 data are typically the simplest way to execute and fetch result data.

 **Use case: large result sets with EXTERNAL_LINKS**

 Using `EXTERNAL_LINKS` to fetch result data allows you to fetch large result sets efficiently.
 The main differences from using `INLINE` disposition are that the result data is accessed
 with  URLs, and
 that there are 3 supported formats: `JSON_ARRAY`, `ARROW_STREAM` and `CSV` compared to only `JSON_ARRAY` with
 `INLINE`.

 ** URLs**

 External links point to data stored within your workspace's internal storage, in the form of
 a  URL. The URLs are valid for only a short
 period, <= 15 minutes. Alongside each `external_link` is an expiration field indicating the time at which the URL
 is no longer valid. In `EXTERNAL_LINKS` mode, chunks can be resolved and fetched multiple times and in parallel.

 ----

 ### **Warning: Databricks strongly recommends that you protect the URLs that are returned by the `EXTERNAL_LINKS` disposition.**

 When you use the `EXTERNAL_LINKS` disposition, a
 short-lived,  URL is generated, which can be
 used to download the results directly
 from . As a
 short-lived  is
 embedded in this  URL, you should protect
 the URL.

 Because  URLs are already generated with
 embedded temporary s,
 you must not set an `Authorization` header in the download requests.

 The `EXTERNAL_LINKS` disposition can be disabled upon request by creating a support
 case. 

 See also [Security best practices](https://docs.databricks.com/sql/admin/sql-execution-tutorial.html#security-best-practices).

 ----

 StatementResponse contains `statement_id` and `status`; other fields might be absent or present depending on
 context. If the SQL warehouse fails to execute the provided statement, a 200 response is returned with
 `status.state` set to `FAILED` (in contrast to a failure when accepting the request, which results in a non-200
 response). Details of the error can be found at `status.error` in case of execution failures.

API scopes: sql

**AWS**

Execute a SQL statement and optionally await its results for a specified time.

**Use case: small result sets with INLINE + JSON_ARRAY**

For flows that generate small and predictable result sets (<= 25 MiB), `INLINE` responses of `JSON_ARRAY` result
data are typically the simplest way to execute and fetch result data.

**Use case: large result sets with EXTERNAL_LINKS**

Using `EXTERNAL_LINKS` to fetch result data allows you to fetch large result sets efficiently.
The main differences from using `INLINE` disposition are that the result data is accessed
with presigned URLs, and
that there are 3 supported formats: `JSON_ARRAY`, `ARROW_STREAM` and `CSV` compared to only `JSON_ARRAY` with
`INLINE`.

**Presigned URLs**

External links point to data stored within your workspace's internal storage, in the form of
a presigned URL. The URLs are valid for only a short
period, <= 15 minutes. Alongside each `external_link` is an expiration field indicating the time at which the URL
is no longer valid. In `EXTERNAL_LINKS` mode, chunks can be resolved and fetched multiple times and in parallel.

----

### **Warning: Databricks strongly recommends that you protect the URLs that are returned by the `EXTERNAL_LINKS` disposition.**

When you use the `EXTERNAL_LINKS` disposition, a
short-lived, presigned URL is generated, which can be
used to download the results directly
from Amazon S3. As a
short-lived access credential is
embedded in this presigned URL, you should protect
the URL.

Because presigned URLs are already generated with
embedded temporary access credentials,
you must not set an `Authorization` header in the download requests.

The `EXTERNAL_LINKS` disposition can be disabled upon request by creating a support
case. See [Support](https://docs.databricks.com/resources/support.html).

See also [Security best practices](https://docs.databricks.com/sql/admin/sql-execution-tutorial.html#security-best-practices).

----

StatementResponse contains `statement_id` and `status`; other fields might be absent or present depending on
context. If the SQL warehouse fails to execute the provided statement, a 200 response is returned with
`status.state` set to `FAILED` (in contrast to a failure when accepting the request, which results in a non-200
response). Details of the error can be found at `status.error` in case of execution failures.

**Azure**

Execute a SQL statement and optionally await its results for a specified time.

**Use case: small result sets with INLINE + JSON_ARRAY**

For flows that generate small and predictable result sets (<= 25 MiB), `INLINE` responses of `JSON_ARRAY` result
data are typically the simplest way to execute and fetch result data.

**Use case: large result sets with EXTERNAL_LINKS**

Using `EXTERNAL_LINKS` to fetch result data allows you to fetch large result sets efficiently.
The main differences from using `INLINE` disposition are that the result data is accessed
with shared access signature (SAS) URLs, and
that there are 3 supported formats: `JSON_ARRAY`, `ARROW_STREAM` and `CSV` compared to only `JSON_ARRAY` with
`INLINE`.

**Shared Access Signature URLs**

External links point to data stored within your workspace's internal storage, in the form of
a SAS URL. The URLs are valid for only a short
period, <= 15 minutes. Alongside each `external_link` is an expiration field indicating the time at which the URL
is no longer valid. In `EXTERNAL_LINKS` mode, chunks can be resolved and fetched multiple times and in parallel.

----

### **Warning: Databricks strongly recommends that you protect the URLs that are returned by the `EXTERNAL_LINKS` disposition.**

When you use the `EXTERNAL_LINKS` disposition, a
short-lived, SAS URL is generated, which can be
used to download the results directly
from Azure storage. As a
short-lived SAS token is
embedded in this SAS URL, you should protect
the URL.

Because SAS URLs are already generated with
embedded temporary SAS tokens,
you must not set an `Authorization` header in the download requests.

The `EXTERNAL_LINKS` disposition can be disabled upon request by creating a support
case.

See also [Security best practices](https://docs.databricks.com/sql/admin/sql-execution-tutorial.html#security-best-practices).

----

StatementResponse contains `statement_id` and `status`; other fields might be absent or present depending on
context. If the SQL warehouse fails to execute the provided statement, a 200 response is returned with
`status.state` set to `FAILED` (in contrast to a failure when accepting the request, which results in a non-200
response). Details of the error can be found at `status.error` in case of execution failures.

**GCP**

Execute a SQL statement and optionally await its results for a specified time.

**Use case: small result sets with INLINE + JSON_ARRAY**

For flows that generate small and predictable result sets (<= 25 MiB), `INLINE` responses of `JSON_ARRAY` result
data are typically the simplest way to execute and fetch result data.

**Use case: large result sets with EXTERNAL_LINKS**

Using `EXTERNAL_LINKS` to fetch result data allows you to fetch large result sets efficiently.
The main differences from using `INLINE` disposition are that the result data is accessed
with signed URLs, and
that there are 3 supported formats: `JSON_ARRAY`, `ARROW_STREAM` and `CSV` compared to only `JSON_ARRAY` with
`INLINE`.

**Signed URLs**

External links point to data stored within your workspace's internal storage, in the form of
a signed URL. The URLs are valid for only a short
period, <= 15 minutes. Alongside each `external_link` is an expiration field indicating the time at which the URL
is no longer valid. In `EXTERNAL_LINKS` mode, chunks can be resolved and fetched multiple times and in parallel.

----

### **Warning: Databricks strongly recommends that you protect the URLs that are returned by the `EXTERNAL_LINKS` disposition.**

When you use the `EXTERNAL_LINKS` disposition, a
short-lived, signed URL is generated, which can be
used to download the results directly
from Google Cloud Storage. As a
short-lived access credential is
embedded in this signed URL, you should protect
the URL.

Because signed URLs are already generated with
embedded temporary access credentials,
you must not set an `Authorization` header in the download requests.

The `EXTERNAL_LINKS` disposition can be disabled upon request by creating a support
case. See [Support](https://docs.databricks.com/resources/support.html).

See also [Security best practices](https://docs.databricks.com/sql/admin/sql-execution-tutorial.html#security-best-practices).

----

StatementResponse contains `statement_id` and `status`; other fields might be absent or present depending on
context. If the SQL warehouse fails to execute the provided statement, a 200 response is returned with
`status.state` set to `FAILED` (in contrast to a failure when accepting the request, which results in a non-200
response). Details of the error can be found at `status.error` in case of execution failures.

## Request body

- `statement` (string, optional)
  The SQL statement to execute. The statement can optionally be parameterized, see `parameters`.
   The maximum query text size is 16 MiB.
  Example: `SELECT * FROM range(10)`
- `warehouse_id` (string, optional)
  Warehouse upon which to execute a statement. See also
   [What are SQL warehouses?](https://docs.databricks.com/sql/admin/warehouse-type.html)
- `catalog` (string, optional)
  Sets default catalog for statement execution, similar to
   [`USE CATALOG`](https://docs.databricks.com/sql/language-manual/sql-ref-syntax-ddl-use-catalog.html)
   in SQL.
- `schema` (string, optional)
  Sets default schema for statement execution, similar to
   [`USE SCHEMA`](https://docs.databricks.com/sql/language-manual/sql-ref-syntax-ddl-use-schema.html)
   in SQL.
- `row_limit` (int64, optional)
  Applies the given row limit to the statement's result set, but unlike the `LIMIT` clause in SQL,
    it also sets the `truncated` field in the response to indicate whether the result was trimmed due to the limit or
    not.
- `byte_limit` (int64, optional)
  Applies the given byte limit to the statement's result size. Byte counts are based on internal data
    representations and might not match the final size in the requested `format`. If the result was truncated due to
    the byte limit, then `truncated` in the response is set to `true`.
    When using `EXTERNAL_LINKS` disposition, a default `byte_limit` of 100 GiB is applied if `byte_limit` is not
    explicitly set.
- `format` (string, optional)
  Statement execution supports three result formats: `JSON_ARRAY` (default), `ARROW_STREAM`, and `CSV`.
  
   Important: The formats `ARROW_STREAM` and `CSV` are supported only with `EXTERNAL_LINKS` disposition.
   `JSON_ARRAY` is supported in `INLINE` and `EXTERNAL_LINKS` disposition.
  
   When specifying `format=JSON_ARRAY`, result data will be formatted as an array of arrays of values, where each
   value is either the *string representation* of a value, or `null`.
   For example, the output of `SELECT concat('id-', id) AS strCol, id AS intCol, null AS nullCol FROM range(3)` would
   look like this:
  
   ```
    [
    [ "id-1", "1", null ],
    [ "id-2", "2", null ],
    [ "id-3", "3", null ],
    ]
   ```
  
   When specifying `format=JSON_ARRAY` and `disposition=EXTERNAL_LINKS`, each chunk in the result contains compact
   JSON with no indentation or extra whitespace.
  
   When specifying `format=ARROW_STREAM` and `disposition=EXTERNAL_LINKS`, each chunk in the result will be formatted
   as Apache Arrow Stream. See the
   [Apache Arrow streaming format](https://arrow.apache.org/docs/format/Columnar.html#ipc-streaming-format).
  
   When specifying `format=CSV` and `disposition=EXTERNAL_LINKS`, each chunk in the result will be a CSV according to
   [RFC 4180](https://www.rfc-editor.org/rfc/rfc4180) standard.
   All the columns values will have *string representation* similar to the `JSON_ARRAY` format, and `null` values will
   be encoded as “null”.
   Only the first chunk in the result would contain a header row with column names.
   For example, the output of `SELECT concat('id-', id) AS strCol, id AS intCol, null as nullCol FROM range(3)` would
   look like this:
  
   ```
   strCol,intCol,nullCol
   id-1,1,null
   id-2,2,null
   id-3,3,null
   ```
  Possible values: `FORMAT_UNSPECIFIED`, `JSON_ARRAY`, `ARROW_STREAM`, `CSV`
  Default: `JSON_ARRAY`
- `disposition` (string, optional)
  The fetch disposition provides two modes of fetching results: `INLINE` and `EXTERNAL_LINKS`.
  
    Statements executed with `INLINE` disposition will return result data inline, in `JSON_ARRAY` format, in a series
    of chunks. If a given statement produces a result set with a size larger than 25 MiB,
    that statement execution is aborted, and no result set will be available.
  
    **NOTE**
    Byte limits are computed based upon internal representations of the result set data, and might not match the sizes
    visible in JSON responses.
  
    Statements executed with `EXTERNAL_LINKS` disposition will return result data as external links: URLs that point
    to cloud storage internal to the workspace. Using `EXTERNAL_LINKS` disposition allows statements to generate
    arbitrarily sized result sets for fetching up to 100 GiB. The resulting links have two important properties:
  
    1. They point to resources _external_ to the <Databricks> compute; therefore any associated authentication
       information (typically a personal access token, OAuth token, or similar) _must be removed_ when fetching from
       these links.
  
    2. These are  URLs
       with a specific expiration, indicated in the response. The behavior when attempting to use an expired link is
       cloud specific.
  **AWS:** The fetch disposition provides two modes of fetching results: `INLINE` and `EXTERNAL_LINKS`.
  
  Statements executed with `INLINE` disposition will return result data inline, in `JSON_ARRAY` format, in a series
  of chunks. If a given statement produces a result set with a size larger than 25 MiB,
  that statement execution is aborted, and no result set will be available.
  
  **NOTE**
  Byte limits are computed based upon internal representations of the result set data, and might not match the sizes
  visible in JSON responses.
  
  Statements executed with `EXTERNAL_LINKS` disposition will return result data as external links: URLs that point
  to cloud storage internal to the workspace. Using `EXTERNAL_LINKS` disposition allows statements to generate
  arbitrarily sized result sets for fetching up to 100 GiB. The resulting links have two important properties:
  
  1. They point to resources _external_ to the <Databricks> compute; therefore any associated authentication
  information (typically a personal access token, OAuth token, or similar) _must be removed_ when fetching from
  these links.
  
  2. These are presigned URLs
  with a specific expiration, indicated in the response. The behavior when attempting to use an expired link is
  cloud specific.
  **Azure:** The fetch disposition provides two modes of fetching results: `INLINE` and `EXTERNAL_LINKS`.
  
  Statements executed with `INLINE` disposition will return result data inline, in `JSON_ARRAY` format, in a series
  of chunks. If a given statement produces a result set with a size larger than 25 MiB,
  that statement execution is aborted, and no result set will be available.
  
  **NOTE**
  Byte limits are computed based upon internal representations of the result set data, and might not match the sizes
  visible in JSON responses.
  
  Statements executed with `EXTERNAL_LINKS` disposition will return result data as external links: URLs that point
  to cloud storage internal to the workspace. Using `EXTERNAL_LINKS` disposition allows statements to generate
  arbitrarily sized result sets for fetching up to 100 GiB. The resulting links have two important properties:
  
  1. They point to resources _external_ to the <Databricks> compute; therefore any associated authentication
  information (typically a personal access token, OAuth token, or similar) _must be removed_ when fetching from
  these links.
  
  2. These are SAS URLs
  with a specific expiration, indicated in the response. The behavior when attempting to use an expired link is
  cloud specific.
  **GCP:** The fetch disposition provides two modes of fetching results: `INLINE` and `EXTERNAL_LINKS`.
  
  Statements executed with `INLINE` disposition will return result data inline, in `JSON_ARRAY` format, in a series
  of chunks. If a given statement produces a result set with a size larger than 25 MiB,
  that statement execution is aborted, and no result set will be available.
  
  **NOTE**
  Byte limits are computed based upon internal representations of the result set data, and might not match the sizes
  visible in JSON responses.
  
  Statements executed with `EXTERNAL_LINKS` disposition will return result data as external links: URLs that point
  to cloud storage internal to the workspace. Using `EXTERNAL_LINKS` disposition allows statements to generate
  arbitrarily sized result sets for fetching up to 100 GiB. The resulting links have two important properties:
  
  1. They point to resources _external_ to the <Databricks> compute; therefore any associated authentication
  information (typically a personal access token, OAuth token, or similar) _must be removed_ when fetching from
  these links.
  
  2. These are signed URLs
  with a specific expiration, indicated in the response. The behavior when attempting to use an expired link is
  cloud specific.
  Possible values: `FETCH_DISPOSITION_UNSPECIFIED`, `INLINE`, `EXTERNAL_LINKS`
  Default: `INLINE`
- `wait_timeout` (string, optional)
  The time in seconds the call 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.
  
   When set to `0s`, the statement will execute in asynchronous mode and the call will not wait for the execution to
   finish. In this case, the call returns directly with `PENDING` state and a statement ID which can be used for
   polling with :method:statementexecution/getStatement.
  
   When set between 5 and 50 seconds, the call will behave synchronously up to this timeout and wait for the statement
   execution to finish. If the execution finishes within this time, the call returns immediately with a manifest and
   result data (or a `FAILED` state in case of an execution error). If the statement takes longer to execute,
   `on_wait_timeout` determines what should happen after the timeout is reached.
  Default: `10s`
- `on_wait_timeout` (string, optional)
  When `wait_timeout > 0s`, the call will block up to the specified time. If the statement execution doesn't
   finish within this time, `on_wait_timeout` determines whether the execution should continue or be canceled.
   When set to `CONTINUE`, the statement execution continues asynchronously and the call returns a statement ID
   which can be used for polling with :method:statementexecution/getStatement. When set to `CANCEL`,
   the statement execution is canceled and the call returns with a `CANCELED` state.
  Possible values: `TIMEOUT_ACTION_UNSPECIFIED`, `CONTINUE`, `CANCEL`
  Default: `CONTINUE`
- `parameters` (array of object, optional)
  A list of parameters to pass into a SQL statement containing parameter markers. A
   parameter consists of a name, a value, and optionally a type. To represent a NULL
   value, the `value` field may be omitted or set to `null` explicitly. If the `type` field
   is omitted, the value is interpreted as a string.
  
   If the type is given, parameters will be checked for type correctness according
   to the given type. A value is correct if the provided string can be converted to
   the requested type using the `cast` function. The exact semantics are described in
   the section [`cast` function](https://docs.databricks.com/sql/language-manual/functions/cast.html) of the SQL language reference.
  
   For example, the following statement contains two parameters, `my_name` and `my_date`:
  
   ```
       SELECT * FROM my_table WHERE name = :my_name AND date = :my_date
   ```
  
   The parameters can be passed in the request body as follows:
  
   `
       {
         ...,
         "statement": "SELECT * FROM my_table WHERE name = :my_name AND date = :my_date",
         "parameters": [
           { "name": "my_name", "value": "the name" },
           { "name": "my_date", "value": "2020-01-01", "type": "DATE" }
         ]
       }
   `
  
   Currently, positional parameters denoted by a `?` marker are not supported by the
   Databricks SQL Statement Execution API.
  
   Also see the section [Parameter markers](https://docs.databricks.com/sql/language-manual/sql-ref-parameter-marker.html) of the SQL language reference.
  - `name` (string, optional)
    The name of a parameter marker to be substituted in the statement.
  - `value` (string, optional)
    The value to substitute, represented as a string. If omitted, the value is interpreted as NULL.
  - `type` (string, optional)
    The data type, given as a string. For example: `INT`, `STRING`, `DECIMAL(10,2)`.
     If no type is given the type is assumed to be `STRING`. Complex types, such as
     `ARRAY`, `MAP`, and `STRUCT` are not supported. For valid types, refer to the
     section [Data types](https://docs.databricks.com/sql/language-manual/functions/cast.html) of the SQL language reference.
- `query_tags` (array of object, optional, Public Preview)
  An array of query tags to annotate a SQL statement. A query tag
   	consists of a non-empty key and, optionally, a value. To represent a NULL
   	value, either omit the `value` field or manually set it to `null` or white space.
   	Refer to the SQL language reference for the format specification of query tags.
   	There's no significance to the order of tags. Only one value per key will be recorded.
    A sequence in excess of 20 query tags will be coerced to 20.
    Example:
  
       {
         ...,
         "query_tags": [
           { "key": "team", "value": "eng" },
           { "key": "some key only tag" }
         ]
       }
  - `key` (string, optional, Public Preview)
  - `value` (string, optional, Public Preview)

## Returns

- `statement_id` (string, optional)
  The statement ID is returned upon successfully submitting a SQL statement, and is a required
   reference for all subsequent calls.
- `status` (object, optional)
  - `state` (string, optional)
    Statement execution state:
     - `PENDING`: waiting for warehouse
     - `RUNNING`: running
     - `SUCCEEDED`: execution was successful, result data available for fetch
     - `FAILED`: execution failed; reason for failure described in accompanying error message
     - `CANCELED`: user canceled; can come from explicit cancel call, or timeout with
     `on_wait_timeout=CANCEL`
     - `CLOSED`: execution successful, and statement closed; result no longer available for fetch
    Possible values: `STATE_UNSPECIFIED`, `PENDING`, `RUNNING`, `SUCCEEDED`, `FAILED`, `CANCELED`, `CLOSED`
  - `error` (object, optional)
    - `error_code` (string, optional)
      Possible values: `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`
    - `message` (string, optional)
      A brief summary of the error condition.
  - `sql_state` (string, optional)
    SQLSTATE error code returned when the statement execution fails.
     Only populated when the statement status is `FAILED`.
- `manifest` (object, optional)
  - `format` (string, optional)
    Possible values: `FORMAT_UNSPECIFIED`, `JSON_ARRAY`, `ARROW_STREAM`, `CSV`
  - `schema` (object, optional)
    - `column_count` (int32, optional)
    - `columns` (array of object, optional)
      - `name` (string, optional)
        The name of the column.
      - `type_text` (string, optional)
        The full SQL type specification.
      - `type_name` (string, optional)
        The name of the base data type. This doesn't include details for complex types such as STRUCT, MAP or ARRAY.
        Possible values: `BOOLEAN`, `BYTE`, `SHORT`, `INT`, `LONG`, `FLOAT`, `DOUBLE`, `DATE`, `TIMESTAMP`, `STRING`, `BINARY`, `DECIMAL`, `INTERVAL`, `ARRAY`, `STRUCT`, `MAP`, `CHAR`, `NULL`, `USER_DEFINED_TYPE`
      - `position` (int32, optional)
        The ordinal position of the column (starting at position 0).
      - `type_precision` (int32, optional)
        Specifies the number of digits in a number. This applies to the DECIMAL type.
      - `type_scale` (int32, optional)
        Specifies the number of digits to the right of the decimal point in a number. This applies to the DECIMAL type.
      - `type_interval_type` (string, optional)
        The format of the interval type.
  - `total_chunk_count` (int32, optional)
    The total number of chunks that the result set has been divided into.
  - `chunks` (array of object, optional)
    Array of result set chunk metadata.
    - `chunk_index` (int32, optional)
      The position within the sequence of result set chunks.
    - `row_offset` (int64, optional)
      The starting row offset within the result set.
    - `row_count` (int64, optional)
      The number of rows within the result chunk.
    - `byte_count` (int64, optional)
      The number of bytes in the result chunk. This field is not available when using `INLINE`
       disposition.
    - `next_chunk_index` (int32, optional)
      When fetching, provides the `chunk_index` for the _next_ chunk. If absent, indicates there are no
       more chunks. The next chunk can be fetched with a
       :method:statementexecution/getstatementresultchunkn request.
    - `next_chunk_internal_link` (string, optional)
      When fetching, provides a link to fetch the _next_ chunk. If absent, indicates there are no more
       chunks. This link is an absolute `path` to be joined with your `$DATABRICKS_HOST`, and should be
       treated as an opaque link. This is an alternative to using `next_chunk_index`.
  - `total_row_count` (int64, optional)
    The total number of rows in the result set.
  - `total_byte_count` (int64, optional)
    The total number of bytes in the result set. This field is not available when using `INLINE`
     disposition.
  - `truncated` (boolean, optional)
    Indicates whether the result is truncated due to `row_limit` or `byte_limit`.
- `result` (object, optional)
  - `external_links` (array of object, optional)
    - `external_link` (string, optional)
      A  URL pointing to a
       chunk of result data, hosted by an external service, with a short expiration time
       (<= 15 minutes). As this URL contains a temporary credential, it should be considered sensitive
       and the client should not expose this URL in a log.
      **AWS:** A presigned URL pointing to a
      chunk of result data, hosted by an external service, with a short expiration time
      (<= 15 minutes). As this URL contains a temporary credential, it should be considered sensitive
      and the client should not expose this URL in a log.
      **Azure:** A SAS URL pointing to a
      chunk of result data, hosted by an external service, with a short expiration time
      (<= 15 minutes). As this URL contains a temporary credential, it should be considered sensitive
      and the client should not expose this URL in a log.
      **GCP:** A signed URL pointing to a
      chunk of result data, hosted by an external service, with a short expiration time
      (<= 15 minutes). As this URL contains a temporary credential, it should be considered sensitive
      and the client should not expose this URL in a log.
    - `expiration` (string, optional)
      Indicates the date-time that the given external link will expire and
       becomes invalid, after which point a new `external_link` must be requested.
    - `chunk_index` (int32, optional)
      The position within the sequence of result set chunks.
    - `row_offset` (int64, optional)
      The starting row offset within the result set.
    - `row_count` (int64, optional)
      The number of rows within the result chunk.
    - `byte_count` (int64, optional)
      The number of bytes in the result chunk. This field is not available when using `INLINE`
       disposition.
    - `next_chunk_index` (int32, optional)
      When fetching, provides the `chunk_index` for the _next_ chunk. If absent, indicates there are no
       more chunks. The next chunk can be fetched with a
       :method:statementexecution/getstatementresultchunkn request.
    - `next_chunk_internal_link` (string, optional)
      When fetching, provides a link to fetch the _next_ chunk. If absent, indicates there are no more
       chunks. This link is an absolute `path` to be joined with your `$DATABRICKS_HOST`, and should be
       treated as an opaque link. This is an alternative to using `next_chunk_index`.
  - `data_array` (array of array of object, optional)
    The `JSON_ARRAY` format is an array of arrays of values, where each non-null value is
     formatted as a string. Null values are encoded as JSON `null`.
  - `chunk_index` (int32, optional)
    The position within the sequence of result set chunks.
  - `row_offset` (int64, optional)
    The starting row offset within the result set.
  - `row_count` (int64, optional)
    The number of rows within the result chunk.
  - `byte_count` (int64, optional)
    The number of bytes in the result chunk. This field is not available when using `INLINE`
     disposition.
  - `next_chunk_index` (int32, optional)
    When fetching, provides the `chunk_index` for the _next_ chunk. If absent, indicates there are no
     more chunks. The next chunk can be fetched with a
     :method:statementexecution/getstatementresultchunkn request.
  - `next_chunk_internal_link` (string, optional)
    When fetching, provides a link to fetch the _next_ chunk. If absent, indicates there are no more
     chunks. This link is an absolute `path` to be joined with your `$DATABRICKS_HOST`, and should be
     treated as an opaque link. This is an alternative to using `next_chunk_index`.

## Request

### Asynchronous execution

```json
{
  "statement": "SELECT * FROM range(100)",
  "wait_timeout": "0s",
  "warehouse_id": "abcdef0123456789"
}
```

### Default (wait up to 10s, fallback to async)

```json
{
  "statement": "SELECT * FROM range(3)",
  "warehouse_id": "abcdef0123456789"
}
```

### EXTERNAL_LINKS with ARROW_STREAM

```json
{
  "disposition": "EXTERNAL_LINKS",
  "format": "ARROW_STREAM",
  "statement": "SELECT * FROM range(100)",
  "warehouse_id": "abcdef0123456789"
}
```

### EXTERNAL_LINKS with CSV

```json
{
  "disposition": "EXTERNAL_LINKS",
  "format": "CSV",
  "statement": "SELECT * FROM range(100)",
  "warehouse_id": "abcdef0123456789"
}
```

### EXTERNAL_LINKS with JSON_ARRAY

```json
{
  "disposition": "EXTERNAL_LINKS",
  "format": "JSON_ARRAY",
  "statement": "SELECT * FROM range(100)",
  "warehouse_id": "abcdef0123456789"
}
```

### Named parameters

```json
{
  "parameters": [
    {
      "name": "my_id",
      "type": "BIGINT",
      "value": "2"
    }
  ],
  "statement": "SELECT id FROM range(10) WHERE id = :my_id",
  "warehouse_id": "abcdef0123456789"
}
```

### Synchronous execution

```json
{
  "on_wait_timeout": "CANCEL",
  "statement": "SELECT * FROM range(100)",
  "wait_timeout": "30s",
  "warehouse_id": "abcdef0123456789"
}
```

### Wait up to 30s, fallback to async

```json
{
  "on_wait_timeout": "CONTINUE",
  "statement": "SELECT * FROM range(100)",
  "wait_timeout": "30s",
  "warehouse_id": "abcdef0123456789"
}
```

## Response

### Statement failed with syntax errror

```json
{
  "statement_id": "01ee48eb-5124-1922-bb90-f98c82f024fe",
  "status": {
    "error": {
      "error_code": "BAD_REQUEST",
      "message": "[PARSE_SYNTAX_ERROR] Syntax error at or near ..."
    },
    "state": "FAILED"
  }
}
```

### Statement running

```json
{
  "statement_id": "01ed9db9-24c4-1cb6-a320-fb6ebbe7410d",
  "status": {
    "state": "RUNNING"
  }
}
```

### Statement succeeded with EXTERNAL_LINKS and CSV

```json
{
  "manifest": {
    "chunks": [
      {
        "chunk_index": 0,
        "row_count": 100,
        "row_offset": 0
      }
    ],
    "format": "CSV",
    "schema": {
      "column_count": 1,
      "columns": [
        {
          "name": "id",
          "position": 0,
          "type_name": "LONG",
          "type_text": "BIGINT"
        }
      ]
    },
    "total_byte_count": 293,
    "total_chunk_count": 1,
    "total_row_count": 100
  },
  "result": {
    "external_links": [
      {
        "byte_count": 293,
        "chunk_index": 0,
        "expiration": "2023-01-30T22:23:23.140Z",
        "external_link": "https://someplace.cloud-provider.com/very/long/path/...",
        "row_count": 100,
        "row_offset": 0
      }
    ]
  },
  "statement_id": "01eda0ea-9b4b-15ce-b8bb-a7d4114cb5ed",
  "status": {
    "state": "SUCCEEDED"
  }
}
```

### Statement succeeeded with INLINE data

```json
{
  "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"
  }
}
```