Skip to content

sql-result-visualization.md

Latest commit

 

History

History
74 lines (58 loc) · 4.64 KB

sql-result-visualization.md

File metadata and controls

74 lines (58 loc) · 4.64 KB

SQL Result Visualization Architecture

This document is normative for AI-assisted SQL result visualization in Studio (view=sql).

The implementation MUST reuse the existing SQL-view AI transport, render inside the shared scrollable result grid, and generate Chart.js configs without any external chart wrappers.

Scope

This architecture governs:

  • the optional AI visualization row inside SQL result rendering
  • prompt construction from the executed query plus full result rows
  • response validation for AI-generated Chart.js configs
  • Chart.js embedding and lifecycle management
  • visualization reset behavior across query executions

Canonical Components

Result-Area Contract

  • Visualization MUST remain optional. If llm is not provided, SQL result rendering MUST NOT show an empty visualization affordance.
  • The idle visualization affordance MUST render on the SQL result summary row, right-aligned on the same line as the "row(s) returned in Xms" text.
  • The mounted chart surface MUST render above the SQL result column header row but inside the shared scrollable grid container.
  • The implementation MUST use DataGrid.getBeforeHeaderRows(...) for the mounted chart rather than a bespoke parallel scroll region.
  • The mounted chart surface MUST render inside a full-width white band that stays pinned to the visible scroll-container width rather than stretching with the total table width.
  • The actual chart body inside that band MUST be centered and width-clamped:
    • minimum 300px
    • grow with available visible width
    • maximum 1200px
    • clip horizontally when the visible space is narrower than 300px
  • The chart band MUST leave a small bottom margin before the grid and visually define the grid top edge with a border.
  • The idle visualization affordance MUST stay visually minimal: icon plus plain text, no bordered button chrome, and no surrounding explanatory copy.
  • The default idle state label MUST read Visualize data with AI.
  • If the user manually runs SQL that was generated by AI and marked as graph-worthy, the idle affordance MUST be skipped and chart generation MUST begin automatically for that result.
  • After graph generation succeeds or fails, the idle action MUST NOT reappear until the next query execution resets the visualization state.

Prompt and Validation Contract

  • The visualization prompt MUST reuse the same embedder-provided llm({ task, prompt }) hook already used for SQL generation.
  • The prompt MUST include:
    • the concrete database engine name
    • the executed SQL text under a stable SQL: line
    • the original AI SQL request when the result came from Generate SQL with AI
    • the full result row set
  • The prompt MUST explicitly request a Chart.js config and forbid external libraries.
  • AI responses MUST be strict JSON and MUST NOT include markdown fences or commentary.
  • JSON-response validation and correction retries SHOULD flow through the shared SQL-view AI JSON utility rather than a visualization-specific retry loop.
  • Provider-level output-limit failures MUST surface as explicit retry issues instead of collapsing into a generic malformed-JSON error.
  • The validated response shape MUST contain a Chart.js config object suitable for new Chart(canvas, config).
  • The supported chart types MUST be constrained to a known allowlist.
  • The implementation MUST retry up to two times when the model returns malformed JSON or an invalid chart config, and each correction prompt MUST include the latest validation error.

Chart Lifecycle Contract

  • Chart rendering MUST use Chart.js directly.
  • The mounted chart instance MUST be destroyed on unmount and before replacing it with a new chart.
  • Visualization reset MUST happen when a new SQL execution starts, even if the previous result grid is still visible while the next query is in flight.

Testing Requirements

Changes to SQL result visualization MUST include tests covering:

  • prompt construction with full result rows
  • Chart.js instantiation for a few supported chart types
  • SQL-view integration showing the summary-row Visualize data with AI affordance
  • automatic chart generation for AI-generated SQL results that request visualization
  • replacement of the action with a mounted chart
  • reset behavior when another query execution starts