developer guide
Join Two Data Grids on a Key
A grid can read a second one as a lookup and carry its columns beside its own, left or inner, on a shared key. The joined result behaves like any other grid and follows the filter of the grid it came from.
Developer guide › Sources and pushdown › Join Two Data Grids on a Key
Joining two grids
Two grids holding their own data, and a third showing where they meet. Both sides stay live.
Bringing an owner's fields across
source: {
mode: 'derived',
from: sites,
join: {
with: owners,
on: { left: 'ownerId', right: 'id' },
type: 'left',
select: ['name', 'tier'],
prefix: 'owner', // owner.name, owner.tier
},
}| Option | Does |
|---|---|
| on | One field name when both sides use it, or { left, right } when they differ. |
| type | inner keeps only rows that matched; left keeps them all. |
| select | Which of the partner's fields to bring across. All of them by default. |
| prefix | Renames the brought-across fields, for when both sides have a name worth keeping. |
| follow | Which of the partner's rows to read: all by default, or filtered. |
A left join is usually the one you want. An inner join quietly drops the
rows that did not match, and those are often the finding: the site with no owner, the payment
with no invoice. left keeps them visible with the partner's fields empty, so the
gap is something you can see and sort by rather than something you have to notice is
missing.
First match wins. The join is a lookup, not a cross product: a row on the left produces exactly one row out, so a grid of ten thousand rows stays a grid of ten thousand rows and cannot silently multiply.
Both sides are live. A change on either grid updates the join, and it is patched from whichever side changed rather than rebuilt.