Saved Queries

Save, version, and execute named SQL queries. Each update creates a new version, preserving the full history. Saved queries are automatically classified by category (e.g., aggregation, join, filtered scan) and can be executed by ID.

List saved queries

Query parameters

• limit integer — Maximum number of results
• offset integer — Pagination offset

Response 200 — List of saved queries

• count integer — required. Min: 0
• has_more boolean — required
• limit integer — required. Min: 0
• offset integer — required. Min: 0
• queries SavedQuerySummary[] — required
  • created_at string — required
  • description string — required
  • id string — required
  • latest_version integer — required
  • name string — required
  • tags string[] — required
  • updated_at string — required

{
  "count": 0,
  "has_more": true,
  "limit": 0,
  "offset": 0,
  "queries": [
    {
      "created_at": "2026-01-01T00:00:00Z",
      "description": "string",
      "id": "string",
      "latest_version": 0,
      "name": "string",
      "tags": [
        "string"
      ],
      "updated_at": "2026-01-01T00:00:00Z"
    }
  ]
}

Create saved query

Save a named SQL query. The SQL is stored as version 1 and automatically analyzed for classification metadata (category, table count, predicate/join/aggregation flags).

Request body

• description string,null
• name string — required
• sql string — required
• tags string[] | null

{
  "description": "Ten highest-spending customers by order total",
  "name": "top-customers",
  "sql": "SELECT customer_id, sum(amount) AS total FROM orders GROUP BY customer_id ORDER BY total DESC LIMIT 10",
  "tags": [
    "sales",
    "weekly"
  ]
}

Response 201 — Saved query created

• category string,null
• created_at string — required
• description string — required
• has_aggregation boolean,null
• has_group_by boolean,null
• has_join boolean,null
• has_limit boolean,null
• has_order_by boolean,null
• has_predicate boolean,null
• id string — required
• latest_version integer — required
• name string — required
• num_tables integer,null
• sql string — required
• sql_hash string — required
• table_size string,null
• tags string[] — required
• updated_at string — required

{
  "category": "string",
  "created_at": "2026-01-01T00:00:00Z",
  "description": "string",
  "has_aggregation": true,
  "has_group_by": true,
  "has_join": true,
  "has_limit": true,
  "has_order_by": true,
  "has_predicate": true,
  "id": "string",
  "latest_version": 0,
  "name": "string",
  "num_tables": 0,
  "sql": "string",
  "sql_hash": "string",
  "table_size": "string",
  "tags": [
    "string"
  ],
  "updated_at": "2026-01-01T00:00:00Z"
}

Errors

Get saved query

Path parameters

• id string — required. Saved query ID

Response 200 — Saved query details

• category string,null
• created_at string — required
• description string — required
• has_aggregation boolean,null
• has_group_by boolean,null
• has_join boolean,null
• has_limit boolean,null
• has_order_by boolean,null
• has_predicate boolean,null
• id string — required
• latest_version integer — required
• name string — required
• num_tables integer,null
• sql string — required
• sql_hash string — required
• table_size string,null
• tags string[] — required
• updated_at string — required

{
  "category": "string",
  "created_at": "2026-01-01T00:00:00Z",
  "description": "string",
  "has_aggregation": true,
  "has_group_by": true,
  "has_join": true,
  "has_limit": true,
  "has_order_by": true,
  "has_predicate": true,
  "id": "string",
  "latest_version": 0,
  "name": "string",
  "num_tables": 0,
  "sql": "string",
  "sql_hash": "string",
  "table_size": "string",
  "tags": [
    "string"
  ],
  "updated_at": "2026-01-01T00:00:00Z"
}

Errors

Update saved query

Update a saved query. If the SQL changes, a new version is created (previous versions are preserved). Name, tags, description, and classification overrides can also be updated.

Path parameters

• id string — required. Saved query ID

Request body

• category_override string,null — Override the auto-detected category. Send null to clear (revert to auto).
• description string,null
• name string,null — Optional new name. When omitted the existing name is preserved.
• sql string,null — Optional new SQL. When omitted the existing SQL is preserved.
• table_size_override string,null — User annotation for table size. Send null to clear.
• tags string[] | null

All fields are optional. Send only the ones you want to set.

Response 200 — Saved query updated

• category string,null
• created_at string — required
• description string — required
• has_aggregation boolean,null
• has_group_by boolean,null
• has_join boolean,null
• has_limit boolean,null
• has_order_by boolean,null
• has_predicate boolean,null
• id string — required
• latest_version integer — required
• name string — required
• num_tables integer,null
• sql string — required
• sql_hash string — required
• table_size string,null
• tags string[] — required
• updated_at string — required

