How the Gateway works

The Gateway is the resource your data tools talk to. It accepts a query, decides whether it has already been answered, and either returns the cached answer or forwards the query to your warehouse. Everything else — credentials, SQL dialect, response shape — passes through untouched.

Where the Gateway sits

Each tenant has a gateway address — a hostname like your-slug.gateway.airbrx.ai. Your Tableau workbooks, Power BI reports, DBeaver connections, and Python scripts point there instead of at your warehouse. From the tool's perspective, nothing else changes: same credentials, same SQL, same drivers.

Behind the gateway address sits a stateless service that proxies traffic to your warehouse. It holds no configuration of its own — every rule it applies is fetched from the API, where you author rules through the App.

The request lifecycle

For every query, the Gateway runs the same five steps:

1. Parse

The Gateway parses the incoming SQL and extracts the metadata that matters for caching decisions: which tables are touched, which columns are read, what kind of statement it is (SELECT, INSERT, UPDATE, DELETE), whether it's parameterized, and which user is asking.

2. Match a rule

The Gateway evaluates the tenant's rules in priority order until one matches. Rules describe both conditions (what the query has to look like) and actions (what to do when it matches). A rule might say "cache SELECTs on the orders table for one hour, keyed by user." Another might say "never cache anything in the finance.salary schema."

See Rules as the differentiator for the conceptual model, and the rule schema reference for the JSON shape.

3. Build a cache key

Cache keys are predictable, not looked-up. The Gateway computes a deterministic hash from the elements the matching rule says are relevant — the statement, the user, the tenant, sometimes the parameter values. There's no cache database to query: the key alone tells the Gateway whether a cached result exists. That's why hit-or-miss determination stays fast no matter how many cached results you have.

4. Check the cache

The Gateway looks for a result at the computed key in cloud storage. If one exists, hasn't been invalidated, and is still within its TTL (or within a configured stale-while-revalidate window — see below), the Gateway returns it directly — no warehouse, no bill, usually a few milliseconds.

5. Forward, cache, return

If there's no cached result — or the cached one has been marked invalid by a DML rule or an explicit invalidation marker — the Gateway forwards the query to your warehouse, captures the response, stores it under the cache key with the rule's TTL, and returns it to the caller. Subsequent identical queries skip steps 4 and 5 entirely.

Stale-while-revalidate

Step 4 has one extra branch worth pulling out. A cache rule can opt in to stale-while-revalidate — a bounded window past its TTL during which the Gateway keeps serving the previously cached value while a background refresh runs against the warehouse. The first user past expiry doesn't pay warehouse latency; they get the cached response immediately, and the refresh populates a new version for everyone after.

Two invariants keep SWR honest. First, invalidation always wins over SWR: a write that fires an invalidation marker suppresses the stale-cached response, even inside the window. Second, only one refresh runs at a time per cache key — the Gateway records the executor and dedupes concurrent refresh requests, so a hot cache that expires under load triggers one warehouse call, not one per in-flight client. If the stale age exceeds the configured window, the rule falls back to a normal miss in step 5.

SWR is per-rule and off by default; tenants opt in by adding a staleWhileRevalidate block on the cache action. See the cookbook recipe for the worked rule pair and the rule schema reference for field shapes.

What the Gateway never touches

The Gateway is built so that anything you'd want to enforce in your warehouse keeps being enforced:

• Credentials. The Gateway forwards your warehouse credentials to your warehouse without storing, logging, or inspecting them. Airbrx never sees usable credentials at rest.
• Row-Level Security. RLS policies live in your warehouse and run on your warehouse. The Gateway doesn't replace them — it just caches per-user results when a rule says to.
• Column masking. Whatever masking your warehouse applies, the Gateway preserves. Cached results carry the masking that was applied when the warehouse computed them.
• Audit trails. Every query that reaches the warehouse appears in your warehouse's native audit logs. Cached responses don't, because no warehouse execution happened — but the Gateway logs them, and the analytics API exposes that record.

Coexistence with direct warehouse access

Routing traffic through the Gateway is opt-in per tool. Plenty of things keep talking directly to your warehouse:

• Native dashboards (Snowsight, Databricks SQL dashboards)
• Scheduled jobs (dbt builds, Airflow tasks, ETL pipelines)
• Data catalogs (Unity Catalog, Alation, DataHub)
• Admin operations (schema migrations, user management)

You decide which traffic flows through the Gateway based on where caching pays off — usually high-volume reads from BI tools and analytics applications. Nothing forces you to route everything through it.

Rolling back to a previous result

Because cloud storage is cheap, the Gateway keeps previous versions of cached results. If a downstream warehouse change goes wrong and starts producing incorrect data, you can serve users yesterday's cache while you investigate. It may be stale — but stale and correct beats fresh and wrong.

Where to go next

• Rules as the differentiator — how cache rules and invalidation rules work together.
• Security posture — credentials, RLS, masking, audit, isolation.
• Connection recipes — point a specific BI tool at a gateway address.