Cache Delete

State Management Flow Control

Synopsis

Removes a single key from a cluster-shared NATS JetStream KV store, with configurable behavior when the key does not exist.

Schema

- cache_delete:
    key: <string>
    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 delete. Mustache template evaluated against the log entry; an empty resolved key is an error
bucket	N	default	Cluster-shared KV bucket name
ttl	N	3600	Bucket TTL in seconds (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 delete
on_failure	N		Processors to run when the processor errors
ignore_missing	N	true	Default true — deleting a key that does not exist is treated as success. Set to false to error on a missing key
ignore_failure	N	false	Continue pipeline processing when the processor errors

Note: ignore_missing defaults to true for cache_delete, which is the opposite of cache_set and cache_get where it defaults to false.

Details

cache_delete removes a single key from a NATS JetStream KV bucket. The key field supports mustache templates ({{field.subfield}}) resolved against the current log entry at execution time. An empty resolved key is always an error regardless of ignore_missing or ignore_failure. The processor deletes only the specified key — it does not delete or purge the bucket itself.

By default, ignore_missing is true: attempting to delete a key that does not exist returns success without error. Set ignore_missing: false to detect and surface missing-key conditions via on_failure or error propagation. This default is intentionally the reverse of cache_set and cache_get, which default ignore_missing to false.

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 accesses the same key space. Behavior is identical on single-node and multi-node deployments.

Each cache_delete operation is a single NATS round-trip with a 2-second timeout. There is no local in-process cache. 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_set to write keys and cache_get to read them.

Examples

Basic Delete (No-Op on Missing Key)

Removing a session entry when a session closes; silently succeeds if already evicted...	{ "session.id": "a3f9d7c1", "event.action": "session_end", "source.ip": "10.4.12.55" } - cache_delete: key: "session:{{session.id}}"
Deletes key session:a3f9d7c1; if the key has already expired or been removed, the processor succeeds silently...	{ "session.id": "a3f9d7c1", "event.action": "session_end", "source.ip": "10.4.12.55" }

Error on Missing Key

Enforcing that an alert must be present in cache before attempting revocation...	{ "alert.id": "THR-20910", "event.action": "alert_resolve", "user.name": "bwilliams" } - cache_delete: key: "alert:{{alert.id}}" bucket: active-threats ignore_missing: false on_failure: - fail: message: "Alert {{alert.id}} was not found in active-threats cache"
If the key is absent, on_failure chain runs rather than silently succeeding...	{ "alert.id": "THR-20910", "event.action": "alert_resolve", "user.name": "bwilliams", "error": { "message": "Alert THR-20910 was not found in active-threats cache" } }

Templated Key from Downstream Signal

Revoking a blocked-IP entry when an authentication succeeds after investigation...	{ "source.ip": "203.0.113.42", "user.name": "analyst01", "event.action": "auth_cleared", "threat.verdict": "false_positive" } - cache_delete: key: "blocked:{{source.ip}}" bucket: blocked-ips if: "threat.verdict == 'false_positive'"
Removes blocked:203.0.113.42 from the blocked-ips bucket only when the verdict is a false positive...	{ "source.ip": "203.0.113.42", "user.name": "analyst01", "event.action": "auth_cleared", "threat.verdict": "false_positive" }