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 log entry (equivalent to a drop, not an error); 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.

Values are stored as JSON by cache_set and round-tripped through json.Unmarshal on read: a string stored as a string comes back as a string, a number comes back as float64, a boolean comes back as bool, a JSON object comes back as map[string]any, and a JSON array comes back as []any. The original Go type is preserved as closely as the JSON round-trip allows.

The backing store is NATS JetStream KV with MemoryStorage. Cache 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
When blocked:203.0.113.5 is absent, the log entry is silently dropped (not an error)...	{}

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 }