Cache Set

State Management Flow Control

Synopsis

Writes a key-value pair to a cluster-shared NATS JetStream KV store, making the value available to any pipeline on any node via cache_get.

Schema

- cache_set:
    key: <string>
    value: <string>
    value_field: <ident>
    bucket: <string>
    ttl: <integer>
    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 write. Mustache template evaluated against the log entry; an empty resolved key is an error
value	Y*		Literal or mustache-template string written as the value. Takes precedence when both value and value_field are set
value_field	Y*		Copy the value from this log-entry field into the cache. Preserves the original field type (number, boolean, object, array)
bucket	N	default	Cluster-shared KV bucket name
ttl	N	3600	Bucket TTL in seconds. Bucket-level, first-writer-wins (see Details)
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 write
on_failure	N		Processors to run when the processor errors
ignore_missing	N	false	Continue silently when value_field is missing from the log entry
ignore_failure	N	false	Continue pipeline processing when the processor errors

* Exactly one of value or value_field is required. When both are set, value takes precedence.

Details

cache_set writes a single key-value entry to a NATS JetStream KV bucket. The key and the value field both support mustache templates ({{field.subfield}}) resolved against the current log entry at execution time. An empty resolved key is always an error regardless of ignore_failure.

When value_field is used instead of a literal value, the field's original type is preserved through JSON serialization: a number stays a number, a boolean stays a boolean, an object stays an object, and so on. A cache_get reading the key back will receive the same Go type via JSON round-trip (number→float64, bool→bool, object→map, array→array).

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 is treated as unset and 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>, then allow the pipeline to recreate it.

Bucket name is the shared-state scope: any pipeline on any cluster node referencing the same bucket name accesses the same key space. Use distinct bucket names to isolate independent caches. Behavior is identical on single-node and multi-node deployments.

Each cache_set operation is a single NATS round-trip with a 2-second timeout. There is no local in-process cache — every write goes directly to the NATS server. If JetStream is not yet initialized (early startup or VMMQ not yet connected), the processor returns an error subject to ignore_failure and on_failure.

Use cache_delete to remove a key and cache_get to read it back in a later pipeline stage.

Examples

Basic Literal Value

Recording a session state for a known source IP...	{ "source.ip": "10.4.12.55", "event.action": "session_start", "session.id": "a3f9d7c1" } - cache_set: key: "session:a3f9d7c1" value: "active"
Writes "active" to key session:a3f9d7c1 in the default bucket...	{ "source.ip": "10.4.12.55", "event.action": "session_start", "session.id": "a3f9d7c1" }

Copying a Typed Field to a Named Bucket

Caching a user risk score (number) into a dedicated risk-scores bucket with a 10-minute TTL...	{ "user.name": "jsmith", "risk.score": 87, "event.type": "authentication" } - cache_set: key: "risk:jsmith" value_field: risk.score bucket: risk-scores ttl: 600
Writes integer 87 to key risk:jsmith in bucket risk-scores; type preserved on read-back...	{ "user.name": "jsmith", "risk.score": 87, "event.type": "authentication" }

Templated Key from Log Fields

Building a composite cache key from two log fields using mustache templates...	{ "source.ip": "203.0.113.42", "user.name": "bwilliams", "alert.id": "THR-20910", "threat.level": "high" } - cache_set: key: "alert:{{source.ip}}:{{user.name}}" value_field: threat.level bucket: active-threats ttl: 1800
Writes "high" to key alert:203.0.113.42:bwilliams in bucket active-threats...	{ "source.ip": "203.0.113.42", "user.name": "bwilliams", "alert.id": "THR-20910", "threat.level": "high" }

Conditional Write

Writing to cache only when an alert severity exceeds the critical threshold...	{ "source.ip": "198.51.100.7", "alert.severity": 9, "alert.category": "lateral-movement" } - cache_set: key: "blocked:{{source.ip}}" value_field: alert.category bucket: blocked-ips ttl: 3600 if: "alert.severity >= 8"
Processor runs only when severity is 8 or higher; entry is skipped otherwise...	{ "source.ip": "198.51.100.7", "alert.severity": 9, "alert.category": "lateral-movement" }