Rules as the differentiator

A cache without rules is a sledgehammer — every query treated the same, every result held for the same length of time, every user sharing the same view. That works for toy demos and almost nothing else. The Airbrx rules engine is what makes caching usable against real workloads.

Why rules

Real workloads aren't uniform. Aggregate queries on slow-changing dimensions can be cached for an hour without anyone noticing. Live transactional reads against orders can't tolerate even a minute of staleness. PII-bearing queries shouldn't be shared across users; aggregate dashboards absolutely should be. A single TTL across all of that either over-caches (and serves stale or leaky data) or under-caches (and squanders most of the savings).

Rules let you describe each kind of traffic on its own terms. The Gateway evaluates them per-query and decides what to cache, how to key it, and how long to keep it.

Two kinds of rule, both first-class

Most caching products treat invalidation as an afterthought — a knob you reach for when caching has already created a problem. In Airbrx, invalidation rules are peers of cache rules. They share the same matching language; they live in the same rule list; you author them in the same App page.

• Cache rules match on read traffic and tell the Gateway how to cache the result: which fields contribute to the cache key, what TTL applies, how isolated different users should be.
• Invalidation rules match on writes — INSERT, UPDATE, DELETE — and tell the Gateway which cached results are now suspect. When an invalidation rule fires, the cache rules it points at start serving fresh results on the next read.

Treating them as peers means you can express things like "cache aggregates on orders for one hour, but invalidate the whole set immediately when an INSERT lands" — without leaving the rules surface, without waiting for the TTL to expire, without reaching for an external invalidation API.

Conditions and actions

Every rule has the same shape: conditions describe what queries the rule applies to, and actions describe what happens when it matches.

Conditions can match on:

• The kind of statement (SELECT, INSERT, UPDATE, DELETE)
• The tables and schemas the query touches
• The user identity, role, and tenant making the request
• The session, warehouse, and database context
• SQL patterns matched against the query text
• Whether the statement is parameterized, and what those parameters look like

Actions describe what the Gateway should do when the conditions match: cache for a TTL, key the result by user or session, refuse to cache, or mark another rule's results invalid.

The exact JSON shape lives in the rule schema reference, and Ship your first cache rule walks through a worked end-to-end example you can run today.

Priority and matching mode

Rules are evaluated in priority order. Lower priority numbers win, which feels backwards until you internalize it: priority 1 is "most important," priority 100 is "fallback." The first rule whose conditions match determines the action; later rules don't get a chance.

Within a single rule, conditions can be combined two ways. "All" mode is logical AND — every condition has to match. "Either" mode is logical OR — any condition matching is enough. Most rules want "all"; "either" is useful for things like "any of these three sensitive schemas should be excluded from caching."

Predictable cache keys

When a cache rule matches, the Gateway computes a cache key by hashing the elements the rule says are relevant — typically the statement, the tenant, sometimes the user, sometimes the parameter values. The key is deterministic: the same inputs always produce the same key, and the Gateway can compute it without consulting any storage.

That deterministic property is load-bearing. It means hit-or-miss is a single hash computation regardless of how many cached results exist, and it means two services computing the same key for the same query reach the same answer. There's no cache directory to query, no global lock, no "is this entry there yet" race.

It also means cache keys are diagnosable. The request lifecycle exposes the key the Gateway used; if a query you expected to hit cache didn't, you can see exactly which inputs went into the key and figure out what differed.

Cross-rule invalidation

Invalidation rules don't operate on the cache directly — they point at the cache rules whose results they make suspect. When a write matches an invalidation rule, the Gateway records a marker against each named cache rule. The next read against a marked cache rule re-executes against the warehouse and re-caches, even if the rule's TTL hadn't expired.

Two practical knobs sit on top of this:

• Required invalidation. A cache rule can declare that it must see recent invalidation activity before serving. That's the right default for caches in front of compliance-critical data: better to fall through to the warehouse than serve a result that should already have been thrown out.
• Invalidation API. When the trigger lives outside the SQL stream — an ETL job finished, a feature flag flipped, an upstream system pushed an event — you can create a marker via the markers API. From the Gateway's point of view, it's the same mechanism: the marker is written, the next read sees it, the cache refreshes.

Where each resource fits

Rules touch all three resources in different ways:

• The App is where you author rules — the Rules workshop is the page where you write conditions, actions, priorities, and invalidation links. The App also runs the rules analyzer, which checks for shadowed rules, priority conflicts, and unreachable conditions.
• The API is where rules are stored. Rule changes are PUTs against tenant configuration; reads are GETs. PATs with rules-admin scope can read or update rules without going through the App.
• The Gateway is where rules execute. Every query that hits the Gateway is matched against the tenant's rule list in priority order; the matching rule's actions determine the response.

When to reach for the JSON

Most rule changes happen in the App's Rules workshop, where the form takes care of shape and validation. You'll reach for the raw rule JSON when you're scripting bulk changes, importing rules from another tenant, or generating rules from an external system. When that's the right move, the rule schema reference has the field list, types, and validation constraints.

Where to go next

• How the Gateway works — how rule evaluation fits into the request lifecycle.
• Ship your first cache rule — a worked end-to-end example: author one rule, run a query twice, watch the second one come back from cache.
• Rule schema reference — JSON shape and validation rules.