NAnace
tools

run_sql

Run one caller-authored read-only SELECT over the workspace's tables.

Cost class: fast. No planner and no answering agent — the statement runs directly in the guarded SQL engine, against every queryable tab in the workspace registered as a view under the table_name that file-metadata and the folder-metadata table census publish. Joins across files are ordinary SQL joins; earlier run-sql results are registered too, so a returned res_… handle can be joined, aggregated, or paged with LIMIT/OFFSET in the next statement.

The full result is retained as parquet whatever the preview shows — result_citation.result_file.download_url fetches it whole. A statement that is not a read, or reads an unregistered table, is refused with invalid_request naming the rule broken and the registered tables. For a natural-language question — or when the answer should be composed and cited for you — use query-tables instead.

post/v1/workspaces/{workspace_id}/tools/run-sql

Request

Path parameters

workspace_idstring uuid required

Workspace identifier.

Headers

Idempotency-Keystring nullable

Replaying a request with the same key returns the original job with 200, never a second job. The key is kept with the job for replay and never cleared, so it must not contain personal data.

Request body

sqlstring required

One read-only SELECT (DuckDB dialect) over the registered tables and earlier res_… handles.

Response

Successful Response

sqlstring required

The normalized statement that ran — the result's provenance.

duplicateboolean
source_pathsstring[]

The uploaded files the statement read — carried on the response itself so source attribution survives when no result file is materialized (job-attributed agent statements).

result_materialization_errorstring nullable
job_idstring uuid nullable

The external operation job; absent for commands inside a search job.

Changes

No recorded changes to this operation across all 1 revision of this API.