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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
orgId | path | string | yes | Organization ID |
Request Body
Required. Content-Type: application/json · Schema: object
Request body fields:
| Field | Type | Required | Description |
|---|---|---|---|
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:
| Field | Type | Required | Description |
|---|---|---|---|
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:
| Field | Type | Required | Description |
|---|---|---|---|
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:
| Field | Type | Required | Description |
|---|---|---|---|
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:
| Field | Type | Required | Description |
|---|---|---|---|
error | string | yes | Error message |
403 — Not a member of the organization
Content-Type: application/json · Schema: AiErrorResponse
AiErrorResponse fields:
| Field | Type | Required | Description |
|---|---|---|---|
error | string | yes | Error message |
413 — INVALID_REQUEST: the body is larger than 256 KiB
Content-Type: application/json · Schema: AnalyticsError
AnalyticsError fields:
| Field | Type | Required | Description |
|---|---|---|---|
error | object | yes |
422 — INVALID_REQUEST: the body is not valid
Content-Type: application/json · Schema: AnalyticsError
AnalyticsError fields:
| Field | Type | Required | Description |
|---|---|---|---|
error | object | yes |
500 — ANALYTICS_UNAVAILABLE: an unexpected failure
Content-Type: application/json · Schema: AnalyticsError
AnalyticsError fields:
| Field | Type | Required | Description |
|---|---|---|---|
error | object | yes |
503 — ANALYTICS_UNAVAILABLE: analytics is not configured or not ready
Content-Type: application/json · Schema: AnalyticsError
AnalyticsError fields:
| Field | Type | Required | Description |
|---|---|---|---|
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.