Submit SQL Query
Use the POST /api/v3/query endpoint of the Data 360 Query API to execute a SQL query against your Data 360 data. Submit a query in ASYNC mode to receive a queryId for polling, or use ADAPTIVE mode to receive results immediately when the query completes quickly. Both modes support JSON and Apache Arrow response formats.
This API is the recommended interface for new integrations. See Migrate from Query API V1 and V2 for guidance on updating existing code.
- HTTP Method: POST
- Format: REST
- URI:
/api/v3/query
| Header | Value |
|---|---|
Authorization | Bearer {accessToken} |
Content-Type | application/json (default) or application/vnd.apache.arrow.stream |
Accept | application/json (default) or application/vnd.apache.arrow.stream |
| Field | Type | Required | Description |
|---|---|---|---|
sql | string | Yes | SQL query to execute. Uses Data 360 SQL syntax. |
transferMode | string | No | Execution mode. Accepted values: ASYNC, ADAPTIVE (default). |
paramStyle | string | No | Parameter binding style. Accepted values: QUESTION_MARK (default), NAMED, DOLLARED. See Parameterized Queries. |
parameters | array | No | Array of parameter objects for parameterized queries. Each object requires type (string) and value (string). |
settings | object | No | Query settings. Supported keys: timezone (for example, "Etc/UTC"), language (for example, "de_DE"). |
resultRange | object | No | Controls what is returned within the REST response. ADAPTIVE mode only. Supported keys: rowLimit (integer), byteLimit (integer, default and maximum 20 MB). |
queryRowLimit | integer | No | Maximum number of rows to produce by the query. Acts as an implicit LIMIT clause — the query will not produce more rows than this value. Set to 0 to retrieve only the schema without producing any rows. |
The paramStyle request field controls how parameters are bound in your SQL:
QUESTION_MARK(default) — Use?placeholdersNAMED— Use named placeholders (:paramName)DOLLARED— Use positional placeholders ($1,$2, …)
Both ASYNC and ADAPTIVE modes share a common response structure.
Both ASYNC and ADAPTIVE modes return these response headers.
| Header | Description |
|---|---|
Date | Timestamp when the response was generated. |
Content-Type | application/json or application/vnd.apache.arrow.stream depending on the Accept request header. |
status | JSON-serialized string containing the full query status. Fields: queryId, completionStatus, chunkCount, rowCount, progress, expirationTime, and executionStats. Use the queryId from this header to poll for results. |
In ASYNC mode, the response body always has "data": null and "returnedRows": 0. Use the queryId from the status response header to poll GET /api/v3/query/{queryId} for completion.
| Field | Description |
|---|---|
metadata | Object containing column schema |
data | Always null in ASYNC mode |
returnedRows | Always 0 in ASYNC mode |
If the query completes within the adaptive timeout, data contains the result rows. If the query exceeds the adaptive timeout without producing rows, the response mimics ASYNC mode: data is null and returnedRows is 0. Use the queryId from the status response header to poll GET /api/v3/query/{queryId} for completion.
| Field | Description |
|---|---|
metadata | Object containing column schema |
data | Array of result rows (each row is an array), or null if timed out |
returnedRows | Number of rows returned (0 if adaptive timeout reached) |
These examples show ASYNC and ADAPTIVE requests and responses.
Response headers (excerpt):
Response body:
Set Accept: application/vnd.apache.arrow.stream to request a binary Arrow IPC stream instead of JSON. Use an Arrow-compatible client library (such as PyArrow or the Apache Arrow Java library) to read the stream.
In ASYNC mode, the response body always contains only schema metadata with no data rows, regardless of the Accept header. Retrieve the queryId from the status response header and poll GET /api/v3/query/{queryId} for completion, then use GET /api/v3/query/{queryId}/rows or /chunks/{chunkId} with Accept: application/vnd.apache.arrow.stream to retrieve results.
Set Accept: application/vnd.apache.arrow.stream to receive an inline ADAPTIVE result as a binary Arrow IPC stream. If the query exceeds the adaptive timeout and falls back to ASYNC mode, the response body contains only schema metadata with no data rows. Retrieve the queryId from the status response header and poll GET /api/v3/query/{queryId} for completion.
V3 returns structured error objects with HTTP status codes.
| Status | Meaning |
|---|---|
| 400 | Invalid SQL or request payload |
| 401 | Missing or invalid authentication |
| 408 | Request timed out |
| 429 | Rate limit exceeded |
| 500 | Internal server error |
Error responses include a rich error model with SQLSTATE codes and human-readable detail.
The position field is included for syntax errors. errorSource indicates whether the error originated from user input ("User") or the system. See Query Services Status Codes for the full reference.
- Query Data using Query API — Connect REST API (recommended for most integrations)
- Query V1 and V2 API — Legacy API reference
- Query Services Status Codes — Error code reference
- API Limits and Guidelines