Cache node

Cache

What it does

The Cache node writes each incoming row into a named, in-memory cache, keyed by the fields you choose. Nodes later in the same run read the cache with lookup expressions such as CACHE_VALUE('countries', CACHE_KEY(code), 'name').

The cache lives for one run. The next run starts with an empty cache. To keep cached values between runs, turn on Caching on a Source or Load node and set its Scope to Persistent.

When to use

• A small reference set (countries, currency codes, owner names) is read once and looked up for every row of a larger stream.
• You want to enrich rows in a Transform, Filter or Router without a Join.
• You want to check whether a key exists before deciding what to do with a row.

Configure

Select the node and press Configure to open Configure Cache.

Save and Done stay unavailable while a required setting is missing. Cancel discards the changes made since the dialog opened or was last saved. A message confirms each save.

Cache identity

• Cache name: the name lookup expressions use as their first argument, for example countries.
• Scope: Execution. The cache is available to this run only.

Key & value fields

• Key fields: the columns that form the key. With no key field, each row is keyed by its position in the input.
• Value fields: the columns stored for each key. Leave blank to store the whole row.

Behavior

• Duplicate keys: what happens when a key is already in the cache.
  • Overwrite: the later row replaces the earlier one.
  • Skip: the first row is kept.
  • Error: the node fails.
• Pass-through:
  • Prime cache and pass-through: every input row continues on out.
  • Prime cache only: the rows are cached and nothing leaves on out.

Lookup preview

The panel shows the expressions to copy into a downstream Transform, Filter or Router. They update as you edit the name and fields.

Preview	Expression	Returns
Key	CACHE_KEY(code)	The key built from one or more values.
Value	CACHE_VALUE('countries', CACHE_KEY(code), 'name')	One stored field, or null.
Object	CACHE_GET('countries', CACHE_KEY(code))	The stored value for the key, or null.
Exists	CACHE_HAS('countries', CACHE_KEY(code))	true when the key is in the cache.

Ports

Port	Direction	Kind	Notes
in	in	data	Rows to write into the cache.
out	out	data	Every input row, unchanged, when Pass-through is Prime cache and pass-through.
error	out	control	Receives the input rows when the node fails, for example on a duplicate key with Error selected.

Examples

Enrich orders with a country name.

1. Connect Start to a Fork and set the Fork's Execution Order to Sequential (one source at a time).
2. On out1, a Source reads the countries table (code, name) into a Cache node: Cache name countries, Key fields code, Value fields name, Pass-through Prime cache only.
3. On out2, a Source reads orders into a Transform with a field country_name set to CACHE_VALUE('countries', CACHE_KEY(country_code), 'name'), then into a Load node.

In sequential order, sources run one at a time in the order they were added to the canvas, so add the countries Source first.

Flag unknown customers. Cache the customer master on customer_id, then in a Router send rows where CACHE_HAS('customers', CACHE_KEY(customer_id)) is false to a review branch.

Troubleshooting

Symptom	Cause	What to do
Lookups return null on every row	The cache name differs, or the reading branch ran before the Cache node.	Check the cache name in the expression. Run the branches in sequence with a Fork set to Sequential.
Lookups return null for some rows	The key values differ, for example us and US.	Normalise the key in both branches with UPPER or TRIM.
The node fails with a duplicate key error	Duplicate keys is set to Error and two rows share a key.	Dedupe the input, or choose Overwrite or Skip.
Nothing reaches the next node	Pass-through is Prime cache only.	Choose Prime cache and pass-through.

Related nodes

Fork

Run sources one at a time so the cache is filled first

Lookup

Enrich rows from a second connection

Transform

Read cached values in a field expression