Workspaces

Run a SQL query

Runs one read-only SELECT (DuckDB dialect) over the workspace's tables and returns a preview of the result. Table names come from locate's tables, read-file's sql_tables and the refusal of a query naming an unknown table, which lists them all. Every result is kept: result.handle (res_…) is a table the next query in this workspace may join, total or page with LIMIT/OFFSET, and result_citation.result_file is the whole result as a Parquet file, downloadable from its download_url without the API key until download_url_expires_at; it is not one of the workspace's files. A statement that isn't a read is refused. File reads and SQL queries together are limited to 600 per account every 10 minutes. Free.

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

Request

Path parameters

idstring required

The workspace's workspace_id.

Headers

Idempotency-Keystring

Up to 200 characters, unique per account. A call that timed out keeps running: send it again with the same key and body to get its answer instead of running it twice.

Request body

sqlstring required

One read-only SELECT (DuckDB dialect) over the workspace's tables and earlier res_… results.

Response

The answer.

sqlstring required

The statement that ran, normalized.

duplicateboolean

True when an earlier identical query's stored result answered it.

source_pathsstring[]

The files the query read.

result_materialization_errorstring nullable
job_idstring nullable

The job the call ran as; GET /v1/documents/jobs/{id} reads it.

Changes

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