Execute compose SQL query
Executes a DuckDB SQL query asynchronously on the pre-aggregate DuckDB engine. Requires run-queries access (interactive viewer and up) and the compose-sql-runner feature flag. The references map exposes other async queries' results as named tables the SQL can select from ({"orders": "queryUuid"} lets the SQL run SELECT * FROM orders); each referenced query is authorized with the same access checks as Get results, so you can reference any query you can already fetch by uuid. References to queries that are still running are waited on — this query executes once every referenced result is ready and fails if a referenced query fails. Direct file access in the SQL is rejected. Returns a queryUuid to poll for results via Get results.
Executes a DuckDB SQL query asynchronously on the pre-aggregate DuckDB engine. Requires run-queries access (interactive viewer and up) and the compose-sql-runner feature flag. The references map exposes other async queries' results as named tables the SQL can select from ({"orders": "queryUuid"} lets the SQL run SELECT * FROM orders); each referenced query is authorized with the same access checks as Get results, so you can reference any query you can already fetch by uuid. References to queries that are still running are waited on — this query executes once every referenced result is ready and fails if a referenced query fails. Direct file access in the SQL is rejected. Returns a queryUuid to poll for results via Get results.
Authentication: personal access token. The spec defines an api_key security
scheme — send an Authorization: ApiKey <your-personal-access-token> header
(value format: ApiKey <your key>). A session_cookie scheme (connect.sid)
exists for browser sessions. Operations in this spec declare security: [], an
artifact of the upstream spec generator — authentication is still enforced by the
server.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
projectUuid | string | Yes |
Request body
{
"parameters": {
"property": "string"
},
"usePreAggregateCache": true,
"invalidateCache": true,
"context": "dashboardView",
"references": {
"property": "string"
},
"limit": 0,
"sql": "string"
}Responses
200 — Success
{
"results": {
"resolvedTimezone": "string",
"usedParametersValues": {
"property": "string"
},
"parameterReferences": [
"string"
],
"cacheMetadata": {
"preAggregate": {
"reason": {
"reason": "no_pre_aggregates_defined"
},
"name": "string",
"hit": true
},
"cacheHit": true,
"cacheKey": "string",
"cacheExpiresAt": "2024-01-01T00:00:00.000Z",
"cacheUpdatedTime": "2024-01-01T00:00:00.000Z"
},
"queryUuid": "string"
},
"status": "ok"
}default — Error
{
"error": {
"data": "string",
"message": "string",
"name": "string",
"statusCode": 0
},
"status": "error"
}