Lookup fields: a window onto a linked value

A lookup shows, on this table, a field that lives on the records at the other end of a link. The demo shop's Orders table has Customer email: each order shows its customer's address without anyone copying it, and when the customer record changes, every order showing it is already right. One fact, one home, many windows.

Make one

A lookup needs the link to exist first — a table with no link fields will say so and send you to add one. It needs the link filled, too: a lookup reads across the link, so it shows a value wherever the link cell points at a record, and nothing wherever the link cell is empty. If the values that would match are already sitting in a text column, linked records turns that column into a filled link in one pass.

1. Add a field and choose Lookup.
2. Through — pick the link field to look across.
3. Field — pick the field on the linked table to show.

The lookup takes its type from the field it surfaces: an email lookup filters as text, a price lookup as a number, a date lookup as a date. There's a third, optional row — "Only linked records that match feed this lookup" — a real condition set on the linked table, for things like the email of the linked contact, but only contacts marked primary.

All three choices are editable later; changing what a lookup shows is an ordinary edit, not a delete-and-re-add.

What it can surface

Text, number, date and checkbox fields come through as themselves. Richer fields come through as their display form: a select as its choice names, a member as the person, an attachment as real read-only thumbnails, and a link as clickable record chips — a window through two tables. What a lookup can't surface is another lookup or rollup; there are no chains in v1, and the editor won't offer them.

Presentation travels with the value: a lookup of a currency field reads $45, not 45.

Read-only, and a list when the link is many

A lookup is read-only everywhere — the cell, the record panel, the API. That's the point rather than a restriction: the value has an owner, and you edit it there. Chips and thumbnails a lookup surfaces still open and preview; they don't edit.

Through a single link the lookup shows one value. Through an allow many link it shows one value per linked record — an order's lookup of plant prices reads 45, 28. Records in the trash drop out of the window immediately and return if restored.

Filtering, grouping and sorting

When a lookup surfaces a plain value — text, number, date, checkbox — you can filter by it like a real column: Customer email contains @gmail. works in views and over the API. When it surfaces a select, link or attachment, the value is display text assembled at read time, and it can't be filtered; the field offers no operators at all.

Grouping is a different question and the answer is yes: a grid groups by a lookup, on the value it borrows. A lookup that borrows several values files its record under the whole set — an order whose plants look up Full sun, Bright indirect sits in one group of that name.

Lookups don't sort, whatever they surface — there's no stored column to order by. If you need to sort by a borrowed number, that's a job for a rollup… which also can't sort, or for storing the value on this table deliberately.

Guarded, both ends

Tabla refuses, by name, anything that would orphan a lookup: deleting the link it rides (…the lookup/rollup field "Customer email" rides this link. Delete "Customer email" first.), deleting the field it surfaces, or changing that field's type out from under it. Adjust or delete the lookup first, then the rest follows.

Over the API

A lookup reads under its own field name, shaped by what it surfaces — here, plain text:

"Customer": [{ "id": "rec_gs8683t5vvcn", "display": "Nour El-Sayed" }],
"Customer email": "nour.elsayed@example.com"

Writing to it is refused: it's computed, there is nothing to assign. See /docs/api.

When a rollup is the field you meant

A lookup shows values; it never does arithmetic on them. The moment the question is how many, how much, latest across the linked records, you've left lookup country — that's a rollup. The rule of thumb, argued properly in lookup vs rollup: one → one, lookup; one → many, rollup.