---
title: "Formulas and relations"
description: "Connect tables with linked records, pull values across tables with lookups and rollups, and compute expressions with formulas."
canonical: "https://grid82.com/docs/build/formulas-and-relations"
updated: "2026-11-20"
---

# Formulas and relations

Grid82 links tables using relational junction storage rather than duplicating strings. From a link field, you can pull values with **lookups**, aggregate child records with **rollups**, and compute record values with **formulas**.

## Link to table (`link`)

Creating a `link` field on one table (for example **Deals -> Company**) automatically creates its symmetric mirror field on the target table (**Companies -> Deals**).

- **Cardinality per side.** Set `config.single: true` on the side that links to at most one parent (one Company per Deal), while leaving the reverse side multiple (many Deals per Company).
- **Symmetric cleanup.** Deleting either half of a link deletes its mirror automatically.
- **Record filters (`config.filter`).** Restrict which target records can be linked (for example, active companies only). The engine enforces `config.filter` on API and UI writes alike and returns a validation error on invalid links. Remember that a link filter checks validity; it is not a security boundary.
- **API shape.** Reads return `[{ id, label }]` (using the target's primary field as `label`). Writes replace the record's visible links with an array of record IDs (`["rec_..."]`).

## Lookups and rollups

Both **`lookup`** and **`rollup`** traverse an existing `link` field (`via`) to read a `target` field on the linked table:

- **`lookup`.** Returns an array of the target field's values across linked records.
- **`rollup`.** Reduces the target values with one aggregation function: `count`, `countUnique`, `countEmpty`, `countFilled`, `sum`, `avg`, `min`, `max`, `earliest`, `latest`, `and`, `or`, `concat`, `concatUnique`. (Use `rollup` with `fn: "count"` to count linked records.)

Both accept three optional refinements applied in sequence:

1. **`conditions`:** A filter tree evaluated on the target table (for instance, count only deals where `Stage = "Won"`).
2. **`sorts`:** Up to 3 `{ fieldId, desc }` sort rules on the target table.
3. **`limit`:** `{ take: "first" | "last", count }` applied after sorting to pick, for example, the 3 most recent activities.

### Permission visibility on lookups and rollups

Because a rollup represents a single fact about a record (such as total contract value), a user whose access to the **target table** is filtered to only some records cannot read the lookup or rollup field at all. Showing a partial sum would leak the existence of hidden records by comparison.

> **Note**
>
> If a role needs a lookup or rollup column, grant that role unscoped read access to the target table (or avoid placing restricted columns inside the rollup). Link fields themselves behave normally and list only the linked records a user can see.

## Formulas (`formula`)

A `formula` field calculates a value dynamically on each record using Grid82's Excel-style expression engine (stored in `config.source`).

```text
IF(AND({fld_r8wj3nd5ya6c} = "Won", {fld_7qk2mv9xp4ht} > 1000), {fld_7qk2mv9xp4ht} * 0.1, 0)
```

- **Reference fields by ID.** Inside the formula source, fields use `{fld_...}` placeholders. The Studio editor renders them with human-readable names, so renaming a field never breaks formulas.
- **Display semantics.** Inside formulas, select fields evaluate to their display label (`"Won"`), user fields evaluate to names, and multi-value lists join with `, `.
- **Operators.** Use `&` for text concatenation and `+` for arithmetic (`+` rejects text operands).
- **Limits.** Formulas allow up to 2,000 characters, 10 nesting levels, and up to 3 relation hops. Formulas are type-checked on save and return the exact character offset of any type error. Call [`fields.functions`](/docs/builder-api/fields/functions) for the complete function catalog.
