# 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[​](#request "Link direto para request")

## Responses[​](#responses "Link direto para Responses")

* 201
* 404
* 422

Successful Response

Not found

Validation Error