Skip to main content

Create Sql Query

POST 
/v1/sql

SQL endpoint with simplified templating handled on backend

  • sql: Either a direct SQL query or path to SQL file
  • templateArgs: Template variables to substitute in the SQL
  • contextType: "viz" or "dataset" for file loading context
  • contextId: ID of the viz or dataset for file loading
  • Backend handles template processing and file loading

Dataset readiness: only a READY dataset has a queryable table behind it. On a cache MISS, a participating dataset that is still ingesting (PENDING/DOWNLOADING/PROCESSING) → 400 query_dataset_not_ready; one whose ingestion failed (FAILED) → 400 query_dataset_failed. Both name the dataset and its processingStatus. This is checked before enqueuing, because such a job can never resolve — it used to return 201 with a pending record that stayed pending indefinitely. A cache HIT is still served (it was computed while the dataset was ready), so a dashboard over a dataset that is mid-re-ingest keeps rendering.

Returns:

  • If cache hit: { sqlQuery: {..., status: "completed"}, cached: true, url: "presigned_url" }
  • If cache miss: { sqlQuery: {..., status: "pending"}, cached: false }

Request​

Responses​

Successful Response