Tables
How an item holds rows in a table its type declares, with typed columns, totals and changes you can undo.
Some things a person keeps are many small records under one heading: the bottles in a wine cellar, the lines of a budget, the messages of a conversation. Making each one an item would bury the item list. Instead, one item holds them as the rows of a table, and the item stays one thing to find, tag, link and move to the bin.
Where a table comes from
A type declares the tables its items hold, each with named, typed columns. core.conversation declares a messages table, so every conversation holds its messages as rows, in the order they were sent.
A core.table item chooses its own columns. It's a table a person keeps by hand, such as a reading log or a list of contacts, and its columns property holds the column definitions. Other items of that type can hold quite different tables.
A column has a type, such as string, integer, date, enum or item, which holds the ID of another item. A column can be required, can say how it adds up (sum, average, min, max or count), and can be searchable, so search finds the rows that mention a word. Define a type shows how a type declares one, and the contract's tables chapter has the limits.
A row is not an item
A row is its id, its values keyed by column, and when it last changed. It has no version, tags, edges or history of its own. It belongs to its item: a key that may read the item's type reads its rows, a key that may write the type writes them, and an item in the bin takes its rows with it.
Writing rows leaves the item's own version and updated_at alone. It moves the item's last_activity_at instead, so a list sorted by last_activity_at puts the conversation with the latest message first.
Write rows in batches
Every write to a table is a batch: a list of operations on one table of one item, applied in order, all or none.
putcreates a row, or replaces the whole row itsidnames.patchsets the columns it names and leaves the others.deleteremoves a row.
This batch adds a bottle of Chablis to a cellar and corrects the count of another wine:
POST /items/01a1f141-38d8-7757-b9c1-b2e60b992c63/tables/table/rows
Authorization: Bearer <key>
Content-Type: application/json
{
"operations": [
{ "op": "put", "values": { "wine": "Chablis Premier Cru", "vintage": 2021, "bottles": 3 } },
{ "op": "patch", "id": "01a1f141-4d6a-7062-b447-f6ee16739f0e", "values": { "bottles": 2 } }
]
}{
"batch": "01a1f141-ad55-7133-88ce-e6fd8377da7f",
"last_activity_at": "2026-11-19T00:42:55.701Z",
"results": [
{ "id": "01a1f141-ad55-7133-88ce-e6fe9959a339", "outcome": "created" },
{ "id": "01a1f141-4d6a-7062-b447-f6ee16739f0e", "outcome": "patched" }
]
}The item is a core.table, so its one table is named table. When two writers change the same row, the later write wins: a row has no version to compare. Send an Idempotency-Key with a batch you may retry, so a repeat is answered rather than written twice. From the CLI, marfa rows write sends a batch, and marfa rows put, marfa rows patch and marfa rows delete send one operation.
Take a batch back
Each table keeps a change log: every batch that changed a row, with each row as it stood before. Undoing a batch puts those rows back, as a new batch of its own, so undoing the undo redoes it. An undo is refused with undo_conflict when a later batch has changed one of the same rows since; undo that one first.
The log keeps each batch for row_log_retention_days, 30 days by default. It's for taking back a recent mistake, not a history: marfa rows batches lists what it holds, and marfa rows undo takes one back.
Read rows
A table's rows come a page at a time, in the order of the column the table names in order, or by row ID where it names none. A read can filter and sort by any column with the same filter grammar items use, written as values.<column>.
Totals answer how many rows a filter selects and what each column that adds up comes to, without reading the rows. For the cellar, that's how many bottles there are in all:
marfa rows totals 01a1f141-38d8-7757-b9c1-b2e60b992c63 tablerow_count 3
totals.bottles.sum 11Find and follow rows
Search matches rows as well as items. A hit for a row names its item and, beside it, the table, the row and the column the match came from.
A link can point at one row, written [[Wine cellar#^<row id>]] in a note's text. It stays a link to the item, with the row named.
A batch that changes rows sends one rows.changed event, with each row as the batch left it, so an app that follows the event stream keeps its rows current without reading the table again. A device can hold a table in its working copy the same way, whole, and queue batches while offline.
Agents read and write rows through the MCP tools marfa_read_rows and marfa_write_rows. An archive carries every row.