---
title: "Execute SQL Statement"
method: POST
path: "/query/v1alpha1"
tags: ["Statements (query/v1alpha1)"]
---

# Execute SQL Statement

`POST /query/v1alpha1`

Executes an arbitrary SQL query against the engine. If the query resolves in under 30 seconds and returns less than 25 MiB, the response will be an inline HTTP 200 OK.  Otherwise, a 202 Accepted response redirects the client to retrieve  results from a separate streamed data location. Rows are returned as JSON strings by default; set `options.result_format` to `ARROW_STREAM` to receive a base64-encoded Arrow IPC stream with native column types instead.

## Request body

- QueryV1alpha1QueryRequest — Request parameters for query analysis and extraction.
  - `catalog_name` string, required — Confluent Cloud environment ID (e.g., env-xyz123)
  - `database_name` string, required — Kafka cluster ID (e.g., lkc-xyz123)
  - `options` QueryV1alpha1QueryOptions — Settings that tune how this query is handled. Omitted fields fall back to service defaults.
    - `max_result_rows` integer — Maximum rows to return up to configured limit.
    - `result_format` string — Encoding for the returned rows, echoed back as `result.result_format`. `JSON` returns `result.data` as an array of rows, requiring clients to coerce values using `result.schema`. `ARROW_STREAM` returns `result.data` as a base64-encoded Arrow IPC stream, preserving native column types. Inline `ARROW_STREAM` payloads are size-capped; larger results are delivered through the asynchronous 202 flow.
  - `query` string, required — SQL query to execute
  - `client_info` object — Free-form client metadata for telemetry and debugging (e.g., client_name, client_version, driver_version). Values are strings; not interpreted by the server.

## Response `200`

Successful synchronous response containing fully inlined metadata and data results.

