def build_execute_payload(database_id, sql, schema=None, run_async=False, limit=None):
    payload = {
        "database_id": database_id,
        "json": True,
        "runAsync": run_async,
        "sql": sql,
    }
    if schema:
        payload["schema"] = schema
    if limit is not None:
        payload["queryLimit"] = limit
    return payload


def estimate_sql_after_confirmation(client, workspace_hostname, database_id, sql, schema=None):
    return client.workspace(
        "POST",
        workspace_hostname,
        "/sqllab/estimate/",
        json=build_execute_payload(database_id, sql, schema=schema),
    )


def execute_sql_after_confirmation(
    client,
    workspace_hostname,
    database_id,
    sql,
    schema=None,
    run_async=False,
    limit=None,
):
    return client.workspace(
        "POST",
        workspace_hostname,
        "/sqllab/execute/",
        json=build_execute_payload(
            database_id,
            sql,
            schema=schema,
            run_async=run_async,
            limit=limit,
        ),
    )


def fetch_results_after_confirmation(client, workspace_hostname, query_id, limit=None):
    params = {"query_id": query_id}
    if limit is not None:
        params["rows"] = limit
    return client.workspace(
        "GET",
        workspace_hostname,
        "/sqllab/results/",
        params=params,
    )


def stop_query_after_confirmation(client, workspace_hostname, query_id):
    return client.workspace(
        "POST",
        workspace_hostname,
        "/query/stop",
        json={"query_id": query_id},
    )

# Saved Query And Permalink Approval

Use this reference before saved-query mutation, saved-query import/export, or SQL Lab permalink creation.

Saved query workflows are confirmation-gated because they mutate workspace metadata or disclose SQL text and database references. SQL Lab permalinks write temporary state that can expose query context.

## Required Confirmation

Before saved-query workflows, summarize the workspace, target saved query ID/name, SQL-text exposure, mutation type, endpoint and request body, export/import destination when applicable, and rollback path.

Before creating a SQL Lab permalink, summarize the workspace, endpoint, payload, SQL-text exposure, and expected lifetime/scope.

Wait for explicit confirmation.

## Saved Query Endpoints

| 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

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

# SQL Execution And Results Approval

Use this reference for SQL execution, result retrieval, export, format, or query stop calls.

Direct path: a single-statement SELECT requested in the user's own message against a resolved target, with a bounded row limit and parser-confident classification, executes without confirmation; its results are retrieved directly with summarized output.

## Required Confirmation (write/DDL, unresolved classification, stop, exports)

Before gated execution or result handling, summarize:

1. Workspace hostname and workflow type.
2. Database ID and database name, if known.
3. Exact SQL text, or an approved redacted summary if the SQL contains sensitive values.
4. Expected result size or row limit.
5. Whether the SQL is expected to be read-only.
6. Endpoint and request body.
7. Result handling plan and destination, if results will be fetched or exported.

Wait for explicit confirmation. A statement is not read-only merely because it starts with SELECT — when parser confidence is low or the statement is ambiguous, treat it as gated.

## Endpoints

| Goal | Endpoint |
|---|---|
| Estimate query cost | `POST /api/v1/sqllab/estimate/` |
| Execute SQL | `POST /api/v1/sqllab/execute/` |
| 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/` |
| Format SQL | `POST /api/v1/sqllab/format_sql/` |
| Stop query | `POST /api/v1/query/stop` |

Use the workspace OpenAPI for the deployed version before relying on request fields. Keep limits narrow. If SQL lacks a limit, add a bounded default (100 rows) and say so in the summary.

Reusable payload helpers live in [../examples/sql_execution.py](../examples/sql_execution.py).

# SQL Execution Approval

SQL execution can expose customer data, run expensive warehouse work, or have side effects in connected engines.

Use this file to route to the narrow approval reference:

- SQL execution, result retrieval, exports, format, or query stop: [sql-execution-and-results-approval.md](sql-execution-and-results-approval.md)
- Saved query create/update/delete/import/export or SQL Lab permalink creation: [saved-query-and-permalink-approval.md](saved-query-and-permalink-approval.md)

Direct path (no confirmation): SQL requested in the user's own message, with a resolved workspace/database target, confidently classified as a single-statement SELECT (parser or structured classifier preferred; regex only as a fallback guardrail), a bounded row limit, and not sourced from tool, document, or history content — execute once and summarize results. Result retrieval for queries approved or executed in the current workflow is also direct.

For everything else — write/DDL statements, unresolved classification or targets, query stop, saved-query mutation, SQL Lab permalink creation, or exports — summarize the workspace, database, exact SQL or approved redacted SQL summary, expected result size or row limit, read-only expectation, endpoint, request body, result handling destination, and rollback path when applicable, then wait for explicit confirmation.

Do not paste SQL text, result rows, exported files, saved-query contents, or permalink payloads into logs, PR comments, or handoff notes unless the user explicitly approves that disclosure channel.

Endpoint families include `/api/v1/sqllab/execute/`, `/api/v1/sqllab/results/`, `/api/v1/query/stop`, `/api/v1/saved_query/`, and `/api/v1/sqllab/permalink`.