Check an analytics query without running it

POST https://api.suger.cloud/ai/org/{orgId}/analytics/describe

Checks a query, and a chart config against the query's result when one is given, without reading any data. When the query is valid, returns the result's columns and their types, the chart drawn without a config, and the chart types the result fits; and every problem found otherwise, each with a JSON path, a message and often a fix. Write the query in the grammar from GetAnalyticsQueryGrammar, with the names from GetAnalyticsDataset. A chart config's `axis` is `{ zero, log, min, max }`, each optional, for the value axis: whether it includes zero (it does unless it is logarithmic), whether it is logarithmic, and where it starts and ends, `min` below `max` and both above zero on a log axis.

Parameters

NameInTypeRequiredDescription
orgId path string yes Organization ID

Request Body

Required. Content-Type: application/json · Schema: object

Request body fields:

FieldTypeRequiredDescription
query object yes An analytics query, in the grammar GetAnalyticsQueryGrammar gives, naming only the datasets ListAnalyticsDatasets lists and the fields, measures and segments GetAnalyticsDataset lists.
chart AnalyticsChartConfig no

AnalyticsChartConfig fields:

FieldTypeRequiredDescription
type string no The chart type; without it, the type the result's shape asks for.
x string no
y object no The measure, or measures sharing one unit, to plot.
series string no A dimension output; each of its values is drawn as its own series.
size string no
value string no
path array<string> no
rows array<string> no
across array<string> no
columns array<string> no
labels object no Display names for outputs, by output name, each at most 200 characters; the model's labels otherwise.
values boolean no
top number no Keep the N largest series, slices or points; at most seven, or ten slices of a pie, whose eighth to tenth are steps of the gray, each named on its slice.
sort string no
highlight object no One series value, drawn in color while the rest are muted.
target number no A goal, in the measure's unit.
axis object no
stack object no Stack the parts end to end, or not; `percent` stacks a bar's parts as shares of its own total, its axis reading 0% to 100%.
smooth boolean no
step boolean no
horizontal boolean no
lines array<string> no
totals boolean no
scale string no
range array<—> no
trend boolean no
period string no The period a number over a time breakdown shows: `whole`, the newest whole period (the default), or `newest`, the newest period, marked partial while it is.
donut boolean no
show string no
bars array<string> no
search boolean no A table's search box, which keeps the rows a cell of which shows the text typed in it, in any case, and counts them.

Responses

200 — Whether the query and chart pass, and why not

Content-Type: application/json · Schema: AnalyticsDescribeResult

AnalyticsDescribeResult fields:

FieldTypeRequiredDescription
ok boolean yes
schema object no The result's kind, limit and columns, when the query is valid.
diagnostics array<AnalyticsDiagnostic> no
lane string no The lane the query would run in, when known.
charts object no The charts the result can be drawn as, when the query is valid.
notes array<string> no What a valid query may not mean as written, such as an average of period-change ratios; a note refuses nothing.

AnalyticsDiagnostic fields:

FieldTypeRequiredDescription
code string yes
path array<object> yes Where the problem is: a JSON path into the query, or into the chart config.
message string yes
fix string no
suggestions array<string> no The nearest names that exist, for a name that does not.

401 — No valid token

Content-Type: application/json · Schema: AiErrorResponse

AiErrorResponse fields:

FieldTypeRequiredDescription
error string yes Error message

403 — Not a member of the organization

Content-Type: application/json · Schema: AiErrorResponse

AiErrorResponse fields:

FieldTypeRequiredDescription
error string yes Error message

413 — INVALID_REQUEST: the body is larger than 256 KiB

Content-Type: application/json · Schema: AnalyticsError

AnalyticsError fields:

FieldTypeRequiredDescription
error object yes

422 — INVALID_REQUEST: the body is not valid

Content-Type: application/json · Schema: AnalyticsError

AnalyticsError fields:

FieldTypeRequiredDescription
error object yes

500 — ANALYTICS_UNAVAILABLE: an unexpected failure

Content-Type: application/json · Schema: AnalyticsError

AnalyticsError fields:

FieldTypeRequiredDescription
error object yes

503 — ANALYTICS_UNAVAILABLE: analytics is not configured or not ready

Content-Type: application/json · Schema: AnalyticsError

AnalyticsError fields:

FieldTypeRequiredDescription
error object yes

Example

The request bodies are this operation's documented examples; the response and error bodies are generated from its schema. Substitute your own ids, and set SUGER_TOKEN to a bearer token from the OAuth client-credentials exchange.

Request

curl -X POST 'https://api.suger.cloud/ai/org/{orgId}/analytics/describe' \
  -H "Authorization: Bearer $SUGER_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "query": {
    "v": 1,
    "from": {
      "dataset": "revenue"
    },
    "stages": [
      {
        "kind": "aggregate",
        "where": {
          "op": "within",
          "arg": {
            "op": "field",
            "path": [
              "invoice_date"
            ]
          },
          "range": {
            "last": 12,
            "unit": "month"
          }
        },
        "group": {
          "month": {
            "op": "trunc",
            "arg": {
              "op": "field",
              "path": [
                "invoice_date"
              ]
            },
            "unit": "month"
          },
          "currency": {
            "op": "field",
            "path": [
              "currency"
            ]
          }
        },
        "measures": {
          "net_revenue": {
            "op": "measure",
            "name": "net_revenue"
          }
        },
        "order": [
          {
            "by": "month"
          }
        ]
      }
    ]
  },
  "chart": {
    "type": "line",
    "x": "month",
    "y": "net_revenue",
    "series": "currency"
  }
}'

Response — 200

{
  "ok": true,
  "schema": {
    "kind": "aggregate",
    "columns": [
      {
        "name": "Acme Corp",
        "role": "dimension",
        "label": "string",
        "type": {},
        "nullable": true,
        "approximate": true,
        "additive": true,
        "time": {
          "grain": "day"
        },
        "change": {
          "vs": "previous",
          "of": "string",
          "as": "delta"
        },
        "bin": {
          "width": 100
        }
      }
    ],
    "limit": 1,
    "order": [
      {
        "by": "string",
        "dir": "asc"
      }
    ]
  },
  "diagnostics": [
    {
      "code": "INVALID_QUERY",
      "path": [
        "string"
      ],
      "message": "string",
      "fix": "string",
      "suggestions": [
        "string"
      ]
    }
  ],
  "lane": "interactive",
  "charts": {
    "inferred": {},
    "fits": [
      "line"
    ]
  },
  "notes": [
    "string"
  ]
}

Error — 401

{
  "error": "string"
}

View as Markdown · API reference overview

Spotted something wrong or out of date on this page? Tell us and we'll correct it.