How do I...?¶

Quick answers to the questions people ask most, written the way they ask them. Each answer is the short version and links to the page that has the full one. If you came from another BI tool, start here: dbt Charts has no drag-and-drop editor, so "move", "resize", and "hide" all mean editing a few lines of YAML.

Getting started¶

How do I install dbt Charts?¶

uv tool install dbt-charts (or pip install dbt-charts) on Python 3.10 or newer, then add the adapter extra for your warehouse. See Installation.

What is the smallest thing I need to make a dashboard?¶

A dbt_charts.yml naming a data source, and one YAML file under charts/ with a query, a chart, and a rows: list. The Quick Start example is complete in about twenty lines.

What is a board?¶

A board is the YAML file that defines a dashboard: its queries, charts, variables, and layout. Boards can nest inside other boards. See Boards.

Is there a drag-and-drop editor?¶

No. Every dashboard is a YAML file in git, and layout is expressed as rows:, cols:, grid:, or tabs:. The Playground and the VS Code extension give you a live preview while you edit.

How do I preview a dashboard while I work on it?¶

Run dct serve and open the board in your browser, or press Cmd+Shift+V in VS Code with the extension installed. Both re-render on save.

How do I see all my dashboards in one place?¶

dct serve lists every board under charts/ at /, or serves charts/index.yml there if you create one. See URL routing.

Can an AI assistant build dashboards for me?¶

Yes. dct init mcp wires the MCP server into Cursor, Claude Code, or ChatGPT, and dct init skills installs authoring skills. Cloud users can also use the Claude and ChatGPT connector.

Where do I find the full list of YAML fields?¶

The generated YAML Schema Reference lists every field on every chart type. The Quick Reference is the one-page cheat sheet.

Arranging a dashboard¶

How do I move a chart?¶

Reorder it in the layout list. Charts render in the order they appear under rows: or cols:; cut the line and paste it where you want it. In a grid:, set col and row on the item to pin it. See Board Layouts.

How do I put two charts side by side?¶

Wrap them in a cols: list. Three items get a third of the width each. See Cols.

How do I make a chart full width?¶

Give it its own entry in rows: rather than sharing a cols: row. In a grid: with columns: 24, set the item's width: 24. See Grid Layout.

How do I resize a chart?¶

Width comes from the layout: set width: "70%" on a cols: item, or a column span on a grid: item. Height is set on the chart with height: 400, or as a shape with style.aspect_ratio. See Board Sizing.

How do I make one column wider than the others?¶

Set width: on the cols: items ("70%" and "30%"), or nest a cols: inside a cols: for splits like 50/25/25. See Unequal Widths with Nesting.

How do I make a row of KPIs shorter?¶

Set height: "120px" on the row item that wraps them. KPI cards, tables, and callouts size themselves; height: on those chart types is rejected. See Height on Rows.

How do I change the overall width of the dashboard?¶

Set style.frame.width for an exact width, or style.frame.max_width to cap how wide the content may grow. See Width Rule.

How do I add a section heading?¶

Give a nested board a title:. Titled sections render as headings, and heading levels follow nesting depth automatically. See Board Content.

How do I add text, notes, or a paragraph of explanation?¶

Add a text: block at the board root or as a layout item. It is Markdown: headings, lists, tables, links, and images all work. See Board Content.

How do I add a logo or image?¶