{
  "category": "string",
  "created_at": "2026-01-01T00:00:00Z",
  "description": "string",
  "has_aggregation": true,
  "has_group_by": true,
  "has_join": true,
  "has_limit": true,
  "has_order_by": true,
  "has_predicate": true,
  "id": "string",
  "latest_version": 0,
  "name": "string",
  "num_tables": 0,
  "sql": "string",
  "sql_hash": "string",
  "table_size": "string",
  "tags": [
    "string"
  ],
  "updated_at": "2026-01-01T00:00:00Z"
}

Errors

Delete saved query

Path parameters

• id string — required. Saved query ID

Response 204 — Saved query deleted

Errors

Execute saved query

Execute a saved query, scoped to a database (required X-Database-Id header). By default runs the latest version. Optionally specify a version number to execute a previous version. The SQL runs inside the given database scope, the same way POST /v1/query does. Returns the same response format as POST /v1/query.

Path parameters

• id string — required. Saved query ID

Headers

• X-Database-Id string — required. Required. Scope execution to this database (its id). A missing or malformed value is a 400; an unknown database id is a 404.

Request body

• version integer,null

All fields are optional. Send only the ones you want to set.

Response 200 — Query executed

• columns string[] — required
• execution_time_ms integer — required. Min: 0
• nullable boolean[] — required. Nullable flags for each column (parallel to columns vec). True if the column allows NULL values, false if NOT NULL.
• preview_row_count integer — required. Number of rows in this response body. Always present. For a large result this is a bounded preview, not the grand total — see total_row_count and truncated.
• query_run_id string — required. Unique identifier for the query run record (qrun...).
• result_id string,null — Unique identifier for retrieving this result via GET /results/{id}. When non-null, the result is being persisted asynchronously. Null only when the result fit entirely in this response (truncated: false) but could not be persisted for later retrieval — see the warning field. A truncated: true response ALWAYS carries a non-null, resolvable result_id: a truncated result that cannot be persisted fails the request with a retryable HTTP 503 (PERSISTENCE_UNAVAILABLE, with a Retry-After header) rather than returning a partial body with a dead ticket.
• row_count integer — required. Deprecated — use preview_row_count (rows in this body) and total_row_count (grand total) instead. Retained as a back-compat alias and always equal to preview_row_count; for a truncated result it is the preview count, not the grand total — read total_row_count for that. Will be removed in a future release once clients migrate. Min: 0
• rows any[][] — required. Array of rows, where each row is an array of column values. Values can be strings, numbers, booleans, or null.
• total_row_count integer,null — Grand total rows in the full result. Present (and equal to preview_row_count) when the whole result fit in this response; null while a truncated result is still being persisted. When null, read the authoritative total from GET /v1/query-runs/{id} (row_count) or the X-Total-Row-Count header on GET /v1/results/{id}.
• truncated boolean — required. True when rows is a bounded preview of a larger result. Fetch the full result via result_id.
• warning string,null — Warning message if result persistence could not be initiated. Present only when the full result is returned inline (truncated: false) but could not be persisted: result_id is then null and the result cannot be re-fetched later, though every row is in this response. A truncated result never carries a warning — if it cannot be persisted the request fails with a retryable HTTP 503 (PERSISTENCE_UNAVAILABLE, with a Retry-After header) instead.

{
  "columns": [
    "string"
  ],
  "execution_time_ms": 0,
  "nullable": [
    true
  ],
  "preview_row_count": 0,
  "query_run_id": "string",
  "result_id": "string",
  "row_count": 0,
  "rows": [
    [
      null
    ]
  ],
  "total_row_count": 0,
  "truncated": true,
  "warning": "string"
}

Errors

List saved query versions

Path parameters

• id string — required. Saved query ID

Query parameters

• limit integer — Maximum number of versions
• offset integer — Pagination offset

Response 200 — List of versions

• count integer — required. Min: 0
• has_more boolean — required
• limit integer — required. Min: 0
• offset integer — required. Min: 0
• saved_query_id string — required
• versions SavedQueryVersionInfo[] — required
  • category string,null
  • created_at string — required
  • has_aggregation boolean,null
  • has_group_by boolean,null
  • has_join boolean,null
  • has_limit boolean,null
  • has_order_by boolean,null
  • has_predicate boolean,null
  • num_tables integer,null
  • sql string — required
  • sql_hash string — required
  • table_size string,null
  • version integer — required

{
  "count": 0,
  "has_more": true,
  "limit": 0,
  "offset": 0,
  "saved_query_id": "string",
  "versions": [
    {
      "category": "string",
      "created_at": "2026-01-01T00:00:00Z",
      "has_aggregation": true,
      "has_group_by": true,
      "has_join": true,
      "has_limit": true,
      "has_order_by": true,
      "has_predicate": true,
      "num_tables": 0,
      "sql": "string",
      "sql_hash": "string",
      "table_size": "string",
      "version": 0
    }
  ]
}

Errors