Query table rows
query_table_rowsRead rows from a table: a filter tree (and / or / not over field clauses, one hop through a relation allowed), text search, sort, a saved view, a keyset-paginated row page, group headers with counts, and calculations (sum, avg, count, min, max, …) over the whole filtered set — all answered over the SAME rows, so a total beside a page is a total of that page’s set. Each row comes back as typed properties keyed by field key: select options carry their labels, related rows and files come back as counted items, and a computed property carries a `stale` flag when a recomputation is outstanding. Pass rows: false for totals only. A question the schema cannot answer is refused with the offending path named.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
tableId | string | required | Table ID — get from list_tables |
filter | unknown | optional | Filter tree. A clause is { field, op, value } where field is a field KEY (or one hop through a relation as "relation.field") and op is one of eq, neq, gt, gte, lt, lte, in, nin, contains, starts_with, ends_with, between, is_null, is_not_null. Combine with { logic: "and" | "or", conditions: [...] } or { logic: "not", condition }. A select field compares by option id; a date takes "YYYY-MM-DD", a range { start, end }, or a relative preset { rel: "this_month" }. |
search | string | optional | Case-insensitive match over the primary field and text fields |
viewId | string | optional | Answer within a saved view: its filter is merged in and its sort used when none is given |
sort | object[] | optional | Sort order as [{ field, direction }] (default: the promoted date field, then row id) |
fields | string[] | optional | Field keys to return; omit for every field |
deleted | boolean | optional | Read the trash instead of live rows |
rows | boolean | object | optional | The row page: { cursor?, limit? } (max 500), or false to skip rows and answer groups / calculations only |
groups | object | optional | Group headers with counts and per-group calculations over the filtered set |
calculations | object | optional | Calculations over the WHOLE filtered set by field key, e.g. { amount: "sum", date: "max" }. Values: count_all, count_values, count_empty, count_unique, percent_empty, percent_filled, sum, avg, median, min, max, range, earliest, latest, date_range. |
Example call
The tool call an MCP client sends (required arguments shown with placeholder values).
{"tool": "query_table_rows","arguments": {"tableId": "tableId_123"}}
Use this tool in
Related Tables tools
list_tablesList the tables in the workspace (id, name, kind — typed or custom — resource type, fields, row count, schema/revision versions).Get tableget_tableGet one table by id: its full field set (key, label, kind, display format, select options, whether the field is feed-owned and whether it can be written), the fields that form row identity, the promoted primary/date/amount bindings, row count, and its schema badge.Create tablecreate_tableCreate a table in the workspace.Update tableupdate_tableUpdate a table’s METADATA — name, icon, retention policy.