Semantic Invalidation: Invalidate by Meaning, Not by Pattern

Every caching team has typed KEYS user:123:* into a console, stared at the result, and wondered: did I get everything? Pattern invalidation is string matching applied to a semantic problem. It cannot understand that pricing:tier:enterprise is related to user:123:billing:next because the relationship is conceptual, not lexicographic. We built a primitive that closes this gap: semantic invalidation, powered by the same vector index that drives Cachee's VSEARCH command.

Pattern Matching Is a Sledgehammer

The standard approach to invalidating multiple cache keys is pattern matching. KEYS user:123:* finds every key that starts with user:123:. It is fast, it is familiar, and it is wrong in ways that do not show up until production.

The first failure mode is under-invalidation. A pricing change affects user:123:price, user:123:discount, and user:123:billing:next — all of which match the pattern. But it also affects pricing:tier:enterprise, which does not share the user:123: prefix. The pattern misses it. That key stays in the cache, serving stale pricing data, until its TTL expires or someone remembers to add it to the invalidation list.

The second failure mode is over-invalidation. The pattern user:123:* also matches user:123:avatar, user:123:preferences, and user:123:theme — none of which have anything to do with pricing. They get flushed anyway. The cache refills them on the next request, burning compute and adding latency for no reason. The hit rate drops. The database sees a spike. Nobody knows why.

The third failure mode is the worst: maintenance burden. Teams that recognize pattern matching is imprecise build invalidation maps. “When pricing changes, invalidate these 47 keys.” The map lives in application code, spread across services. Every schema change, every renamed key, every new feature breaks it. One missed entry means stale data in production. One extra entry means unnecessary cache misses. The map is never correct. It is only ever less wrong.

Semantic Invalidation: Embed the Intent, Search for Matches

Semantic invalidation works by giving every cache key a lightweight vector embedding. The embedding is computed at SET time (or lazily on first access) and stored in Cachee's built-in HNSW vector index — the same index that powers the VSEARCH command for similarity search.

When you need to invalidate, instead of constructing a pattern, you describe the intent:

INVALIDATE WHERE intent="user 123 pricing data" CONFIDENCE 0.9

The cache embeds the intent query, runs a vector similarity search against the key index, and invalidates every key whose embedding has greater than 90% similarity to the intent. The result is precise and auditable:

# Matched and invalidated (>90% similarity):
#   user:123:price          (0.97)
#   user:123:discount       (0.94)
#   user:123:billing:next   (0.92)
#   pricing:tier:enterprise (0.91)

# NOT invalidated (<90% similarity):
#   user:123:avatar         (0.31)
#   user:123:preferences    (0.44)

The pricing:tier:enterprise key is found even though it shares no prefix with user:123:*. The user:123:avatar key is left alone even though it shares the exact prefix. The cache understands the meaning behind the keys, not just the characters in their names.

The Confidence API: Operator-Controlled Precision

The CONFIDENCE parameter is the operator's precision dial. It controls the similarity threshold for inclusion in the invalidation set, and it gives you explicit control over the precision-recall tradeoff.

• CONFIDENCE 0.95 — Surgical. Only keys with very strong semantic similarity are invalidated. Use this in production for critical paths where over-invalidation has measurable cost.
• CONFIDENCE 0.9 — Standard production threshold. Catches all strongly related keys while filtering out tangential matches.
• CONFIDENCE 0.7 — Broad. Useful for development, debugging, or when you want to invalidate an entire category like “anything related to billing” without knowing every key name.

Every INVALIDATE WHERE command returns the full list of matched keys with their similarity scores. You can see exactly what was invalidated, inspect the scores, and adjust the threshold. There is no black-box AI making decisions behind the scenes. You set the threshold. You see the results. You tune it.

How It Compares to Every Other Method

Semantic invalidation does not replace other invalidation strategies. It fills a specific gap in the toolkit — the space between “I know the exact key” and “I need to invalidate a concept.”

Each method has a use case. Exact key deletion when you know the name. Pattern matching when keys share a predictable prefix. CDC when the cache maps directly to database rows. Dependency graph when you have explicit, known relationships between keys. Semantic when you know what changed conceptually but do not know — or cannot enumerate — every affected key.

Composition: Semantic + Dependency Graph + Triggers

The real power of semantic invalidation emerges when it composes with Cachee's other primitives.

Semantic + Dependency Graph: A semantic invalidation can match a source key in the dependency graph. When INVALIDATE WHERE intent="billing changes" CONFIDENCE 0.9 finds and invalidates billing:plan:enterprise, the dependency graph cascades that invalidation to every derived key that declared a dependency on it — dashboards, reports, composite API responses. The semantic match triggers the DAG cascade. One intent query propagates through the entire dependency chain.

Semantic + Triggers: Cachee's ON_INVALIDATE trigger fires for every key that is semantically matched and invalidated. You can log the full list of matched keys with their similarity scores, emit metrics to your observability stack, or fire webhooks for downstream systems. The trigger system gives you complete visibility into what semantic invalidation does, on every invocation.

Semantic + CDC: CDC auto-invalidation handles the database-to-cache mapping. Semantic invalidation handles the cases CDC cannot reach — keys that are related by meaning but not by direct table mapping. Together, they provide total invalidation coverage without maintaining a single line of invalidation logic in application code.

Related Reading

• Semantic Invalidation Product Page
• Causal Dependency Graph
• CDC Auto-Invalidation
• Cache Coherence
• Cache Triggers