Cache rule schema

Rules in Airbrx are JSON objects stored on a tenant's configuration. The App's rules workshop is the usual edit surface; this page is the underlying shape — for scripting bulk changes, importing rules from another tenant, or generating rules from an external system. For the conceptual model, start with Rules as the differentiator.

Top-level shape

{
  "id": "cache_customer_data",
  "name": "Cache customer queries for 1 hour",
  "description": "Per-user cache on the CUSTOMER table",
  "enabled": true,
  "priority": 10,
  "mode": "all",
  "conditions": { /* what queries match */ },
  "actions":    { /* what happens on match */ },
  "respectSqlHints": true,
  "invalidateRules": [],
  "requireInvalidation": false
}

Required fields

Optional fields

Conditions

Conditions match query metadata. Within a single condition type, operators combine with AND. The rule's mode controls how condition types combine.

Tables

Schema / catalog

Statement type

Common values: SELECT, INSERT, UPDATE, DELETE, SHOW, DESCRIBE, WITH.

SQL pattern

Columns

User

Parameterized queries

Match queries with parameter placeholders — :name, ?, $1:

{
  "conditions": {
    "hasParameters": true,
    "parameters": {
      "customer_id": { "equals": "VIP123" },
      "region":      { "in": ["US","CA","MX"] },
      "ssn":         { "exists": true }
    }
  }
}

Parameter values are automatically included in cache keys when present — you don't need to specify them in cacheKeyElements.

Modes

"mode": "all" (default) — every condition must match. "mode": "either" — any condition matching is enough.

Actions

Cache TTL

{
  "actions": {
    "cache": { "ttlSeconds": 3600 }
  }
}

Stale-while-revalidate

Opt a cache rule into stale-while-revalidate by adding a staleWhileRevalidate block on the cache action. When a cached entry is past its TTL but within the SWR window, the Gateway returns the cached value immediately and fires a background refresh against the warehouse. See the cookbook recipe for when to reach for it.

{
  "actions": {
    "cache": {
      "ttlSeconds": 3600,
      "staleWhileRevalidate": {
        "enabled": true,
        "windowSeconds": 86400
      }
    }
  }
}

Validation. enabled: true with no windowSeconds is a load-time error — tenants must explicitly choose a stale ceiling (including null for forever). Negative or non-finite values are also rejected.

Invalidation precedence. An invalidation marker against a cache rule always suppresses its stale-cached response, even inside the SWR window. SWR bounds latency; invalidation bounds correctness, and correctness wins.

Cache key elements

What makes a cached entry unique. The Gateway hashes these inputs to compute the cache key.

{
  "actions": {
    "cacheKeyElements": ["userId", "warehouse", "standardizedSql"]
  }
}

These are included automatically and don't need to be listed: proxyVersion (cache invalidates on Gateway upgrades), sessionState (session vars and catalog/schema context), describeOnly (separates schema queries from data queries), parameterValues (parameter values for parameterized queries).

Invalidation rules (DML)

A rule that matches DML statements (INSERT/UPDATE/DELETE) can name cache rules to invalidate when it fires:

{
  "id": "orders-dml",
  "name": "Orders Table Changes",
  "priority": 5,
  "conditions": {
    "statementType": { "in": ["INSERT","UPDATE","DELETE"] },
    "tables": { "includes": "ORDERS" }
  },
  "actions": {},
  "invalidateRules": ["cache-orders-aggregates","cache-orders-recent"]
}

Pair with "requireInvalidation": true on a cache rule to refuse cache hits if recent invalidation activity can't be confirmed — right default for compliance-critical caches.

Worked example

{
  "id": "cache_customer_data",
  "name": "Cache customer queries per user for 1 hour",
  "description": "Aggregate reads on CUSTOMER, isolated per user (RLS).",
  "enabled": true,
  "priority": 10,
  "mode": "all",
  "conditions": {
    "tables":         { "includes": "CUSTOMER" },
    "statementType":  { "equals": "SELECT" }
  },
  "actions": {
    "cache": { "ttlSeconds": 3600 },
    "cacheKeyElements": ["userId", "warehouse", "standardizedSql"]
  }
}

See also

• Rules as the differentiator — the conceptual model for cache + invalidation rules.
• Markers API — fire invalidation markers from outside the SQL stream.
• API reference — the endpoints that PUT rules onto a tenant.