Cache Get

State Management Flow Control

Synopsis

Reads a key from a cluster-shared NATS JetStream KV store and writes the decoded value into a specified log-entry field, with configurable behavior when the key is absent.

Schema

- cache_get:
    key: <string>
    target_field: <ident>
    bucket: <string>
    ttl: <integer>
    default_value: <string>
    description: <text>
    disabled: <boolean>
    if: <script>
    tag: <string>
    on_success: <processor[]>
    on_failure: <processor[]>
    ignore_missing: <boolean>
    ignore_failure: <boolean>

Configuration

The following fields are used to define the processor:

Field	Required	Default	Description
key	Y		Key to read. Mustache template evaluated against the log entry; an empty resolved key is an error
target_field	Y		Log-entry field where the decoded cache value is written
bucket	N	default	Cluster-shared KV bucket name
ttl	N	3600	Bucket TTL in seconds (see Details)
default_value	N		Written to target_field when the key is not found in the cache
description	N		Explanatory note
disabled	N	false	Disable this processor without removing it from the pipeline
if	N		Condition expression; processor runs only when the expression evaluates to true
tag	N		Identifier for this processor instance
on_success	N		Processors to run after a successful read
on_failure	N		Processors to run when the processor errors
ignore_missing	N	false	When the key is absent and no default_value is set, silently skip the log entry instead of erroring
ignore_failure	N	false	Continue pipeline processing when the processor errors

When the requested key is not found, the processor applies the following precedence: if default_value is set, write it to target_field and continue; else if ignore_missing is true, skip the processor, leaving target_field untouched (no error, no on_failure); else return an error subject to on_failure and ignore_failure.

Details

cache_get retrieves a single key from a NATS JetStream KV bucket and writes the value into target_field on the current log entry. The key field supports mustache templates ({{field.subfield}}) resolved against the log entry at execution time. An empty resolved key is always an error regardless of ignore_failure.

cache_set stores each value as JSON, and cache_get reads it back the same way. A string comes back as a string, a boolean as a boolean, an object as an object and an array as an array. A number always comes back as a floating-point number, even when it was stored as an integer.

The cache is a NATS JetStream key-value bucket held in memory. Its contents are not persisted to disk and are lost if the NATS server restarts. Buckets are created automatically on first reference; no administrative setup is required.

TTL is a bucket-level property with first-writer-wins semantics: the first processor to reference a bucket establishes its TTL. Subsequent processors specifying a different ttl value against an already-created bucket have no effect. The default TTL is 1 hour (3600 seconds). A value of 0 resolves to the 1-hour default; a negative value is a hard configuration error. To change TTL on an existing bucket, delete and recreate it with nats kv del <bucket>.

Bucket name is the shared-state scope: any pipeline on any cluster node referencing the same bucket name sees the same key space. Behavior is identical on single-node and multi-node deployments.

Each cache_get operation is a single NATS round-trip with a 2-second timeout. There is no local in-process cache — every read reflects canonical NATS state at the moment of execution. A ErrSkippedEntry result (from ignore_missing) is passed through as-is and does not trigger on_failure.

Use cache_set to write keys and cache_delete to remove them.

Examples

Basic Read into Target Field

Reading a cached session state into the log entry...	{ "session.id": "a3f9d7c1", "event.action": "file_access", "source.ip": "10.4.12.55" } - cache_get: key: "session:{{session.id}}" target_field: session.state
Writes the cached value into session.state...	{ "session.id": "a3f9d7c1", "event.action": "file_access", "source.ip": "10.4.12.55", "session.state": "active" }

Default Value on Cache Miss

Providing a fallback risk level when no cached score exists for the user...	{ "user.name": "newuser", "event.action": "login", "source.ip": "192.0.2.14" } - cache_get: key: "risk:{{user.name}}" target_field: user.risk_level bucket: risk-scores default_value: "unknown"
Key risk:newuser not found; default_value is written to user.risk_level...	{ "user.name": "newuser", "event.action": "login", "source.ip": "192.0.2.14", "user.risk_level": "unknown" }

Silent Skip on Missing Key

Skipping log entries silently when no blocked-IP record exists for the source...	{ "source.ip": "203.0.113.5", "event.type": "network_connection", "destination.port": 443 } - cache_get: key: "blocked:{{source.ip}}" target_field: threat.category bucket: blocked-ips ignore_missing: true
Key blocked:203.0.113.5 is absent; the processor is silently skipped, threat.category is not written, and the log entry continues unchanged...	{ "source.ip": "203.0.113.5", "event.type": "network_connection", "destination.port": 443 }

Typed Round-Trip (Number and Object)

Reading back a risk score stored as a number and an alert context stored as an object...	{ "user.name": "jsmith", "event.action": "privilege_escalation" } - cache_get: key: "risk:{{user.name}}" target_field: user.cached_score bucket: risk-scores
Number stored by cache_set comes back as float64; object stored by cache_set comes back as map...	{ "user.name": "jsmith", "event.action": "privilege_escalation", "user.cached_score": 87 }