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.
1. Submit
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
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
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:
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?