Skip to main content

Tables & data

Define structured tables and manage their rows from chat. These scenarios use the table functions.

Reading flow: table-read (schema + views) → table-read-rows (a page of rows) or table-value-counts (counts per column value) → table-read-row (one row). Writing flow: table-row-create / table-row-update → table-read-row to confirm. Filters: TableRecordFilter.

Create a table and define its columns​

Goal — Create a table, then describe its row shape and metadata.

Example prompt

"Create a table Tasks. … Give it columns title (text, required) and status (text), and set the description to 'project task tracker'."

Functions used

  1. table-create — creates the table (with or without an initial schema).
  2. folder-list — finds the table id (t_…).
  3. table-update-interface — sets the schema and description.
  4. table-read — reads back the schema to confirm.

What you get — A table with a defined JSON Schema, ready for rows.

You can also pass the full schema directly on table-create in one step, e.g. {"type":"object","properties":{"title":{"type":"string"},"status":{"type":"string"}},"required":["title"]}.

Add a row, verify it, then update it​

Goal — Insert a record, confirm it persisted, and change a field later.

Example prompt

"Add a task titled 'Onboard new hire' with status 'open'. … Confirm it saved. … Now mark it 'done'."

Functions used

  1. folder-list — finds the table id.
  2. table-row-create — inserts \{ title: "Onboard new hire", status: "open" \}; returns a recordId.
  3. table-read-row — reads that recordId to confirm persistence.
  4. table-row-update — merges \{ status: "done" \} into the row.
  5. table-read-row — confirms the update.

What you get — A row created, verified, updated, and verified again — addressed throughout by its __record_id.

Browse and filter rows​

Goal — Review what's in a large table without loading everything.

Example prompt

"Show me the first 20 open tasks, sorted by title."

Functions used

  1. table-read — fetches the schema and any saved views.
  2. table-read-rows — pages through rows with pageSize: 20, a filter on status = open (or a saved viewId), and sortBy: "title".

What you get — A paginated slice of rows plus pagination metadata (totalRows, hasNextPage), so you can ask for the next page when needed.

Example filter: \{ "field": "status", "op": "eq", "value": "open" \} or shorthand \{ "status": "open" \}.

Create a saved view for open rows​

Goal — Persist a reusable filter (and optional column layout) so later reads can pass viewId instead of repeating the filter.

Example prompt

"On the Tasks table, create a view Open that only shows rows where status is open."

Functions used

  1. table-create — creates the table with a status column (or use an existing table).
  2. table-read — confirms schema and lists existing views.
  3. table-view-create — saves the view, e.g. filter: \{ "field": "status", "op": "eq", "value": "open" \}.
  4. table-read — confirms the new viewId appears under views.

What you get — A saved view you can pass to table-read-rows or table-value-counts via viewId.

Rank or summarize by column value​

Goal — Answer "how many per X" or "which X has the most rows" without loading every row.

Example prompt

"On Contracts, which seller has the most rows? Break down counts by VerkaeuferNr."

Functions used

  1. table-read — loads schema so column is a real property name.
  2. table-value-counts — column: "VerkaeuferNr"; returns groups sorted by count and topGroup for the leader.

What you get — Up to 100 distinct values with counts. Add filter or viewId when the question is scoped (e.g. only contracts ending next week).

Prefer table-value-counts over paging table-read-rows for distributions and rankings. Use table-read-rows when you need actual row payloads or to edit specific records.