Lookup Join Node
Join two input streams on one or more key fields
Last updated 24 Jun 2026
The Lookup Join node merges records from two upstream inputs by matching on configured key fields. It is a dual-input node: the default input is the left (primary) dataset and the lookup input is the right (reference) dataset.
When to Use
Use Lookup Join when you have a reference dataset (e.g. company firmographics, territory assignments) and want to enrich your primary records with data from it, matched on one or more shared keys.
Ports
- default — left/primary input.
- lookup — right/reference input.
Configuration
| Field | Type | Description |
|---|---|---|
keys | array | Key mappings of { leftField, rightField }. At least one is required |
joinType | inner | left | right | full | Join type |
multipleMatches | first | last | all | How to handle multiple right-side matches for one left row |
rightPrefix | string | Optional prefix applied to right-side field names to avoid collisions |
includeFields | string[] | Optional list of right-side fields to include (all if omitted) |
Example
Enrich lead records with territory data, keyed on differing field names:
keys:
- leftField: account_id
rightField: id
joinType: left
multipleMatches: first
rightPrefix: "territory_"
includeFields: [region, owner, tier]
Left input: [{ account_id: "A1", name: "Acme" }]
Lookup input: [{ id: "A1", region: "EMEA", owner: "Jane", tier: "enterprise" }]
Output: [{ account_id: "A1", name: "Acme", territory_region: "EMEA", territory_owner: "Jane", territory_tier: "enterprise" }]
Notes
- Right-side join-key fields are excluded from the output by default — the left key already carries the matching value (and is kept under the left field's name).
- With
joinType: left, unmatched primary records are still emitted with null lookup fields;inneremits only matched rows;right/fullalso surface unmatched right rows. - Multiple key mappings form a composite key (all must match).
- The lookup input is loaded into memory before joining begins.
Related articles
Still stuck? Browse the FAQ or contact us.