# Query Control

Use this reference for stopping or canceling running SQL Lab queries.

Stopping a query mutates execution state. Use `preset-sql-execution` before stopping a query.

| Goal | Endpoint |
|---|---|
| Stop query | `POST /api/v1/query/stop` |

Before stopping a query, summarize:

1. Workspace hostname.
2. Query ID, client ID, or other target identifier.
3. Current query status when known.
4. Expected effect on the running warehouse query or Superset task.
5. Any user-visible impact.

Wait for explicit confirmation before calling the endpoint.

# Query History

Use this reference for SQL Lab query history reads.

Query history includes SQL text. Read the user's own history directly when they asked in their own message AND a current-user/owner filter is applied before SQL-bearing fields are fetched (default page 25 records, hard cap 100 without explicit confirmation). Other users' history, or any read where owner filtering cannot be applied first, stays confirmation-gated as SQL-text disclosure.

```python
import rison

me = client.workspace("GET", hostname, "/me/")["result"]
q = rison.dumps({
    "page": 0,
    "page_size": 25,
    "filters": [{"col": "user", "opr": "rel_o_m", "value": me["id"]}],
})
queries = client.workspace("GET", hostname, f"/query/?q={q}")["result"]
```

Useful query endpoints:

| Goal | Endpoint |
|---|---|
| List query history | `GET /api/v1/query/` |
| Get query detail | `GET /api/v1/query/{pk}` |
| Query updates since timestamp | `GET /api/v1/query/updated_since` |
| Related fields | `GET /api/v1/query/related/{column_name}` |

Do not paste SQL into logs or comments unless the user asks and it is safe to share.

# Query Results And Exports

Use this reference for SQL Lab result retrieval, CSV/JSON exports, and cached result handling.

SQL result endpoints expose customer data. Retrieve results of a query approved or executed in the current workflow directly with summarized output; use `preset-sql-execution` for exports and queries outside the current workflow.

## Endpoints

| Goal | Endpoint |
|---|---|
| Get execution result | `GET /api/v1/sqllab/results/` |
| Export result CSV | `GET /api/v1/sqllab/export/{client_id}/` |
| Streaming CSV export | `POST /api/v1/sqllab/export_streaming/` |

Before exporting results, or fetching results of queries outside the current workflow, summarize:

1. Workspace hostname.
2. Query ID or client ID.
3. Result format and destination.
4. Expected row count, byte size, or limit.
5. Expected customer data exposure.

Do not paste returned rows into logs, PR comments, or handoff notes unless the user confirms that the data is safe to share.

# SQL Lab Routing Essentials

Use this compact routing reference when a task spans SQL Lab bootstrap, query history, saved queries, result retrieval, query stop, and execution.

Default to inspecting SQL Lab bootstrap metadata first. Route each request separately: query history can expose SQL text, saved queries can expose or mutate SQL definitions, result retrieval/export returns customer data, query stop changes execution state, and SQL execution starts a new job.

Run directly: the user's own query history and saved-query reads when current-user/owner filtering is applied before SQL-bearing fields are fetched (bounded page size), and result retrieval for a query approved or executed in the current workflow. A confidently classified, user-requested, bounded single-statement SELECT runs directly through `preset-sql-execution`.

Confirm first: other users' SQL text or any history read where owner filtering cannot be applied first, result export, query stop, permalink creation, saved-query mutation, and SQL whose classification or target is unresolved. Summarize the workspace, target query or saved query, endpoint, and expected data exposure or state change, then get explicit approval. Always redact secrets, tokens, SQLAlchemy URIs, and credentials.

# Saved Queries

Use this reference for saved-query reads and mutation routing.

Saved queries include SQL text. Read the user's own saved queries directly when they asked in their own message AND a created_by/owner filter is applied before SQL-bearing fields are fetched (default page 25 records, hard cap 100 without explicit confirmation). Other users' saved queries, or reads where owner filtering cannot be applied first, stay confirmation-gated as SQL-text disclosure.

