You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
feat(tables): GA table_v2 and mark the v1 Table block legacy
Follows the gmail_v2 / github_v2 / confluence_v2 / cursor_v2 cutovers: v1
is renamed "(Legacy)", hidden from discovery, and points at its successor;
v2 drops the preview gate. Both edits must land together — the registry
check fails a sunset block whose replacedBy is still preview, verified by
splitting them locally.
v1's `triggers.enabled` deliberately stays true. Webhook execution gates
on it at runtime rather than on discovery, so flipping it would break every
deployed v1 table-trigger workflow. Both versions host the same
`table_new_row` trigger and dispatch is provider-keyed, so hiding v1
changes nothing for triggers.
No BLOCK_META_REGISTRY entry is needed — meta coverage is required only for
`category: 'tools'` blocks and both Table blocks are `category: 'blocks'`.
Docs regenerate from v2 now that v1 is skipped as a source, so the
generated page moves to the predicate grammar and cursor pagination. The
hand-written regions did not, and are updated here: the operator reference
and combining examples, the workflow guide's field walkthrough, and the
pagination advice — which previously told readers to advance an offset
while looping on nextCursor, mixing both versions.
Verified in the browser: the toolbar yields a `table_v2` block whose Query
Rows shows Cursor/Order; the Agent tool picker stores
`type: table_v2, toolId: table_query_rows_v2` and groups it under built-ins;
and a pre-existing v1 block still renders its own Offset/Sort fields behind
an amber legacy badge.
@@ -17,7 +17,7 @@ Tables allow you to create and manage custom data tables directly within Sim. St
17
17
-**No external setup**: Create tables instantly without configuring external databases
18
18
-**Workflow-native**: Data persists across workflow executions and is accessible from any workflow in your workspace
19
19
-**Flexible schema**: Define columns with types (string, number, currency, boolean, date, json, select) and constraints (required, unique)
20
-
-**Powerful querying**: Filter, sort, and paginate data using MongoDB-style operators
20
+
-**Powerful querying**: Filter, sort, and paginate data using a typed predicate grammar
21
21
-**Agent-friendly**: Tables can be used as tools by AI agents for dynamic data storage and retrieval
22
22
23
23
**Key Features:**
@@ -54,7 +54,7 @@ Tables are created from the **Tables** section in the sidebar. Each table requir
54
54
55
55
## Usage Instructions
56
56
57
-
Create and manage custom data tables. Store, query, and manipulate structured data within workflows. Query Rows returns every matching row when Limit is omitted and fails if the result exceeds 5MB.
57
+
Create and manage custom data tables. Store, query, and manipulate structured data within workflows.
58
58
59
59
60
60
@@ -204,29 +204,29 @@ Delete multiple rows that match filter criteria. Use with caution - supports opt
204
204
205
205
### Query Rows
206
206
207
-
Query rows from a table with filtering, sorting, and pagination
207
+
Query rows with a typed predicate filter and cursor pagination. A single filter can be a plain condition: `\{"field":"wins","op":"gte","value":10\}`. Use `all` (AND) or `any` (OR) groups for multiple or nested conditions. Operators: eq, ne, gt, gte, lt, lte, in, nin, like, ilike, nlike, nilike, contains, startsWith, endsWith, isNull, isNotNull, isEmpty, isNotEmpty. Order is a sort spec, e.g. `[\{"field":"wins","direction":"desc"\}]`. Omit limit to return the entire result — the query fails if it exceeds the 5MB budget (narrow with a filter or set a limit). With a limit, a page can end early at the byte budget: a non-null nextCursor means more rows exist — pass it back as cursor to continue; never infer completion from page size.
|`sort`| object | No | Sort order as \{field: "asc"\|"desc"\}|
216
-
|`limit`| number | No | Maximum rows to return. Omit to return every matching row; the query fails if the result exceeds the 5MB response budget. |
217
-
|`offset`| number | No | Number of rows to skip \(default: 0\)|
214
+
|`filter`| json | No | Predicate condition, e.g. `\{"field":"wins","op":"gte","value":10\}`. Use `all` or `any` for multiple conditions; omit to match all rows. |
215
+
|`columns`| array | No | Stable column IDs or table column names to include in each row data object. Omit or pass an empty array to return all columns. A reference that matches no column is ignored. |
216
+
|`order`| json | No | Sort spec, e.g. `\[\{"field":"wins","direction":"desc"\}\]`. |
217
+
|`limit`| number | No | Maximum rows per page. Omit to return the entire matching result — fails if it exceeds the 5MB budget. With a limit, pages may byte-cut early and set nextCursor when more remain. |
218
+
|`cursor`| string | No | Opaque pagination cursor returned by a prior query. Omit for the first page. |
218
219
219
220
#### Output
220
221
221
222
| Parameter | Type | Description |
222
223
| --------- | ---- | ----------- |
223
-
|`success`| boolean | Whether query succeeded |
224
+
|`success`| boolean | Whether the query succeeded |
224
225
|`rows`| array | Query result rows |
225
226
|`rowCount`| number | Number of rows returned |
226
-
|`totalCount`| number | Total rows matching filter |
227
-
|`limit`| number | Limit used in query |
228
-
|`offset`| number | Offset used in query |
229
-
|`nextCursor`| string | Non-null when more rows match past this page. A page can end early at the byte budget, so this — not a short rowCount — is what says whether more remain. To page, advance offset by rowCount and stop when this is null. |
227
+
|`totalCount`| number | Total rows matching the predicate \(computed on the first page only\)|
228
+
|`limit`| number | Limit used in the query |
229
+
|`nextCursor`| string | Cursor to fetch the next page, or null on the last page |
230
230
231
231
### Get Row
232
232
@@ -272,65 +272,95 @@ Get the schema configuration of a table
272
272
{/* MANUAL-CONTENT-START:notes */}
273
273
## Filter Operators
274
274
275
-
Filters use MongoDB-style operators for flexible querying:
275
+
A filter is a predicate. One condition is an object naming a column, an operator, and a value:
Order is a list of column/direction pairs, applied in order:
344
+
345
+
```json
346
+
[{"field": "createdAt", "direction": "desc"}]
347
+
```
348
+
325
349
Multi-column sorting:
326
350
327
351
```json
328
-
{
329
-
"priority": "desc",
330
-
"name": "asc"
331
-
}
352
+
[
353
+
{"field": "priority", "direction": "desc"},
354
+
{"field": "name", "direction": "asc"}
355
+
]
332
356
```
333
357
358
+
## Pagination
359
+
360
+
Omit **Limit** to return every matching row in one response; the query fails if the result exceeds 5MB, so narrow with a filter rather than guessing a limit.
361
+
362
+
With a **Limit**, results page. A page can end at the limit *or* at the 5MB byte budget, whichever comes first, so a short page does not mean the end. Pass the returned `nextCursor` back as **Cursor** to fetch the next page and stop only when `nextCursor` is null — never infer completion from the row count.
Copy file name to clipboardExpand all lines: apps/docs/content/docs/tables/using-in-workflows.mdx
+15-6Lines changed: 15 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -19,7 +19,7 @@ Throughout this page the running example is a `leads` table with columns `compan
19
19
20
20
A **Table block** performs one operation against one table. The **Operation** dropdown picks the action; the **Table** selector picks the target. The fields below those two change based on the operation you choose.
21
21
22
-
{/* VISUAL: Table block UI showing the Operation dropdown open, plus the conditional fields that appear for Query Rows (Filter Conditions, Sort Order, Limit, Offset). */}
22
+
{/* VISUAL: Table block UI showing the Operation dropdown open, plus the conditional fields that appear for Query Rows (Filter, Order, Columns to Return, Limit, Cursor). */}
23
23
24
24
The operations fall into three groups:
25
25
@@ -65,15 +65,24 @@ Later blocks read these by name: `<table1.rows>` is the array, `<table1.rowCount
65
65
]}
66
66
/>
67
67
68
-
**Filter Conditions**narrow the result. In the default **Builder** input mode you add rules visually: pick a column, an operator, and a value. Switch the **Input Mode** to **Editor** to write the filter as an object instead, using operators like `$eq`, `$gt`, `$contains`, and `$in`:
68
+
**Filter**narrows the result. You can build rules visually - pick a column, an operator, and a value - or write the filter directly as a predicate. One condition names a field, an operator, and a value:
**Sort Order** orders the result, again visually in Builder mode or as an object in Editor mode, for example `{ createdAt: "desc" }`. **Limit** caps how many rows come back (default 100, max 1000) and **Offset** skips rows for pagination.
74
+
Combine conditions with `all` (AND) or `any` (OR), and nest the groups for mixed logic:
75
75
76
-
{/* VISUAL: Filter Conditions and Sort Order builders, showing a status = unprocessed rule and a createdAt descending sort, with the equivalent Editor-mode object beside them. */}
**Order** sorts the result as a list of column/direction pairs, for example `[{"field": "createdAt", "direction": "desc"}]`. **Columns to Return** narrows each row to the fields a downstream step actually needs. **Limit** caps how many rows come back per page, and **Cursor** continues a previous page - see [Paginate large reads](#tips) below.
84
+
85
+
{/* VISUAL: Filter and Order builders, showing a status = unprocessed rule and a createdAt descending sort, with the equivalent predicate JSON beside them. */}
77
86
78
87
For a one-off point lookup, use **Get Row by ID** with a single `Row ID`. **Get Schema** returns the table's column definitions, useful when a workflow needs to inspect structure before writing. The full operator list lives in the [Table block reference](/integrations/table).
79
88
@@ -125,7 +134,7 @@ After the run, the table holds the enriched rows. The next run queries them agai
125
134
126
135
**Iterate row by row.** Wrap a Query → process → update cycle in a [Loop block](/workflows/blocks/loop) to handle one row at a time. This runs sequentially, slower than a batch update but useful when each row needs its own multi-step logic. Inside the loop the Agent reads the current row and an Update Row by ID writes its result.
127
136
128
-
**Paginate large reads.**Query Rows returns at most 1000 rows, and a page can also end early once its rows reach the response size budget — so a page may come back shorter than your **Limit** even when more rows match. Advance **Offset** by the `rowCount` you actually received, not by the Limit you asked for, and keep going while `nextCursor` is set. Stop when `nextCursor` is null. Stepping by the Limit instead skips whatever a short page left behind.
137
+
**Paginate large reads.**Omit **Limit** to get every matching row in one response; the query fails if the result exceeds 5MB, so narrow with a filter rather than guessing a limit. With a **Limit**, a page can end at the limit *or* early once its rows reach the 5MB budget — so a short page does not mean the end. Pass the returned `nextCursor` back as **Cursor**and keep going while it is non-null. Stop only when `nextCursor` is null; never infer completion from the row count.
Copy file name to clipboardExpand all lines: apps/docs/content/docs/workflows/triggers/table.mdx
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,7 +7,7 @@ import { BlockPreview } from '@/components/workflow-preview'
7
7
8
8
The **Table trigger** runs a workflow when a row is inserted or updated in a [Sim table](/tables). Use it to react to data changes — enrich a row when it's added, or send a follow-up when a status column flips.
'Create and manage custom data tables. Store, query, and manipulate structured data within workflows. Query Rows returns every matching row when Limit is omitted and fails if the result exceeds 5MB.',
- Use Columns to Return to keep only the fields a downstream step needs (e.g. ["col_email","name"]) — the 5MB budget counts only the returned columns, so narrowing columns is another way to fit a large table; leave it empty for every column.`,
0 commit comments