Lookup node

Transform

The Lookup node enriches every input row by querying a second connection using a value from that row as the lookup key. Match found: the second connection's fields are merged into the row. No match: the row is emitted, dropped, or routed to error depending on the failure policy.

When to use

• You have a rowset from one system and need to attach a few fields from another (customer id in Postgres → account name from Salesforce).
• You want per-row enrichment without the memory cost of pulling the entire second dataset into a Join build side.
• The lookup key values repeat and can be cached within the run so you don't hit the second system once per row.

Ports

Port	Direction	Kind	Notes
in	in	data	Rows to enrich.
out	out	data	Enriched rows.
error	out	control	Fires per-row when the lookup fails and onFailure: "error".
notify	out	control	Notification policy port.

Configuration

• Lookup connection — the second connection to query. Any read-capable connection (SQL family, Salesforce, Generic API GET) is eligible.
• Key expression — evaluated per row via the runtime expression engine. Plain field names (customerId) or function calls (LOWER(email), TRIM(id)) both work.
• Merge policy.
  • spread (default) — lookup fields take precedence on key collision with the input row.
  • preserveRow — input row fields take precedence.
• Failure policy.
  • emit (default) — emit the row unchanged when no match.
  • drop — skip the row on no match.
  • error — route the row to the error port on no match.
• Cache within run (default on) — memoize per-key results so repeat keys don't re-query the second connection.

Runtime behaviour

• Cache scope is one run; cross-run caching is the Cache node's job.
• The lookup connection is resolved via the same resolveConnection path every other node uses; the configKey argument is lookupConnectionId so the primary connectionId field is untouched.

Failure modes

• Missing lookup connection. The executor throws Lookup node "X": lookup connection is not configured. and the run fails. Wire the second connection in the Configure modal.
• Wrong key values. Wrap both sides in LOWER(...) or TRIM(...) if the sources normalize case or whitespace differently.

Related nodes

Join

Correlate two upstreams by key (edge-based)

Cache

Persist values across runs

Compute

Derive fields from what's already on the row