Module query 

Read side of the analytics store (DW-043): dashboard series, Top-N reports, and the structured query endpoint’s translator.

Every query reads ONLY the rollup tables (the dashboard contract is “week of traffic under 100 ms” — that is rollup-shaped work, not raw-scan work). All dynamic values bind as SQL parameters; the ONLY strings interpolated into SQL are schema identifiers chosen from closed sets (DIM_COLUMNS) — the structured query endpoint never accepts SQL text.

Structs

DimensionQuery

The custom-dimension query endpoint’s request body (DW-093): a closed grammar over the rollup_dim table — never SQL text.

DimensionRow

One custom-dimension query row (DW-093): aggregated metrics for one (window, dimension name, value) tuple, read from the rollup_dim table. The dimension name is config-bounded (the rollup key); the value is the captured tag value.

Filters

Equality filters on dimension columns (dashboard drill-down).

FiltersBody

The filter map of a StructuredQuery: column -> required value.

GovernanceAuditQuery

The governance audit endpoint’s request body (DW-084): a time window over the ai_governance_events table.

GovernanceEventRow

One governance audit event row (DW-084): a raw ai_governance_events record — the shadow-audit view of which consumer/team called which model and whether the governance layer allowed or denied it.

JourneyRow

One journey/funnel query row (DW-093): a raw raw table record for one correlation id — the per-request step in a business journey. Ordered by time ascending so the caller sees the request sequence.

McpToolCallQuery

Query parameters for MCP tool call records (DW-087).

McpToolCallRow

One MCP tool call row (DW-087).

PromptLogQuery

The prompt-logs endpoint’s request body (DW-081): a time window over the ai_prompt_logs table, optionally filtered by consumer.

PromptLogRow

One prompt log row (DW-081): a raw ai_prompt_logs record — the redacted prompt and response for one captured AI request.

QueryRow

The structured query endpoint’s row: group key (in the query’s group_by order) plus the full metric set.

SeriesPoint

One point of a dashboard series.

SpendQuery

The spend query endpoint’s request body (DW-079): a closed grammar over the ai_spend table — never SQL text from the caller.

SpendRow

One spend summary row (DW-079): aggregated token and cost totals for one group key over a billing window.

StructuredQuery

The structured query endpoint’s request body (DW-043): a closed grammar translated to SQL — never SQL text from the caller.

TopEntry

One Top-N entry.

Enums

DimensionQueryError

Why a dimension query was rejected before SQL was built.

GovernanceAuditError

Why a governance audit query was rejected before SQL was built.

PromptLogError

Why a prompt-logs query was rejected before SQL was built.

QueryError

Why a structured query was rejected before SQL was built.

SpendQueryError

Why a spend query was rejected before SQL was built.

TopKind

Top-N report kinds (the five frozen in the feature analysis).

Constants

DIM_COLUMNS

The fixed dimension columns queries may group or filter by. The closed set the structured endpoint accepts; also the dashboard’s drill-down axes.

SPEND_GROUP_COLUMNS

The dimension columns the spend summary may group by (DW-079). The closed set the spend endpoint accepts — a subset of the ai_spend table’s columns (no provider/version to keep the billing view focused on who/what, not the routing detail).

Functions

dashboard

Dashboard series: per-window metric points at a granularity (0=1m..3=1d), optionally split by ONE dimension and filtered — the drill-down axes of the dashboard data API.

dimension_query

Execute a validated custom-dimension query (DW-093): aggregate the rollup_dim table over a time range at a granularity, filtered by dimension name and optional value. Rows order by window start ascending, then request count descending within each window.

governance_audit

Execute a governance audit query (DW-084): return the raw ai_governance_events rows in a time window, newest first. Reads the RAW rows directly — governance events are per-check, not rolled up (the volume is orders of magnitude below the access record path).

journey_query

Execute a journey/funnel query (DW-093): return all raw records matching a correlation id, ordered by time ascending. Optional time range filter narrows the scan. Reads the RAW raw table directly (journey analysis is per-request, not rolled up). The correlation_id index keeps the scan bounded.

mcp_tool_calls

Execute an MCP tool call query (DW-087): return the raw mcp_tool_calls rows in a time window, newest first, optionally filtered by session id, consumer, or tool name.

prompt_logs

Execute a prompt-logs query (DW-081): return the raw ai_prompt_logs rows in a time window, newest first. Reads the RAW rows directly — prompt logs are per-request, not rolled up. Optionally filtered by consumer.

spend_summary

Execute a validated spend query (DW-079): aggregate the ai_spend table over a billing window, grouped by the requested dimensions. Rows order by cost descending (the billing-relevant axis). Reads the RAW ai_spend rows directly — spend is per-request, not rolled up (the volume is orders of magnitude below the access record path, and billing windows are short).

structured

Execute a validated structured query. Range-aggregate shape: the window column is NOT grouped (per-window series is the dashboard endpoint’s job); rows order by request volume descending.

top

Top-N over a time range, summed across the FINEST granularity’s windows (summing finer windows loses nothing — the whole schema is additive).