Execute source queries
Submits one or more source queries through the common interface. Every query body is tagged by sourceType and every query returns a queryUuid, polled with the standard async query results endpoint (or Get source query status for many at once). Queries reference each other's results by nodeId: a duckdb query's references expose other queries' results as tables, named by node id (array shorthand) or by alias (map form, which also accepts queryUuids of results from previous submissions). A referenced result keeps the column names of the query that produced it — field ids for semanticLayer queries, SELECT output names for sql queries. All queries are submitted immediately; a query referencing still-running results waits inside its own execution and fails if a referenced query fails, so no orchestration happens outside the queries themselves. Submit queries one at a time (interactive use) or as a whole pipeline in one call — the two are equivalent, so a serialized multi-query analysis is just the bodies of the queries that were run interactively, with queryUuid references swapped for node ids. Note that results expire: re-run upstream queries whose results have expired instead of referencing their old queryUuids.
Submits one or more source queries through the common interface. Every query body is tagged by sourceType and every query returns a queryUuid, polled with the standard async query results endpoint (or Get source query status for many at once).
Queries reference each other's results by nodeId: a duckdb query's references expose other queries' results as tables, named by node id (array shorthand) or by alias (map form, which also accepts queryUuids of results from previous submissions). A referenced result keeps the column names of the query that produced it — field ids for semanticLayer queries, SELECT output names for sql queries.
All queries are submitted immediately; a query referencing still-running results waits inside its own execution and fails if a referenced query fails, so no orchestration happens outside the queries themselves. Submit queries one at a time (interactive use) or as a whole pipeline in one call — the two are equivalent, so a serialized multi-query analysis is just the bodies of the queries that were run interactively, with queryUuid references swapped for node ids. Note that results expire: re-run upstream queries whose results have expired instead of referencing their old queryUuids.
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
{
"invalidateCache": true,
"parameters": {
"property": "string"
},
"context": "dashboardView",
"queries": [
{
"pivotConfiguration": {
"pivotColumnsOrder": [
{
"reference": "string"
}
],
"passthroughDimensions": [
{
"reference": "string"
}
],
"sortOnlyDimensions": [
{
"reference": "string"
}
],
"sortOnlyColumns": [
{
"aggregation": "sum",
"reference": "string"
}
],
"metricsAsRows": true,
"sortBy": [
{
"pivotValues": [
{
"value": "string",
"reference": "string"
}
],
"nullsFirst": true,
"direction": "ASC",
"reference": "string"
}
],
"groupByColumns": [
{
"reference": "string"
}
],
"valuesColumns": [
{
"aggregation": "sum",
"reference": "string"
}
],
"indexColumn": {
"type": "time",
"reference": "string"
}
},
"timezone": "string",
"customDimensions": [
{
"id": "string",
"name": "string",
"table": "string",
"type": "bin",
"dimensionId": "string",
"binType": "fixed_number",
"binNumber": 0
}
],
"additionalMetrics": [
{
"label": "string",
"type": "percentile",
"description": "string",
"sql": "string",
"hidden": true,
"round": 0,
"compact": "auto",
"format": "km",
"separator": "default",
"table": "string",
"name": "string",
"index": 0,
"filters": [
{
"includeNull": true,
"values": [
"string"
],
"operator": "isNull",
"id": "string",
"target": {
"fieldRef": "string"
},
"settings": "string",
"disabled": true,
"required": true,
"caseSensitive": true
}
],
"baseDimensionName": "string",
"baseMetricName": "string",
"uuid": "string",
"percentile": 0,
"distinctKeys": [
"string"
],
"formatOptions": {
"type": "default",
"round": 0,
"separator": "default",
"currency": "string",
"compact": "auto",
"prefix": "string",
"suffix": "string",
"timeInterval": "RAW",
"custom": "string"
},
"generationType": "periodOverPeriod",
"baseMetricId": "string",
"timeDimensionId": "string",
"granularity": "RAW",
"periodOffset": 0
}
],
"tableCalculations": [
{
"totalMode": "formula",
"type": "number",
"format": {
"type": "default",
"round": 0,
"separator": "default",
"currency": "string",
"compact": "auto",
"prefix": "string",
"suffix": "string",
"timeInterval": "RAW",
"custom": "string"
},
"displayName": "string",
"name": "string",
"index": 0,
"sql": "string"
}
],
"limit": 0,
"sorts": [
{
"pivotValues": [
{
"value": "string",
"reference": "string"
}
],
"nullsFirst": true,
"descending": true,
"fieldId": "string"
}
],
"filters": {
"tableCalculations": "string",
"metrics": "string",
"dimensions": "string"
},
"metrics": [
"string"
],
"dimensions": [
"string"
],
"exploreName": "string",
"nodeId": "string",
"sourceType": "semanticLayer"
}
]
}Responses
200 — Success
{
"results": {
"queries": [
{
"queryUuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"sourceType": "semanticLayer",
"nodeId": "string"
}
]
},
"status": "ok"
}default — Error
{
"error": {
"data": "string",
"message": "string",
"name": "string",
"statusCode": 0
},
"status": "error"
}Scan query source schema
Scans the schema of one query source into the standard shape: tables with columns of {reference, type}. For the semantic layer, tables are explores and columns are field ids; for warehouse SQL, tables come from the warehouse catalog resolved for your credentials, like the SQL runner; the duckdb source has no schema of its own — its tables are the references given to each query.
Get source query status
Gets the status of many submitted queries at once — the standard async query status lifecycle (pending, running, ready, error, ...) plus the error message for failed queries. Poll this after Execute source queries; fetch each ready query's rows with the standard async query results endpoint. Statuses are visible to the query creator only.