Use a Markdown image in a text: block: ![Logo](https://example.com/logo.svg). See Images.

How do I split a dashboard into tabs?¶

Use tabs: with an items: list; each item is a nested board with its own title: and layout. See Tab Layout.

How do I collapse a section by default?¶

Add details: with a summary: label to a nested board; it renders as a click-to-expand section with no JavaScript. See Details.

How do I hide a chart without deleting it?¶

Set visible: false on the layout item, or point visible: at a checkbox variable so readers can toggle it. See Layout Visibility.

How do I reuse the same header or KPI row on several dashboards?¶

Put it in a partial file (_header.yml) and list the path as a layout item. See Board Imports.

How do I change the spacing between charts?¶

Gap sizing lives under style.layout (rows, cols, and grid.gap). Set it on the board, or in charts/meta.yml for the whole project. See Board Styling.

What happens on a phone?¶

cols: layouts wrap to a vertical stack on narrow screens. See Cols Layout.

How do I show just one chart from a dashboard?¶

Append chart_focus: <chart_id> to the board file, or pass --chart <chart_id> to dct render. See Focusing a Single Chart.

Charts¶

Can I add a chart type the language doesn't have?¶

Not yet as a new type:. Many shapes compose from the built-in ones, text blocks can carry raw HTML on boards you host yourself, and a custom chart type is planned. See Chart types and extensibility.

How do I change the chart type?¶

Change type: (bar, line, area, scatter, pie, donut, heatmap, histogram, table, kpi, map, and more). Each type has its own required fields. See Supported Built-In Types.

How do I plot several series on one chart?¶

Add color: naming the column that splits the series. See Multi-Series Line Graph.

How do I plot two measures on one chart?¶

Give y: a list: y: [revenue, units_sold]. Add color: as well when the result is already grouped by a dimension. See Multiple Measures by a Dimension.

How do I make a stacked bar chart?¶

Add color: and set style.stack: zero. Use normalize for 100% stacked and none for grouped side-by-side bars. See Axis, Scale, and Orientation.

How do I make bars horizontal?¶

Set style.orientation: horizontal. Left on auto, categorical x-axes already render horizontally. See Vertical Columns and Horizontal Bars.

How do I sort bars by value?¶

Add sort: with by: a column and order: desc. See Labels and Ranking.

How do I make the bars thinner?¶

Set style.marks.bar.band_width to a fraction of the band, such as 0.4. See Bar Width.

How do I show the value on each bar or point?¶

Set style.marks.bar.labels.visible: true (or marks.line, marks.point). See Value Labels.

How do I label the end of each line instead of using a legend?¶

Set style.endpoint_labels.visible: true. See Endpoint Labels.

How do I hide the legend?¶

Set style.legend.visible: false. See Chart Styling.

How do I move the legend?¶

Set style.legend.position to top, bottom, left, right, or a corner. See LegendStyle.

How do I limit how many legend entries show?¶

Set style.legend.symbol_limit, or pin an explicit list with style.legend.values. See Legend.

How do I rename the axis titles?¶

Set x_label: and y_label: on the chart. See Axis Labels, Formatting, and Styling.

How do I rotate or skip crowded axis labels?¶

Overlapping labels are skipped and tilted automatically. Force an angle with style.axis_x.labels.angle: -45, or turn the automatic handling off. See Axis Labels.

How do I hide axis labels or grid lines?¶

style.axis_y.labels.visible: false hides labels; style.axis.grid.visible: false hides grid lines. See Other label controls.

How do I set the axis minimum and maximum?¶

Set style.axis_y.scale.continuous.domain: [0, 100]. On a date axis, also set scale.continuous.type: temporal. See Extending the visible range.

How do I stop the y-axis from starting at zero?¶

Set style.axis_y.scale.continuous.zero: false. Bar charts always keep the zero baseline. See Target and Reference Lines.

How do I use a log scale?¶

Set style.axis_y.scale.continuous.type: log. Values must be strictly positive, and bars do not support it. See Axis Scales.

How do I format numbers as currency or percent?¶

Set style.number_format on the chart (currency, currency_whole, percent, integer, and more), or format: on a KPI or table column. Percent formats expect a 0 to 1 ratio. See Format names and aliases.

How do I define a number format once and reuse it?¶

Add an alias under style.formats (for example revenue: "$,.0f") and use the alias name in any format: field. See Global Styling.

How do I change how dates show on the axis?¶

Set style.axis_x.time_unit for the grain and style.axis_x.labels.format for the label text. Date columns are detected automatically. See Time Axes.

Why does my line chart skip months with no data?¶

Missing calendar buckets are synthesized automatically; style.axis_x.fill decides whether the gap breaks the line ("null"), reads as zero, or is interpolated. See Gap handling.

How do I smooth a line?¶

Set style.marks.line.curve: monotone. Use step for a step line. See Smoothing and Step Lines.

How do I put bars and a line on the same chart?¶

Add a layers: list to the chart; each layer has its own type: and y:. See Layered Charts.

How do I add a second y-axis?¶

On a layer, set axis_y.position: right. The layer gets its own scale on the right. See Dual Y-Axis.

How do I add a trend line?¶

Compute it in SQL (most warehouses have REGR_SLOPE and REGR_INTERCEPT) and overlay it as a line layer with its own query:. See Trend Lines.

How do I add a target or goal line?¶

There is no field for an arbitrary threshold line yet. Zero baselines and 100% lines are drawn automatically when relevant; for a fixed target, emit the target as a column and overlay it as a line layer. See Target and Reference Lines.

How do I make a pie or donut chart?¶

type: pie (or donut) with theta: for the size column and color: for the slice column. total: puts a grand total in the center of a donut. See Sector Charts.

How do I repeat one chart per region (small multiples)?¶

Add multiples: with rows: or columns: naming the field to split on. See Small Multiples.

How do I make a heatmap?¶

type: heatmap with x:, y:, and color: for the value. See Heatmap.

How do I show a distribution?¶

type: histogram with x:; bins are computed for you. See Histogram.

How do I make a map?¶

type: map for filled regions, point_map for markers, bubble_map for sized markers. See Maps.

How do I show a single big number?¶

type: kpi with value: and label:. The query must return exactly one row. See KPI Charts.

How do I show a change versus last period on a KPI?¶

Compute the delta in the query and put it in the KPI's support: block with a format: like percent_delta, a glyph:, and a tone:. See KpiSupportConfig.

How do I add a note or warning card?¶

type: callout with message: and an optional style.tone of info, positive, negative, or warning. See Callout Charts.

How do I change chart colors?¶

Pick a palette with style.color.categorical.palette (for example vivid-10), or fix one color with style.color.static. See Chart Color Channels and Palettes.

How do I give one category the same color on every chart?¶

Pin it under style.charts.category_colors at the board root, so the value gets the same swatch everywhere. See One value, one color.

How do I color by value (a gradient)?¶

Set color: to a numeric column and add style.color.gradient with a palette and optional min/max. See Gradient scale.

How do I highlight values above a threshold?¶

Add a conditional_formatting: block keyed by column, with when: rules like gte: 50000 that set background or font. Works on tables and KPIs. See Conditional (threshold).

Tooltips show the hovered row's values automatically and follow the chart's number_format. Their paint (background, font, value format) is set board-wide under style.charts.tooltip. See Hover Tooltips and TooltipStyle.

How do I make a chart clickable (drill down)?¶

Set link: to a URL template; {{ x }}, {{ y }}, and {{ color }} are replaced with the clicked value. See Drill-Down Links.

How do I add a title, subtitle, or description to a chart?¶

title: and subtitle: render above the chart. notes: never renders; it is metadata for search and AI tools. See Field Reference.

How do I hide a chart's title?¶

Leave title: out. A chart with no title renders without one.

How do I set a chart's height?¶

Set height: 400 at the chart root, or style.aspect_ratio for a shape. min_height and max_height under style: clamp the automatic height. See Chart Sizing.

Why is my chart blank?¶

Usually the query returned no rows or a named column is missing. Run dct render board.yml --format json --allow-chart-errors to see what the chart received, and dct validate for schema errors. See Chart Not Displaying.

One chart shows an error but the others are fine. Is that expected?¶

Yes. A failing query or data-shape error renders as a red callout in that chart's tile while the rest of the board renders. See Error Handling.

Tables¶

How do I reorder table columns?¶

Reorder the SELECT list in the query. Column order always comes from the query, never from style.columns. See Table Column Config.

How do I hide a table column?¶

Set visible: false on that column under style.columns. Its values stay available to link: templates. See Table Column Config.

How do I rename a table column?¶

Set label: on the column under style.columns, or alias it in SQL. See Table Column Config.

How do I set a column's width or alignment?¶

width: (pixels or a percentage) and align: under style.columns.<column>. style.column_defaults applies to every column at once. See Table Column Config.

How do I format numbers or dates in a table?¶

Set format: on the column: a d3 spec like "$,.0f", a preset like number_full, or a strftime spec like "%B %d, %Y" for dates. See Number Formatting.

How do I paginate a long table?¶

Set style.pagination.page_rows: 25. Use the query's limit: when you want fewer rows fetched, not just fewer shown. See Table Pagination.

How do I make a link in a table cell?¶

Set link: on the chart (every cell) or on a column under style.columns, with {{ column_id }} placeholders. See Linking Between Boards.

How do I add a sparkline inside a table?¶

Set spark: on a column whose cells hold a list of values. See Inline Spark Columns.

How do I make a pivot (cross-tab) table?¶

On a table chart, add rows:, columns:, and values: naming the fields. The query stays long-form. See Pivot.

How do I add a totals row or column?¶

Emit the totals from the query (a literal "Total" value in the pivot field). The renderer never sums for you. See Row and Column Totals.

How do I show the data behind a chart as a table?¶

Add support_table: to the chart to attach a mini data grid, or add a second type: table chart on the same query. See Support Table.

Queries and data¶

How do I query a dbt model?¶

Write SQL against a dbt_profile source and use {{ ref('model_name') }}. Run dbt parse first so target/manifest.json exists. See Queries.

How do I connect to my warehouse?¶

Add a sources: entry to dbt_charts.yml: type: dbt_profile to reuse your dbt profile, or a direct postgres, snowflake, bigquery, duckdb, or sqlite block. See Sources.

Which warehouses are supported?¶

BigQuery, Snowflake, Postgres, Redshift, DuckDB, SQLite, MySQL, SQL Server, Trino, Athena, Databricks, and Spark, plus CSV, Parquet, and JSON files. See Source Types.

How do I use a CSV file as a data source?¶

Add a type: csv source pointing at the file (or folder) in dbt_charts.yml, then query it with SQL. See Files and APIs.

How do I put a few rows of data straight into the YAML?¶

Use a values query: rows: with a list of mappings, or columns: plus values:. No database needed. See Values Queries.

How do I chart data from an API?¶

Use type: http with a url:, optional method, headers, and body. See HTTP / API Queries. Runs under local dct only; Not supported on dbtcharts.com.

Can I use one query for several charts?¶

Yes. Name the query once under queries: and reference it from each chart with query: <name>. It runs once. See Reuse Queries Across Charts.

Can one query build on another?¶

Yes. Reference it as {{ queries.other_query }} inside your SQL and it is inlined as a subquery. See Query References.

How do I limit the number of rows?¶

Set limit: on the query. Chart-level row limiting does not exist. See Raw SQL Queries.

How do I group by week, month, or quarter?¶

Bucket the date in SQL (DATE_TRUNC) and chart the bucketed column; the axis picks up the grain. See Use Time Grain.

Can I join data from two different sources?¶

Yes. Reference each query's cached rows with {{ queries.name.cache }} and the join runs in the local cache engine (DuckDB). Plain {{ queries.name }} references must share a source. See Cross-Source Composition via Cache.

How do I refresh the data?¶

Locally, restart dct serve, pass --no-cache, or set a cache.ttl in dbt_charts.yml. See Caching; Cloud's refresh is described in Refresh.

Can I schedule a refresh?¶

Locally, a cron job running dct render with a persistent --cache file does the job. For Cloud, see Refresh.

Why is my dashboard slow?¶

Usually one heavy query. Add limit:, aggregate in SQL rather than fetching raw rows, and reuse queries across charts. See Performance Optimization.

How do I check my SQL without rendering anything?¶

dct query board.yml <query-name> runs one query and prints rows; --validate lints it. See dct query.

Filters and variables¶

Define it under variables: and reference it in each query's WHERE clause with {{ filter('column', variable_name) }}. Variables never filter anything on their own. See Variables.

How do I set the dropdown's options?¶

options.static for a fixed list, column: to read distinct values from a table column, or query: for custom SQL. See Variables.

How do I set a default value?¶

Set default: on the variable. Unset, it starts null and filter() applies no filter; there is no automatic "All" option, so author one if you want it. See UI Elements.

How do I add a date range picker?¶

input: daterange, then {{ filter_date_range('created_at', date_range) }} in the query. Date columns default to this input. See Date Range Filtering.

How do I make a filter apply to every chart?¶

Reference the variable in every query that should respond to it. Charts whose queries do not mention it are unaffected. See Wiring Variables to Queries.

Source the second variable from a query that filters on the first. See Dependent Variables.

How do I set a filter from the URL?¶

Add it as a query parameter: /sales/?region=West. Every variable is settable this way, including hidden ones. See URL routing.

How do I hide a variable's control but keep using it?¶

Set visible: false on the variable. It can still be set from the URL or a link. See Variable.

How do I require a value before the dashboard renders?¶

Set required: true. The board asks for a value instead of rendering. See Variables.

How do I click a bar to filter the rest of the page?¶

Use link: with a query parameter for the variable, for example link: "?region={{ x }}". See In-page variable updates.

What input types are there?¶

select, multiselect, text, textarea, number, slider, datepicker, daterange, checkbox, and radio. See Variable UI Elements.

Styling¶

How do I change the theme?¶

Set theme: at the board root to clarity, paper, vivid, neon, or stark. See Themes.

Is there a dark mode?¶

neon is the dark theme. Custom dark themes extend it. See The five built-in themes.

How do I make my own brand theme?¶

Create charts/_my-brand.yaml with extends: clarity and your overrides, then extends: it from each board. See Custom themes.

How do I set the theme for a whole project?¶

Put theme: and other presentation keys in charts/meta.yml. dbt_charts.yml is for engine settings only and rejects them. See Project Configuration.

How do I change the font?¶

Set style.font.family at the board root. See Global Styling.

How do I change the background color?¶

style.background on the board for the page, or on a chart for that chart's card. See Global Styling.

How do I add a border or rounded corners to a section?¶

Set style.border on the nested board, as a CSS shorthand or a width / color / radius block. See Board Styling.

How do I move or remove the "Data as of" timestamp?¶

style.timestamp.position and style.timestamp.align place it; style.timestamp.format rewrites the text. See Data-freshness stamp.

Can I use raw HTML?¶

Yes, with html_policy: trusted-raw at the board root, for dashboards you control. Cloud caps this. See HTML Policy.

Why do my emoji look gray?¶

Emoji render in a calm monochrome by default. Set style.font.emoji: system-default for color emoji. See Emoji handling.

How do I export a dashboard as an image or PDF?¶

dct render board.yml --format png (or pdf, svg, html). See Output formats.

How do I export one chart?¶

dct render board.yml --chart <chart_id> --format png. See dct render.

How do I export the underlying data?¶

dct render board.yml --format data returns every query's rows as JSON. See Extract the underlying data.

How do I embed a dashboard in another site?¶

Render to HTML or SVG and include the file, or use the MkDocs integration to embed live boards in documentation. Set public_url so links resolve when embedded elsewhere. See Origin-absolute links.

Push the board to git and open it in dbt Charts Cloud. See Access Control.

How do I make a dashboard public?¶

Public access is a Cloud feature. See Public access.

Who can see which dashboards?¶

In Cloud, that is decided by Access Control. dct serve has no access control; everything it serves is visible to whoever can reach it.

How do I invite someone?¶

By email, from the organization's members page in Cloud. See Sign in and create an organization.

How do I connect Cloud to my repository?¶

Through the dbt Charts GitHub App, or a public GitHub URL. Only GitHub is supported. See Connect your git repository.

Where do my edits in Cloud go?¶

Into git, as commits. See Git workflow.

Can I require a review before a change goes live?¶

Yes, in Cloud. See Review mode. With dct serve, your git host's pull-request review does the same job, and dct validate in CI keeps broken boards out; see Validating Boards in CI.

How do I duplicate a dashboard?¶

Copy the YAML file. If you want two dashboards to share content, use a partial import instead of copying.

How do I rename or move a dashboard?¶

Rename or move the file; the URL follows the path. See URL routing. A moved board's Cloud permissions follow the path too; see Access Control.

How do I delete a dashboard?¶

Delete the file and commit.

Where is version history?¶

In git. Every change is a commit. Cloud surfaces it too; see Commit history.

Can I email a dashboard on a schedule?¶

Not built in, locally or in Cloud. dct render --format pdf in a cron job, piped to your mailer, is the workaround.

What credentials does Cloud need?¶

A read-only warehouse user. See Data connections and Warehouse privileges.

Can I use DuckDB in Cloud?¶

DuckDB is a local-development source. What Cloud connects to is listed under Supported warehouses.

Tooling and troubleshooting¶

How do I check a dashboard for mistakes before committing?¶

dct validate charts/ checks schema and cross-references in under a second. Add --warehouse to check columns against the database. See dct validate.

How do I validate dashboards in CI?¶

dct init ci scaffolds a GitHub Actions workflow. See Validating Boards in CI.

What does this error code mean?¶

Look it up in the Error Reference or Warning Reference, or run dct docs warnings <CODE>.

How do I silence a warning I have decided to accept?¶

Pass --ignore-warning <CODE> to dct render, or suppress it in the board. See Suppressing a Diagnostic.

My YAML worked last month and now fails. What changed?¶

The grammar moved. Run dct migrate --dry-run to preview the rewrite, then dct migrate to write it. See dct migrate.

How do I find which dashboards use a column I am about to rename?¶

dct impact <column>. See dct impact.

How do I search across all my dashboards?¶

dct search <keyword> ranks boards by title, notes, and query text. See dct search.

Which editor should I use?¶

Any editor built on VS Code (VS Code, Cursor). dct init code installs the extension with highlighting, snippets, and live preview. See VS Code and Cursor Extension.

Is there somewhere to try YAML without installing anything?¶

The Playground renders a board from YAML in the browser, with sample data.

Why does `ref()` say the manifest is missing?¶

target/manifest.json is gitignored build output. Run dbt parse in the dbt project first. See Queries.

Why does dbt suddenly report version 1.x, or say the adapter is missing?¶

The dct install pulled its own dbt into the same environment. See dbt v2 troubleshooting.

Where do I ask a question the docs do not answer?¶

Open an issue on the dbt Charts GitHub repository. Include the board YAML and the output of dct validate.