SQL

One SELECT or one WITH over the table files this caller can see. The statement uses relation names, not paths.

POST /v1/drives/{drive}/query runs one read statement. MCP query is that same call. The desk task is on Search and SQL.

The body is statement and exactly one of directoryId or fileId. Naming both, or naming neither, is 400 with detail Name a directory or a file. A hidden target is 404. A file that is not a table is 400 with detail The file is not a table. A directory with no visible table is 400 with detail No table is visible here. More than 200 attached table files is 400 with detail Narrow the query to fewer files.

Relation names

A table file is CSV, Parquet, or a flat JSON array. The statement uses the relation name. It does not use a path or an object key.

The name is lowercase. A character other than a letter, a digit, or _ becomes _. A name that would start with a digit gains a leading _. An empty name is relation.

A query on one file uses that file’s name without the extension. March invoices.csv is march_invoices.

A query on a directory binds the table files in that directory, and one level of children:

  • Files that share one column schema are one relation. When the directory has one schema, that relation takes the directory name. Ledger is ledger.
  • A schema shared by more than one file also takes the directory name. One directory name is used once.
  • Any other schema stays its own relation, named for that file without the extension.
  • A child directory whose own tables are already one relation is included, under the child’s name.
  • A child with more than one schema is left out. A directory below that child is left out.
  • A name already used gains _2, then _3.

Hidden files are not attached. The response field relations is the names that were bound, each with its file ids. A later statement for the same target uses those names.

The statement

The statement is one SELECT or one WITH. A trailing semicolon is dropped. A second statement, or a comment, is 400 with detail The statement can only read the bound relations. So is a call that opens a file, or a word such as insert, update, delete, create, drop, copy, set, or call. A relation may itself be named query. Write that name as a table.

LIMIT and OFFSET belong on the outer statement, as constant integers. A LIMIT inside a WITH stays part of the question. A non-constant or a negative outer LIMIT or OFFSET is 400 with detail The statement's LIMIT and OFFSET must be constant integers. A statement over 10,000 characters is 400 with detail The statement is too long.

The response is { "relations", "columns", "rows", "limit", "offset", "truncated" }. The page has at most 2,000 rows. limit is that page size, or the statement’s LIMIT when that is smaller. offset is the statement’s OFFSET, or 0. truncated is true when another row exists after the page. The next page is the same statement with OFFSET raised by the number of rows returned. Stop when truncated is false.

A statement that does not finish is 400 with detail The statement took too long. A statement that cannot be run is 503 with detail The statement could not be run.

A question

POST /v1/drives/{drive}/query/draft takes question and exactly one of directoryId or fileId. The service writes one statement from the bound schema and runs it. The response adds statement to the page above. MCP draft_query is that same call.

No visible table, a hidden target, and a file that is not a table use the same details as query. No model is 503 with detail The model is not configured. An empty statement is 503 with detail The statement could not be written.

The next page of a draft is query, with the returned statement and a higher OFFSET.

A saved statement is a stored query on that same directory or file. POST /v1/drives/{drive}/queries/{query}/run returns this same page. Those routes are on the HTTP reference.