CREATE CHART

Renders an inline source query as an SVG chart and returns it in the execution result for the GUI to display.

Syntax

CREATE CHART <type> FROM (<select_query>)
  [X <column>] [Y <column> [, <column> ...]] [Y2 <column> [, <column> ...]]
  [TITLE '<text>'] [SUBTITLE '<text>']
  [XLABEL '<text>'] [YLABEL '<text>']
  [XFORMAT '<fmt>'] [YFORMAT '<fmt>']
  [XRANGE <min> <max>] [YRANGE <min> <max>]
  [XSCALE LOG] [YSCALE LOG]
  [VALUES ON|OFF] [LEGEND ON|OFF|TOP|BOTTOM|LEFT|RIGHT]
  [GRID ON|OFF] [STACKED] [SMOOTH]
  [ROTATE <deg>] [FONTSIZE <n>]
  [COLORS ('<hex>', ...)] [THEME DARK|LIGHT|GRAFANA|ANT]
  [WIDTH <px>] [HEIGHT <px>]
  [GROUP BY <column>] [LIMIT <n>] [BINS <n>]

Description

## Overview CREATE CHART executes an inline SELECT query, renders the result as an SVG, and attaches the SVG to the statement's execution result. The GUI displays the SVG inline; the CLI receives it in the response payload but has no way to render it. ## Behavior - The source query runs as a normal SELECT against the session catalog. It can reference any tables visible to the session. - The query is wrapped with `LIMIT (row_limit + 1)` to bound memory. The hard upper bound on rows is 10,000; queries returning more rows are silently truncated. - The resulting Arrow batches are extracted into typed vectors: the X column is treated as labels, Y columns as f64 values. - Rendering uses the `charts-rs` crate. Layout (margins, label rotation, font size) adapts to the data density. - The maximum SVG payload size is 5 MB. Charts that would exceed this are rejected. - CREATE CHART is read-only. It performs no inserts, updates, or schema changes; it does not commit anything to any Delta table. ## Auto column detection - X axis: the first column of the source query when no X clause is supplied. - Y axis: every numeric column other than the X column when no Y clause is supplied. - Pie chart: the first column is treated as labels and the next numeric column as slice values. Slices beyond the first 12 are bucketed into a single 'Other' slice. - Histogram: BINS defaults to Sturges' rule (ceil(log2(n)) + 1) when omitted. ## Access Control The source query runs under the session's existing privileges. CREATE CHART itself requires no additional privilege beyond what the source query needs. ## Compatibility DeltaForge extension. The SVG output is consumed by the DeltaForge GUI and IDE integrations; other clients receive the raw SVG and decide how to render it.

Parameters

Name	Type	Description
chart_type		Specifies the chart kind. Valid values: BAR, HBAR (horizontal bar), LINE, SCATTER, PIE, AREA, HISTOGRAM, HEATMAP, RADAR, CANDLESTICK.
source_query		Specifies the inline SELECT query enclosed in parentheses. The query is wrapped with LIMIT (row_limit + 1) and capped at 10,000 rows.
x_column		Column for the X axis. Defaults to the first column of the source query.
y_columns		Columns for the Y axis. Defaults to all numeric columns except the X column.
y2_columns		Columns plotted against a secondary Y axis.
group_by		Pivots a single Y column into multiple series, one per distinct value of the GROUP BY column.
limit		Caps the rows fetched from the source query. Hard upper bound is 10,000 regardless of the value supplied.
bins		Histogram bin count. Defaults to Sturges' rule when omitted.
theme		Visual theme. Valid values: DARK, LIGHT, GRAFANA, ANT.
width		SVG width in pixels. Capped at 2000.
height		SVG height in pixels. Capped at 2000.

Examples

-- Bar chart of total sales by region
CREATE CHART BAR FROM (SELECT region, SUM(amount) AS total FROM sales GROUP BY region)
  X region Y total
  TITLE 'Sales by Region';

-- Line chart with multiple series
CREATE CHART LINE FROM (SELECT day, signups, churn FROM gold.daily_metrics ORDER BY day)
  X day Y signups, churn
  TITLE 'Daily Signups vs Churn'
  THEME DARK;

-- Pie chart with overflow bucketing
CREATE CHART PIE FROM (SELECT category, SUM(revenue) FROM sales GROUP BY category)
  TITLE 'Revenue by Category';

-- Histogram with auto bin count
CREATE CHART HISTOGRAM FROM (SELECT order_amount FROM orders WHERE order_amount IS NOT NULL)
  TITLE 'Order Amount Distribution';

-- Pivoted line series via GROUP BY
CREATE CHART LINE FROM (SELECT day, region, SUM(amount) AS total FROM sales GROUP BY day, region)
  X day Y total GROUP BY region
  TITLE 'Sales by Region Over Time';

Pitfalls

• Source queries returning more than 10,000 rows are silently truncated. Aggregate or LIMIT inside the source query when working with large tables so the chart reflects the data you intend to plot.
• When run from the CLI or any non-GUI client, the SVG payload is returned in the execution result but is not displayed. CHART is intended for the GUI surface; CLI usage is mostly diagnostic.