proxy_logs columns

proxy_logs is the queryable log — one row per request, 51 data columns plus the day partition, read with read-only SQL over POST /tenants/{tenant}/query. This page is the column list, and the handful of conventions that decide whether your query is correct or merely plausible.

New to the three logs and not sure this is the one you want? Start with the three logs.

Read this first

Five conventions account for almost every wrong answer this table produces. None of them are guessable from a column name.

• day is the only column that prunes. It is the partition, a VARCHAR of the form 'YYYY-MM-DD'. Compare it as a string, not a DATE. Every query should carry a day predicate — without one, even SELECT count(*) reads the tenant’s entire history and will likely hit the 15-second timeout.
• Times are epoch milliseconds, not TIMESTAMP. timestamp and cacheExpiresAt both. Wrap them: to_timestamp(timestamp / 1000).
• responseSize and responseTimeMs report “unmeasured” as a number, not null. 0 when nothing could be measured, and -1 on responseSize when the Gateway explicitly said so. Filter them with > 0 — not >= 0, and not IS NOT NULL. Every other numeric column uses null, which aggregates skip on their own.
• tables and parameterValues are JSON text, not arrays. Open them with json_extract. The row shape is deliberately flat so nothing reading it needs nested-type support.
• Every column is nullable, including on rows written before that column existed. A null can mean “the request carried no value” or “this field did not exist yet.”

Confirming the list yourself

The table below is generated from the same definition the query service serves, but a tenant’s table picks up new columns on its own schedule. To see exactly what yours holds, ask it for a row and read the columns array off the response:

curl -X POST \
  -H "Authorization: Bearer $AIRBRX_PAT" \
  -H "Content-Type: application/json" \
  -d '{"sql":"SELECT * FROM proxy_logs LIMIT 1"}' \
  "https://api.airbrx.ai/tenants/your-slug/query"

DESCRIBE proxy_logs does not work — the executor accepts SELECT and WITH only, and rejects everything else with a 400.

The columns

Partition

Request

Cache decision

The SQL

Correlation

Caller identity and request headers

These are here so a security review is a query rather than a grep over raw JSON. Every value except clientIp is supplied by the caller and copied down verbatim — inspect it, never trust it. clientIp is the address the Gateway resolved through its trusted-proxy rules, which is why it, and not xForwardedFor, is the one that agrees with the audit log.

Worked queries

Each of these carries a day predicate. Copy that habit before you copy anything else.

What is the cache actually doing?

SELECT cacheStatus, count(*) AS executions
FROM proxy_logs
WHERE day >= '2026-06-01'
GROUP BY ALL
ORDER BY executions DESC

Expect more than four rows. PASSTHROUGH is the interesting one — those statements matched no rule at all, so they are the population your next cache rule would be drawn from. BLOCKED is a deny rule refusing a statement, not an error.

Which uncached statements repeat the most?

SELECT queryHash,
       any_value(standardizedSql)    AS statement,
       count(*)                      AS executions,
       count(DISTINCT userName)      AS users,
       sum(warehouseExecutionTimeMs) AS warehouse_ms
FROM proxy_logs
WHERE day >= '2026-06-01'
  AND cacheStatus = 'PASSTHROUGH'
GROUP BY queryHash
HAVING count(*) > 1
ORDER BY warehouse_ms DESC
LIMIT 25

The ranked list of work your warehouse did more than once and did not need to. Sorting by warehouseExecutionTimeMs rather than execution count puts the expensive repeats first, which is the order you want to write rules in — and it is the right column for the job, because responseTimeMs is wall-clock through the Gateway and cannot tell you what the warehouse itself spent.

Is a rule earning its keep?

SELECT matchedRuleName,
       ruleVersion,
       count(*)                                    AS executions,
       count(*) FILTER (WHERE cacheStatus = 'HIT') AS hits,
       round(100.0 * count(*) FILTER (WHERE cacheStatus = 'HIT') / count(*), 1) AS hit_rate_pct
FROM proxy_logs
WHERE day >= '2026-06-01'
  AND matchedRule IS NOT NULL
GROUP BY ALL
ORDER BY executions DESC

High executions with a low hit rate usually means a cache key that is too specific — every execution computes a different key, so nothing is ever read back. missReason will tell you which kind of miss it is.

Everything one caller did

SELECT to_timestamp(timestamp / 1000) AS at,
       userName, userAgent, cacheStatus, statusCode, standardizedSql
FROM proxy_logs
WHERE day >= '2026-06-01'
  AND clientIp = '203.0.113.24'
ORDER BY timestamp

Security review is a first-class use of this table, which is why the caller columns are here: clientIp, userTokenHash, userAgent and the forwarded header set. They are already in the raw logs this table derives from, under the same tenant prefix and the same retention — a column adds query reach, not exposure.

What did the cache save us?

SELECT day,
       count(*) FILTER (WHERE cacheStatus = 'HIT') AS hits,
       sum(warehouseExecutionTimeMs) FILTER (WHERE cacheStatus <> 'HIT') AS warehouse_ms
FROM proxy_logs
WHERE day >= '2026-06-01'
GROUP BY day
ORDER BY day

For tying a HIT to the cost it avoided, queryId is the join key into your warehouse’s own query history.

What is not here

• originalSql. This table carries standardizedSql, which has literal values removed. The statement with its literals inline exists only in the raw logs.
• Response headers, and any fingerprint of the result data. Neither is captured anywhere. Every hash the Gateway computes — queryHash, userTokenHash, cacheKey — covers request-side input. Two rows with the same queryHash asked the same question; the table cannot say whether they got the same answer.
• Result rows. Never read, never retained. No query you write here can reach the contents of anyone’s data.

See also

• The three logs — which log answers which question, and where they disagree.
• Query the raw log — the workflow: scoping a token, the limits, what the executor allows.
• Query log reference — the record itself, and the raw storage layout.
• Analytics API — the pre-aggregated summaries, when a rollup will do.