Skip to main content
Run a structured query against one or more tables. The query is read from --query; the response is written to stdout as JSON. A table must be enabled for querying with clay tables update before you can query it — check your workspace’s usage with clay tables query-usage. 
clay tables query --query <file|-> [--limit <n>] [--cursor <token>]

​
Flags

FlagDescription
--query <file|->Path to a JSON file containing the structured query. Use - to read from stdin.
--limit <n>Maximum rows to return. Must be in range 1–100. Defaults to 50.
--cursor <token>Resume from a previous response’s cursor to fetch the next page.

​
Query shape

The --query file is the query itself — what to fetch. Pagination is not part of it. The minimal query is { "tables": [{ "id": "tbl_..." }] }. Beyond tables, a query may also include filter, select, join, order_by, group_by, and field_mode. Field references can use ids or names; multi-table queries declare each table in tables.

​
Output

{
  "data": [
    {
      "col_email": { "status": "success", "value": "jane@acme.com", "fields": null }
    }
  ],
  "cursor": "next_page_token",
  "fields": {
    "col_email": { "id": "col_email", "name": "Email", "type": "text" }
  }
}
FieldTypeDescription
data[]objectEach result row is a map of field id to a cell object (see below).
cursorstringPresent when more results are available. Pass it back via --cursor. Omitted on the last page.
fieldsobjectMap of field id to { id, name, type } metadata for the returned fields. May be omitted.

​
Cell shape

Each cell is discriminated on status:
StatusFieldsMeaning
successvalue (computed value), fields (object | null), isStale (optional true)The cell has a computed value; structured content is in fields.
errorerror (string, optional)The cell errored; error carries the message.
running, queued, retry, rate_limited, awaiting_callback—The cell is still being computed.
empty—The cell has no value yet.

​
Errors

CodeExitNotes
validation_error2Missing --query, unreadable file, invalid JSON, or a request that does not match the schema.
auth_forbidden3The API key lacks the cli:all scope, or the public-API beta is not enabled.
not_found6A referenced table or field does not exist.

​
Examples

clay tables query --query ./query.json | jq '.data | length'
echo '{"tables":[{"id":"tbl_..."}]}' | clay tables query --query - --limit 100
clay tables query --query ./query.json --limit 100 --cursor "$CURSOR"