Referencev2
Execute merge query
Validates and executes a merge as one asynchronous query request.
POST/api/v2/projects/{projectUuid}/query/merge-query
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"
},
"invalidateCache": true,
"context": "dashboardView",
"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"
}
]
},
"chart": {
"pivotConfig": {
"rows": [
"string"
],
"columns": [
"string"
]
},
"chartConfig": {
"config": {
"comparisonField": "string",
"conditionalFormattings": [
{
"textStyle": {
"underline": true,
"italic": true,
"bold": true
},
"applyTo": "cell",
"rules": [
{
"includeNull": true,
"values": [
0
],
"operator": "isNull",
"id": "string"
}
],
"darkColor": "string",
"color": "string",
"target": {
"fieldId": "string"
}
}
],
"comparisonLabel": "string",
"flipColors": true,
"comparisonFormat": "raw",
"showComparison": true,
"showTableNamesInLabel": true,
"showBigNumberLabel": true,
"selectedField": "string",
"style": "auto",
"label": "string"
},
"type": "big_number"
}
},
"mode": {
"type": "interactive"
}
}Responses
200 — Success
{
"results": {
"fieldOrigins": {
"property": {
"sourceFieldId": "string",
"sourceId": "string",
"kind": "source"
}
},
"parameterReferences": [
"string"
],
"query": {
"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",
"warnings": [
{
"tables": [
"string"
],
"fields": [
"string"
],
"message": "string"
}
],
"fields": {
"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"
}
},
"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"
}
},
"outcome": "started"
},
"status": "ok"
}default — Error
{
"error": {
"data": "string",
"message": "string",
"name": "string",
"statusCode": 0
},
"status": "error"
}Calculate totals
Calculates totals for a previously-executed query, referenced by its queryUuid. Re-runs the source query's MetricQuery against the warehouse so totals are correct for every metric type (count distinct, average, ratio, etc.) — unlike client-side cell summation, which only works for sum/count. The requested `kind` selects which totals to compute.
Execute compose merge query
Validates and executes a merge on the compose engine as one asynchronous query request. Unlike Execute merge query, sources may reference existing query results by queryUuid; each referenced query is authorized with the same access checks as fetching its results. Requires the merge-on-compose feature flag.