{"id":103336,"plugin_id":"plugin_asdk_app_6aedf6ea2fac819180910f8b98663c77","kind":"skill","collection_source":"plugin_package","comparison_source":null,"observed_at":"2026-11-18T06:19:21.053Z","digest":"b43b014872502afd7ff5b5cc535415aa982ab7170506c426b117e03fbf4bec66","against":null,"payload":{"description":"Clay tables — inspect, query, and export data from an existing table via the `clay tables` CLI (list, columns, rows, query-live, structured query). To investigate a table or record, use the focused `/tables-*` skills (analyze, trace, error-sweep, value-trace, capacity).","included_files":[{"relative_path":"dependency-catalog.md","size_in_bytes":3039}],"name":"tables-cli","skill_md_contents":"---\nname: tables-cli\ndescription: Clay tables — inspect, query, and export data from an existing table via the `clay tables` CLI (list, columns, rows, query-live, structured query). To investigate a table or record, use the focused `/tables-*` skills (analyze, trace, error-sweep, value-trace, capacity).\n---\n\nBefore using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.\n\nClay tables are spreadsheet-like: columns (basic, formula, or enrichment), rows\n(usually people or companies), and sources that add rows. This skill only **reads**\ntables that already exist. For tool access or authentication problems, read the `clay` entry skill before continuing.\n\n## Finding a table\n\nResolve it to a `t_...` id. Use `clay tables list --filter workbook.id=<wb_...>`\nwhen the workbook is known (`clay workbooks list`), otherwise `clay tables list` and\npick by `.name` with `jq`. Do not use `--filter queryEnabled=true` unless you only want\nquery-synced tables — it hides the rest. If the user named no table or workbook,\nask rather than sweeping the workspace.\n\nID prefixes: `t_` table, `f_` column, `r_` row, `wb_` workbook.\n\n## Not supported\n\n- **Creating tables** (or adding fields/columns). Tell the user to create the table\n  in the Clay app first; you can work with it once it exists.\n- **Writing data.** These table operations cannot insert rows, update cells, or trigger enrichments.\n  `clay tables update` only toggles whether a table is queryable (`--query-enabled`);\n  it does not write data. Rows enter through the Clay app. The Public API is\n  query/list-only as well.\n\n## CLI: `clay tables`\n\nPrefer `columns list|get` / `get` / `rows list|get` / `query-live` for everyday work; use\n`clay tables query` when you need synced Enterprise joins/pagination. (`columns` and\n`rows` are command groups — `clay tables columns <tableId>` is not a command.)\n\n**Availability:** `clay tables query` requires **API table sync** (Enterprise).\nWithout sync, `clay tables query` fails with `auth_forbidden` and\n`clay tables update --query-enabled true` with `plan_upgrade_required` (older CLI\nversions report `auth_forbidden`), both saying \"API table sync is not enabled for\nthis workspace\" —\nthat's an account limitation, not a bug: don't retry or re-login. Fall back to\n`columns` / `rows` / `query-live` (no sync required), and tell the user to contact\nClay about Enterprise access for synced `query`.\n\n`clay tables --help` (and `clay tables <cmd> --help`) is the authoritative spec —\nread it for exact flags, JSON shapes, and error codes.\n\n### Reading rows vs. querying\n\nPick by how much querying power you need:\n\n- **Read rows directly** — `clay tables get`, `columns`, `rows list/get`. Works on\n  any table with no setup. Filtering is exact-match only (`rows list --filter col=value`,\n  ANDed together). Best for quick lookups and pulling cell values as-is.\n  `rows list` returns `data[].cells` keyed by column id — each cell is an object\n  (`{ \"cells\": { \"<f_id>\": { \"status\": ..., \"value\": ... } } }`), not a flat\n  `{ \"<f_id>\": <value> }` map (synced `query` cells are `{status, value}` objects too —\n  see below). Pages with `--limit` (1-100, default 20) and `--cursor`.\n- **Query live (ClayQL)** — `clay tables query-live`. Structured ClayQL against the\n  table's live Postgres data — no Enterprise sync required. Use `columns get` / `get`\n  to learn the schema before writing the query.\n- **Query (synced)** — `clay tables query`. Richer: range / contains / OR filters,\n  **joins across tables**, sorting, grouping, and paging past 100 rows. The table must\n  first be **enabled for querying** (below); requires API table sync (Enterprise).\n\nReach for `query-live` or `query` the moment a plain `rows list --filter` can't\nexpress what you need — a range or text match, an OR, a join, sorting, grouping, or\na large ordered pull. Prefer `query-live` when sync isn't enabled; use synced `query`\nfor multi-table joins and cursor paging (and for a complete large pull when sync is\navailable — `query-live` is capped at 100 rows per call; page with `LIMIT n OFFSET m`\nin `--query`). Otherwise a direct `rows list` is faster and needs no setup.\n\n**Bulk enrichment exception:** if `rows list` returns `truncated: true`, treat the result as one unfiltered, unordered sample of at most 20 currently retained passthrough rows. It accepts no cursor or filters, and completed rows may already have been deleted, so an empty sample is valid and the result is never a complete source listing. For migration, use `clay tables columns get` as the source of truth and inspect its sources to determine the origin. An Audiences-backed source includes `audience.entityType`, `segments[].id`, `isGlobal`, and `entityIdOnly`; a global Audience has `isGlobal: true` and no segment objects.\n\n### Row ordering\n\nBoth `rows list` and `tables query` return rows in a stable, consistent order that\nroughly tends to follow the order rows were created — but treat that as a loose\ntendency only, never a guarantee. It's approximate, the two commands don't necessarily\norder rows the same way as each other, and neither matches the order rows appear in\nthe Clay app. So don't rely on position for anything: don't map a row's position in\nthe output to what the user sees on screen, and don't read \"the first / most recent\nN rows\" from position. To find a **specific record**, filter by an identifier\n(`rows list --filter`, or a `tables query` / `query-live` filter) rather than relying\non position. Caller-controlled order is available on both query paths: `tables query`\nvia `order_by` (single page only — can't combine with cursor paging), and `query-live`\nvia ClayQL `ORDER BY` (also subject to the 100-row cap / `LIMIT`/`OFFSET` paging).\n\n### List tables\n\nDiscover navigation-visible tables and their ids. Each row carries a `queryEnabled` flag\nfor whether the table is enabled for querying.\n\n```bash\nclay tables list                                              # navigation-visible tables\nclay tables list --filter queryEnabled=true                   # query-sync-enabled only\nclay tables list --filter workbook.id=wb_123                 # tables in one workbook\nclay tables list --filter owner.id=1417322 --limit 50         # by owner\nclay tables list --limit 50 --cursor cursor_abc123            # pagination\n```\n\n### Run a live ClayQL query\n\n`clay tables query-live` runs ClayQL against the table's live Postgres data — no\nEnterprise sync required. Learn column names with `columns get` / `get` first; omit\nany `FROM` clause (the table comes from `<tableId>`):\n\n```bash\nclay tables columns get t_abc123\nclay tables query-live t_abc123 --query 'SELECT {{Name}}, {{ARR}} ORDER BY {{ARR}} DESC LIMIT 10'\n```\n\nClayQL is a whitelisted SQL subset — `clay tables query-live --help` lists the exact\nsupported grammar. The two most common traps: date ranges use literal ISO strings\n(`{{Close date}} >= '2026-06-01'`) because `NOW()`, `INTERVAL`, and date arithmetic are\nrejected, and `CAST` works only to `decimal`.\n\nSee `clay tables query-live --help` for output shape and errors. Output is\n`{ query, queryName?, rowCount, results }` — rows live under **`results`**, not `data`.\nEach call returns at most **100 rows**; page with `LIMIT n OFFSET m` in `--query` (bump\n`OFFSET` until a page returns fewer than `n` rows). Prefer this over synced `query` when\nAPI table sync isn't enabled, or for a quick single-table look. For a complete large\nexport when sync _is_ available, prefer synced `query` + cursor paging instead.\n\n### Enable a table for querying\n\n`clay tables query` can only read a table that's been **enabled for querying**. Toggle\nit with `update`:\n\n```bash\nclay tables update t_abc123 --query-enabled true    # { id, queryEnabled: true }\nclay tables update t_abc123 --query-enabled false\n```\n\n- **Not instant.** Enabling prepares the table in the background. A `query` run too soon\n  may return no/partial rows; retry after a short wait. Larger tables take longer.\n- **Limited per workspace.** Check `clay tables query-usage` (`{ used, limit }`); at the\n  cap, disable a table before enabling another. A `limit` of 0 means API table sync isn't\n  enabled for the workspace (see the availability note above).\n\n### Run a structured query\n\n`clay tables query` takes a **structured JSON query** that supports **joins across\nmultiple tables** and cursor pagination — so it's the right choice for complex queries\nor reading past 100 rows. The query is read from a file or stdin via `--query`.\n\n```bash\nclay tables query --query ./query.json | jq '.data | length'\necho '{\"tables\":[{\"id\":\"t_abc123\"}]}' | clay tables query --query - --limit 100\nclay tables query --query ./query.json --limit 100 --cursor cursor_abc123\n```\n\n- The `--query` payload is the query itself (what to fetch); pagination is separate.\n  Minimal shape: `{ \"tables\": [{ \"id\": \"t_...\" }] }`. Beyond `tables`, it may include\n  `filter`, `select`, `join`, `order_by`, `group_by`, and `field_mode`. Field references\n  can use ids or names. See `clay tables query --help` for the most up to date information.\n- Pagination is via flags: `--limit <n>` (1–100, default 50) and `--cursor <token>`.\n  When more rows remain, the response includes a top-level `cursor` — pass it back via\n  `--cursor` to fetch the next page.\n- Output is `{ data: [ { \"<fieldId>\": <cell> } ], cursor?, fields? }`, where each `<cell>`\n  carries a `status` (`success` / `error` / `running` / `queued` / `retry` /\n  `rate_limited` / `awaiting_callback` / `empty`) plus its value.\n\nTypical flow: `clay tables list --filter queryEnabled=true` to find the id → (if needed)\n`clay tables update <id> --query-enabled true` → wait, then `clay tables query`. To\nexport, serialize the JSON `data` array to CSV with a real writer (see below).\n\n### Saving query results to CSV\n\nAfter a `query-live` or `query` run, save the results locally as a CSV so the user can\naccess them — **`.results`** for `query-live` (responses are capped, so page with\n`LIMIT`/`OFFSET` and append until a page comes back short), **`.data`** for synced\n`query`, projecting\neach synced cell wrapper to its `value` with an explicit marker for error and pending\ncells (they carry no `value`, and a blank would misread as empty). Serialize with a\nkeyed CSV writer (for example `csv.DictWriter`, with fieldnames seeded from the\nresponse's `fields` plus any extra keys seen in rows), never by hand-writing delimiter\ntext, prefix string values starting with `=`, `+`, `-`, or `@`\nwith a single quote (leave numeric cells untouched), and write to a file like\n`./query-results.csv`.\n\n## Example: join across tables\n\n\"Join our Accounts and Contacts tables and pull the contacts at software companies\":\n\n**1. List tables to get their ids.**\n\n```bash\nclay tables list --filter queryEnabled=true | jq -r '.data[] | [.id, .name] | @tsv'\n# t_accounts123   Accounts\n# t_contacts456   Contacts\n```\n\n**2. Get each table's schema** so you know field ids, types, and the join key.\n\n```bash\nclay tables columns get t_accounts123\nclay tables columns get t_contacts456\n```\n\nSay `Accounts` has `f_industry` (text) and `f_account_id`, and `Contacts` has\n`f_company` that references the account.\n\n**3. Enable querying if needed** (see above — not instant), then run the structured\nquery. Use the field ids from step 2.\n\n```bash\nclay tables update t_accounts123 --query-enabled true\nclay tables update t_contacts456 --query-enabled true\n```\n\n```bash\necho '{\"tables\": [{ \"id\": \"t_contacts456\" }, { \"id\": \"t_accounts123\" }], \"join\": [{ \"table\": \"t_accounts123\", \"on\": { \"left\": \"f_company\", \"right\": \"f_account_id\" } }], \"filter\": { \"field\": \"f_industry\", \"op\": \"contains\", \"value\": \"software\" }}' | clay tables query --query - --limit 100 | jq '.data | length'\n```\n\n**4. Page past 100 rows** by passing the previous response's `cursor` back via\n`--cursor` until the response no longer returns one:\n\n```bash\necho '{\"tables\": [{ \"id\": \"t_contacts456\" }, { \"id\": \"t_accounts123\" }], \"join\": [{ \"table\": \"t_accounts123\", \"on\": { \"left\": \"f_company\", \"right\": \"f_account_id\" } }], \"filter\": { \"field\": \"f_industry\", \"op\": \"contains\", \"value\": \"software\" }}' | clay tables query --query - --limit 100 --cursor CURSOR_FROM_PREVIOUS_RESPONSE | jq -c '.data[]'\n```\n\n`clay tables query --help` lists the top-level query keys and pagination flags. Inner\nshapes (filter ops, join `on`, `select` / `group_by`) are in the developer docs:\nhttps://developers.clay.com/llms.txt\n\n## Investigating tables\n\nBeyond querying data, the CLI's read commands (`clay tables get`, `columns list|get`,\n`rows list|get`) support diagnostic work. These need no query sync. Each investigation\nis a focused skill:\n\n| The user wants…                                                    | Skill                 |\n| ------------------------------------------------------------------ | --------------------- |\n| \"what does this table do?\" / \"explain the {table} workflow\"        | `/tables-analyze`     |\n| \"trace {id}\" / \"where is {id} and what state is it in?\"            | `/tables-trace`       |\n| \"what's erroring in {table}?\" / \"show failed rows\" (no identifier) | `/tables-error-sweep` |\n| \"why is {id} stuck/failing?\" / \"where did {value} come from?\"      | `/tables-value-trace` |\n| \"why aren't new rows being added / why is the import stuck?\"       | `/tables-capacity`    |\n\n`/tables-analyze` and `/tables-value-trace` share the column-DAG extraction recipe in\n`tables-cli/dependency-catalog.md`.\n\n## Rebuilding a Table as a Workflow\n\nIf a user wants to convert their table logic into a Clay workflow (reusable, branching,\nor scheduled), use the `workflows` skill to rebuild the enrichment pipeline as\nconnected nodes.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}