- QueryV1alpha1QueryResponseInline — Response structure returned directly for fast inline extractions.
  - `api_version` string, required — APIVersion defines the schema version of this representation of a resource.
  - `kind` string, required — Kind defines the object this REST resource represents.
  - `result` QueryV1alpha1QueryResult, required — Query result containing schema metadata and row data. This envelope is the same for every statement kind. `SHOW` and `DESCRIBE` return declared column types in `schema` and string-encoded values in `data` exactly as `SELECT` does, so a client needs only one result reader and never has to branch on the statement it sent.
    - `result_format` string, required — Encoding of `data`, echoing the `options.result_format` requested on the statement.
    - `schema` QueryV1alpha1ResultSchema, required — The table columns of the result schema.
      - `columns` QueryV1alpha1ColumnDetails[], required — Column definitions in result order, matching the order of values within each row.
        - `name` string, required — The name of the SQL result column.
        - `type` QueryV1alpha1DataType, required — Flink logical type descriptor, mirroring `DataType` in the Flink Gateway API. Complex types nest recursively: `elementType`, `keyType`, `valueType` and `fields[].fieldType` are themselves `DataType` objects, so `ROW`, `ARRAY`, `MAP` and `MULTISET` nest to arbitrary depth. The value of `type` determines which parameter properties are present; all others are absent. | `type` | Parameters | | --- | --- | | `BOOLEAN`, `TINYINT`, `SMALLINT`, `INTEGER`, `BIGINT`, `FLOAT`, `DOUBLE`, `DATE`, `NULL` | none | | `CHAR`, `VARCHAR`, `BINARY`, `VARBINARY` | `length` | | `DECIMAL` | `precision`, `scale` | | `TIME_WITHOUT_TIME_ZONE`, `TIMESTAMP_WITHOUT_TIME_ZONE`, `TIMESTAMP_WITH_TIME_ZONE` | `precision` | | `INTERVAL_YEAR_MONTH` | `precision`, `resolution` | | `INTERVAL_DAY_TIME` | `precision`, `fractionalPrecision`, `resolution` | | `ARRAY`, `MULTISET` | `elementType` | | `MAP` | `keyType`, `valueType` | | `ROW` | `fields` |
          - `type` string, required — The Flink logical type name of the column or field.
          - `nullable` boolean, required — Whether values of this column or field can be null.
          - `length` integer — Declared length of `CHAR`, `VARCHAR`, `BINARY` and `VARBINARY`. Unbounded `VARCHAR` and `VARBINARY` report 2147483647.
          - `precision` integer — Declared precision of `DECIMAL`, the `TIME`/`TIMESTAMP` types and the `INTERVAL_*` types.
          - `scale` integer — Declared scale of `DECIMAL`.
          - `keyType` QueryV1alpha1DataType — recursive
          - `valueType` QueryV1alpha1DataType — recursive
          - `elementType` QueryV1alpha1DataType — recursive
          - `fields` QueryV1alpha1RowFieldType[] — Fields of a `ROW`, in declaration order.
            - `name` string, required — The name of the field.
            - `fieldType` QueryV1alpha1DataType, required — recursive
            - `description` string — Optional field comment from the type declaration.
          - `resolution` string — Interval resolution, for example `YEAR_TO_MONTH` for `INTERVAL_YEAR_MONTH` or `DAY_TO_SECOND` for `INTERVAL_DAY_TIME`.
          - `fractionalPrecision` integer — Fractional-second precision of `INTERVAL_DAY_TIME`.
          - `class_name` string — Class name of a structured type. Present in the Flink type model; the engine does not currently emit structured types.
    - `data` union, required — Result rows in the encoding named by `result_format`: an array of rows for `JSON`, where each row is a positional array of column values ordered to match `schema.columns`; or a base64-encoded Arrow IPC stream for `ARROW_STREAM`, carrying native column types rather than stringified values. Inline Arrow payloads are size-capped by the service; larger results are delivered through the asynchronous 202 flow. Under `JSON`, individual values — including those of complex `ROW`, `ARRAY`, `MAP` and `MULTISET` columns — are encoded as described by `ResultValue`.
      - QueryV1alpha1ResultRow[]
        - QueryV1alpha1ResultValue[] — A single result row — column values ordered to match `schema.columns`. Rows carry no changelog operation marker: this API returns a point-in-time snapshot rather than a changelog stream, so there are no retractions to express.
          - union — One value within a `JSON` result row. Scalar values are JSON strings encoded according to the declaring column's `DataType.type`. JSON `null` is SQL NULL, at any depth. Complex values are JSON arrays whose elements are themselves `ResultValue`s: - `ROW` — a positional array with one element per entry of the type's `fields`, in the same order. Field names are never repeated inline; recovering them requires the schema. - `ARRAY` — one element per collection element, in order. - `MAP` and `MULTISET` — an array of two-element `[key, value]` arrays. A complex value that is itself SQL NULL is JSON `null`, which is distinct from an array whose elements are null. Canonical scalar encodings: | `DataType.type` | Encoding | | --- | --- | | `NULL` | JSON `null` | | `BOOLEAN` | `"TRUE"` or `"FALSE"`, upper case | | `TINYINT`, `SMALLINT`, `INTEGER`, `BIGINT` | base-10 integer string, optional leading `-` | | `FLOAT`, `DOUBLE` | shortest round-trip decimal string, in exponent notation where Java would use it | | `DECIMAL` | plain decimal string with exactly `scale` fractional digits, no exponent | | `CHAR`, `VARCHAR` | the string value verbatim, UTF-8 | | `BINARY`, `VARBINARY` | hexadecimal literal, for example `"x'7f0203'"` | | `DATE` | `YYYY-MM-DD` | | `TIME_WITHOUT_TIME_ZONE` | `HH:MM:SS[.fff]` | | `TIMESTAMP_WITHOUT_TIME_ZONE` | `YYYY-MM-DD HH:MM:SS[.fff]`, space separated | | `TIMESTAMP_WITH_TIME_ZONE` | `YYYY-MM-DD HH:MM:SS[.fff]`, rendered in UTC. Flink's `TIMESTAMP_LTZ` is reported under this name; the instant is stored as UTC and the zone is metadata only, so no offset is emitted | | `INTERVAL_YEAR_MONTH` | `+YYYY-MM` | | `INTERVAL_DAY_TIME` | `+D HH:MM:SS.fff` | These render SQL values, not API datetime or numeric fields — each format follows the column's declared SQL type and matches Confluent Flink's documented value encodings, so one decoder serves both surfaces. `TIMESTAMP` therefore uses a space separator rather than RFC 3339's `T`. These encodings apply only when `result_format` is `JSON`. Under `ARROW_STREAM` values are carried natively, with `ROW` mapping to an Arrow struct, `ARRAY` and `MULTISET` to a list, and `MAP` to a map.
            - string, nullable
            - QueryV1alpha1ResultValue[], nullable
      - string, byte

## Other responses

- `202` — Asynchronous request registration. Returned when data sets exceed 25 MiB or execution times cross the 30s processing barrier.
- `400` — Bad Request
- `401` — The request lacks valid authentication credentials for this resource.
- `403` — The access credentials were considered insufficient to grant access
- `404` — Not Found
- `429` — Rate Limit Exceeded
- `500` — Oops, something went wrong!

---

[API](https://skmtc.dev/confluent/apis/confluent-cloud-apis.md) · [All operations](https://skmtc.dev/confluent/apis/confluent-cloud-apis/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/confluent/confluent-cloud-apis/revisions/a6a73f98a698/schema)