Compile merge query
Compile several queries into a single merged warehouse statement. Returns the statement and the fields it produces, without running it. Use it to validate a merge while it is being built: a merge that would produce wrong numbers comes back with `errors` and a null `sql` — most importantly the fan-out case, where a query still carries a dimension that is neither joined on nor pivoted. Run a valid merge with POST {projectUuid}/mergeQuery/run.
Compile several queries into a single merged warehouse statement.
Returns the statement and the fields it produces, without running it.
Use it to validate a merge while it is being built: a merge that would
produce wrong numbers comes back with errors and a null sql — most
importantly the fan-out case, where a query still carries a dimension
that is neither joined on nor pivoted. Run a valid merge with
POST {projectUuid}/mergeQuery/run.
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"
},
"mergeQuery": {
"limit": 0,
"tableCalculations": [
{
"sql": "string",
"displayName": "string",
"name": "string"
}
],
"joinType": "full",
"joinKey": [
{
"fieldIdBySourceId": {
"property": "string"
},
"name": "string"
}
],
"sources": [
{
"metricQuery": {
"metadata": {
"hasADateDimension": {
"name": "string",
"label": "string",
"table": "string"
}
},
"pivotDimensions": [
"string"
],
"timezone": "string",
"dimensionOverrides": {
"property": {
"formatOptions": {
"type": "default",
"round": 0,
"separator": "default",
"currency": "string",
"compact": "auto",
"prefix": "string",
"suffix": "string",
"timeInterval": "RAW",
"custom": "string"
}
}
},
"metricOverrides": {
"property": {
"formatOptions": {
"type": "default",
"round": 0,
"separator": "default",
"currency": "string",
"compact": "auto",
"prefix": "string",
"suffix": "string",
"timeInterval": "RAW",
"custom": "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": {
"or": [
{}
],
"id": "string"
},
"metrics": {
"or": [
{}
],
"id": "string"
},
"dimensions": {
"or": [
{}
],
"id": "string"
}
},
"metrics": [
"string"
],
"dimensions": [
"string"
],
"exploreName": "string"
},
"id": "string"
}
]
}
}Responses
200 — Success
{
"results": {
"errors": [
{
"message": "string",
"fieldIds": [
"string"
],
"sourceId": "string",
"kind": "too_few_sources"
}
],
"requiresCompose": true,
"fieldIdByColumn": {
"property": "string"
},
"usedParametersValues": {
"property": "string"
},
"parameterReferences": [
"string"
],
"fieldOrigins": {
"property": {
"sourceFieldId": "string",
"sourceId": "string",
"kind": "source"
}
},
"itemsMap": {
"property": {
"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"
}
},
"fields": [
{
"sourceFieldId": "string",
"sourceId": "string",
"type": "string",
"kind": "dimension",
"label": "string",
"column": "string"
}
],
"columns": {
"valueColumnBySourceColumn": {
"property": {}
},
"joinKeyColumns": [
"string"
]
},
"terminalWrapper": {
"sourceLimitExceededSql": "string",
"limit": 0,
"orderBy": [
"string"
]
},
"typedColumns": [
{
"origin": {
"sourceFieldId": "string",
"sourceId": "string",
"kind": "source"
},
"type": "string",
"reference": "string"
}
],
"coreSql": "string",
"sql": "string"
},
"status": "ok"
}default — Error
{
"error": {
"data": "string",
"message": "string",
"name": "string",
"statusCode": 0
},
"status": "error"
}Run SQL query
Deprecated — use the v2 Execute SQL query endpoint instead. This endpoint was deprecated on 17 February 2025 and is past its sunset date (17 May 2025) — it may be removed at any time. Migrate to the v2 async query flow: Execute SQL query, then Get results.
Run merge query
Run a merge, returning a query uuid to page results from. The merged statement is registered as an ordinary async query, so its results are fetched, formatted, cancelled and downloaded through the same endpoints as any other query — page them with GET /api/v2/projects/{projectUuid}/query/{queryUuid}. A merge that cannot be run is rejected here rather than returned: compile it first to show the problem against the query that caused it.