For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to page URLs.
Skip to content

Query lifecycle

Learn how asynchronous requests progress from submission to a final result or error.

REST, Semantic SQL, Metrics, and Source SQL use one asynchronous lifecycle. Separating submission from result download lets the API queue warehouse work, deduplicate identical queries, reuse successful results, and serve large Parquet files without keeping the original connection open.

GraphQL normally completes this lifecycle inside one request. If it returns 202, follow its retry guidance.

Deep dive: the flow above is the short version. Statement lifecycle walks through the same states as detailed sequence diagrams (Client ↔ API ↔ Queue ↔ Worker ↔ Object Store) for the standard flow, the error path, deduplication, and the GraphQL timeout path. Use it when you need to see exactly which component does what at each step.

1. Submit

Method
Endpoint

Semantic REST

POST /api/v1/query/semantic/rest

Semantic SQL

POST /api/v1/query/semantic/sql

Named metric

GET or POST /api/v1/query/metric/{metric_name}

Source SQL

POST /api/v1/query/statement

An executable request returns 202 Accepted, a statement id, and a Location header. Persist the ID.

{
  "id": "stmt_abc123",
  "status": "QUEUED",
  "strategy": "EXECUTE",
  "fingerprint": "...",
  "is_stale": false,
  "_links": {
    "self": {"href": "/api/v1/query/statement/stmt_abc123"}
  }
}

2. Read the execution strategy

Strategy
Meaning
Client action

EXECUTE

A new warehouse execution was queued.

Poll this statement.

AWAIT_PRIMARY

An identical query is already running; this request follows it.

Poll normally; do not resubmit.

REUSE_RESULT

A previous successful result can be reused.

Status can already be SUCCESS; fetch immediately.

Branch on status and _links; do not assume every accepted request starts a warehouse query.

3. Poll

Status
Meaning

ACCEPTED

Received but not yet queued.

QUEUED

Waiting for a worker.

IN_PROGRESS

Running against the warehouse.

SUCCESS

Result is available.

FAILED

Execution ended with an error; inspect error.

Stop polling on SUCCESS or FAILED. Use bounded exponential backoff instead of polling continuously. Do not call /result after FAILED.

4. Fetch

After SUCCESS:

Format
Behavior

parquet

Default. Returns 307 to a presigned object-store URL. limit, offset, and columns are ignored.

json

Inline cols, rows, types, row_count, size_bytes, and links.

csv

Inline CSV text.

yaml

Inline YAML.

For text formats, columns=store_region,total_revenue projects columns and limit / offset paginate rows. Follow redirects when downloading Parquet.

Handle staleness

is_stale: true or Is-Stale: true means one or more dependent models have pending intervals. The query still succeeded; its result may not include the latest expected data. Show freshness separately from execution status.

Retry safely

Poll the existing ID for normal retries. The server already deduplicates identical in-flight queries and can reuse successful results.

Use ?retry_on_recent_failure=true only when deliberately rerunning an identical query that failed recently. Semantic REST and Semantic SQL also accept ?transpile_only=true; this returns 200 with compiled SQL, creates no statement, and has no poll or fetch stage.

GraphQL exception

GraphQL returns inline data and execution metadata under extensions when it finishes within the wait window. If it returns 202, respect Retry-After and resend the identical GraphQL request or poll extensions._links.self. Deduplication prevents a second warehouse execution.

Last updated

Was this helpful?