> ## Documentation Index
> Fetch the complete documentation index at: https://developers.clay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# tables query

> Run a structured query across one or more tables.

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`](/cli/reference/tables-update) before you can query it — check your workspace's usage with [`clay tables query-usage`](/cli/reference/tables-query-usage).

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
clay tables query --query <file|-> [--limit <n>] [--cursor <token>]
```

## Flags

| Flag                | Description                                                                      |
| ------------------- | -------------------------------------------------------------------------------- |
| `--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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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" }
  }
}
```

| Field    | Type   | Description                                                                                     |
| -------- | ------ | ----------------------------------------------------------------------------------------------- |
| `data[]` | object | Each result row is a map of field id to a cell object (see below).                              |
| `cursor` | string | Present when more results are available. Pass it back via `--cursor`. Omitted on the last page. |
| `fields` | object | Map of field id to `{ id, name, type }` metadata for the returned fields. May be omitted.       |

### Cell shape

Each cell is discriminated on `status`:

| Status                                                            | Fields                                                                           | Meaning                                                           |
| ----------------------------------------------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `success`                                                         | `value` (computed value), `fields` (object \| null), `isStale` (optional `true`) | The cell has a computed value; structured content is in `fields`. |
| `error`                                                           | `error` (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

| Code               | Exit | Notes                                                                                          |
| ------------------ | ---- | ---------------------------------------------------------------------------------------------- |
| `validation_error` | 2    | Missing `--query`, unreadable file, invalid JSON, or a request that does not match the schema. |
| `auth_forbidden`   | 3    | The API key lacks the `cli:all` scope, or the public-API beta is not enabled.                  |
| `not_found`        | 6    | A referenced table or field does not exist.                                                    |

## Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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"
```