--- title: "Execute SQL Statement" method: POST path: "/query/v1" tags: ["Statements (query/v1)"] --- # Execute SQL Statement `POST /query/v1` ## Request - Base URL: `https://sql...confluent.cloud` - URL: `https://sql...confluent.cloud/query/v1` - Auth: HTTP basic Executes an arbitrary SQL query against the engine. If the query resolves in under 10 seconds and returns less than 4 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 - QueryV1QueryRequest: 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` QueryV1QueryOptions: Settings that tune how this query is handled. Omitted fields fall back to service defaults. - `max_result_rows` integer: Maximum rows to return inline, up to 200. - `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. - QueryV1QueryResponseInline: 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` QueryV1QueryResult, 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` QueryV1ResultSchema, required: The table columns of the result schema. - `columns` QueryV1ColumnDetails[], 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` QueryV1DataType, required: Flink logical type descriptor, mirroring `DataType` in the Flink Gateway API. Complex types nest recursively: `element_type`, `key_type`, `value_type` and `fields[].field_type` 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`, `fractional_precision`, `resolution` | | `ARRAY`, `MULTISET` | `element_type` | | `MAP` | `key_type`, `value_type` | | `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`. - `key_type` QueryV1DataType (recursive) - `value_type` QueryV1DataType (recursive) - `element_type` QueryV1DataType (recursive) - `fields` QueryV1RowFieldType[]: Fields of a `ROW`, in declaration order. - `name` string, required: The name of the field. - `field_type` QueryV1DataType, 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`. - `fractional_precision` 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`. - QueryV1ResultRow[] - QueryV1ResultValue[]: 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 - QueryV1ResultValue[], nullable - string, byte ## Other responses - `202`: Asynchronous request registration. Returned when data sets exceed 4 MiB or execution times cross the 10s processing barrier. Poll the URL in the `Location` header (see `Query Async Job Status`) until the job reaches a terminal state; a successful job's response carries the presigned URL(s) the result can be downloaded from. - `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! ## Changes - **2026-10-24** `f63ccf92fb4a`: 1 info - endpoint added [Operation history](https://skmtc.dev/confluent/apis/confluent-cloud-apis/changes/query/v1/post.md) --- [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.dev/confluent/apis/confluent-cloud-apis/revisions/018ddeaf203e?raw)