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.

Leave the name blank and the lookup names itself after what it shows — Status (from Projects) — so a table with three lookups through three different links reads as three different things rather than Field 7, 8 and 9. Type a name and yours stands.

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 own coloured chips — the same colours, in the same order, as in the table it came from — a member as the person, an attachment as real read-only thumbnails, and a link as clickable record chips: a window through two tables.

A lookup can surface another lookup, one level deep. Orders links to Customers, Customers looks up its city's name from Cities, and Orders can look up that — so the city reaches the order without a link between them. The chain stops at two: the lookup you point at has to read a plain field itself, and one that already reaches through another lookup isn't offered. That limit is the feature, not a shortfall — a chain that could go on forever is a chain that can loop back on itself, and two levels cannot. A chained lookup takes its type from the field at the far end (a date two tables away is still a date), and any filter on the lookup in the middle still applies. A rollup can't be surfaced: it adds many records up rather than pointing at one.

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.