Invalidation strategies

A cache is only as good as its busting story. Airbrx gives you three sources of invalidation — DML in the SQL stream, markers from outside, and plain TTL — and they compose. The job here is picking the right mix for each cache rule.

The three sources

• DML-triggered. An invalidation rule matches a write that flowed through the Gateway — an INSERT, UPDATE, DELETE, or MERGE — and flips one or more cache rules to stale. The next read against any of those cache rules re-executes against the warehouse and refreshes.
• Marker-driven. A write hit the warehouse outside the SQL stream — an ETL completed, a scheduled refresh ran, an upstream event triggered a load — so the Gateway never saw it. You post a marker via the markers API; the Gateway treats that marker the same as if it had seen the DML.
• TTL-only. No invalidation rule, no marker — just a wall-clock expiry. Cheap to author, cheap to reason about, and the right answer when freshness only matters at the day/hour granularity.

When to reach for which

DML-triggered: writes routed through the Gateway

Use when the writes that should invalidate the cache are already running through Airbrx — a BI tool, dbt run, application backend, or any other connection that uses the gateway address.

Why it's the cleanest option. The Gateway sees the write at the moment it lands, and the invalidation rule fires synchronously alongside it. No external system to keep in sync, no race between the write and the next read.

Invalidation rules are regular rules whose conditions match a write. The list of cache rule IDs to mark stale lives in the rule's top-level invalidateRules array — the actions block can stay empty.

{
  "id": "invalidate_dim_caches",
  "name": "Invalidate dim caches on dim writes",
  "enabled": true,
  "priority": 5,
  "mode": "all",
  "conditions": {
    "statementType": { "in": ["INSERT","UPDATE","DELETE","MERGE"] },
    "schema":        { "equals": "dim" }
  },
  "actions": {},
  "invalidateRules": ["cache_reference_dimensions", "cache_per_user_analytics"]
}

Marker-driven: writes that bypass the Gateway

Use when the source of fresh data isn't a SQL write through Airbrx — an ETL platform loads tables directly in the warehouse, a stream sink lands data, a scheduled refresh runs server-side. The Gateway can't catch what it doesn't see; markers are how you tell it anyway.

Markers are small records you create via the API. The marker carries the same matching attributes a rule would (tenant, schema, statement pattern), and the next read against a cache rule whose conditions overlap with the marker re-executes against the warehouse.

Pair a marker call with the end of your ETL job. A typical pattern is a final HTTP call after the load completes:

curl -X POST \
  https://api.airbrx.ai/config/tenants/<tenant-id>/markers \
  -H "Authorization: Bearer $AIRBRX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "schema": "fact", "table": "orders", "reason": "nightly-load-complete" }'

TTL-only: when freshness is bounded by time, not events

Use when there's no event you can tie invalidation to, and stale reads in the meantime are acceptable. A reporting cache that nobody minds being an hour behind is a TTL-only cache rule.

TTL-only is also the right starting point for any rule you're not sure about. Ship it with a conservative TTL, watch the traffic, then bolt on an invalidation rule once you understand the write pattern.

Combining strategies

Most production cache rules end up using more than one. A common shape:

• A reasonable TTL (an hour, a day) as a safety net for slowly-arriving writes you might not have caught.
• An invalidation rule on the same-tenant writes that flow through the Gateway, so most freshness changes are immediate.
• A marker call from any out-of-band loader that touches the same tables.

The Gateway honors whichever fires first. Any one of the three triggers a re-execute on the next read; the cached entry is replaced, not flushed.

Stale-while-revalidate and invalidation

A cache rule can opt in to stale-while-revalidate — serve the previously cached value past TTL while a background refresh runs. SWR layers on top of invalidation, it doesn't replace it. Invalidation always wins. When a DML invalidation rule or a marker fires against a cache rule that's currently inside its SWR window, the stale-cached response is suppressed: the next read falls through to the warehouse, the new result repopulates the cache, and the SWR window restarts from the new entry's TTL. SWR bounds latency; invalidation bounds correctness, and correctness takes priority on every read.

Required invalidation

Set "requireInvalidation": true at the top level of a cache rule and the Gateway will refuse to serve from cache if invalidation can't be confirmed for that rule — useful when a stale read would be worse than a slow read. The request falls through to the warehouse instead, even within TTL.

Required invalidation is the right safety knob for compliance-critical reads. Don't set it on every rule — it defeats the cache by design.

Common pitfalls

• Forgetting markers on ETL. The cleanest DML invalidation in the world doesn't help if your nightly load runs server-side. Audit every loader and either route it through the Gateway or wire up a marker.
• Over-broad invalidation. An invalidation rule that names every cache rule will work, but it'll bust caches it doesn't need to. Be precise about which cache rules a given write actually affects.
• Cross-tenant linkage. Invalidation rules and markers are scoped to a single tenant. If two tenants share a downstream warehouse and you want one to bust the other's cache, that's an out-of-band marker call, not a shared rule.

Where to go next

• Cache rule cookbook — recipes for cache rules that pair with these invalidation strategies.
• Markers API reference — endpoint shapes for creating, listing, and deleting markers.
• Rules as the differentiator — concept-level treatment of why invalidation rules are peers, not afterthoughts.