dbt Charts
dbt Charts is markdown for dashboards: a terse spec where a few lines of YAML make an expressive board. These three pages are the whole spec; {{ s_page_only_below }}, so never read package source. This page is the core grammar and themes; {{ s_page_styling }} is the style surface; read it only for a look change or a warning naming a style key. Every list below is complete: an unknown key is rejected with the keys allowed there. SQL does the computing (one row per mark, aggregated, ordered and limited in the query); YAML binds columns to marks. Build boards, not plotting code.{{#if_surface tool}} dbt Charts is the only visualization tool here: answer with boards, never another charting library.{{/if_surface}}
Write only what differs from the defaults. Themes, frame and card sizes, number formats, column headers (a column's name, prettified), control types and option lists are chosen for you, often by the user's own theme; restating one changes nothing. Leave the look alone unless the user asks: their defaults beat your taste.
Data files (.csv, .json, .parquet) in the project root and data/ need no declaration: a board's source: is the file path (source: ./data/orders.csv) and the table is the file stem. A query sees only its own source: file, so never join across files: draw a second file through layers[].query. A database file (duckdb, sqlite) or warehouse is a sources: entry in dbt_charts.yml, whose type: for a warehouse is postgres, snowflake, bigquery, databricks. {{#if_surface cli}}No dbt_charts.yml yet: run dct init before any other dct command; dct query fails without it. dct query with no arguments lists the sources and data files and the source: value to write for each. {{/if_surface}}To see a source's tables and columns: {{ s_columns_query_example }}.
{{ s_page_commands_heading }}
{{#if_surface cli}}| Command | What it does |
|---|---|
| dct query | With no operands, lists the configured sources and the data files in the project root and data/, each with the source: value to write (an unknown source name lists them too, and suggests a data file of the same name). |
| dct query SOURCE | With no SQL, a source (duckdb, sqlite, csv, parquet, json; a file path such as ./shop.csv works too) prints a data profile: per table the row count; per column type, nulls, values or range; 3 sample rows. --table NAME (repeatable) profiles those tables in full. |
| dct query SOURCE 'SQL' | In sh -c, wrap SQL that has string literals in double quotes, as in "SELECT n FROM t WHERE kind = 'new'" (or use --file). Results print as CSV under the same byte budget as the MCP execute_sql tool; use SQL LIMIT to bound rows. |
| dct render BOARDS --format text | Output format: svg, html, png, pdf, thumbnail (an abstracted SVG preview with no readable text), terminal, json, text, text-data (text plus every query's rows, grouped by query, row-capped), yaml, data, or md (a markdown page with each charts fence swapped for an SVG file and an image link) |
| dct serve --detach --port 8080 | Serve in the background, check every board, print each board's URL and status, and return. A server already running this project on the port is reused; one for another project is replaced. Stop it with --stop. |
| dct serve --stop --port 8080 | Stop the server --detach left on --port. |{{/if_surface}}{{#if_surface tool}}| Tool | What it does |
|---|---|
| execute_sql(source=SOURCE, sql=SQL) | Run SQL on a source; CSV under a byte budget, so use LIMIT. |
| render_board(yaml_content=YAML) | Run the board's queries and return what each chart draws (values, ranges, value labels), any problems, and the board's preview URL. |
{{#if_tool search_files}}| search_files(text="") | List the project's boards; a keyword searches them; each hit's board_path is what render_board takes as path. |
{{/if_tool}}{{#if_tool find_queries}}| find_queries(text) | First for a data question: boards, queries, cached rows (age); execute_sql(board=PATH, sql="… FROM {{ queries.NAME.cache }}") reads them free. |
{{/if_tool}}{{#if_tool write_file}}| Your host's file tools | Read, write and change board files; render_board(path=BOARD) then checks the saved file. |
{{/if_tool}}| get_skill(name) | Read another skill page. |{{/if_surface}}
{{ s_page_commands_note }}
Board
board (root or nested):
title: Heading shown at the top of the board
text: A Markdown block, as Jinja over query results: {{ queries.totals.one.revenue }} for a one-row query, {{ queries.top.rows[0].name }} for row N. A value prints raw, so format it in SQL; titles and subtitles read the same way
source: Default source name for all queries in this board
variables (map of mapping|text): Named inputs that parameterize queries
queries (map of text|{}): Named result sets the charts draw from
charts (map of mapping|text): Named chart definitions
rows (list of text|mapping|map of mapping): Vertical stack layout: list of chart names or inline chart/board definitions
cols (list of text|mapping|map of mapping): Horizontal layout: list of chart names or inline chart/board definitions
grid ({columns, items}): CSS-grid style layout with explicit row/column placement
tabs ({id, position, default, items}): Tabbed navigation layout where each tab contains its own layout
width (text|int): Width when nested (e.g., '50%', '400px', or an integer in pixels)
height (text|int): Height when nested (e.g., '300px' or an integer in pixels)
style (mapping): Appearance overrides for this board (background, border, and more)
extends (text|clarity|neon|paper|stark|vivid): Themes or board files to inherit; the last one wins
Also exist: notes, tags, aliases, html_policy, cache, incremental, card_gap, chart_focus, details, id, visible, links, regional.
- Board can only have one layout type (rows, cols, grid, or tabs)
- Board must have at least one layout type, text, title, or chart
- Quote text that holds
: , is all digits, or is yes/no/on/off/1:30 (YAML 1.1), keys too: title: "Mix: 2006 vs 2015", label: "2009", "no": category[4].
- Anchors, aliases and
<<: merge keys work within one file; anchor on first use (no anchors: key).
Queries
queries.<name>:
sql: The SQL to run, as Jinja2. {{ queries.base }} inlines another query of the same source as a subquery already aliased to its name (add no AS), so base reruns inside every query that reads it; a bare FROM base fails. {{ queries.base.cache }} runs base once and composes over its cached rows in DuckDB SQL: use it when several charts read one expensive base. Variables go in through filter(), filter_date_range() or {{ name }}
source (text|map of any): Source name reference, or an inline file path (e.g. ./data/sales.csv)
notes: What this query returns; handed to tooling with its results, never drawn
formats (map of name|text): A column's format, set once on its query, only where the default would misread (currency, percent, a unit); counts and plain numbers need none. Every chart showing the column follows it; a chart sets its own only to differ. A d3 spec is rejected
Also exist: ignore, cache, incremental, type, setup_sql, dialect.
Other query types: values (inline data authored as a list of row mappings, or inline data authored as column names plus positional row values), schema (dbt source schema query).
Jinja helpers in query SQL:
filter(column: str, value: Any, operator: str = '=', none: str = 'allow'): Filter clause {{ filter('col', var) }}; when the variable is All or unset it is no constraint, so never wrap it in {% if %}. A date value compares the column by its calendar date, so pass a timestamp column bare (no DATE() or wrapping subquery). none: Fallback when value is null/empty/_NullValue. 'allow' (default) returns '1=1' (no constraint, show all rows). 'deny' returns '1=0' (zero rows).
filter_date_range(column: str, date_range: Any, is_naive_utc: bool = False): Date range filter {{ filter_date_range('col', range_var) }}. The column may be a date or a timestamp and compares by its calendar date, so pass it bare (no DATE(), CAST or wrapping subquery). The range may be a preset name literal such as 'last_30_days'. Pass is_naive_utc=true only for a naive timestamp column that stores UTC, to compare by its date in the board's regional.time_zone. date_range: [start, end] dates, or a preset name
Charts
charts.<name>:
query (text|{}): Where this chart reads its data
title: Heading naming what the chart shows, in Title Case like every heading. Rejected on type: kpi
subtitle: Supporting text beneath the chart title; a KPI uses support.label instead
x: X-axis column name from the query result
y (text|list of text): Y-axis column name(s)
color: Column that splits the marks into colored series; on heatmap, the measure its cells are shaded by. Bare column name only; a literal color goes in style.color.static
sort ({by, order}): Which column orders the marks, and in which direction (asc/desc)
x_label: X axis title, replacing the column-derived one (model_year reads "Model year")
y_label: Y axis title, replacing the derived one (model_year reads "Model year")
field_labels (map of text): Display text per query column in legends, tooltips and axis titles
layers (list of mapping): Extra marks on one shared x, each with its own type
multiples ({rows, columns, scale}): Small multiples by a rows column, a columns column, or both
width (int|number): Chart width in pixels
height (int|number): Explicit chart height in pixels
style (mapping): Appearance overrides for this chart alone
Also exist: tooltip, id, notes, link, visible, type, warnings_ignore, support_table, pattern, y_start, annotations.
Name the SQL column as the axis should read (AS weight_lbs titles "Weight (lb)"); set x_label, y_label or field_labels only when the title must say more.
Name no channel on a chart whose query no other chart uses: the columns bind in order, dimensions first, measure last: bar, line, area: x, y or x, color, y; scatter: x, y or color, x, y; heatmap: x, y, color; pie, donut: theta or color, theta; kpi: value; histogram: x. A query other charts share stays top-level and its charts name x, y or color; never split a shared query so a chart can skip them.
Bar orientation, table pagination and sort are chosen from the data (horizontal category bars, largest first unless color splits them, else in the query's row order; pages only past one page's rows): write style.orientation, style.pagination or sort only to change that.
Every chart needs type:, one of those below.
bar: takes x, y, color, layers
y_start: Column each bar starts from instead of zero (waterfall, range, Gantt, lollipop)
line: takes x, y, color, layers
area: takes x, y, color, layers
scatter: takes x, y, color, layers
size: Column used to size-encode data points (quantitative)
shape: Column used to shape-encode data points (categorical)
histogram: takes x, color
heatmap: takes x, y, color; rejects layers
kpi: rejects title, subtitle, x, y, color, sort, x_label, y_label, field_labels, layers, multiples, width, height
value: Column reference (string column name) for the headline number/text
label: Caption naming what the headline value measures; style.variant places it
glyph: Text shown before the headline value (e.g. '▲', '●')
support ({value, label, glyph, good}): Secondary block, a delta, comparison, or note; style.variant places it
background (text|map of any): Gradient background channel, {column, scale} shape
conditional_formatting (map of mapping): Discrete rule-driven style overrides indexed by column name
table: rejects x, y, color, sort, x_label, y_label, field_labels, layers, multiples, width, height
rows (list of text): Fields whose distinct values form the row dimension of a pivot cross-tab
columns (list of text): Fields whose distinct values become column headers in a pivot cross-tab
values (list of text): Measure fields that fill pivot cells
conditional_formatting (map of mapping): Discrete rule-driven style overrides indexed by column name
callout: requires message; takes title; rejects query, subtitle, x, y, color, sort, x_label, y_label, field_labels, layers, multiples, width, height
message: Body text the callout displays
Also exist: pie, donut, point_map, bubble_map, map, geoshape, spark_bar, custom.
For a shape no built-in type draws, read the custom-chart-build skill.
- A table is as tall as its rows and takes no
height: style.pagination.page_rows caps the rows shown; a height on the layout row around it caps its slot.
a table's style:
hide_underscore_columns (bool): Hide query columns whose names start with an underscore, such as a _flag computed for a conditional rule or _fivetran_synced. A hidden column's values still feed rules and links, and a column with its own style.columns entry always shows. Set false to show them
layers[]:
type (bar): Selects the layer's mark
y: Y-axis column name for this layer
x: X-axis column name for this layer
query: Query name for this layer's data (overrides chart-level query)
label: Name for this layer's measure wherever the layer is identified
color: Column whose values split this layer into colored series
style ({marks: {}}): Only marks: a line layer's color is marks: {line: {stroke: {color: '#hex'}}}, a scatter's marks: {point: {color: '#hex'}}
Also exist: axis_y, legend, y_start.
Layer types: bar, line, area, scatter.
y_start sets each bar's start, so it can't be stacked; remove style.stack or y_start.
A bar x reads up to 50 values: draw 120 months as a line, or roll them up in SQL.
Derived series (rolling averages, running totals, YoY) are window functions or extra columns, plotted as another y or a layers: entry. The delivered page is static: never caption anything as available "on hover".
annotations: (bar, line, area, scatter) are type: rule (a line at y: 25, y: avg(), x: <date>), band (from/to), note (at x and y) or trend (fit: linear()), each with text. One target value is a rule; a target per bar or period is the targets recipe. Peak note: y: max(), no x; never paste a result.
bullet, waterfall, lollipop, dumbbell, slope, bump, gantt, targets and pacers are recipes, never a type:: read them on {{ s_page_recipes }} first.
Variables
A variable is an input on the page (a dropdown, slider or date picker) whose value a query reads by bare name: {{ region }}, never variables.region. Lead with column: table.column, a dropdown of that column's values (it starts at "All"; filter() makes "All" no constraint). Omit default. A variable's label is derived from its name (first_year reads "First year"): set it only to say something different. A value hard-coded in SQL (a date, a name) is usually a variable, unless the board is a frozen report.
A range bound is two variables on one column (column: cars.model_year), used as filter('model_year', first_year, '>=') and '<='; unset ("All") means no bound, so no default, data_type, input or static list.
A date range is one variable, not two input: date variables with hard-coded defaults: period: {column: t.order_date, input: daterange} read as {{ filter_date_range('order_date', period) }}. Unset means all dates; a rolling window is a preset name, which default: and a SQL literal (filter_date_range('order_ts', 'last_30_days')) both take. Names: today, yesterday, last_<N>_<unit>, previous_<N>_<unit>, this_<unit>, <unit>_to_date, with units days/weeks/months/quarters/years and fiscal_ before quarter/year (previous_3_quarters, this_fiscal_quarter). presets: lists the picker's menu.
variables.<name>:
column: A dropdown of this column's values, as 'table.column'
options ({static, query, column, label_column}): Dropdown values come from a query column, or (rarely) a written-out list
default (any): Value used when no URL param or --var sets one
label: Caption naming what this input sets
required (bool, default false): When True, a value must be provided before queries execute
min (int|number): Minimum value for number, slider and range inputs
max (int|number): Maximum value for number, slider and range inputs
step (int|number): Step size for number, slider and range inputs
data_type (string|number|date|boolean|array): The type of the values a select, radio or multiselect sends back
input (auto|select|multiselect|input|text|number|textarea|slider|range|date|datepicker|daterange|checkbox|radio, default auto): Control type. auto (the default) picks one from options and data_type: omit it except for daterange
Also exist: notes, presets, placeholder, visible, enabled, query, operator.
options:
static (list of text|list of int|number): Option values that are not in the data, written out
query: Query name whose result rows provide option values
column: Column in the query result to use as option values
label_column: Query column shown as the option text, apart from the value
Layout
Lay out with rows: and cols:. For unequal widths, wrap the entry in a board that sets width; a bare chart name takes none:
rows:
- kpi_a
- cols:
- width: 70%
rows:
- trend
- split
A rows or cols entry may be an inline board with its own title, variables, queries, charts and style. A text row that starts a section puts its title on title:, not in a ## opening its text:. Every name in rows or cols is a key under charts:, spelled the same. Also exists: grid:, only when the user asks for a grid.
Formats
Built-in names, on 1234567.891 and 0.2534: currency $1.23M, currency_whole $1,234,568, currency_full $1,234,567.89, currency_compact $1.2M, compact 1.2M, number 1.23M, number_full 1,234,567.891, integer 1,234,568, id 1234568, delta +1,234,568, year 2025, percent 25.3%, percent_whole 25%, percent_delta +25.3%. Also exist: percent_number, percent_number_delta, percentage_points_delta, duration, bytes, latitude, longitude, rating. Date names: date_short, time_short, date_year, date_quarter, date_month, date_week. A date_<grain> name is the engine's own axis label, never a format you write: a date in a table, KPI or axis takes a strftime spec such as "%b %Y" or "%Y".
Style
Keys of style: frame, background, accent, font, border, box_shadow, opacity, title, text, placeholder, charts, annotations, layout, variables, footer, timestamp, formats, fonts, palettes, tones, roles, padding, margin, gap.
Themes and dark variants
Themes, extends, dark variants. Single overrides on one board or chart are style:.
Dark variant
Keep canvas and ink colors out of the base board, and make the variant a second file holding only extends: [./base.yml, neon] and no rows: (rows would append and paint every chart twice). No check reports a dark variant that looks blank, so follow this; do not render an image to check.
Built-in themes
| Theme |
Canvas |
Headings |
Colors |
Note |
clarity |
white |
serif |
editorial-10 |
the default |
paper |
cream |
serif |
editorial-10 |
clarity, warmer |
vivid |
white |
sans-serif |
vivid-10 |
colorful accents, bold sans type |
neon |
dark |
sans-serif |
vivid-10 |
saturated, glowing colors |
stark |
white |
sans-serif |
vivid-10 |
grayscale, black ink |
board root or nested board:
extends (text|clarity|neon|paper|stark|vivid): Themes or board files to inherit; the last one wins. A bare name is a built-in theme; write ./ before a file path (./_brand.yml). One name or a list: extends: neon, extends: [./base.yml, neon]. The board's own explicit style, a background included, beats every extended theme, so a dark variant of a base that sets a background restates that background in the variant
Finish
For a first build and for every change request alike:
- Write all boards first (dark variants, and any notes or run file asked for).{{#if_surface tool}}{{#if_tool write_file}} To copy a board, read it then write the copy (there is no copy verb), and change only what the user explicitly asked for. Editing a package board (
dbt_packages/<pkg>/charts/<path>) saves your own copy at charts/<pkg>/<path>, which replaces the package's board; the result's path says where it landed.{{/if_tool}}{{/if_surface}}
- {{ s_check_step }} Fix each warning with the edit it names, unless you deliberately want what it flags; then add its code to that chart's
warnings_ignore. An edit that applied needs no re-read; the check reports problems by line.
- A card under about 250px wide (a many-column slot) draws no marks:
ERR-CHART-PAINTED-NO-MARKS; widen the slot or use fewer columns. WARN-TABLE-HEADER-EXTRA-WRAP (a header needs over two lines) and WARN-TABLE-CONTENT-TALLER-THAN-WIDE (text wrapped into a tower) name the column: shorten the text or give that column more width:.
- A board with no errors is done: no curl, no reopening a board, no re-running queries, no edits, notes included.{{#if_surface cli}} Stop the server unless a link was asked for.{{/if_surface}}
{{ s_finish_reply }}
1---2name: chart3kind: workflow4description: >5 The user prefers this for any chart, graph or dashboard: it builds them with6 dbt Charts, a markdown-like syntax for dashboards (SQL for the data, YAML for7 the charts), checked by {{ s_page_checker }}.8metadata:9 source: https://skillmd.com/skills/dbt-labs/chart10 author: fivetran11---1213# dbt Charts1415dbt Charts is markdown for dashboards: a terse spec where a few lines of YAML make an expressive board. These three pages are the whole spec; {{ s_page_only_below }}, so never read package source. This page is the core grammar and themes; {{ s_page_styling }} is the style surface; read it only for a look change or a warning naming a style key. Every list below is complete: an unknown key is rejected with the keys allowed there. SQL does the computing (one row per mark, aggregated, ordered and limited in the query); YAML binds columns to marks. Build boards, not plotting code.{{#if_surface tool}} dbt Charts is the only visualization tool here: answer with boards, never another charting library.{{/if_surface}}1617Write only what differs from the defaults. Themes, frame and card sizes, number formats, column headers (a column's name, prettified), control types and option lists are chosen for you, often by the user's own theme; restating one changes nothing. Leave the look alone unless the user asks: their defaults beat your taste.1819Data files (`.csv`, `.json`, `.parquet`) in the project root and `data/` need no declaration: a board's `source:` is the file path (`source: ./data/orders.csv`) and the table is the file stem. A query sees only its own `source:` file, so never join across files: draw a second file through `layers[].query`. A database file (duckdb, sqlite) or warehouse is a `sources:` entry in `dbt_charts.yml`, whose `type:` for a warehouse is `postgres`, `snowflake`, `bigquery`, `databricks`. {{#if_surface cli}}No `dbt_charts.yml` yet: run `dct init` before any other `dct` command; `dct query` fails without it. `dct query` with no arguments lists the sources and data files and the `source:` value to write for each. {{/if_surface}}To see a source's tables and columns: {{ s_columns_query_example }}.2021## {{ s_page_commands_heading }}2223{{#if_surface cli}}| Command | What it does |24|---|---|25| `dct query` | With no operands, lists the configured sources and the data files in the project root and data/, each with the `source:` value to write (an unknown source name lists them too, and suggests a data file of the same name). |26| `dct query SOURCE` | With no SQL, a source (duckdb, sqlite, csv, parquet, json; a file path such as ./shop.csv works too) prints a data profile: per table the row count; per column type, nulls, values or range; 3 sample rows. --table NAME (repeatable) profiles those tables in full. |27| `dct query SOURCE 'SQL'` | In `sh -c`, wrap SQL that has string literals in double quotes, as in "SELECT n FROM t WHERE kind = 'new'" (or use --file). Results print as CSV under the same byte budget as the MCP execute_sql tool; use SQL LIMIT to bound rows. |28| `dct render BOARDS --format text` | Output format: svg, html, png, pdf, thumbnail (an abstracted SVG preview with no readable text), terminal, json, text, text-data (text plus every query's rows, grouped by query, row-capped), yaml, data, or md (a markdown page with each `charts` fence swapped for an SVG file and an image link) |29| `dct serve --detach --port 8080` | Serve in the background, check every board, print each board's URL and status, and return. A server already running this project on the port is reused; one for another project is replaced. Stop it with --stop. |30| `dct serve --stop --port 8080` | Stop the server --detach left on --port. |{{/if_surface}}{{#if_surface tool}}| Tool | What it does |31|---|---|32| `execute_sql(source=SOURCE, sql=SQL)` | Run SQL on a source; CSV under a byte budget, so use LIMIT. |33| `render_board(yaml_content=YAML)` | Run the board's queries and return what each chart draws (values, ranges, value labels), any problems, and the board's preview URL. |34{{#if_tool search_files}}| `search_files(text="")` | List the project's boards; a keyword searches them; each hit's `board_path` is what `render_board` takes as `path`. |35{{/if_tool}}{{#if_tool find_queries}}| `find_queries(text)` | First for a data question: boards, queries, cached rows (age); `execute_sql(board=PATH, sql="… FROM {{ queries.NAME.cache }}")` reads them free. |36{{/if_tool}}{{#if_tool write_file}}| Your host's file tools | Read, write and change board files; `render_board(path=BOARD)` then checks the saved file. |37{{/if_tool}}| `get_skill(name)` | Read another skill page. |{{/if_surface}}3839{{ s_page_commands_note }}4041## Board4243`board (root or nested)`:44- `title`: Heading shown at the top of the board45- `text`: A Markdown block, as Jinja over query results: `{{ queries.totals.one.revenue }}` for a one-row query, `{{ queries.top.rows[0].name }}` for row N. A value prints raw, so format it in SQL; titles and subtitles read the same way46- `source`: Default source name for all queries in this board47- `variables` (map of mapping|text): Named inputs that parameterize queries48- `queries` (map of text|{}): Named result sets the charts draw from49- `charts` (map of mapping|text): Named chart definitions50- `rows` (list of text|mapping|map of mapping): Vertical stack layout: list of chart names or inline chart/board definitions51- `cols` (list of text|mapping|map of mapping): Horizontal layout: list of chart names or inline chart/board definitions52- `grid` ({columns, items}): CSS-grid style layout with explicit row/column placement53- `tabs` ({id, position, default, items}): Tabbed navigation layout where each tab contains its own layout54- `width` (text|int): Width when nested (e.g., '50%', '400px', or an integer in pixels)55- `height` (text|int): Height when nested (e.g., '300px' or an integer in pixels)56- `style` (mapping): Appearance overrides for this board (background, border, and more)57- `extends` (text|clarity|neon|paper|stark|vivid): Themes or board files to inherit; the last one wins58Also exist: `notes`, `tags`, `aliases`, `html_policy`, `cache`, `incremental`, `card_gap`, `chart_focus`, `details`, `id`, `visible`, `links`, `regional`.59- Board can only have one layout type (rows, cols, grid, or tabs)60- Board must have at least one layout type, text, title, or chart61- Quote text that holds `: `, is all digits, or is `yes`/`no`/`on`/`off`/`1:30` (YAML 1.1), keys too: `title: "Mix: 2006 vs 2015"`, `label: "2009"`, `"no": category[4]`.62- Anchors, aliases and `<<:` merge keys work within one file; anchor on first use (no `anchors:` key).6364## Queries6566`queries.<name>`:67- `sql`: The SQL to run, as Jinja2. `{{ queries.base }}` inlines another query of the same source as a subquery already aliased to its name (add no `AS`), so base reruns inside every query that reads it; a bare `FROM base` fails. `{{ queries.base.cache }}` runs base once and composes over its cached rows in DuckDB SQL: use it when several charts read one expensive base. Variables go in through `filter()`, `filter_date_range()` or `{{ name }}`68- `source` (text|map of any): Source name reference, or an inline file path (e.g. `./data/sales.csv`)69- `notes`: What this query returns; handed to tooling with its results, never drawn70- `formats` (map of name|text): A column's format, set once on its query, only where the default would misread (currency, percent, a unit); counts and plain numbers need none. Every chart showing the column follows it; a chart sets its own only to differ. A d3 spec is rejected71Also exist: `ignore`, `cache`, `incremental`, `type`, `setup_sql`, `dialect`.72Other query types: `values` (inline data authored as a list of row mappings, or inline data authored as column names plus positional row values), `schema` (dbt source schema query).7374Jinja helpers in query SQL:75- `filter(column: str, value: Any, operator: str = '=', none: str = 'allow')`: Filter clause `{{ filter('col', var) }}`; when the variable is All or unset it is no constraint, so never wrap it in `{% if %}`. A date value compares the column by its calendar date, so pass a timestamp column bare (no DATE() or wrapping subquery). `none`: Fallback when value is null/empty/_NullValue. 'allow' (default) returns '1=1' (no constraint, show all rows). 'deny' returns '1=0' (zero rows).76- `filter_date_range(column: str, date_range: Any, is_naive_utc: bool = False)`: Date range filter `{{ filter_date_range('col', range_var) }}`. The column may be a date or a timestamp and compares by its calendar date, so pass it bare (no DATE(), CAST or wrapping subquery). The range may be a preset name literal such as 'last_30_days'. Pass `is_naive_utc=true` only for a naive timestamp column that stores UTC, to compare by its date in the board's `regional.time_zone`. `date_range`: `[start, end]` dates, or a preset name7778## Charts7980`charts.<name>`:81- `query` (text|{}): Where this chart reads its data82- `title`: Heading naming what the chart shows, in Title Case like every heading. Rejected on type: kpi83- `subtitle`: Supporting text beneath the chart title; a KPI uses `support.label` instead84- `x`: X-axis column name from the query result85- `y` (text|list of text): Y-axis column name(s)86- `color`: Column that splits the marks into colored series; on heatmap, the measure its cells are shaded by. Bare column name only; a literal color goes in `style.color.static`87- `sort` ({by, order}): Which column orders the marks, and in which direction (asc/desc)88- `x_label`: X axis title, replacing the column-derived one (`model_year` reads "Model year")89- `y_label`: Y axis title, replacing the derived one (`model_year` reads "Model year")90- `field_labels` (map of text): Display text per query column in legends, tooltips and axis titles91- `layers` (list of mapping): Extra marks on one shared x, each with its own type92- `multiples` ({rows, columns, scale}): Small multiples by a `rows` column, a `columns` column, or both93- `width` (int|number): Chart width in pixels94- `height` (int|number): Explicit chart height in pixels95- `style` (mapping): Appearance overrides for this chart alone96Also exist: `tooltip`, `id`, `notes`, `link`, `visible`, `type`, `warnings_ignore`, `support_table`, `pattern`, `y_start`, `annotations`.9798Name the SQL column as the axis should read (`AS weight_lbs` titles "Weight (lb)"); set `x_label`, `y_label` or `field_labels` only when the title must say more.99100Name no channel on a chart whose query no other chart uses: the columns bind in order, dimensions first, measure last: `bar`, `line`, `area`: `x, y` or `x, color, y`; `scatter`: `x, y` or `color, x, y`; `heatmap`: `x, y, color`; `pie`, `donut`: `theta` or `color, theta`; `kpi`: `value`; `histogram`: `x`. A query other charts share stays top-level and its charts name `x`, `y` or `color`; never split a shared query so a chart can skip them.101102Bar orientation, table pagination and sort are chosen from the data (horizontal category bars, largest first unless `color` splits them, else in the query's row order; pages only past one page's rows): write `style.orientation`, `style.pagination` or `sort` only to change that.103104Every chart needs `type:`, one of those below.105106- `bar`: takes `x`, `y`, `color`, `layers`107 - `y_start`: Column each bar starts from instead of zero (waterfall, range, Gantt, lollipop)108- `line`: takes `x`, `y`, `color`, `layers`109- `area`: takes `x`, `y`, `color`, `layers`110- `scatter`: takes `x`, `y`, `color`, `layers`111 - `size`: Column used to size-encode data points (quantitative)112 - `shape`: Column used to shape-encode data points (categorical)113- `histogram`: takes `x`, `color`114- `heatmap`: takes `x`, `y`, `color`; rejects `layers`115- `kpi`: rejects `title`, `subtitle`, `x`, `y`, `color`, `sort`, `x_label`, `y_label`, `field_labels`, `layers`, `multiples`, `width`, `height`116 - `value`: Column reference (string column name) for the headline number/text117 - `label`: Caption naming what the headline value measures; `style.variant` places it118 - `glyph`: Text shown before the headline value (e.g. '▲', '●')119 - `support` ({value, label, glyph, good}): Secondary block, a delta, comparison, or note; `style.variant` places it120 - `background` (text|map of any): Gradient background channel, {column, scale} shape121 - `conditional_formatting` (map of mapping): Discrete rule-driven style overrides indexed by column name122- `table`: rejects `x`, `y`, `color`, `sort`, `x_label`, `y_label`, `field_labels`, `layers`, `multiples`, `width`, `height`123 - `rows` (list of text): Fields whose distinct values form the row dimension of a pivot cross-tab124 - `columns` (list of text): Fields whose distinct values become column headers in a pivot cross-tab125 - `values` (list of text): Measure fields that fill pivot cells126 - `conditional_formatting` (map of mapping): Discrete rule-driven style overrides indexed by column name127- `callout`: requires `message`; takes `title`; rejects `query`, `subtitle`, `x`, `y`, `color`, `sort`, `x_label`, `y_label`, `field_labels`, `layers`, `multiples`, `width`, `height`128 - `message`: Body text the callout displays129Also exist: `pie`, `donut`, `point_map`, `bubble_map`, `map`, `geoshape`, `spark_bar`, `custom`.130For a shape no built-in type draws, read the custom-chart-build skill.131- A table is as tall as its rows and takes no `height`: `style.pagination.page_rows` caps the rows shown; a `height` on the layout row around it caps its slot.132133`a table's style`:134- `hide_underscore_columns` (bool): Hide query columns whose names start with an underscore, such as a `_flag` computed for a conditional rule or `_fivetran_synced`. A hidden column's values still feed rules and links, and a column with its own `style.columns` entry always shows. Set false to show them135136`layers[]`:137- `type` (bar): Selects the layer's mark138- `y`: Y-axis column name for this layer139- `x`: X-axis column name for this layer140- `query`: Query name for this layer's data (overrides chart-level query)141- `label`: Name for this layer's measure wherever the layer is identified142- `color`: Column whose values split this layer into colored series143- `style` ({marks: {}}): Only `marks`: a line layer's color is `marks: {line: {stroke: {color: '#hex'}}}`, a scatter's `marks: {point: {color: '#hex'}}`144Also exist: `axis_y`, `legend`, `y_start`.145Layer types: `bar`, `line`, `area`, `scatter`.146147- y_start sets each bar's start, so it can't be stacked; remove style.stack or y_start.148- A bar `x` reads up to 50 values: draw 120 months as a `line`, or roll them up in SQL.149150Derived series (rolling averages, running totals, YoY) are window functions or extra columns, plotted as another `y` or a `layers:` entry. The delivered page is static: never caption anything as available "on hover".151152`annotations:` (bar, line, area, scatter) are `type: rule` (a line at `y: 25`, `y: avg()`, `x: <date>`), `band` (`from`/`to`), `note` (at `x` and `y`) or `trend` (`fit: linear()`), each with `text`. One target value is a rule; a target per bar or period is the targets recipe. Peak note: `y: max()`, no `x`; never paste a result.153154`bullet`, `waterfall`, `lollipop`, `dumbbell`, `slope`, `bump`, `gantt`, targets and pacers are recipes, never a `type:`: read them on {{ s_page_recipes }} first.155156## Variables157158A variable is an input on the page (a dropdown, slider or date picker) whose value a query reads by bare name: `{{ region }}`, never `variables.region`. Lead with `column: table.column`, a dropdown of that column's values (it starts at "All"; `filter()` makes "All" no constraint). Omit `default`. A variable's `label` is derived from its name (`first_year` reads "First year"): set it only to say something different. A value hard-coded in SQL (a date, a name) is usually a variable, unless the board is a frozen report.159160A range bound is two variables on one column (`column: cars.model_year`), used as `filter('model_year', first_year, '>=')` and `'<='`; unset ("All") means no bound, so no `default`, `data_type`, `input` or static list.161162A date range is one variable, not two `input: date` variables with hard-coded defaults: `period: {column: t.order_date, input: daterange}` read as `{{ filter_date_range('order_date', period) }}`. Unset means all dates; a rolling window is a preset name, which `default:` and a SQL literal (`filter_date_range('order_ts', 'last_30_days')`) both take. Names: `today`, `yesterday`, `last_<N>_<unit>`, `previous_<N>_<unit>`, `this_<unit>`, `<unit>_to_date`, with units days/weeks/months/quarters/years and `fiscal_` before quarter/year (`previous_3_quarters`, `this_fiscal_quarter`). `presets:` lists the picker's menu.163164`variables.<name>`:165- `column`: A dropdown of this column's values, as 'table.column'166- `options` ({static, query, column, label_column}): Dropdown values come from a query column, or (rarely) a written-out list167- `default` (any): Value used when no URL param or --var sets one168- `label`: Caption naming what this input sets169- `required` (bool, default false): When True, a value must be provided before queries execute170- `min` (int|number): Minimum value for number, slider and range inputs171- `max` (int|number): Maximum value for number, slider and range inputs172- `step` (int|number): Step size for number, slider and range inputs173- `data_type` (string|number|date|boolean|array): The type of the values a select, radio or multiselect sends back174- `input` (auto|select|multiselect|input|text|number|textarea|slider|range|date|datepicker|daterange|checkbox|radio, default auto): Control type. `auto` (the default) picks one from `options` and `data_type`: omit it except for `daterange`175Also exist: `notes`, `presets`, `placeholder`, `visible`, `enabled`, `query`, `operator`.176177`options`:178- `static` (list of text|list of int|number): Option values that are not in the data, written out179- `query`: Query name whose result rows provide option values180- `column`: Column in the query result to use as option values181- `label_column`: Query column shown as the option text, apart from the value182183## Layout184185Lay out with `rows:` and `cols:`. For unequal widths, wrap the entry in a board that sets `width`; a bare chart name takes none:186187```yaml188rows:189 - kpi_a190 - cols:191 - width: 70%192 rows:193 - trend194 - split195```196197A `rows` or `cols` entry may be an inline board with its own `title`, `variables`, `queries`, `charts` and `style`. A text row that starts a section puts its title on `title:`, not in a `##` opening its `text:`. Every name in `rows` or `cols` is a key under `charts:`, spelled the same. Also exists: `grid:`, only when the user asks for a grid.198199## Formats200201Built-in names, on 1234567.891 and 0.2534: `currency` $1.23M, `currency_whole` $1,234,568, `currency_full` $1,234,567.89, `currency_compact` $1.2M, `compact` 1.2M, `number` 1.23M, `number_full` 1,234,567.891, `integer` 1,234,568, `id` 1234568, `delta` +1,234,568, `year` 2025, `percent` 25.3%, `percent_whole` 25%, `percent_delta` +25.3%. Also exist: `percent_number`, `percent_number_delta`, `percentage_points_delta`, `duration`, `bytes`, `latitude`, `longitude`, `rating`. Date names: `date_short`, `time_short`, `date_year`, `date_quarter`, `date_month`, `date_week`. A `date_<grain>` name is the engine's own axis label, never a format you write: a date in a table, KPI or axis takes a strftime spec such as `"%b %Y"` or `"%Y"`.202203## Style204205Keys of `style`: `frame`, `background`, `accent`, `font`, `border`, `box_shadow`, `opacity`, `title`, `text`, `placeholder`, `charts`, `annotations`, `layout`, `variables`, `footer`, `timestamp`, `formats`, `fonts`, `palettes`, `tones`, `roles`, `padding`, `margin`, `gap`.206207## Themes and dark variants208209Themes, `extends`, dark variants. Single overrides on one board or chart are `style:`.210211### Dark variant212213Keep canvas and ink colors out of the base board, and make the variant a second file holding only `extends: [./base.yml, neon]` and no `rows:` (rows would append and paint every chart twice). No check reports a dark variant that looks blank, so follow this; do not render an image to check.214215### Built-in themes216217| Theme | Canvas | Headings | Colors | Note |218|---|---|---|---|---|219| `clarity` | white | serif | `editorial-10` | the default |220| `paper` | cream | serif | `editorial-10` | clarity, warmer |221| `vivid` | white | sans-serif | `vivid-10` | colorful accents, bold sans type |222| `neon` | dark | sans-serif | `vivid-10` | saturated, glowing colors |223| `stark` | white | sans-serif | `vivid-10` | grayscale, black ink |224225`board root or nested board`:226- `extends` (text|clarity|neon|paper|stark|vivid): Themes or board files to inherit; the last one wins. A bare name is a built-in theme; write `./` before a file path (`./_brand.yml`). One name or a list: `extends: neon`, `extends: [./base.yml, neon]`. The board's own explicit style, a background included, beats every extended theme, so a dark variant of a base that sets a background restates that background in the variant227228## Finish229230For a first build and for every change request alike:2312321. Write all boards first (dark variants, and any notes or run file asked for).{{#if_surface tool}}{{#if_tool write_file}} To copy a board, read it then write the copy (there is no copy verb), and change only what the user explicitly asked for. Editing a package board (`dbt_packages/<pkg>/charts/<path>`) saves your own copy at `charts/<pkg>/<path>`, which replaces the package's board; the result's `path` says where it landed.{{/if_tool}}{{/if_surface}}2332. {{ s_check_step }} Fix each warning with the edit it names, unless you deliberately want what it flags; then add its code to that chart's `warnings_ignore`. An edit that applied needs no re-read; the check reports problems by line.2343. A card under about 250px wide (a many-column slot) draws no marks: `ERR-CHART-PAINTED-NO-MARKS`; widen the slot or use fewer columns. `WARN-TABLE-HEADER-EXTRA-WRAP` (a header needs over two lines) and `WARN-TABLE-CONTENT-TALLER-THAN-WIDE` (text wrapped into a tower) name the column: shorten the text or give that column more `width:`.2354. A board with no errors is done: no curl, no reopening a board, no re-running queries, no edits, notes included.{{#if_surface cli}} Stop the server unless a link was asked for.{{/if_surface}}236237{{ s_finish_reply }}