Run SQL pivot query

Run a SQL pivot query

POST /api/v1/projects/{projectUuid}/sqlRunner/runPivotQuery

Error

A valid request URL is required to generate request examples

200

{
  "results": {
    "jobId": "<string>"
  },
  "status": "ok"
}

Path Parameters

projectUuid · string · required

Body

application/json

sql · string · required

valuesColumns · object[] · required

Show child attributes

limit · number<double>

pivotColumnsOrder · object[]

Declared order of the pivot-column dimensions (visible groupByColumns plus hidden sortOnlyDimensions) as they appear in the chart's pivotConfig.columns. column_ranking orders columns by this sequence so a hidden sort-only dim sorts at its DECLARED position — hiding a dim then leaves column order identical to when it was visible, instead of hoisting the hidden dim to the front of the ORDER BY. Passthrough (hidden, non-sort) dims are excluded since they don't drive sort. When omitted, ordering falls back to hoisting sort-only sort targets to the front (legacy behavior).

Show child attributes

passthroughDimensions · object[]

Hidden pivot-column dimensions that are NOT sort targets but still need their values carried through the SQL pipeline so that other fields' richText / image: templates can reference them via row.<table>.<field>.raw. They participate in group_by_query SELECT and GROUP BY (same as sortOnlyDimensions) but do NOT affect column_ranking ORDER BY (they don't drive sort). Without this bucket the dim would be dropped entirely from the query and row.*.raw references would silently resolve to undefined.

Show child attributes

sortOnlyDimensions · object[]

Dimensions referenced by ORDER BY but NOT spread into pivot columns. Used when a user hides a dim that's part of pivotConfig.columns and has a sort entry on it: the dim still ranks column order via the GROUP BY / ORDER BY pipeline, but it doesn't become a pivot column header level. Mirrors sortOnlyColumns (which serves the same purpose for metrics).

Show child attributes

sortOnlyColumns · object[]

Metrics/table calculations needed for sort anchor CTEs but not for display. These are merged into valuesColumns for SQL generation in PivotQueryBuilder, but excluded from pivotDetails so they don't appear as chart series.

Show child attributes

metricsAsRows · boolean

When true, metrics are displayed as rows instead of columns. This affects column limit calculation - when metrics are rows, we don't need to divide the column limit by the number of metrics. Defaults to false for backward compatibility (SQL runner behavior).

sortBy · object[]

Show child attributes

groupByColumns · object[]

Show child attributes

indexColumn · object

object

object[]

Show child attributes

savedSqlUuid · string

Response

200

application/json

Success

results · object · required

Show child attributes

status · enum<string> · required

Available options: ok