```python
import rison

me = client.workspace("GET", hostname, "/me/")["result"]
q = rison.dumps({
    "page": 0,
    "page_size": 25,
    "filters": [{"col": "created_by", "opr": "rel_o_m", "value": me["id"]}],
})
saved = client.workspace("GET", hostname, f"/saved_query/?q={q}")["result"]
```

Useful saved-query read endpoints:

| Goal | Endpoint |
|---|---|
| List saved queries | `GET /api/v1/saved_query/` |
| Get saved query detail | `GET /api/v1/saved_query/{pk}` |
| Related fields | `GET /api/v1/saved_query/related/{column_name}` |
| Distinct fields | `GET /api/v1/saved_query/distinct/{column_name}` |

Saved query create, update, delete, import, and export are confirmation-gated because they mutate workspace metadata or disclose SQL text and database references.

Use `preset-sql-execution` before saved-query mutations.

| Goal | Endpoint |
|---|---|
| Create saved query | `POST /api/v1/saved_query/` |
| Update saved query | `PUT /api/v1/saved_query/{pk}` |
| Delete saved query | `DELETE /api/v1/saved_query/{pk}` |
| Bulk delete saved queries | `DELETE /api/v1/saved_query/` |
| Export saved queries | `GET /api/v1/saved_query/export/` |
| Import saved queries | `POST /api/v1/saved_query/import/` |

## SQL Lab Permalinks

Reading SQL Lab permalinks can expose query context. Creating permalinks writes temporary state. Use `preset-sql-execution` before creating SQL Lab permalinks.

| Goal | Endpoint |
|---|---|
| Read SQL Lab permalink | `GET /api/v1/sqllab/permalink/{key}` |
| Create SQL Lab permalink | `POST /api/v1/sqllab/permalink` |

# SQL Execution Routing

Use this reference when a SQL Lab workflow reaches SQL execution or cost estimation.

SQL execution is high impact even when the SQL is read-only. It can expose customer data, run expensive warehouse work, or create side effects in engines that allow non-read statements.

Use `preset-sql-execution` for SQL execution, result retrieval, result export, query stop, saved-query mutation, and SQL Lab permalink creation workflows. This reference maps only SQL execution and formatting endpoints; adjacent result, export, query-control, saved-query, and permalink surfaces live in the focused SQL Lab references. The focused Phase 5 skill owns the approval template.

## SQL Execution Endpoints

| Goal | Endpoint |
|---|---|
| Estimate query cost | `POST /api/v1/sqllab/estimate/` |
| Execute SQL | `POST /api/v1/sqllab/execute/` |
| Format SQL | `POST /api/v1/sqllab/format_sql/` |

Direct path: a confidently classified single-statement SELECT (no DML/DDL/CALL/COPY/MERGE, no multi-statement) requested in the user's own message, against a resolved workspace/database target, with a bounded row limit, runs through `preset-sql-execution` without a confirmation stop. Summarize results without raw row dumps.

Confirm first (writes, DDL, low parser confidence, or unresolved target), summarize and wait for explicit confirmation before calling the execution endpoint:

1. Workspace hostname.
2. Database ID and database name, if known.
3. SQL text or an exact summary if the SQL contains sensitive values.
4. Expected result size or row limit.
5. Why the statement is gated (write/DDL, low parser confidence, or unresolved target).
6. Endpoint and request body.

A statement is not read-only merely because it starts with SELECT; when parser confidence is low, treat it as gated.

# SQL Lab Bootstrap

Use this reference for SQL Lab availability, database options, permissions, and UI defaults.

```bash
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://{workspace_hostname}/api/v1/sqllab/" | jq '.result'
```

```python
bootstrap = client.workspace("GET", hostname, "/sqllab/")["result"]
```

The bootstrap response helps identify SQL Lab availability, database options, and UI defaults for the authenticated user.

This is metadata discovery. If the user asks to execute SQL, fetch result sets, export result sets, or stop a running query, route to `preset-sql-execution`.