Tables

Functions for creating and editing workspace tables and their rows. A table's row shape is described by a root JSON Schema (an object with properties). Rows are addressed by a record id (__record_id).

Schema first: Call table-read for a tableId before table-read-rows, row writes, table-value-counts, or dashboard widgets that name columns — use only property keys from schema.properties (and saved views from the same result).

Typical reading flow: table-read → table-read-rows (paginated slice) or table-value-counts (distribution / ranking over all matching rows) → table-read-row for one row. Typical writing flow: table-row-create / table-row-update → table-read-row to verify. Saved views: table-read → table-view-create → table-read to confirm.

---

table-create

Create one workspace table. Only name is required. If schema is omitted, an empty object-shaped schema is applied — define columns later with table-update-interface.

Input

Field	Type	Required	Description
name	string	Yes	Display name for the table.
schema	object	No	Full root JSON Schema for the row shape.
description	string	No	Table description.
interfaceName	string	No	Interface/model name shown in the table editor.

Output

Field	Type	Description
tableId	string	Id of the new table (t_…).
table	object	\{ id, name \}.

---

table-read

Read one table's definition: JSON schema, interface name, description, metadata, active columns, saved filters, available views (id, name, filter), and row count. Does not return row payloads — use table-read-rows for rows.

Input

Field	Type	Required	Description
tableId	string	Yes	Table id (t_…).

Output

Field	Type	Description
table	object	Schema, interfaceName, description, metadata, activeColumns, filters, views[], and row count.

---

table-read-rows

Read a paginated slice of rows (like reading a section of a long file). Supports keyword search, structured filter, saved viewId, and sorting. Returns rows plus pagination metadata.

Input

Field	Type	Required	Description
tableId	string	Yes	Table id (t_…).
page	number	No	1-based page index (default 1).
pageSize	number	No	Rows per page (default 10, max 100).
search	string	No	Case-insensitive keyword search across all columns.
filter	object	No	TableRecordFilter (optional).
viewId	string	No	Saved view id (from table-read); its filter is AND-merged with filter.
sortBy	string	No	Column key to sort by.
sortOrder	enum	No	asc or desc (default asc when sortBy is set).

Output

Field	Type	Description
tableId	string	The table id.
rows	array	The page of rows.
pagination	object	\{ page, pageSize, totalRows, totalPages, hasNextPage \}.

---

table-read-row

Read one row by record id. Use after a create/update to confirm persistence.

Input

Field	Type	Required	Description
tableId	string	Yes	Table id (t_…).
recordId	string	Yes	Row id (__record_id, or the recordId returned on create).

Output

Field	Type	Description
tableId	string	The table id.
row	object	The row payload.

---

table-row-create

Insert one row. Match the column keys from the table's JSON schema. Do not pass __record_id.

Input

Field	Type	Required	Description
tableId	string	Yes	Table id (t_…).
data	object	Yes	Row fields keyed by schema property names.

Output

Field	Type	Description
tableId	string	The table id.
recordId	string	Id of the inserted row.
row	object	The inserted row plus __record_id.

---

table-row-update

Update one row by record id with a partial data object (merged into the existing row).

Input

Field	Type	Required	Description
tableId	string	Yes	Table id (t_…).
recordId	string	Yes	Row id (__record_id).
data	object	Yes	Partial fields to merge into the row.

Output

Field	Type	Description
tableId	string	The table id.
recordId	string	The updated row id.
row	object	The merged row plus __record_id.

---

table-view-create

Create one saved row view on a table (used by the data table UI and by table-read-rows / dashboard widgets via viewId). Call table-read first for schema and existing views.

Input

Field	Type	Required	Description
tableId	string	Yes	Table id (t_…).
name	string	Yes	View display name (unique per table).
filter	object	No	TableRecordFilter (same as table-read-rows). Omit when the view shows all rows.
visibleColumns	string[]	No	Schema property keys shown in the view. Omit or [] = all columns (same as the table UI).
editableColumns	string[]	No	Schema property keys editable in the view. Omit or [] = UI default (all visible columns).
isDefault	boolean	No	Set as default view. Default true when this is the first view on the table.

Output

Field	Type	Description
tableId	string	The table id.
viewId	string	New view id (UUID).
viewName	string	View display name.
isDefault	boolean	Whether this view is the table default.
filter	object | null	Row filter stored on the view, if any.
visibleColumns	string[]	Columns shown in the view.
editableColumns	string[]	Columns editable in the view.

---

table-value-counts

Count rows per distinct value of one column (SQL GROUP BY), sorted by count descending. Prefer this over paging through table-read-rows when you need distributions or rankings ("which status is most common", "which seller has the most contracts"). Call table-read first so column matches a schema property name.

Supports the same optional filter and viewId as table-read-rows (merged AND). Each call is standalone.

Input

Field	Type	Required	Description
tableId	string	Yes	Table id (t_…).
column	string	Yes	Schema property key to group by (e.g. status, VerkaeuferNr).
filter	object	No	TableRecordFilter; omit for the whole table.
viewId	string	No	Saved view id from table-read; AND-merged with filter.
limit	number	No	Max distinct values returned (default 100, max 100).

Output

Field	Type	Description
tableId	string	The table id.
column	string	The column grouped by.
groups	array	\{ label, value \}[] — distinct values with row counts, highest count first.
distinctValues	number	Number of groups returned (up to limit).
topGroup	object | null	The group with the highest count, if any.
filterApplied	object | null	Effective filter after merging view + filter.
viewIdApplied	string | null	View id used, if any.

---

table-update-interface

Update a table's definition: pass at least one of schema, name, description, or interfaceName. schema must be a full root JSON Schema object (not an array of fields).

Input

Field	Type	Required	Description
tableId	string	Yes	Table id (t_…).
schema	object	No	Full replacement JSON Schema object for rows.
name	string	No	New display name.
description	string	No	New description.
interfaceName	string	No	New interface/model label.

Output

Field	Type	Description
tableId	string	The table id.
name	string	The table name.
updatedAt	string	Update timestamp.

---

TableRecordFilter

Row filters for table-read-rows, table-view-create, and table-value-counts. Field names must exist on the table schema (table-read → schema.properties).

Shape

Single condition

{ "field": "status", "op": "eq", "value": "open" }

Combine conditions

{ "and": [
  { "field": "status", "op": "eq", "value": "open" },
  { "field": "priority", "op": "gte", "value": 3 }
]}

{ "or": [
  { "field": "status", "op": "eq", "value": "open" },
  { "field": "status", "op": "eq", "value": "in_progress" }
]}

Shorthand (one or more keys → implicit eq)

{ "status": "open" }

{ "status": "open", "assignee": "usr_abc" }

→ normalized to { "and": [ { "field": "status", "op": "eq", "value": "open" }, … ] }.

Operators (op)

op	Meaning
eq	Equals
neq	Not equals
lt	Less than
lte	Less than or equal
gt	Greater than
gte	Greater than or equal
in	Value in array (value must be an array)
exists	Field is present / non-null
contains	String contains (value is substring)

Saved views

A viewId from table-read applies that view's stored filter AND any filter you pass on the same call. Use views for reusable slices (e.g. "Open tasks"); use inline filter for one-off questions.