Investigate a statement

Sooner or later a query you expected to hit cache doesn't — or hits when it shouldn't. The traffic page in the App lets you drill from a single statement into the rule that matched, the cache key the Gateway computed, and the inputs that produced it. This is the page for diagnosing "why."

Get to the statement

Open the App and navigate to traffic. Filter by user, schema, or rule, or paste in part of the SQL. Every row is a single statement and links to its detail. The detail view is the same surface whether you came from the dashboard, an alert link, or a colleague's bookmark.

What the detail view tells you

• The standardized SQL — the form the Gateway used when matching rules and computing the key. Whitespace, comments, and literal parameters are removed; column order is normalized. If two queries you thought were the same actually differ, this view shows where.
• The matched rule — name, priority, and the action that fired. If the rule list changed since this statement ran, the historical name is preserved so you can tell which version mattered.
• The cache key — the deterministic hash that would have been (or was) used to look up the entry, plus the inputs that produced it (userId, statement form, parameters, anything else the rule named).
• The cache outcome — HIT, MISS, or NO-CACHE, and the reason. A MISS will show "no entry yet," "entry expired by TTL," "invalidated by marker," or "invalidated by rule X."
• Timings — how long the Gateway took to decide, plus the warehouse-side time on a MISS.

Common patterns and what to do

A query you expected to hit is missing

Compare two adjacent statements — one that hit, one that didn't. Look at the standardized SQL and the cache key inputs. The usual culprits:

• A different user. Cache rules that include userId in the cache key give every user their own entry. The second user's first run is supposed to miss.
• A different parameter. If the rule keys on parameters, two queries with different literal values are different cache entries.
• Standardization difference. The standardized SQL view is the truth here. If one query has a comment another doesn't, or an extra qualifier, the keys diverge.
• Invalidation fired between the runs. If the outcome is MISS with reason "invalidated by rule X" or "by marker," a write or marker landed in between.

A rule that should match isn't matching

Open the rule in the workshop and compare its conditions against the statement detail. Walk the rule list in priority order; an earlier rule may be matching first. If you don't see a match at all, the rule's conditions are probably wrong — check schema and table casing, exact-equals vs like-comparison, and whether the statement is a SELECT vs something else.

A rule is matching that shouldn't

This usually means a guardrail belongs at higher priority. Add a zero-TTL rule or a more specific cache rule at priority 1 for the traffic you don't want to fall through. See the no-PII guardrail recipe.

Heavy queries always miss; light ones always hit

The hit rate looks great but the savings tile doesn't move. Slice the traffic page by warehouse-time and look at where the misses concentrate. Often a single dashboard with deep aggregates is missing every time because its parameters keep rotating; a parameter-aware key (see the parameterized statements recipe) can fix that.

From investigation to fix

Most investigations end with one of three actions:

• Adjust a rule's conditions or cache key elements.
• Author or update an invalidation rule.
• Post an invalidation marker by hand for a one-off freshness need.

The traffic page links directly to the matching rule in the rules workshop so you can edit and re-test in two clicks.

Where to go next

• Handle rule issues — the analyzer often spots these problems before they reach traffic.
• Invalidation strategies — turn a one-off marker into a recurring pattern.
• Response headers — see cache outcome and matched rule from any BI tool or driver.