Lookup table

A lookup table is a read-only view of a query embedded in a document. Unlike a spreadsheet (document-local) or a registration table (writes back), a lookup table just shows the query's results, and re-runs whenever the data it reads is written.

Insert it by typing / and picking Lookup Table from the Data category.

When to use it

Use a lookup table when you want to:

• Reference data that lives in an environment without copying it into the doc.
• Show a live view of "all animals in DLA-7 with baseline weight > 24 g" inside the protocol document so the team can see them while running the study.
• Build a study summary that always reflects the freshest results.
• Feed a chart block, which can point at a lookup table as its data source.

Don't use it when you need users to enter data, use a Registration table instead.

What you see

The columns are whatever the query returns. Cells render by column type:

• Reference cells and any UUID value become a chip showing the object's display ID.
• File cells become a file chip; clicking it opens that file's page.
• Booleans read Yes / No, tinted.
• Numbers are locale-formatted with the column's unit symbol (24.8 g), dates and datetimes are locale-formatted, JSON is stringified, and empty cells show a dash.
• Multi-value columns render as a list of chips.

Rows themselves are not clickable, and there is no side panel. File chips are the only clickable cell content; a reference chip shows the display ID but does not link anywhere. Results are paginated, 25 rows to a page, with Previous / Next controls and a total count in the footer.

Two ways to populate it

1. Saved Query

   Best for reuse. Pick a saved query from the searchable library, which spans every environment and fills the environment in for you. Updating the saved query updates every document that uses it.

2. Build Query

   For one-off views. Pick a starting table, then open the relations builder to traverse into related tables, including result schemas, and return matching rows. The query definition is stored on the block.

Documents saved before this change may still be in the legacy Results mode, an aggregation over a single result schema. It is soft-retired: the toggle only appears for blocks already using it, and new blocks should build a traversal query across the result schema instead.

When the query's root table is project- or entry-scoped, a Scope control appears so the block can be limited to this document, this project, or everything.

A realistic example

In a DLA-7 PK/PD study document:

Animals receiving 30 mg/kg with baseline weight > 24 g

animal_id	sex	strain	baseline_weight_g	study_group
ANM-019	F	C57BL/6	24.1	GRP-4
ANM-022	F	C57BL/6	25.6	GRP-4
ANM-024	F	C57BL/6	24.8	GRP-4

This lookup table sits alongside the protocol so the bench scientist can see at a glance which animals match the inclusion criterion. If a fourth animal's weight is updated tomorrow, the table updates everywhere it's embedded.

Refreshing

Refresh is not something you configure. The block subscribes to the data sources its query reads, the root table, any joined result schemas, and the environment as a fallback, and re-runs the query when a registration grid, data form, well plate, collaborator or the AI assistant writes to one of them. A manual refresh button also sits in the block header whenever a query is configured.

Which columns come back, how they are filtered and in what order, all live in the query definition. The block itself has no column-visibility, sort or row-limit setting.

In templates

A lookup table configured inside a template does not execute there. It shows "Query configured, results load when a document is created from this template", and every document spawned from that template runs the query against live data on open.

Tips

What's next