Document Queries feature behavior

Author: sorenbs

Architecture/query-insights.md

@@ -116,6 +116,19 @@ The query table uses the per-query samples as follows:
 - First-snapshot context rows show one representative execution with average per-execution counters so a fresh view can still show useful rows without pretending the whole cumulative provider history happened inside the selected window.
 - The detail sheet and AI recommendation prompt use the same selected-window query row shown in the table.
 
+## View Interaction Contract
+
+- The `Queries` view MUST render under the Studio `Visualizer` navigation item and MUST NOT be available when `Adapter.queryInsights` is absent.
+- The top-level description SHOULD explain that Studio monitors database activity and helps identify poorly performing queries.
+- The activity chart MUST show `Queries/s` and `Avg latency` summaries, share one selected range with the query table, and expose `1m`, `5m`, `15m`, and `1h` range controls.
+- The query table SHOULD include `Latency`, `Query`, `Executions`, `Rows Returned`, and `Last Seen` columns. `Rows Returned` is the user-facing label for `rowsReturned`; `reads` remains an internal and AI-prompt signal.
+- When AI recommendations are available, the query table SHOULD add an `Analysis` column with queued, running, manual analyze, and completed severity states.
+- The table filter SHOULD use touched tables derived from the selected-window rows, not from stale cumulative provider data.
+- Sorting SHOULD operate on selected-window row values, not provider cumulative counters.
+- Clicking a query row SHOULD open a detail sheet with SQL, touched tables, selected-window metrics, and optional recommendations.
+- The detail sheet SHOULD support previous/next navigation through the currently visible sorted table rows.
+- Pause/resume SHOULD stop and restart polling the provider without clearing already retained local samples.
+
 ## @prisma/sqlcommenter-query-insights Mapping
 
 When SQL includes `@prisma/sqlcommenter-query-insights` metadata, embedders SHOULD remove the `prismaQuery` tag from the displayed `query` and map it into `prismaQueryInfo`.
@@ -263,4 +276,9 @@ Changes to query insights MUST include tests covering:
 - navigation visibility and stale `view=queries` fallback
 - rendering provider snapshots in the Queries view
 - hiding AI recommendations when no `llm` hook is configured
+- chart and table metrics scoped to the selected time range
+- first-snapshot context rows that do not create fake throughput
+- cumulative counter deltas, counter resets, and stale/equal snapshots
+- long chart gaps, short connected gaps, and isolated sample markers
+- serial automatic AI analysis with the five-query cap and manual analysis beyond that cap
 - demo aggregation behavior for successful query executions

FEATURES.md

@@ -141,6 +141,7 @@ Users can pan/zoom, inspect key and nullable markers, and jump from a node direc
 Embedders can optionally provide live query snapshots through Studio's BFF bridge, and Studio shows them in a dedicated `Queries` view directly under the schema visualizer.
 The view plots live query throughput and average latency from recent snapshot rows and successive snapshot updates, defaulting to the most recent 5 minutes with quick switches for 1 minute, 15 minutes, and 1 hour. The chart summary and query list follow the selected time window, including row execution and rows-returned counters, while historical first-snapshot rows render as latency context points instead of fake throughput spikes or cumulative totals. Live throughput points use one-second buckets at the query's observed time, live lines stay connected across short bursts, long unmeasured gaps break into separate segments, isolated samples render as points, and hovering the plot shows exact readings.
 Users can filter by touched table, sort by operational signals, and open a detail sheet for SQL, metrics, query metadata, and optional recommendations.
+The table labels returned-row volume as `Rows Returned`, while lower-level read estimates remain available to AI prompts and sort logic when a provider can supply them.
 When Studio's shared `llm` hook is available, the query table adds an Analysis column that analyzes newly observed query groups in the background, one at a time, and stops automatic work after the first five groups. Rows show a running indicator, a manual Analyze action, and a completed all-good, info, or warning icon; the detail sheet uses the same analysis queue for manual recommendations. Without that hook, the AI analysis UI is hidden.
 If an embedder does not provide query insights, Studio hides the `Queries` menu item and stale `view=queries` URLs fall back to the normal default view.
 

README.md

@@ -240,12 +240,23 @@ const adapter = createPostgresAdapter({
 
 If your BFF does not implement `query-insights`, leave `queryInsights` undefined. Studio will hide the `Queries` menu item and stale `view=queries` URLs will fall back to the normal default view.
 
+What the `Queries` view renders:
+
+- a live chart for `Queries/s` and average latency with `1m`, `5m`, `15m`, and `1h` ranges
+- a query table with `Latency`, sanitized SQL, `Executions`, `Rows Returned`, `Last Seen`, and optional `Analysis`
+- table filtering and sorting by rows returned, latency, execution count, or last-seen time
+- a detail sheet with the selected query SQL, touched tables, selected-window metrics, and optional AI recommendations
+- a pause/resume control for polling the injected snapshot provider
+
+The chart and table always use the same selected time range. Studio derives visible `Executions`, `Rows Returned`, reads, latency, and last-seen values from the samples it can place inside that range; it does not show cumulative provider counters as if they all happened in the visible window. The first snapshot can still show recent rows as context when their `lastSeen` timestamp is inside the selected range, but those context rows do not create live throughput values.
+
 Consumer migration notes:
 
 - The Studio route is `#view=queries`. Do not link to `#view=query-insights`.
 - `queryInsights` is an adapter capability, not a top-level `<Studio />` prop. Pass it into `createPostgresAdapter`, `createMySQLAdapter`, or `createSQLiteAdapter` alongside the executor.
 - The packaged BFF bridge uses snapshot polling with `procedure: "query-insights"`. Studio does not require a Prisma Streams `streamUrl`; hosts with SSE, pg_stat_statements, ppg.query_stats, proxy logs, or control-plane telemetry should adapt that source into a `StudioQueryInsightsSnapshot`.
 - AI recommendations use the shared `llm` hook with `task: "query-insights"`. Studio does not expose a separate query-specific `analyze()` or `enableAiRecommendations()` transport. Hosts that need consent should enforce it in the `llm` implementation they pass to Studio.
+- Automatic AI analysis runs serially, with at most one `llm` request in flight, and stops after the first five automatically discovered query groups. Users can still manually analyze additional rows from the table or detail sheet.
 
 Snapshot rows should be aggregated by a stable normalized query identity. Do not send raw parameter values or sensitive payloads; use parameterized SQL or another sanitized query representation. `reads`, `rowsReturned`, `duration`, `count`, and `lastSeen` are best-effort operational signals for display and sorting, not accounting-grade telemetry. Studio derives visible chart and table metrics from deltas between cumulative snapshots inside the selected time window; it does not display cumulative provider counters as selected-window totals. A first snapshot can render recent rows as context, but live throughput is only available after Studio has two increasing snapshots to compare.