# Overview (https://docs.dbtcharts.com/)

# dbt Charts Overview

*dbt Charts* makes it easy to build any *Interface* for your *Database*. You (or an AI assistant) write straightforward YAML declaring what you want to see, and dbt Charts renders it as an interactive dashboard, in a variety of formats.

Built on top of dbt, it turns a text file and a SQL query into a live, shareable dashboard: no JavaScript, no drag-and-drop BI tool, no proprietary format.

## What is it for?

dbt Charts is a visualization and dashboarding layer for data teams. It's good at two things:

### Reporting & dashboards
Build polished, interactive dashboards and share them in multiple formats. Rich layouts, filters, and styling, all declared in YAML that lives in Git alongside your dbt models.

### Data exploration
Go from a query to a chart instantly. A fast, iterative loop for exploring data and finding insights without the overhead of building a full report.

## How It Works

1. **You write a YAML file** describing what data to show and how to visualize it
2. **dbt Charts compiles it** into an interactive board
3. **The board queries your database** via SQL to fetch data
4. **Users interact** with filters, click through charts, and explore the data

## Quick Start Example

Here's a compact dashboard that runs the moment you install dbt Charts, no database required. Each query embeds its rows inline with `type: values`, and the charts map query columns to visual encodings. `cols` places the two charts side by side.

```dbt-charts-example
title: "Document activity"

queries:
  by_status:
    type: values
    columns: [status, document_count]
    values:
      - [Signed, 412]
      - [Sent, 168]
      - [Draft, 97]
      - [Voided, 24]

  monthly:
    type: values
    columns: [month, documents]
    values:
      - [Jan, 120]
      - [Feb, 145]
      - [Mar, 138]
      - [Apr, 171]
      - [May, 189]
      - [Jun, 203]

charts:
  status_chart:
    query: by_status
    type: bar
    title: "Documents by status"
    x: status
    y: document_count

  trend_chart:
    query: monthly
    type: line
    title: "New documents per month"
    x: month
    y: documents

rows:
  - cols:
      - status_chart
      - trend_chart
```

That's it: inline data, two charts, a side-by-side layout, and a live board. When you're ready for real data, swap `type: values` for **SQL against your warehouse**; the charts stay the same (see the [Quick Guide](quick-guide.md)). Querying the dbt Semantic Layer by metric name is planned; that work is tracked in [dbt-labs/dbt-charts#1](https://github.com/dbt-labs/dbt-charts/issues/1).

## Why dbt Charts

- **YAML is the source of truth**: Dashboards are text files. Version-controlled, diffable, reviewable in a pull request.
- **SQL today, dbt metrics next**: Write raw SQL against your dbt models now. Asking for a governed metric by name through the dbt Semantic Layer is planned, so the definition stays in the dbt project.
- **Dashboards that track your models**: Dashboards live alongside your dbt models in Git. When your models change on a branch, the dashboards on that branch change with them; no dangling references to fix after a migration.
- **AI-friendly by design**: YAML is far easier for an AI assistant to write correctly than JavaScript, a proprietary BI config, or hand-drawn SQL. "Show me sales by region" becomes a valid dashboard an agent can generate, review, and refine.
- **Open source**: The engine, CLI, and YAML language are free and open source; everything on this site describes them unless marked otherwise. [dbt Charts Cloud](cloud/index.md) is the optional hosted product that adds team features (access control, git-backed editing, and a shared warehouse connection) on top of the same YAML.

## What You Need to Know

To use dbt Charts effectively, it helps to be comfortable with:

- **SQL or dbt**: a basic grasp of your data models (metrics and dimensions)
- **YAML**: basic syntax; it's simple
- **Git**: basic version control

You don't need JavaScript, a frontend framework, or web-deployment know-how; dbt Charts handles rendering and query generation.

## Get Started

- **[Install dbt Charts](guides/installation.md)**: get set up in your environment
- **[Quick Guide](quick-guide.md)**: learn boards, queries, charts, and variables, and build a dashboard in a few minutes
- **[FAQ](faq.md)**: quick answers to "how do I move a chart?" and a hundred other questions, each linking to the full page
- **[Examples](examples/quickstart.md)**: complete, working dashboards to copy from
- **[VS Code & Cursor Extension](editor-extension.md)**: highlighting, snippets, and a live dashboard preview while you edit

Once you're building, the [Charts](charts/index.md), [Variables](variables/index.md), [Themes](themes.md), [Styling](styling.md), and [YAML Reference](reference/yaml-reference.md) sections cover everything the language can do.

# Quick Guide (https://docs.dbtcharts.com/quick-guide/)

# Quick Guide

dbt Charts boards are YAML files that render as dashboards. The fastest way to
your first board is to hand the tool to a coding agent. The rest of this page is
the setup by hand, and the syntax you will read in whatever the agent writes.

---

## Start with your agent

In the project you want charts for, paste this into Claude Code, Codex, or any
coding agent:

```text
I want to make charts of this data with dbt Charts. Run `uv tool install dbt-charts`, then `dct skills intro`, and follow what it prints.
```

The agent installs `dct`, reads the intro skill (which teaches it the language
and which skill to read next), looks at your data, writes boards into `charts/`,
and renders them for you to look at. Ask for changes in plain language; every
edit lands in the same YAML file, which you can read, diff, and review.

That prompt installs with [uv](https://docs.astral.sh/uv/getting-started/installation/);
install it first if you don't already have it.

This works in any agent that has a shell and your files: Claude Code, Codex,
Cursor, GitHub Copilot's agent mode, and the like. In claude.ai or ChatGPT there
is nothing to install, so start on [dbtCharts.com](https://dbtcharts.com/)
instead (see [dbt Charts Cloud](cloud/index.md)).

Already ran it? Skip to [Syntax](#syntax) to read what your agent wrote.

---

## Or by hand

Install dbt Charts with [uv](https://docs.astral.sh/uv/getting-started/installation/)
or [pip](https://pip.pypa.io/en/stable/installation/); both of those pages cover
Windows, macOS, and Linux. Then scaffold a project with `dct init`:

```bash
uv tool install dbt-charts   # or: pip install dbt-charts
dct init
```

[Installation & Setup](guides/installation.md) has the full walkthrough,
including warehouse adapters.

`dct init` writes a `dbt_charts.yml` project anchor and a `charts/` directory with a
starter dashboard (`charts/guide.yml`) that renders without a database. Preview it
right away with `dct serve`, then edit the starter or add your own board alongside
it. `dct init` can also set up editor and AI integrations.

If you are starting in an existing dbt project, run `dct init` in the project
root: `dct serve` discovers the root from `dbt_project.yml`, and SQL queries run
against the connection your dbt `profiles.yml` names for the project. You do not
need to declare a source.

See [Getting Started](guides/getting-started.md) for the full setup path.

---

## Syntax

The board is the base element: a layout tree that can hold text, variables,
queries, charts, and other boards. Start with board layout, then add the pieces
that make a board interactive.

### Boards

A board can be as small as a title and Markdown text:

```dbt-charts-example
title: "Simple board"
text: |
  This is Markdown text.

  - **bold** for important points
  - *italics* for nuance
  - `code` for field names
```

Boards become powerful because they nest. When you need structure, `rows`
stacks items vertically, `cols` places them side by side, and each item is
itself a board:

```dbt-charts-example
title: "This is the parent board"
width: 600

rows:
  - text: |
      With just **some text** on it. It's Markdown, so we can put things like
      [links](https://example.com/), *emphasis*, and lists:

      - keep prose close to the data
      - call out important details
      - add structure without adding a chart
    style:
      border:
        width: 1
        color: "#cbd5e1"

  - title: "Nested board"
    text: |
      This is a nested board with its own border.
    style:
      border:
        width: 1
        color: "#cbd5e1"

  - title: "Two nested boards"
    cols:
      - text: |
          And here's another with just text, no title.

          - **Bold text** works inside nested boards.
          - *Italic text* does too.
          - Bullets make short notes easy to scan.
        style:
          border:
            width: 1
            color: "#cbd5e1"
      - title: "And another with just a title"
        style:
          border:
            width: 1
            color: "#cbd5e1"
```

When a board defines charts but no explicit layout, dbt Charts renders those charts
as implicit rows. Use `rows`, `cols`, `tabs`, or `grid` when the arrangement
matters.

See [Boards](boards/index.md) for layout patterns.

---

### Variables

Variables are the controls readers use to change a board. This one creates a
segment selector with three static options:

```dbt-charts-example
variables:
  segment:
    input: select
    options:
      static:
        - Enterprise
        - SMB
        - Mid-Market

text: |
  # Segment: {{ segment or 'All segments' }}

  Change the selector above. The text reads **{{ segment or 'All segments' }}**
  from the current variable value.
```

The `{{ segment }}` expression can appear in text, titles, links, SQL, and
query filters. A variable does not filter data by itself; you wire it into a
query explicitly.

Variables are usually not static like this first example. In production, you
often populate them from a query, a source column, or a dbt model column;
they also support many UI element and styling options. Read more in
[Variables](variables/index.md).

---

### Queries

Queries define the data a board can use. A board can mix database-backed SQL
queries with static values for targets, labels, or small reference tables:

```yaml {contract=board-root}
queries:
  revenue: # sql to a database
    sql: |
      SELECT month, segment, revenue
      FROM mart_revenue
      ORDER BY month
    source: analytics

  targets: # static values
    type: values
    columns: [segment, target]
    values:
      - [Enterprise, 438000]
      - [SMB, 228000]
      - [Mid-Market, 285000]
```

Queries can use the same `{{ segment }}` variable from above. The `filter`
helper writes the SQL predicate for the selected value, or a no-op predicate
when no segment is selected:

```yaml {contract=board-fragment}
queries:
  revenue:
    sql: |
      SELECT month, segment, revenue
      FROM mart_revenue
      WHERE {{ filter('segment', segment) }}
      ORDER BY month
    source: analytics
```

Each query has a name (`revenue`, `targets`) and returns named columns.
Queries can reference other queries, read previous query results, tune cache
behavior, and combine SQL with CSV, dbt model data, HTTP, and static values.
Read more in [Queries](queries.md).

---

### Charts

Charts reference queries and map result columns to visual channels. Start with a
query, then bind its columns to a chart:

```dbt-charts-example
queries:
  monthly_revenue:
    sql: |
      SELECT date, SUM(revenue) AS revenue
      FROM ecommerce_orders
      GROUP BY date
      ORDER BY date
    source: examples_db

charts:
  revenue_trend:
    query: monthly_revenue
    type: line
    title: "Revenue trend"
    x: date
    y: revenue
```

The chart does not aggregate or infer meaning. The query owns the rows and
columns; the chart owns the visual encoding. Here, the SQL groups orders by
date, and the line chart maps `date` to the x-axis and `revenue` to the y-axis.

Variables can then feed the same query layer. This example populates a category
selector from SQL and uses the selected value in the revenue query:

```dbt-charts-example
variables:
  category:
    input: select
    options:
      query: category_options

queries:
  category_options:
    sql: |
      SELECT DISTINCT category AS value
      FROM ecommerce_orders
      ORDER BY category
    source: examples_db

  revenue:
    sql: |
      SELECT category, SUM(revenue) AS revenue
      FROM ecommerce_orders
      WHERE {{ filter('category', category) }}
      GROUP BY category
      ORDER BY revenue DESC
    source: examples_db

charts:
  revenue_by_category:
    query: revenue
    type: bar
    title: "Revenue by category"
    x: category
    y: revenue
```

Here, the variable changes the SQL predicate, while the chart still only maps
the category and revenue columns to the axes.

Charts come in many families, and extensible charts can render custom SVG or
HTML when the built-in families are not enough. Dive into
[Charts](charts/index.md).

---

### Styling

dbt Charts keeps styling declarative too. Choose a theme for the whole board,
then use typed chart options for labels, axes, formats, colors, marks, and
scale behavior. Built-in themes are `clarity` (the default), `paper`,
`vivid`, `neon`, and `stark` (see [Themes](themes.md)); chart-local style only
needs to override what should differ from the theme:

```dbt-charts-example
title: "Styled revenue trend"
theme: paper
width: 600

queries:
  daily_revenue:
    sql: |
      SELECT date, SUM(revenue) AS revenue
      FROM ecommerce_orders
      GROUP BY date
      ORDER BY date
    source: examples_db

charts:
  revenue_trend:
    query: daily_revenue
    type: line
    x: date
    y: revenue
    x_label: "Order date"
    y_label: "Daily revenue"
    style:
      marks:
        line:
          curve: monotone
      axis_y:
        labels:
          format: currency_whole
```

Use styles when the default rendering needs more polish, but keep data meaning
in the query and visual mapping in the chart definition. See
[Styling](styling.md) and the chart family pages for the full option set.

---

### Bringing It All Together Cheat Sheet

Start with the same pattern in a small board: one variable, one query, two KPIs
above one single-value chart.

```dbt-charts-example
title: "Category snapshot"
width: 600

variables:
  category:
    label: "Category"
    input: select
    options:
      query: category_options

queries:
  category_options:
    sql: |
      SELECT DISTINCT category AS value
      FROM ecommerce_orders
      ORDER BY category
    source: examples_db

  summary:
    sql: |
      SELECT
        SUM(revenue) AS revenue,
        COUNT(*) AS orders,
        AVG(revenue) AS avg_order
      FROM ecommerce_orders
      WHERE {{ filter('category', category) }}
    source: examples_db

charts:
  revenue:
    query: summary
    type: kpi
    label: "Revenue"
    value: revenue
    style:
      value:
        format: currency_whole

  orders:
    query: summary
    type: kpi
    label: "Orders"
    value: orders

  avg_order:
    query: summary
    type: kpi
    label: "Avg order"
    value: avg_order
    style:
      value:
        format: currency_whole

rows:
  - cols:
      - revenue
      - orders
  - avg_order
```

dbt Charts is flexible enough that you could use it to write the quick guide
itself. The fuller cheat sheet below uses the same pieces, then nests the
examples so the board reads like a compact version of this page. The parent
board sets the default `clarity` theme explicitly, and most of the embedded
example boards add their own border, so they read as cards nested inside the
guide. Notice the chart definitions live at the top, then nested boards list
chart IDs like `revenue_by_month` and `target_by_month` where those charts
should appear.

```dbt-charts-example
title: "dbt Charts quick start cheat sheet"
theme: clarity

variables:
  segment:
    input: select
    options:
      static: [Enterprise, SMB, Mid-Market]

queries:
  revenue:
    type: values
    columns: [month, segment, revenue, target]
    values:
      - [Jan, Enterprise, 142000, 130000]
      - [Feb, Enterprise, 151000, 138000]
      - [Mar, Enterprise, 164000, 146000]
      - [Jan, SMB, 68000, 72000]
      - [Feb, SMB, 74000, 76000]
      - [Mar, SMB, 81000, 80000]
      - [Jan, Mid-Market, 97000, 91000]
      - [Feb, Mid-Market, 101000, 95000]
      - [Mar, Mid-Market, 109000, 99000]

charts:
  revenue_by_month:
    query: revenue
    type: bar
    title: "Revenue by month"
    x: month
    y: revenue
    color: segment
    style:
      axis_y:
        labels:
          format: currency_whole

  target_by_month:
    query: revenue
    type: line
    title: "Target by month"
    x: month
    y: target
    color: segment
    style:
      axis_y:
        labels:
          format: currency_whole

rows:
  - title: "1. Boards"
    cols:
      - text: |
          A board starts with a `title`, then stacks `rows` or places `cols`
          beside each other. Text cells support **markdown**, including links,
          lists, emphasis, and inline `code`.

          ```yaml
          title: "Basic board"

          rows:
            - text: |
                This is markdown text.

                - **bold** for important points
                - *italics* for nuance
                - `code` for field names

            - cols:
                - title: "Left panel"
                  text: "Boards can sit side by side."
                - title: "Right panel"
                  text: "Each item is itself a board."
          ```

      - title: "Basic board"
        rows:
          - text: |
              This is markdown text.

              - **bold** for important points
              - *italics* for nuance
              - `code` for field names

          - cols:
              - title: "Left panel"
                text: "Boards can sit side by side."
              - title: "Right panel"
                text: "Each item is itself a board."

  - title: "2. Variables"
    cols:
      - text: |
          Variables define controls. This board has a `segment` selector, and
          both the text and charts read the current value. The board on the
          right is an actual nested board with its own variable definition.

          
          ```yaml
          variables:
            example_segment:
              label: "Segment"
              input: select
              options:
                static: [Enterprise, SMB, Mid-Market]

          rows:
            - text: |
                Current segment:
                **{{ example_segment or 'All segments' }}**
          ```
          

      - style:
          border:
            width: 1
            radius: 8
        title: "Rendered variable"
        variables:
          example_segment:
            label: "Segment"
            input: select
            options:
              static: [Enterprise, SMB, Mid-Market]
        text: |
          Current segment: **{{ example_segment or 'All segments' }}**.

          Change this nested board's selector and the text updates with it.

  - title: "3. Queries"
    cols:
      - text: |
          Queries own the rows and columns. They can come from SQL, CSV, dbt
          models, HTTP data, or inline values.

          ```yaml
          queries:
            revenue:
              type: values
              columns: [month, segment, revenue, target]
              values:
                - [Jan, Enterprise, 142000, 130000]
                - [Feb, Enterprise, 151000, 138000]
                - [Mar, Enterprise, 164000, 146000]
          ```

      - style:
          border:
            width: 1
            radius: 8
        title: "Query result"
        text: |
          The `revenue` query in this cheat sheet returns monthly revenue,
          segment, and target columns. The chart definitions below decide how to
          encode those columns visually.

  - title: "4. Charts"
    rows:
      - text: |
          Charts reference a query and bind result columns to visual channels.
          The chart definitions are declared once above, then this nested board
          lists the chart IDs in `cols` to place them side by side.

          ```yaml
          charts:
            revenue_by_month:
              query: revenue
              type: bar
              title: "Revenue by month"
              x: month
              y: revenue
              color: segment
          ```

      - style:
          border:
            width: 1
            radius: 8
        title: "Rendered charts"
        cols:
          - revenue_by_month
          - target_by_month

  - title: "5. Nested boards"
    cols:
      - text: |
          Nested boards are how larger dashboards stay organized. This nested
          board has its own variable, query, charts, and layout. Inside it,
          chart IDs are placed where they belong.

          ```yaml
          title: "Segment review"
          variables:
            review_segment:
              label: "Segment"
              input: select
              options:
                static: [Enterprise, SMB, Mid-Market]

          queries:
            review_revenue:
              type: values
              columns: [month, segment, revenue, target]
              values:
                - [Jan, Enterprise, 142000, 130000]
                - [Feb, Enterprise, 151000, 138000]
                - [Mar, Enterprise, 164000, 146000]

          charts:
            review_revenue_by_month:
              query: review_revenue
              type: bar
              x: month
              y: revenue

          cols:
            - text: |
                Current segment:
                **{{ review_segment or 'All segments' }}**
            - review_revenue_by_month
          ```

      - style:
          border:
            width: 1
            radius: 8
        title: "Segment review"
        variables:
          review_segment:
            label: "Segment"
            input: select
            options:
              static: [Enterprise, SMB, Mid-Market]
        queries:
          review_revenue:
            type: values
            columns: [month, segment, revenue, target]
            values:
              - [Jan, Enterprise, 142000, 130000]
              - [Feb, Enterprise, 151000, 138000]
              - [Mar, Enterprise, 164000, 146000]
              - [Jan, SMB, 68000, 72000]
              - [Feb, SMB, 74000, 76000]
              - [Mar, SMB, 81000, 80000]
              - [Jan, Mid-Market, 97000, 91000]
              - [Feb, Mid-Market, 101000, 95000]
              - [Mar, Mid-Market, 109000, 99000]
        charts:
          review_revenue_by_month:
            query: review_revenue
            type: bar
            title: "Revenue"
            x: month
            y: revenue
            color: segment
            style:
              axis_y:
                labels:
                  format: currency_whole

          review_target_by_month:
            query: review_revenue
            type: line
            title: "Target"
            x: month
            y: target
            color: segment
            style:
              axis_y:
                labels:
                  format: currency_whole
        cols:
          - text: |
              Current segment: **{{ review_segment or 'All segments' }}**

              - compare revenue against target
              - keep the explanation beside the visuals

          - rows:
              - review_revenue_by_month
              - review_target_by_month
```

Small boards compose into larger reports, and those reports can compose again.
When a nested board gets large, move it to its own board YAML file and import it
from the layout.

---

### Quick Reference

```yaml {contract=board-root}
title: "My Board"

variables:
  segment:
    input: select
    options:
      static: [Enterprise, SMB, Mid-Market]

queries:
  revenue:
    type: values
    columns: [month, segment, revenue]
    values:
      - [Jan, Enterprise, 142000]

charts:
  revenue_by_month:
    query: revenue
    type: bar
    x: month
    y: revenue

rows:
  - title: "Revenue"
    text: "Monthly revenue by selected segment."
  - revenue_by_month
```

Start with the data and interaction you need, then add the board shape that
makes it readable.

---

## Tools

Use `dct render` when you want a static artifact from one board file:

```bash
dct render charts/revenue.yml
dct render charts/revenue.yml --format html
dct render charts/revenue.yml --format png --output revenue.png
```

Use `--var` to render a specific variable state:

```bash
dct render charts/revenue.yml --var segment=Enterprise
```

See [`dct render`](cli/render.md) for every output format.

Use `dct serve` when you want live browser previews while editing YAML:

```bash
dct serve
dct serve --port 3000
```

Board paths map to URLs. For example, `charts/revenue.yml` renders at
`/revenue/`, and query parameters set variables:

```text
http://localhost:3000/revenue/?segment=Enterprise
```

See [`dct serve`](cli/serve.md) for routing, ports, and database options.

# FAQ (https://docs.dbtcharts.com/faq/)

# 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.11 or newer, then add the adapter extra for your warehouse. See [Installation](guides/installation.md).

### 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](examples/quickstart.md) 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](boards/index.md).

### 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](https://play.dbtcharts.com) and the [VS Code extension](editor-extension.md) 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](editor-extension.md#live-preview) 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](cli/serve.md#url-routing).

### Can an AI assistant build dashboards for me?

Yes. `dct init mcp` wires the [MCP server](cli/mcp.md) into Cursor, Claude Code, or ChatGPT, and `dct init skills` installs authoring skills. Cloud users can also use the [Claude and ChatGPT connector](cloud/claude-chatgpt-connector.md).

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

The generated [YAML Schema Reference](reference/yaml-reference.md) lists every field on every chart type. The [Quick Reference](reference/quick-reference.md) 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](boards/layouts.md).

### 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](boards/layouts.md#cols-horizontal-stack).

### 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](boards/layouts.md#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](boards/sizing.md).

### 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](boards/sizing.md#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](boards/sizing.md#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](boards/sizing.md#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](boards/content.md#title-heading-levels).

### 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](boards/content.md).

### How do I add a logo or image?

Use a Markdown image in a `text:` block: `![Logo](https://example.com/logo.svg)`. See [Images](boards/content.md#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](boards/layouts.md#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](boards/layouts.md#details-collapsible-sections).

### 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](variables/advanced.md#layout-visibility-visible).

### 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](boards/imports.md).

### 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](boards/index.md#board-styling).

### What happens on a phone?

`cols:` layouts wrap to a vertical stack on narrow screens. See [Cols Layout](reference/layout-types.md#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](boards/index.md#focusing-a-single-chart).

---

## Charts

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

Yes: `type: custom` draws a shape from your own SVG template. Many shapes also compose from the built-in ones, and text blocks can carry raw HTML on boards you host yourself. See [Chart types and extensibility](charts/extensibility.md).

### 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](charts/more-types.md#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](charts/line-graphs.md#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](charts/line-graphs.md#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](charts/bar-charts.md#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](charts/bar-charts.md#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](charts/bar-charts.md#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](charts/bar-charts.md#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](charts/bar-charts.md#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](charts/line-graphs.md#endpoint-labels).

### How do I hide the legend?

Set `style.legend.visible: false`. See [Chart Styling](charts/index.md#chart-styling).

### How do I move the legend?

Set `style.legend.position.edge` to `top`, `bottom`, `left` or `right`. `align` (`start`, `center`, `end`) places it along that edge, and `overlay: true` floats it over the plot instead of reserving a strip. See [LegendStyle](reference/yaml-reference.md#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](charts/color-channels.md#legend).

### How do I rename the axis titles?

Set `x_label:` and `y_label:` on the chart. See [Axis Labels, Formatting, and Styling](charts/line-graphs.md#axis-labels-formatting-and-styling).

### How do I rename a column in the legend or tooltip?

Set `field_labels:` on the chart, mapping the column to its display text. See [Field Labels](charts/line-graphs.md#field-labels).

### 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](charts/axis-labels.md).

### 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](charts/axis-labels.md#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](charts/time-axes.md#extending-the-visible-range-past-the-data-scalecontinuoustype-scalecontinuousdomain).

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

Set `style.axis_y.scale.continuous.zero: false` on a line or scatter chart. A bar chart rejects it, because a bar's length is measured from zero, and an area chart warns, because its fill is too; use a line for a zoomed range. See [Target and Reference Lines](charts/layered-charts.md#target-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](charts/axis-scales.md).

### How do I format numbers as currency or percent?

Name the format on the query with `formats:` (`currency`, `currency_whole`, `percent`, `integer`, and more) and every chart that shows the column uses it (see [Column formats](queries.md#column-formats)). A chart's own exception goes in its slot: `style.axis_y.labels.format` on a measure axis, or `format:` on a KPI or table column. Percent formats expect a 0 to 1 ratio. See [Format names and aliases](styling.md#format-names-and-aliases).

### How do I change the default currency?

Set `regional.currency` to an ISO code. In `charts/meta.yml` it changes every board in the folder; in a board it overrides it:

```yaml {contract=board-root}
regional:
  currency: EUR
```

`currency`, `currency_whole`, `currency_full` and every `$` spec then print `€`, at the locale's placement. A board has one currency; to show a second one, define a `style.formats` alias with a `prefix:` or `suffix:`. See [Regional settings](styling.md#regional-settings).

### How do I use European number separators?

Set `regional.locale.number` to a locale name, e.g. `fr-FR` for `1 234,5`, or to a d3 locale definition. The locale's own currency comes with it unless `regional.currency` says otherwise. `regional.locale.time` does the same for month and weekday names (`de-DE` prints `Mrz`). See [Regional settings](styling.md#regional-settings).

### 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](styling.md#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](charts/time-axes.md).

### 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](charts/time-axes.md#gap-handling-synthesized-rows-for-missing-buckets).

### How do I smooth a line?

Set `style.marks.line.curve: monotone`. Use `step` for a step line. See [Smoothing and Step Lines](charts/line-graphs.md#smoothing-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](charts/layered-charts.md).

### 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](charts/layered-charts.md#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](charts/layered-charts.md#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](charts/layered-charts.md#target-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](charts/sector-charts.md).

### 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](charts/small-multiples.md).

### How do I make a heatmap?

`type: heatmap` with `x:`, `y:`, and `color:` for the value. See [Heatmap](charts/more-types.md#heatmap).

### How do I show a distribution?

`type: histogram` with `x:`; bins are computed for you. See [Histogram](charts/more-types.md#histogram).

### How do I make a map?

`type: map` for filled regions, `point_map` for markers, `bubble_map` for sized markers. See [Maps](charts/maps.md).

### How do I show a single big number?

`type: kpi` with `value:` and `label:`. The query must return exactly one row. See [KPI Charts](charts/tables.md#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](reference/yaml-reference.md#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](charts/tables.md#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](charts/color-channels.md) and [Palettes](guides/palettes.md).

### 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](guides/palettes.md#one-value-one-color-across-the-whole-board).

### 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](charts/color-channels.md#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)](charts/color-channels.md#conditional-threshold).

### How do I customize the tooltip?

Tooltips show the hovered row's values automatically and follow the measure's format (the query's `formats:` or the chart's `axis_y.labels.format`). Their paint (background, font, value format) is set board-wide under `style.charts.tooltip`. See [Hover Tooltips](charts/interactions.md#hover-tooltips) and [TooltipStyle](reference/yaml-reference.md#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](charts/interactions.md#drill-down-links-link).

### 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](charts/index.md#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](charts/index.md#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](guides/troubleshooting.md#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](guides/error-handling.md).

---

## 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](charts/tables.md#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](charts/tables.md#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](charts/tables.md#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](charts/tables.md#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](charts/tables.md#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](charts/tables.md#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](boards/linking.md#drill-down-from-charts-and-tables).

### 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](charts/tables.md#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](queries.md#pivot-cross-tab-tables).

### 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](queries.md#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](reference/chart-support-table.md).

---

## 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](queries.md).

### How do I connect to my warehouse?

In a dbt project there is nothing to add: with no `sources:` declared, dbt Charts uses your dbt profile. Otherwise (or to pick a profile target) 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](sources/index.md).

### Which warehouses are supported?

BigQuery, Snowflake, Postgres, Redshift, DuckDB, SQLite, SQL Server, Trino, Athena, ClickHouse, Databricks, and Spark, plus CSV, Parquet, and JSON files. See [Source Types](sources/index.md#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](sources/index.md#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](queries.md#2-values-queries-inline-data).

### How do I chart data from an API?

Use `type: http` with a `url:`, optional `method`, `headers`, and `body`. See [HTTP / API Queries](queries.md#3-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](queries.md#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](queries.md#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](queries.md#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](guides/best-practices.md#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](queries.md#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](cli/serve.md#caching); Cloud's refresh is described in [Refresh](cloud/refresh.md).

### Can I schedule a refresh?

Locally, a cron job running `dct render` with a persistent `--cache` file does the job. For Cloud, see [Refresh](cloud/refresh.md).

### 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](guides/best-practices.md#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](cli/query.md).

---

## Filters and variables

### How do I add a filter (dropdown) to a dashboard?

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](variables/index.md).

### 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](variables/index.md).

### How do I set a default value?

Set `default:` on the variable. Unset, it starts null and `filter()` applies no filter; a non-required select or multiselect already offers a clear-selection row back to that state, so you don't need to author an "All" option yourself. See [UI Elements](variables/ui-elements.md#default).

### 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](variables/expressions.md#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](variables/index.md#wiring-variables-to-queries).

### How do I make one dropdown depend on another?

Source the second variable from a query that filters on the first. See [Dependent Variables](variables/advanced.md#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](cli/serve.md#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](reference/yaml-reference.md#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](variables/index.md).

### 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](charts/interactions.md#in-page-variable-updates).

### What input types are there?

`select`, `multiselect`, `text`, `textarea`, `number`, `slider`, `datepicker`, `daterange`, `checkbox`, and `radio`. See [Variable UI Elements](variables/ui-elements.md).

---

## Styling

### How do I change the theme?

Set `theme:` at the board root to `clarity`, `paper`, `vivid`, `neon`, or `stark`. See [Themes](themes.md).

### Is there a dark mode?

`neon` is the dark theme. Custom dark themes extend it. See [The five built-in themes](themes.md#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](themes.md#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](guides/installation.md#project-configuration-optional).

### How do I change the font?

Set `style.fonts.body.family` for prose and `style.fonts.heading.family` for titles and headings. See [Typography](styling.md#typography).

### 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](styling.md#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](boards/index.md#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](styling.md#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](boards/html-policy.md).

### 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](styling.md#emoji-handling).

---

## Sharing, exporting, and Cloud

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

`dct render board.yml --format png` (or `pdf`, `svg`, `html`). See [Output formats](cli/render.md#output-formats).

### How do I export one chart?

`dct render board.yml --chart <chart_id> --format png`. See [dct render](cli/render.md).

### 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](cli/render.md#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](integrations/mkdocs.md) to embed live boards in documentation. Set `public_url` so links resolve when embedded elsewhere. See [Origin-absolute links](cli/render.md#origin-absolute-links-in-exports).

### How do I share a dashboard with my team?

Push the board to git and open it in [dbt Charts Cloud](cloud/index.md). See [Access Control](cloud/access-control.md).

### How do I make a dashboard public?

Public access is a Cloud feature. See [Public access](cloud/access-control.md#public-access-org-and-project-opt-in).

### Who can see which dashboards?

In Cloud, that is decided by [Access Control](cloud/access-control.md). `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](cloud/getting-started.md#sign-in-and-create-an-organization).

### How do I connect Cloud to my repository?

Through the dbt Charts GitHub App, or a repository's HTTPS URL (private ones with a username and password or token). See [Connect your git repository](cloud/getting-started.md#connect-your-git-repository).

### Where do my edits in Cloud go?

Into git, as commits. See [Git workflow](cloud/git-workflow.md).

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

Yes, in Cloud. See [Review mode](cloud/git-workflow.md#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](guides/ci.md).

### How do I duplicate a dashboard?

Copy the YAML file. If you want two dashboards to share content, use a [partial import](boards/imports.md) instead of copying.

### How do I rename or move a dashboard?

Rename or move the file; the URL follows the path. See [URL routing](cli/serve.md#url-routing). A moved board's Cloud permissions follow the path too; see [Access Control](cloud/access-control.md#the-filesystem-mental-model).

### 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](cloud/git-workflow.md#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](cloud/connections.md) and [Warehouse privileges](cloud/warehouse-privileges.md).

### Can I use DuckDB in Cloud?

DuckDB is a local-development source. What Cloud connects to is listed under [Supported warehouses](cloud/connections.md#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](cli/validate.md).

### How do I validate dashboards in CI?

`dct init ci` scaffolds a GitHub Actions workflow. See [Validating Boards in CI](guides/ci.md).

### What does this error code mean?

Look it up in the [Error Reference](reference/errors.md) or [Warning Reference](reference/warnings.md), 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](guides/error-handling.md#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](cli/migrate.md).

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

`dct impact <column>`. See [dct impact](cli/impact.md).

### How do I search across all my dashboards?

`dct search <keyword>` ranks boards by title, notes, and query text. See [dct search](cli/search.md).

### 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](editor-extension.md).

### Is there somewhere to try YAML without installing anything?

The [Playground](https://play.dbtcharts.com) 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](queries.md).

### 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](guides/dbt-fusion.md#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`.

# Queries (https://docs.dbtcharts.com/queries/)

# Queries

Queries define what data to fetch from your data sources. dbt Charts supports **four types** of queries. Most projects start with SQL.

1. **SQL queries** - Direct SQL against database tables (also how you query dbt models, via `ref()`)
2. **Values queries** - Inline data embedded directly in your YAML
3. **HTTP / API queries** - Fetch JSON data from REST endpoints
4. **Schema queries** - Introspect configured sources, schemas, tables, and columns

---

## Basic Query Structure

Every query has a unique name and defines what data to fetch. **Query names must be unique within a file and across all imported files.**

The simplest way to write a SQL query is a bare string: just the SQL itself. Set `source:` once at the board level and every string query uses it automatically:



```yaml {contract=board-root}
source: my_postgres
variables:
  status:
    input: select
    options:
      static: ["new", "open", "solved"]
  date_range:
    input: daterange
    default: ["2024-01-01", "2024-12-31"]
queries:
  tickets: |
    SELECT
      status,
      priority,
      COUNT(*) AS ticket_count
    FROM dundersign.tickets
    WHERE {{ filter('status', status) }}
      AND {{ filter_date_range('created_at', date_range) }}
    GROUP BY 1, 2
```


When you need to override the source, use `notes` for AI search metadata (it never renders), or mix query types on the same board, use the dict form instead:



```yaml {contract=board-root}
queries:
  tickets:
    notes: "Open tickets by priority"
    sql: |
      SELECT ...
    source: my_postgres
```


---

## Query Types

### 1. SQL Queries (Baseline)

**String shorthand**: set `source:` once at the board level and write queries as bare SQL strings:



```yaml {contract=board-root}
source: my_postgres
variables:
  status:
    input: select
    options:
      static: ["new", "open", "solved"]
  date_range:
    input: daterange
    default: ["2024-01-01", "2024-12-31"]
queries:
  tickets: |
    SELECT
      status,
      priority,
      COUNT(*) as ticket_count
    FROM dundersign.tickets
    WHERE {{ filter('status', status) }}
      AND {{ filter_date_range('created_at', date_range) }}
    GROUP BY 1, 2
    ORDER BY ticket_count DESC
```


**Dict form**: use when you need to override the source per query, set a `target`, or add a `notes` (never rendered; AI search metadata only):



```yaml {contract=board-root}
queries:
  sales:
    sql: |
      SELECT ...
    source: my_postgres  # Required when no board-level source
    target: prod           # Optional: dbt target name (defaults to 'dev')
```


Use the pipe (`|`) after `sql:` (or directly after the query name for string shorthand) to start a YAML literal block. Everything you indent under it becomes one multiline string, so you can paste your SQL verbatim.

#### `setup_sql`: a preamble statement

`setup_sql` runs as its own statement on the same connection, immediately before `sql`. Use it for a warehouse-specific declaration your main query depends on; the canonical case is a BigQuery `CREATE TEMP FUNCTION`:

```yaml {contract=board-root}
queries:
  scaled_revenue:
    setup_sql: |
      CREATE TEMP FUNCTION double_it(x FLOAT64) AS (x * 2);
    sql: SELECT month, double_it(revenue) AS revenue_x2 FROM dundersign_serving.monthly_metrics
    source: my_warehouse
```

`setup_sql` is **non-nestable**: it may not contain `{{ queries.X }}` references, and a query that references another query's SQL still picks up that query's `setup_sql` automatically (the engine walks the dependency chain and runs every preamble, once each, before the composed query). Only `CREATE TEMP FUNCTION` / `CREATE TEMP TABLE` / `CREATE TEMP VIEW`, and DuckDB's `CREATE [OR REPLACE] MACRO`, are accepted; anything else (including non-`TEMP` `CREATE`, `DROP`, `INSERT`) is rejected. Not supported for SQLite sources.

#### Database Connection via Source Configuration

**dbt Charts uses source configuration for SQL database connections.** A source name can refer to a dbt profile defined in `profiles.yml`. This means:

- ✅ **Works with dbt profiles** - dbt Charts reads your existing `profiles.yml` file
- ✅ **Works with all dbt-supported databases** - Postgres, Snowflake, BigQuery, Redshift, DuckDB, etc.
- ✅ **Leverages dbt's adapter system** - Handles database-specific quirks automatically
- ✅ **Same credentials as dbt** - Uses your existing database connections

**Setting up sources:**

1. **Create or edit `~/.dbt/profiles.yml`** (or `profiles.yml` in your project directory)
2. **Define your database connection** using dbt's profile format:


```yaml {contract=unverified}
# ~/.dbt/profiles.yml
my_postgres:
  outputs:
    dev:
      type: postgres
      host: localhost
      port: 5432
      user: myuser
      password: mypass
      dbname: mydb
      schema: public
    prod:
      type: postgres
      host: prod.example.com
      port: 5432
      user: prod_user
      password: "{{ env_var('DB_PASSWORD') }}"
      dbname: analytics
      schema: public
  target: dev  # Default target
```


3. **Reference the source in your queries** using the `source` field (and optionally `target`):

```yaml {contract=board-root}
queries:
  tickets:
    sql: SELECT * FROM dundersign.tickets
    source: my_postgres  # Uses 'my_postgres' source (matches dbt profile name)
    target: prod           # Uses 'prod' target (defaults to 'dev' if not specified)
```

**For more information:**
- See [dbt's profile documentation](https://docs.getdbt.com/reference/profiles.yml) for complete profile configuration options
- See [dbt adapter documentation](https://docs.getdbt.com/docs/connect-data-platform) for database-specific connection parameters

To query a dbt model, write a plain SQL query against a `dbt_profile` source and resolve the model with dbt's `ref()` macro:

```yaml {contract=board-root}
queries:
  model_sales:
    sql: SELECT month, region, revenue, order_count FROM {{ ref('fct_orders') }}
    source: my_postgres
```

`ref()` and `source()` are resolved from the dbt manifest, so the project needs one: run `dbt parse` (or any command that writes `target/manifest.json`). A `dbt_profile` source with `target_path:` reads `<target_path>/manifest.json` instead ([details](sources/index.md#which-manifest-ref-resolves-against)). `target/` is gitignored dbt build output, so it must be regenerated after every fresh clone. Without a manifest the query fails with `ERR-DBT-MANIFEST-MISSING`. On dbtcharts.com you need no manifest: refs resolve against your production warehouse ([details](sources/index.md#on-dbtcharts-com)).

**Type Inference**: Query types are automatically inferred from the keys present:
- `sql:` → SQL Query (requires `source` field)
- `rows:` or `values:` → Values Query (inline data)
- `url:` → HTTP Query
- Schema queries have no key-based inference; set `type: schema` explicitly

**Use cases:**
- Most common use case - direct SQL queries
- Full control over query logic
- Works with any dbt-supported database
- Requires source configuration (minimal setup - just `profiles.yml`)

### 2. Values Queries (Inline Data)

Values queries embed data directly in your YAML; no database or file needed. Perfect for examples, documentation, small reference datasets, and prototyping.

**Dict rows syntax**: each row is a key-value mapping:

```yaml {contract=board-root}
queries:
  products:
    rows:
      - { product: "Widget A", revenue: 100, category: "Electronics" }
      - { product: "Widget B", revenue: 140, category: "Electronics" }
      - { product: "Gadget X", revenue: 180, category: "Accessories" }
```

**Columns + values syntax**: compact, SQL-style:

```yaml {contract=board-root}
queries:
  products:
    columns: [product, revenue, category]
    values:
      - ["Widget A", 100, "Electronics"]
      - ["Widget B", 140, "Electronics"]
      - ["Gadget X", 180, "Accessories"]
```

Both syntaxes produce identical results. Use whichever reads better for your data.

**Type Inference**: Detected by the presence of `rows:` or `values:`; no explicit `type:` needed.

**Use cases:**

- Examples and documentation that need to be self-contained
- Small lookup/reference tables (categories, labels, thresholds)
- Prototyping charts before connecting a real data source
- Test fixtures and demo dashboards

### 3. HTTP / API Queries

Fetch data from any JSON API. This is useful for integrating external data sources (weather, stock prices) or calling your own services (ML models, Jupyter notebooks exposed as endpoints).

Runs under local `dct` only; Not supported on dbtcharts.com.



```yaml {contract=board-root}
queries:
  prediction:
    type: http
    url: "https://api.model-service.com/predict"
    method: POST
    headers:
      Authorization: "Bearer {{ env.MODEL_API_KEY }}"
    body:
      features:
        region: "{{ region }}"
        date: "{{ date_range[0] }}"
```


**Type Inference**: Detected by the presence of `url:` or explicit `type: http`.

**Use cases:**
- Calling ML inference endpoints
- Fetching data from 3rd party APIs
- Triggering server-side workflows (if read-only)

### 4. Schema Queries

Introspect the project's own configured sources, schemas, tables, and columns instead of fetching business data. Useful for building meta-dashboards (data catalogs, source health checks) on top of dbt Charts's own configuration:

```yaml {contract=board-root}
queries:
  orders_columns:
    type: schema
    source: my_postgres
    schema: public
    table: orders
```

Set only the fields that narrow the introspection you want: omit `table` to list tables in a schema, omit `schema` to list schemas in a source, omit `source` to list configured sources, or set `column` (requires `schema` and `table`) to profile a single column's value distribution. Each field requires the ones above it: `table` needs `schema`, `schema` needs `source`. `type: schema` is always explicit; there's no key-based inference for this type.

Schema rows carry whatever metadata the source and its profiling depth provide, so their key set varies. `fields:` projects (and orders) the result rows to exactly the listed keys, the schema-query counterpart of a SQL SELECT list. A projected key a row lacks yields null, giving the consuming table a stable column set:

```yaml {contract=board-root}
queries:
  tables:
    type: schema
    source: warehouse
    schema: analytics
    fields: [name, row_count]
```

**Use cases:**
- Data-catalog / "what's in this warehouse" dashboards
- Health checks over your own `dbt_charts.yml` sources

### Column formats

A query knows what its columns mean, so it can say how they print. `formats:` maps
a column to a format name, and every chart showing that column uses it: axis
ticks, tooltips, mark labels, table cells and KPI values. Works on every query
type.

```dbt-charts-example
title: "EMEA results"

queries:
  region_results:
    columns: [region, revenue, target, churn_rate]
    values:
      - ["EMEA", 1234567, 1500000, 0.031]
    formats:
      revenue: currency
      target: currency
      churn_rate: percent

charts:
  revenue_bar:
    query: region_results
    type: bar
    x: region
    y: [revenue, target]
  results_table:
    query: region_results
    type: table
  churn:
    query: region_results
    type: kpi
    value: churn_rate

rows:
  - cols:
      - revenue_bar
      - churn
  - results_table
```

The bar, the table and the KPI above carry no format of their own. A value is a
format name: an engine name (`currency`, `percent`, `integer`, `year`, ...) or a
name the board defines in `style.formats`. A d3 spec such as `"$,.0f"` is
rejected with `ERR-QUERY-FORMAT-SPEC`; define a name for it in `style.formats`
and use that. Names resolve against the board that renders the query, so a
shared query naming a format of your own needs it defined in every board that
imports it. See [Format names and aliases](styling.md#format-names-and-aliases).

From weakest to strongest: the engine's format for the kind (`number`), the
board's redefinition of that name in `style.formats`, board- and theme-level
slot formats (`style.charts.axis_y.labels.format`), then the query's
`formats:`, then a chart's own
slot format: a KPI `value.format`, a table `columns.<c>.format`, a chart's
`axis_y.labels.format`. A board-wide axis format therefore never hides a
query's `formats:`; the chart that wants something else says so in its own slot.

A format reaches an axis of its own kind: a number format on a numeric axis, a
time format on a date axis. A year-shaped integer `x` is a date axis and prints
its own years; a band axis prints its category text as it is. An axis painting
several columns (`y: [revenue, orders]`) uses a query format only when every
column names the same one; otherwise it keeps the engine's `number`. Heatmap
cells and tooltips take the color column's format, a pie its `theta` column's.
A continuous color legend (a numeric `color:` on a bar or scatter) has no format
slot and keeps its default.

A `formats:` key must be a column the query returns, or the render fails with
`ERR-QUERY-FORMAT-COLUMN-MISSING` listing the columns that came back. A `values`
query is checked when the board compiles, a SQL query by `dct validate
--warehouse` and when its rows return. An empty result has no columns to check.

#### Formats from dbt

A dbt model is where a column is defined, so it can say how the column prints once
for every board that reads it. Set `meta.format` on the column:

```yaml {contract=unverified}
models:
  - name: orders
    columns:
      - name: amount
        config:
          meta:
            format: currency
```

A board query that reads `{{ ref('orders') }}` or `{{ source(...) }}` then prints
`amount` as `currency` with no `formats:` of its own. The format follows the column
through the SQL by a fixed set of rules, and stops where it cannot be known:

| Expression | Prints as |
|---|---|
| a column, an alias, `CAST` to a numeric type | the column's format |
| `SUM`, `AVG`, `MIN`, `MAX`, `MEDIAN`, `PERCENTILE_*` (and window forms) | the column's format; `SUM` of a `percent` column has none |
| `COUNT(...)` | `integer` |
| `a + b`, `a - b` with the same format | that format |
| `a / b` with the same format | `percent` |
| `currency / integer` | `currency` |
| `CASE`, `COALESCE`, `IF` whose branches share a format | that format |
| `EXTRACT(year ...)`, `YEAR(...)` | `year` |
| `ROUND`, `ABS`, `FLOOR`, `CEIL` | the column's format |
| `UNION` whose branches share a format | that format |

Everything else has no format, including `price * quantity`, `amount * 100`, and
inputs with different formats. An `id` column under any aggregate but `COUNT` has
none. Set the format yourself with the query's `formats:`, which always beats the
dbt column.

A `meta.format` that is neither an engine format nor defined in the root board's
`style.formats` (nested boards inherit it) fails the chart that reads the column with
`ERR-DBT-COLUMN-FORMAT-UNKNOWN`, naming the model and column. A column no query reads, or one the query's own `formats:` names, is
never checked. The format comes from `target/manifest.json`, so run
`dbt parse` after changing it.

---

## Field Reference

### Values Queries

```yaml {contract=unverified}
queries:
  <query_name>:
    # Option 1: Dict rows
    rows:                        # List of {key: value} dicts
      - { col1: val1, col2: val2 }

    # Option 2: Columns + values (compact)
    columns: [string]            # Column names
    values:                      # List of value arrays
      - [val1, val2]
```

### HTTP / API Queries

Runs under local `dct` only; Not supported on dbtcharts.com.

```yaml {contract=unverified}
queries:
  <query_name>:
    type: http                     # Required
    url: string                    # Required: URL (supports Jinja)
    method: GET | POST             # Optional: Default GET
    headers: Record<string, string> # Optional: HTTP headers
    params: Record<string, string>  # Optional: Query parameters
    body: any                      # Optional: JSON body (for POST)
    json_path: string              # Optional: dot-path to the row array in a nested response
    limit: number                  # Optional: max rows
```

Non-GET http sources are refused under `dct mcp serve` and other agent surfaces; `dct render`, `dct serve`, Streamlit, and the docs renderer allow them.

Use `json_path` when the API wraps its rows inside an envelope object instead of returning a bare array. It's dot-notation (`$.key.subkey`), not full JSONPath; it must resolve to a list:



```yaml {contract=board-root}
queries:
  orders_api:
    type: http
    url: "https://api.example.com/orders"
    json_path: "$.data.orders"   # response is { "data": { "orders": [ {...}, {...} ] } }
```


Omit `json_path` when the response is already a bare array of row objects.

### Raw SQL Queries

**String shorthand** (recommended when all queries share one source):
```yaml {contract=unverified}
source: my_postgres  # board-level default
queries:
  <query_name>: string  # bare SQL; inherits board source
```

**Dict form** (use when overriding source, setting target, or adding notes):
```yaml {contract=unverified}
queries:
  <query_name>:
    sql: string           # Required: SQL query (supports Jinja)
    source: string        # Required if no board-level source
    target: string        # Optional: dbt target name (defaults to 'dev')
    dialect: string       # Optional: warehouse dialect the SQL is written in (see below)
    notes: string           # Optional: metadata for AI search; never rendered
```

**Example:**

```yaml {contract=board-root}
source: my_postgres
queries:
  tickets: |
    SELECT * FROM dundersign.tickets
    WHERE status = 'solved'
    LIMIT 100
```

**Database Connection via Source Configuration:**

dbt Charts uses **source configuration** for SQL database connections. The `source` field must match a profile name defined in your dbt `profiles.yml` file (typically located at `~/.dbt/profiles.yml` or in your project directory).

**Source Configuration:**

1. **Create or edit `~/.dbt/profiles.yml`** with your database connection:


```yaml {contract=unverified}
my_postgres:
  outputs:
    dev:
      type: postgres
      host: localhost
      port: 5432
      user: myuser
      password: mypass
      dbname: mydb
      schema: public
    prod:
      type: postgres
      host: prod.example.com
      port: 5432
      user: prod_user
      password: "{{ env_var('DB_PASSWORD') }}"
      dbname: analytics
      schema: public
  target: dev  # Default target
```


2. **Reference the source in your queries:**

```yaml {contract=board-root}
queries:
  tickets:
    sql: SELECT * FROM dundersign.tickets
    source: my_postgres  # Uses 'my_postgres' source
    target: prod           # Uses 'prod' target (defaults to 'dev' if not specified)
```

**For more information:**
- See [dbt's profile documentation](https://docs.getdbt.com/reference/profiles.yml) for complete profile configuration options
- See [dbt adapter documentation](https://docs.getdbt.com/docs/connect-data-platform) for database-specific connection parameters (Postgres, Snowflake, BigQuery, Redshift, etc.)

---

## Filters

SQL queries have no declarative `filters:` field; you filter by writing the `WHERE` clause yourself, using Jinja to reference variables. Reach for the `filter()` / `filter_date_range()` helpers (below) instead of hand-rolled conditionals; they handle null-checking, list-to-`IN`, and parameter binding for you.

### Jinja in SQL

Board SQL is ordinary SQL with Jinja. You can use your board's variables, the `filter()` and `filter_date_range()` helpers, `{{ queries.<name> }}` to compose another query, and `{{ ref() }}` / `{{ source() }}` to name your dbt models and sources. Write it in one dialect and set `dialect:`: dbt Charts translates common SQL to the warehouse you run it on, and raises an error on constructs it can't translate. dbt Charts doesn't run dbt macros: put business logic in your models.

Reference variables directly in the SQL text:

```yaml {contract=board-root}
variables:
  priority:
    input: text
  ticket_type:
    input: text
queries:
  filtered_tickets:
    sql: |
      SELECT priority, status, COUNT(*) AS ticket_count
      FROM dundersign.tickets
      WHERE priority = '{{ priority }}'
        AND ticket_type = '{{ ticket_type }}'
      GROUP BY priority, status
    source: my_warehouse
```

See the [Expressions](variables/expressions.md) guide for the `filter()` / `filter_date_range()` helpers, which parameterize these Jinja-based filters against SQL injection and handle unset variables automatically.

### Writing SQL once with `dialect:`

A board that has to run on several warehouses, such as a dashboard pack shipped inside a dbt package, would otherwise need one query per dialect. Set `dialect:` to the dialect you wrote the SQL in. When it differs from the source's warehouse, dbt Charts translates the query before running it:

```yaml {contract=board-root}
queries:
  monthly_tickets:
    dialect: duckdb
    source: my_warehouse
    sql: |
      SELECT
        date_trunc('month', created_at) AS month,
        COUNT(*) AS tickets,
        SUM(solved) / NULLIF(COUNT(*), 0) AS solve_rate
      FROM {{ ref('fct_tickets') }}
      GROUP BY 1
```

Run against BigQuery, Snowflake, Redshift, Databricks, or Postgres, the same query gets each warehouse's spelling of `date_trunc` and integer division.

What to know:

- Without `dialect:`, nothing is translated. The SQL runs as written.
- Translation fails with `ERR-SQL-DIALECT-UNSUPPORTED` when the SQL does not parse, holds more than one statement, calls a function dbt Charts does not know, or uses a construct the target cannot express. It is not a guarantee: a function that exists in both dialects but behaves differently, or one the warehouse lacks, can still fail at the warehouse.
- Queries joined with `{{ queries.<name> }}` must all set the same `dialect:`, or all leave it unset (`ERR-QUERY-DIALECT-MIXED`).
- `setup_sql` is never translated. Write it in the source's own dialect.
- `dialect:` is not supported on file sources, with `{{ queries.<name>.cache }}` (which runs on DuckDB), or with `incremental:`. Each raises `ERR-SQL-DIALECT-UNSUPPORTED` when the dialect differs from the one the query runs in.
- A variable that ends up inside a string after translation, such as `INTERVAL {{ n }} DAY` on Postgres, is rejected with `ERR-SQL-DIALECT-UNSUPPORTED`. Write `{{ n }} * INTERVAL '1 day'` instead.
- `dialect:` takes one spelling per warehouse: `athena`, `bigquery`, `clickhouse`, `databricks`, `duckdb`, `fabric`, `mysql`, `postgres`, `presto`, `redshift`, `snowflake`, `spark`, `sqlite`, `sqlserver`, `trino`.

Some behavior differs by warehouse even when the SQL translates. BigQuery weeks start on Sunday. On Postgres, `datediff` counts full 24-hour periods, while Snowflake counts calendar boundaries crossed.

**Percentiles and medians.** Percentile functions do not translate reliably. Compute an exact median in plain SQL instead: rank the rows and average the one or two middle values.

```yaml {contract=board-root}
queries:
  median_resolution_by_group:
    dialect: duckdb
    source: my_warehouse
    sql: |
      WITH ranked AS (
        SELECT
          group_name,
          resolution_minutes,
          ROW_NUMBER() OVER (PARTITION BY group_name ORDER BY resolution_minutes) AS rn,
          COUNT(*) OVER (PARTITION BY group_name) AS n
        FROM dundersign.tickets
        WHERE resolution_minutes IS NOT NULL
      )
      SELECT group_name, AVG(resolution_minutes) AS median_resolution_minutes
      FROM ranked
      WHERE rn IN (FLOOR((n + 1) / 2.0), CEIL((n + 1) / 2.0))
      GROUP BY group_name
```

---

## Pivot (Cross-Tab Tables)

A tidy (long-form) query is pivoted into a cross-tab grid at render time by
adding `rows` / `columns` / `values` channels to a **table** chart. A field
on `columns` *is* the pivot: the SQL and the rows returned by the database
are unchanged; only the table's layout is reshaped.

```yaml {contract=board-root}
queries:
  tickets_long:
    sql: |
      SELECT priority, ticket_type, COUNT(*) AS ticket_count
      FROM dundersign.tickets
      GROUP BY priority, ticket_type
      ORDER BY priority, ticket_type
    source: warehouse

charts:
  tickets_crosstab:
    type: table
    query: queries.tickets_long
    rows: [priority]      # row headers down the left side
    columns: [ticket_type]  # distinct values become column headers (the pivot)
    values: [ticket_count]  # measure(s) that fill the cells
```

The table has one row per `priority` and one column per distinct `ticket_type`,
with `ticket_count` filling the cells. List more than one measure on `values`
(for example, `values: [revenue, units]`) to get a spanning column group per pivot
value. If a cell maps to more than one source row the engine raises an error
instead of silently aggregating; move the extra field onto `rows` or
`columns`.

Column order: a pivot dimension whose values have a canonical order (dates
and timestamps (chronological) or numbers (ascending)) renders its columns
in that order regardless of the query's row order, the way every reference
tool does. Any other dimension (plain strings, booleans, or a mix of dates
and a literal like `"Total"`) orders its columns by each value's first
appearance in the result set, kept as one consistent order across the whole
header when another dimension sorts, so an `ORDER BY` stays your lever for
business-ordered categories and total-column placement.

That lever is not optional for those dimensions. First-seen order is whatever
order the warehouse hands back, and a `GROUP BY` whose `ORDER BY` does not
constrain the pivot dimension has no defined order at all; parallel
aggregation can return a different one run to run, so the same data renders a
different column order on different days. Rows are first-seen too, and
unconditionally, no row dimension is ever sorted for you, so order by every
field you put on `rows` *and* `columns` (that is why the example above orders
by both `priority` and `ticket_type`), or accept an arbitrary order.

Pivot channels apply only to the `table` chart type; bar, line, and other
charts use `x` / `y` / `color` and are unaffected.

### Row and Column Totals

Totals are never computed by the render layer; a pivot table with totals
needs a query that emits them. Two independent signals drive the two kinds
of total:

- **Row totals** (a trailing "Total" column): emit a literal `"Total"`
  value in the `columns` field alongside the real pivot values; it reshapes
  into a trailing column like any other value.
- **Column totals** (a "Total" row): emit rows tagged with the same
  row-role column flat tables use for summary/total styling
  (`style.table.row.role`, for example, `_df_row_role`). Rows whose role resolves to
  `"total"` bucket by their `rows` value like every other row and get the
  total row's styling; a single grand total therefore means one consistent
  `rows` label (`priority = 'Total'` in the example) and merges into one row,
  while distinct total labels (per-group subtotals) stay distinct rows.
  Placement is the query's job: render never reorders *rows* (they keep
  first-seen order), so an `ORDER BY` decides where a total lands; put the
  total partition last to get a bottom total row. Render never merges or
  re-labels the values: the `rows` value on a total row is real data, not
  decoration.

```yaml {contract=board-root}
queries:
  tickets_with_totals:
    sql: |
      SELECT priority, ticket_type, COUNT(*) AS ticket_count, 'value' AS row_role
      FROM dundersign.tickets
      GROUP BY priority, ticket_type
      UNION ALL
      SELECT priority, 'Total' AS ticket_type, COUNT(*) AS ticket_count, 'value' AS row_role
      FROM dundersign.tickets
      GROUP BY priority
      UNION ALL
      SELECT 'Total' AS priority, ticket_type, COUNT(*) AS ticket_count, 'total' AS row_role
      FROM dundersign.tickets
      GROUP BY ticket_type
      UNION ALL
      SELECT 'Total' AS priority, 'Total' AS ticket_type, COUNT(*) AS ticket_count, 'total' AS row_role
      FROM dundersign.tickets
      ORDER BY
        CASE WHEN priority = 'Total' THEN 1 ELSE 0 END, priority,
        CASE WHEN ticket_type = 'Total' THEN 1 ELSE 0 END, ticket_type
    source: warehouse

charts:
  tickets_crosstab_with_totals:
    type: table
    query: queries.tickets_with_totals
    rows: [priority]
    # Both the priority rows and the ticket_type columns reshape in first-seen
    # (query) order; rows always do, and ticket_type is a string dimension, the
    # kind whose columns follow query order (dates/numbers would sort instead),
    # so the ORDER BY above pins both: priorities then types, each with its
    # "Total" sorted last. The total ROW lands last only because the ORDER BY
    # puts the 'Total' priority-partition last; drop that clause and the total
    # row renders wherever the query returns it.
    columns: [ticket_type]
    values: [ticket_count]
    style:
      row:
        role: row_role    # tags "total" rows for styling; query order places them
```

The role tag marks *rows*, not cells: the row-total UNION branch above stays
`'value'` because it's still a detail priority row (it just carries a `'Total'`
ticket_type cell), and only the bottom-row partition is tagged `'total'`. Tagging
the row-total branch `'total'` would collide it with that priority's detail
bucket and raise a `conflicting row roles` error at render.

A role-tagged total row gets the same double-rule styling as a flat table's
total row; pivot render only reshapes the role-tagged rows, it does not
restyle or re-derive them. Nothing styles a column by value; the trailing
total column is plain, it's only in the last position because of query order.

---

## Best Practices

### Reuse Queries Across Charts

Multiple charts can reference the same query, which is more efficient:

```yaml {contract=unverified}
queries:
  sales:
    sql: SELECT month, region, SUM(revenue) AS total_revenue FROM dundersign.orders GROUP BY 1, 2
    source: my_postgres

rows:
  - cols:
      - chart1:
          query: queries.sales  # Same query
          type: bar
          x: month
          y: total_revenue
      - chart2:
          query: queries.sales  # Same query
          type: line
          x: month
          y: total_revenue
          color: region
```

### Use Query References for DRY SQL

Instead of repeating SQL, reference other queries:


```yaml {contract=unverified}
# ❌ Bad: Repetitive SQL
queries:
  open_tickets:
    sql: |
      SELECT
        priority,
        COUNT(*) as ticket_count
      FROM dundersign.tickets
      WHERE status = 'new'
      GROUP BY 1
    source: my_postgres

  resolved_tickets:
    sql: |
      SELECT
        priority,         # Repeated
        COUNT(*) as ticket_count  # Repeated
      FROM dundersign.tickets
      WHERE status = 'solved'    # Only difference
      GROUP BY 1
    source: my_postgres

# ✅ Good: DRY with query references
queries:
  base_tickets:
    sql: |
      SELECT
        priority,
        status,
        COUNT(*) as ticket_count
      FROM dundersign.tickets
      GROUP BY 1, 2
    source: my_postgres

  open_tickets:
    sql: |
      SELECT * FROM {{ queries.base_tickets }}
      WHERE status = 'new'
    source: my_postgres

  resolved_tickets:
    sql: |
      SELECT * FROM {{ queries.base_tickets }}
      WHERE status = 'solved'
    source: my_postgres
```


### Performance Considerations

- Use `limit` when you don't need all rows
- Filter early, in the query's own `WHERE` clause (using `filter()`/`filter_date_range()`) rather than fetching all rows and filtering elsewhere
- Reuse queries across multiple charts

### Naming Conventions

- Use descriptive names (for example, `sales`, `products`) and reference with explicit namespacing (`queries.sales`)
- Use descriptive names that indicate what data the query fetches
- Keep names lowercase with underscores

---

## Testing and Validation

### Validate Your Dashboard

After writing queries, validate your dashboard to catch errors early:

```bash
dct validate charts/sales.yml
```

See the [CLI Reference](cli/validate.md) for validation options.

### Render to Inspect Resolved Queries

Render your dashboard to JSON to see the resolved query structure with executed results:

```bash
dct render charts/sales.yml --format json
```

See the [CLI Reference](cli/render.md) for rendering options.

---

## Query References

You can reference other queries within your SQL using Jinja template syntax. This enables CTE-style query composition where complex queries can be built from simpler building blocks.



```yaml {contract=board-root}
queries:
  # Base query - tickets by status
  tickets_by_status:
    sql: |
      SELECT
        status,
        COUNT(*) as ticket_count
      FROM dundersign.tickets
      WHERE status = 'solved'
      GROUP BY 1
    source: my_postgres

  # Reference the base query
  top_status_tickets:
    sql: |
      SELECT ticket_count as current_ticket_count
      FROM {{ queries.tickets_by_status }}
      ORDER BY ticket_count DESC
      LIMIT 1
    source: my_postgres
```


### How It Works

When you use `{{ queries.query_name }}`, dbt Charts:
1. Substitutes the referenced query's SQL inline as a parenthesized subquery
2. Aliases that subquery to the **query name**, so you reference its columns as
   `query_name.column`, and the same SQL is valid on both DuckDB and Postgres
   (Postgres requires the alias; DuckDB tolerates it)
3. Detects circular dependencies

You don't add the parentheses or the alias yourself. The example above becomes:

```sql
SELECT ticket_count as current_ticket_count
FROM (
  SELECT
    status,
    COUNT(*) as ticket_count
  FROM dundersign.tickets
  WHERE status = 'solved'
  GROUP BY 1
) AS tickets_by_status
ORDER BY ticket_count DESC
LIMIT 1
```

### Chained References

You can chain multiple query references:



```yaml {contract=board-root}
queries:
  solved_tickets:
    sql: |
      SELECT * FROM dundersign.tickets WHERE status = 'solved'
    source: my_postgres

  priority_totals:
    sql: |
      SELECT
        priority,
        COUNT(*) as ticket_count
      FROM {{ queries.solved_tickets }}
      GROUP BY 1
    source: my_postgres

  top_priority:
    sql: |
      SELECT ticket_count
      FROM {{ queries.priority_totals }}
      ORDER BY ticket_count DESC
      LIMIT 1
    source: my_postgres
```


### Referencing Columns (the automatic alias)

The subquery is aliased to the **query name**, so qualify its columns with that
name. Don't add your own `AS` alias; the query already has one and writing
`FROM {{ queries.base_tickets }} AS b` produces a SQL parse error (`... AS
base_tickets AS b`) because the alias is inserted automatically. To use a
different alias, rename the query itself:



```yaml {contract=board-root}
queries:
  base_tickets:
    sql: |
      SELECT status, ticket_type FROM dundersign.tickets
    source: my_postgres

  top_statuses:
    sql: |
      SELECT base_tickets.status, COUNT(*) as ticket_count
      FROM {{ queries.base_tickets }}
      GROUP BY base_tickets.status
      HAVING COUNT(*) > 10
    source: my_postgres
```


Referencing the **same** query twice in one statement collides on the alias and
fails; give each its own query name instead.

### Cross-Source Composition via Cache

`{{ queries.X }}` inlines query X as a SQL subquery; both queries must run against the **same source**. To join results from **different sources**, use the cache read token `{{ queries.X.cache }}` instead.

`{{ queries.X.cache }}` reads query X's **cached result rows** and evaluates the composing query in the local cache engine (DuckDB), making cross-source joins possible:



```yaml {contract=board-root}
queries:
  # Runs against your data warehouse
  monthly_revenue:
    sql: |
      SELECT month, revenue
      FROM dundersign_serving.monthly_metrics
    source: my_warehouse

  # Runs against your CRM (different source)
  monthly_leads:
    sql: |
      SELECT month, COUNT(*) AS leads
      FROM leads
      GROUP BY 1
    source: my_crm

  # Joins the two sources; evaluated in the local cache engine.
  # Each cache reference is aliased to its query name (no AS needed).
  efficiency:
    sql: |
      SELECT
        month,
        monthly_revenue.revenue,
        monthly_leads.leads,
        monthly_revenue.revenue / NULLIF(monthly_leads.leads, 0) AS revenue_per_lead
      FROM {{ queries.monthly_revenue.cache }}
      JOIN {{ queries.monthly_leads.cache }} USING (month)
    source: my_warehouse
```


**How it works:** dbt Charts executes `monthly_revenue` and `monthly_leads` first, caches their results, then evaluates the composing query inside the cache engine (DuckDB) using the cached rows as tables.

**Opt out of caching** by setting `cache: false` on a query. Queries with caching disabled cannot be referenced via `.cache`:

```yaml {contract=board-root}
queries:
  sensitive_data:
    sql: SELECT * FROM pii_table
    source: my_warehouse
    cache: false  # results never cached
```

### How long results stay cached

`cache:` takes a duration: `5m`, `1h`, `7d`, or a compound like `1h30m`
(`m` is minutes). Cached rows older than that are recomputed on the next read.
`cache: forever` never auto-expires, and `cache: false` turns caching off. The
default is 24 hours.

One limit on `forever`: the default cache file of `dct render` and `dct serve`
drops entries older than about a week, whatever their duration. Give them a
cache file of your own (`--cache <path>`) to keep results longer.

`dct render` and `dct serve` keep cached results on disk between runs, so
rendering a board again inside that window does not query the warehouse again.
[Caching in `dct render`](cli/render.md#caching) covers where the file lives,
how to force fresh data, and running several processes at once.

Write it once at the top of a dashboard and every query in it inherits:

```yaml {contract=board-root}
title: Sales
cache: 1h        # every query on this board expires after an hour

queries:
  overview:
    sql: SELECT * FROM daily_rollup   # 1h, inherited

  live_tickets:
    sql: SELECT * FROM dundersign.tickets WHERE status = 'new'
    cache: 30s                        # this one needs to be fresher

  pii_lookup:
    sql: SELECT * FROM pii_table
    cache: false                      # never cached
```

The nearest setting wins: a query's own `cache:` beats the dashboard's, which
beats the source's, which beats the project default in `dbt_charts.yml`. Anything
you leave out is inherited, so `cache: 30s` above changes only the duration.

### Limitations & Notes

**Query references are powerful** - they let you build complex analyses by composing simpler queries. Just two simple limitations:

**1. Top-Level Only**

**All query references** (`` `{{ queries.* }}` ``) **MUST reference top-level queries** in the current dashboard's `queries:` section:


```yaml {contract=unverified}
queries:
  base_query:  # ✅ Top-level - can be referenced
    sql: SELECT * FROM dundersign.tickets
    source: my_postgres

  # Import from other files and add to top level:
  shared_sales: _shared_queries.queries.base_sales  # ✅ Top-level - can be referenced

  my_analysis:  # ✅ Top-level - can be referenced
    sql: |
      SELECT * FROM {{ queries.shared_sales }} WHERE amount > 100
      UNION ALL
      SELECT * FROM {{ queries.base_query }}
    source: my_postgres

rows:
  - queries:  # ❌ NESTED - cannot be referenced anywhere!
      nested_query:
        sql: SELECT * FROM products
        source: my_postgres
```


**Important:** Even if you import a query from another file that has internal references (like `{{ queries.raw_data }}`), you must import ALL referenced queries to the top level of your current dashboard for them to work.

**2. SQL Only**

Only SQL queries can reference other queries. Values, HTTP, CSV, and other query types cannot use `{{ queries.* }}`.

## Importing Queries from Other Files

You can reuse queries across multiple dashboards by referencing queries from other files directly in your `queries:` section.

### Import Syntax

Use the format: `file_name.queries.query_name`


```yaml {contract=unverified}
queries:
  # Import queries from other files
  base_sales: _shared_queries.queries.base_sales
  customer_data: _shared_queries.queries.customer_data

  # Use imported queries like any other query
  my_analysis:
    sql: |
      SELECT * FROM {{ queries.base_sales }}
      WHERE revenue > 1000
    source: my_postgres

charts:
  sales_chart:
    query: my_analysis
    type: bar
    x: month
    y: revenue
```


### Import Examples

**Import from same directory:**

```yaml {contract=unverified}
queries:
  # _shared_queries.yml is in the same directory (underscore prefix means not rendered)
  orders: _shared_queries.queries.base_orders
  customers: _shared_queries.queries.base_customers
```

**Import from subdirectory:**

```yaml {contract=unverified}
queries:
  # analytics/metrics.yml
  revenue: analytics/metrics.queries.total_revenue

  # ml/predictions.yml
  top_customers: ml/predictions.queries.predict_top_customers
```

**Import from a sibling directory:**

A reference may start with one or more `../` segments to climb out of the
current directory. This is how a board in one folder reuses queries defined in
another:

```yaml {contract=unverified}
queries:
  # from charts/gtm_weekly/mqls.yml, reaching charts/sales/pipeline.yml
  mqls_by_week: ../sales/pipeline.queries.mqls_by_week
```

Paths are resolved relative to the importing file, and may not escape the
project root; `../../../etc/passwd.queries.x` is rejected.

**Use imported queries:**


```yaml {contract=unverified}
queries:
  base_sales: _shared.queries.sales

  filtered_sales:
    sql: |
      SELECT *
      FROM {{ queries.base_sales }}
      WHERE region = '{{ filter("region", "US") }}'
    source: my_postgres

  summary:
    sql: |
      SELECT
        COUNT(*) as total_orders,
        SUM(amount) as total_revenue
      FROM {{ queries.filtered_sales }}
    source: my_postgres

charts:
  summary_chart:
    query: summary
    type: kpi
    value: total_revenue
```


### Best Practices

1. **Use imports for shared queries**: Create `_shared_queries.yml` files (underscore prefix means not rendered as dashboards) for queries used across multiple dashboards
2. **Don't overdo it**: If you find yourself creating many shared query files, consider whether you need better data modeling in dbt or a proper data mart instead. Query references are for composition, not data transformation pipelines.
3. **Use for composition**: Build complex queries from simple, reusable building blocks
4. **Consider CTEs**: For simple cases or one-off queries, standard SQL CTEs might be clearer
5. **Reference columns by query name**: A reference is auto-aliased to its query name, so qualify columns as `base.column`; don't add your own `AS` alias
6. **Test separately**: Ensure referenced queries work independently before chaining them
7. **Keep it simple**: Avoid deep chains (A → B → C → D). Two levels is usually enough

---

## Security: Parameterized Queries

**dbt Charts uses parameterized queries to prevent SQL injection attacks.** When you use variables in your SQL queries, they are automatically passed as parameters to the database driver rather than being interpolated directly into the SQL string.

### How It Works

When you write:



```yaml {contract=board-root}
variables:
  priority:
    input: text
  status:
    input: text
queries:
  tickets:
    sql: |
      SELECT * FROM dundersign.tickets
      WHERE priority = '{{ priority }}'
        AND {{ filter('status', status) }}
    source: my_postgres
```


dbt Charts converts this to a parameterized query:

```sql
-- SQL sent to database:
SELECT * FROM dundersign.tickets
WHERE priority = $1
  AND status = $2

-- Parameters sent separately:
params = ['normal', 'new']
```

This separation ensures that:
- **Malicious input cannot alter query logic** - Even if a user enters `'; DROP TABLE tickets; --` as input, it's treated as a literal string value, not SQL code
- **Database can cache query plans** - The same parameterized SQL structure enables query plan reuse
- **No escaping needed** - The database driver handles type conversion and escaping automatically

### Filter Helper Behavior

The `filter()` and `filter_date_range()` helpers return `1=1` (always true) when the variable is `None`, `undefined`, or empty. This means:

- **Filter applied:** `{{ filter('priority', 'normal') }}` → `priority = $1` (with 'normal' as parameter)
- **Filter skipped:** `{{ filter('priority', None) }}` → `1=1` (all rows match, no filtering)

This pattern allows optional filtering where unset variables don't restrict results.

#### Deny-on-null fallback

For mandatory-scope dashboards (audit views, customer-specific dashboards, anything where the unfiltered superset is the wrong default), pass `none='deny'` to flip the fallback from `1=1` to `1=0` (zero rows):

- **`{{ filter('priority', None, none='deny') }}` → `1=0`** (no rows when unset)
- **`{{ filter('priority', 'normal', none='deny') }}` → `priority = $1`** (normal filter when set)

`none` is keyword-only; valid values are `'allow'` (default) and `'deny'`. Anything else raises `ValueError`.

### Security Validations

The parameterized filter helpers include additional security measures:

1. **Operator validation**: Only valid SQL operators (=, !=, >, <, >=, <=, LIKE, IN, etc.) are allowed. Invalid operators raise an error.
2. **Column name validation**: Column names must contain only letters, numbers, underscores, and optionally one dot (for `table.column` format).

### Best Practices

- **Use `filter()` for user-controlled values** - Always use the filter helpers for variables that come from user input
- **Don't construct SQL from user strings** - Avoid patterns like `WHERE {{ user_column }} = ...` where column names come from user input
- **Validate at the variable level** - Use variable validation (data types, options) to restrict allowed values

---

## Related

- [Variables](variables/index.md) - Using variables in filters
- [Expressions](variables/expressions.md) - Variable references and Jinja expressions
- [Charts](charts/index.md) - Visualizing query data
- [CLI Reference](cli/index.md) - Validate, render, serve, and more
- [YAML Schema Reference](reference/yaml-reference.md) - Complete field reference
- [Troubleshooting Guide](guides/troubleshooting.md) - Common query issues

# Overview (https://docs.dbtcharts.com/sources/)

# Sources

Sources define where a board reads data from. Most projects use one warehouse
connection for SQL queries, but a board can also read files, HTTP endpoints,
inline values, or dbt models.

Connection sources are defined once, in the project's root `dbt_charts.yml`, as a
named `sources:` registry. A board (or `charts/meta.yml`) never defines a
connection inline; it only references a source by name:

```yaml {contract=project-config}
# dbt_charts.yml
sources:
  analytics:
    type: dbt_profile
    profile: my_dbt_project
    target: dev
```

```yaml {contract=board-root}
source: analytics   # References the "analytics" source above

queries:
  tickets: SELECT * FROM dundersign.tickets
```

Every `sources:` block on this page belongs in `dbt_charts.yml`, not in a board.
A board's own `source:` field always holds a name (or, for a single colocated
data file, an inline path; see [Inline File Sources](#inline-file-sources)),
never a connection definition.

dbt Charts `sources:` are connection definitions. They are separate from dbt
`sources:` resources, which document raw tables inside a dbt project. If you are
setting up dbt source tables, use dbt's
[source properties](https://docs.getdbt.com/reference/source-properties)
reference.

## Source Types

For warehouse-backed SQL, dbt Charts uses dbt-compatible connection settings. In
most dbt projects, use `type: dbt_profile` and let dbt own the adapter-specific
credentials. Direct warehouse source types use the same field names as dbt
profiles, but they are flat because boards read data; they do not build dbt
models.

You do not need `profiles.yml` for direct sources such as `postgres`,
`snowflake`, `bigquery`, `duckdb`, or `sqlite`. dbt Charts uses the direct source
block as the connection config. The dbt links below are still useful because
they document the same adapter credential fields.

| Source | dbt Charts setup | Credential fields / setup |
|---|---|---|
| Existing dbt project | `type: dbt_profile` | [dbt profiles.yml](https://docs.getdbt.com/docs/local/profiles.yml) |
| BigQuery | `type: bigquery` | [BigQuery connection](https://docs.getdbt.com/docs/local/connect-data-platform/bigquery-setup) |
| DuckDB | `type: duckdb` | [DuckDB connection](https://docs.getdbt.com/docs/local/connect-data-platform/duckdb-setup) |
| Postgres | `type: postgres` | [Postgres connection](https://docs.getdbt.com/docs/local/connect-data-platform/postgres-setup) |
| Redshift | `type: redshift` | [Redshift connection](https://docs.getdbt.com/docs/local/connect-data-platform/redshift-setup) |
| Snowflake | `type: snowflake` | [Snowflake connection](https://docs.getdbt.com/docs/local/connect-data-platform/snowflake-setup) |
| SQL Server | `type: dbt_profile` | [dbt-sqlserver connection](https://docs.getdbt.com/docs/local/connect-data-platform/mssql-setup) (install `dbt-charts[sqlserver]`) |
| Microsoft Fabric | `type: dbt_profile` | [dbt-fabric connection](https://docs.getdbt.com/docs/local/connect-data-platform/fabric-setup) (install `dbt-charts[fabric]`) |
| Trino / Starburst | `type: trino` | [Trino](#trino) (install `dbt-charts[trino]`) |
| Athena | `type: dbt_profile` | [dbt-athena connection](https://docs.getdbt.com/docs/local/connect-data-platform/athena-setup) (install `dbt-charts[athena]`) |
| ClickHouse | `type: dbt_profile` | [dbt-clickhouse connection](https://docs.getdbt.com/docs/local/connect-data-platform/clickhouse-setup) (install `dbt-charts[clickhouse]`) |
| SQLite | `type: sqlite` | dbt Charts direct source; no dbt setup |
| Databricks | `type: databricks` | [Databricks](#databricks), token or OAuth service principal |
| Lake compute | `type: lakecompute` | [Lake compute](#lake-compute) (install `dbt-charts[lakecompute]`) |
| Spark | `type: dbt_profile` | [Apache Spark connection](https://docs.getdbt.com/docs/local/connect-data-platform/spark-setup) |
| dbt models | `sql` query using `ref()` with a dbt profile source | [dbt profiles.yml](https://docs.getdbt.com/docs/local/profiles.yml) |
| CSV files | `type: csv` | [Files and APIs](#files-and-apis) |
| Parquet files | `type: parquet` | [Files and APIs](#files-and-apis) |
| JSON files | `type: json` | [Files and APIs](#files-and-apis) |
| HTTP endpoints | `type: http` query | [Files and APIs](#files-and-apis) |
| Inline static data | `type: values` query | No source setup |

**ClickHouse and `max_execution_time`.** `max_query_duration_seconds` is a ceiling.
If your dbt profile's `custom_settings` already sets a stricter `max_execution_time`,
dbt Charts keeps yours; a looser one is capped at the ceiling. ClickHouse types the
setting as whole seconds and reads `0` as *no limit*, so a fractional or zero value is
rejected rather than silently disabling the cap.

**ClickHouse read-only users need `readonly = 2`.** dbt Charts caps every query with
ClickHouse's `max_execution_time`, sent as a per-request setting. A `readonly = 1` user
cannot change any setting, so the connection fails at setup with ClickHouse's own
`Cannot modify 'max_execution_time' setting in readonly mode`. `readonly = 2` is the
read-only mode ClickHouse gives BI clients: read-only queries, settings changes allowed.

**SQL Server and `query_timeout`.** `max_query_duration_seconds` is enforced through
your dbt profile's `query_timeout`, which T-SQL needs because it has no per-statement
`SET`. A stricter `query_timeout` of your own is kept; `0` means no cap and is replaced
by the ceiling. The `mssql-python` backend ignores `query_timeout`, so dbt Charts
refuses it rather than run uncapped; use the default `pyodbc` backend. SQL Server also
needs Microsoft ODBC Driver 17 or 18 installed on the host, which `pip` cannot provide. A query that fails
on SQL Server is not retried, including one that failed because an idle session was
dropped; run it again.

## dbt Profile Sources

dbt Charts can either read your warehouse credentials from a dbt profile or accept
a direct source definition with dbt-style field names.

Use `dbt_profile` when your project already has `profiles.yml`:

```yaml {contract=project-config}
# dbt_charts.yml
sources:
  analytics:
    type: dbt_profile
    profile: my_dbt_project
    target: dev
```

dbt Charts resolves `profiles.yml` in this order:

1. `profiles_dir` on the source config
2. `DBT_PROFILES_DIR`
3. The linked dbt project directory, next to `dbt_charts.yml` by default, or an external directory named via `--dbt-project-dir` / `DBT_PROJECT_DIR` / `dbt_project_dir:` (see [`--dbt-project-dir`](../cli/index.md#-dbt-project-dir-path))
4. `~/.dbt/profiles.yml`

If none of those locations contains `profiles.yml`, dbt Charts raises an error.
Without a linked dbt project, steps 2 and 4 still apply (`profiles_dir` is relative to the project, so it needs one).

`profile:` is optional. When the source omits it, dbt Charts uses `DBT_PROFILE`,
then the `profile:` in the linked dbt project's `dbt_project.yml`, the same order
dbt uses. A board shipped inside a dbt package can therefore declare
`type: dbt_profile` and follow whichever profile the consuming project names. If
none of the three names a profile, the query fails with an error listing them.

### No `dbt_charts.yml` needed inside a dbt project

When `dbt_project.yml` is at the project root and `dbt_charts.yml` declares no
`sources:` (or there is no `dbt_charts.yml` at all), dbt Charts adds one source
for you. It is named after the project's `profile:` and behaves as if you had
written `type: dbt_profile` for it, so it shows up in `dct doctor` and is usable
as `source: <profile>`. A SQL query that names no `source:` (on the query, at the
board root, or in a `meta.yml`) runs against it. Boards shipped in a dbt package
can leave `source:` out and follow whichever profile the consuming project names.

Declaring any `sources:` turns the implicit source off, and a SQL query that names
no source then fails with `ERR-SOURCE-NOT-NAMED`, as it does outside a dbt
project. A `dbt_project.yml` with no `profile:` (a dbt package) gets no implicit
source. On dbt Charts Cloud the implicit source appears as one unmapped
connection to bind; Cloud never reads your `profiles.yml`.

### Which manifest `ref()` resolves against

`target:` picks the connection, but `ref()` and `source()` resolve against a dbt
manifest, and dbt does not record which target built it. With `target: prod` and a
manifest from `dbt parse --target dev`, queries run against dev relations. Point
the source at the manifest built for its target with `target_path:`, the same
meaning as dbt's `--target-path`, relative to the dbt project directory:

```yaml {contract=project-config}
# dbt_charts.yml
sources:
  analytics:
    type: dbt_profile
    profile: my_dbt_project
    target: prod
    target_path: target/prod
```

```bash
dbt parse --target prod --target-path target/prod
```

Without `target_path:`, the manifest is `<dir>/manifest.json`, where `<dir>` is
`DBT_TARGET_PATH`, then `target-path:` in `dbt_project.yml`, then `target`. The
directory must be relative to the dbt project (`ERR-DBT-TARGET-PATH-INVALID`
otherwise). A missing manifest at the resolved path raises `ERR-DBT-MANIFEST-MISSING`
naming it; dbt Charts never falls back to another one. A query inlined through
`{{ queries.X }}` resolves its `ref()` calls against the including query's source.

#### On dbtcharts.com

dbtcharts.com has no manifest to build and resolves `ref()` and `source()` against
your production warehouse only. It reads the model, seed, snapshot and source
definitions in your dbt project on the default branch, lists the tables in the
project's default source, and links each name to the table that exists there. A
`target/manifest.json` committed to the repository still wins. dbt macros in board
SQL are not supported: put the logic in a dbt model and `ref()` it.

A name that cannot be linked fails its chart with `ERR-DBT-REF-UNKNOWN-NODE` (or
`ERR-DBT-SOURCE-UNKNOWN-TABLE`) instead of guessing a table. The usual reasons:

- The model has not been built in production yet, or is ephemeral or disabled.
- Its schema, alias or database comes from Jinja or a macro rather than a literal
  value in `dbt_project.yml`, a properties file or `config()`.
- Its name exists in more than one candidate schema, or the project overrides
  `generate_alias_name` or `generate_database_name`.
- It lives in another database than the default source's.

A project with no default source, or whose first index is not built yet, fails
`ref()` charts with `ERR-DBT-MANIFEST-MISSING`. The index rebuilds when dbt files on
the default branch change and when the default source changes. A chart that fails on
a name the index lacks, on a missing manifest, or with `ERR-BINDER-UNKNOWN-RELATION`
(the warehouse reports the table or view does not exist) in a board that uses `ref()`
or `source()` also asks for a rebuild, so a table a production run creates or moves
is picked up by the next render. That request is made at most once every five minutes.

### Who validates the target

`profiles.yml` is dbt's file, so **dbt validates it**; dbt Charts applies no schema
of its own. Every field your installed dbt adapter accepts works, including
`threads` and dbt's canonical `database:` / `schema:` spelling for BigQuery
(`project:` / `dataset:` work too, exactly as in dbt). A field dbt requires but
your target omits is reported when the dashboard runs, naming the profile and
target.

The flip side: a misspelled key is **not** an error. dbt ignores keys it does not
recognize, so `hostt: localhost` is silently unused, by dbt Charts and by
`dbt run` alike. If a connection behaves unexpectedly, check the spelling of your
target's fields.

This differs from the direct warehouse sources below, where dbt Charts owns the
schema and an unknown key *is* an error.

Installing that adapter is a separate step: dbt Charts connects through a Python
adapter package, which ships as an extra. See
[Warehouse adapters](../guides/installation.md#warehouse-adapters).

## Direct Warehouse Sources

Direct warehouse sources are useful for small projects that do not share a dbt
project. This is the full connection config; no `profiles.yml` file is required.
For larger dbt projects, prefer `type: dbt_profile`.

Postgres (`connect_timeout`) and BigQuery (`job_creation_timeout_seconds`) give up
connecting after 5 seconds unless you set a different value. Redshift's
`connect_timeout` is the socket timeout for the whole connection, so unset it follows
`max_query_duration_seconds` plus a small headroom.

### Postgres


```yaml {contract=project-config}
# dbt_charts.yml
sources:
  analytics:
    type: postgres
    host: "{{ env_var('ANALYTICS_HOST') }}"
    port: 5432
    dbname: analytics
    schema: public
    user: "{{ env_var('ANALYTICS_USER') }}"
    password: "{{ env_var('ANALYTICS_PASSWORD') }}"
```


### DuckDB

```yaml {contract=project-config}
# dbt_charts.yml
sources:
  local_db:
    type: duckdb
    path: ./data/analytics.duckdb
    schema: crm
```

DuckDB sources are **local-only**. A `.duckdb` file is a version-coupled,
single-writer binary, so dbt Charts Cloud does not read `.duckdb` files from
connected repositories. For Cloud, export the tables to Parquet or CSV and
register them as [file sources](#files-and-apis) instead.

### SQLite

```yaml {contract=project-config}
# dbt_charts.yml
sources:
  local_sqlite:
    type: sqlite
    path: ./data/analytics.sqlite
```

### Databricks

A Databricks source connects to a SQL warehouse and authenticates with exactly
one of two credential sets: a personal access token, or an OAuth machine-to-machine
(M2M) service principal. Databricks recommends the service principal for
automation, and it is the only option when your admins have turned tokens off.


```yaml {contract=project-config}
# dbt_charts.yml
sources:
  db:
    type: databricks
    host: "{{ env_var('DATABRICKS_HOST') }}"
    http_path: /sql/1.0/warehouses/abc123def456
    catalog: main
    schema: analytics
    client_id: "{{ env_var('DATABRICKS_CLIENT_ID') }}"
    client_secret: "{{ env_var('DATABRICKS_CLIENT_SECRET') }}"
```


For a personal access token, replace the two service principal fields with `token`:


```yaml {contract=project-config}
# dbt_charts.yml
sources:
  db:
    type: databricks
    host: "{{ env_var('DATABRICKS_HOST') }}"
    http_path: /sql/1.0/warehouses/abc123def456
    catalog: main
    schema: analytics
    token: "{{ env_var('DATABRICKS_TOKEN') }}"
```


Setting both credential sets, only one of `client_id` and `client_secret`, or
neither is an error; dbt Charts never picks a method for you. Create the secret
under Settings, Identity and access, Service principals, Secrets in your
workspace, and grant the principal `CAN USE` on the SQL warehouse (see the
[Databricks OAuth M2M guide](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-m2m)).
A literal `client_secret` or `token` in `dbt_charts.yml` is rejected; use `env_var()`.

`connect_timeout` is how many seconds a connection attempt may keep retrying while
the SQL warehouse starts, 15 by default. `socket_timeout` bounds each socket read
separately.

### Trino

Trino connects through the `trino` Python client rather than a dbt adapter. Install
the extra (`pip install "dbt-charts[trino]"`).


```yaml {contract=project-config}
# dbt_charts.yml
sources:
  lake:
    type: trino
    host: trino.example.com
    port: 8443
    catalog: analytics
    schema: public
    user: ana
    method: ldap
    password: "{{ env_var('TRINO_PASSWORD') }}"
```


The field names are the keys of a dbt `type: trino` profile target. `catalog` and
`database` both name the catalog. `method` picks the way to authenticate; leave it
out to connect as `user` with no credential:

| `method` | Fields |
|---|---|
| none (default) | `user` |
| `ldap` | `user`, `password`, `impersonation_user` (optional) |
| `jwt` | `jwt_token` |
| `certificate` | `client_certificate`, `client_private_key` |
| `oauth`, `oauth_console` | none; signs in through a browser or a printed link |
| `kerberos`, `gssapi` | `principal`, `krb5_config`, `service_name` (all optional) |

Every authenticated method connects over HTTPS. The server certificate is verified
unless you set `cert: false`; `cert` also takes the path to a CA bundle. Kerberos
reads its keytab from the `KRB5_CLIENT_KTNAME` environment variable, so `keytab:`
on the source is an error.

`max_query_duration_seconds` is sent as the `query_max_run_time` session property.
If `session_properties` sets `query_max_run_time` itself, the shorter of the two
applies.

Column types come from Trino's own result metadata. `array`, `map` and `row`
values arrive as JSON text. A type dbt Charts does not read (an `interval`, a
`time with time zone`, a sketch type) fails the query with a message naming the
column; `CAST` it in the query, for example to `varchar`.

**Through `profiles.yml`.** A `type: trino` target works with `type: dbt_profile`
and takes the same keys as the direct source, plus dbt's `method: none` for no
authentication. `threads:` governs `dbt run`, so
dbt Charts reads past it. Unlike other targets, dbt Charts validates this one
itself, so an unknown key is an error. `target_path:` on the `dbt_profile` source
is not supported for Trino and raises.

If your dbt project's own target is Trino, a query that uses `{{ ref() }}` with no
`source:` fails with `ERR-DBT-TARGET-NEEDS-SOURCE`. Declare a `dbt_profile` source
for the target and set `source:` on the query.

### Lake compute

Lake compute has no dbt Core adapter. dbt Charts connects through the same ADBC
driver dbt v2 uses, which is why the source type is spelled the way dbt v2 spells
it: `lakecompute`. `lake_compute` and `alt` are not accepted.

Install the extra (`pip install "dbt-charts[lakecompute]"`). The driver itself is
downloaded from dbt's CDN the first time a query runs, checked against a pinned
SHA-256, and cached where dbt v2 keeps its own. A machine that has already run dbt
v2 downloads nothing.


```yaml {contract=project-config}
# dbt_charts.yml
sources:
  lake:
    type: lakecompute
    token: "{{ env_var('DBT_COMPUTE_AUTH_TOKEN') }}"
```


The field names are dbt v2's profile keys, flat. `method` picks the way to
authenticate, and each method takes only its own fields:

| `method` | Fields |
|---|---|
| `token` (default) | `token` |
| `api_key` | `api_key` |
| `okta_browser` | `okta_auth_url`, `okta_token_url`, `okta_client_id` (all optional) |
| `fivetran` | `fivetran_credential`, `fivetran_auth_url` (optional) |

Every method also accepts `base_url` and `catalog_bundle`, both optional:


```yaml {contract=project-config}
# dbt_charts.yml
sources:
  lake:
    type: lakecompute
    method: fivetran
    fivetran_credential: "{{ env_var('FIVETRAN_PAT') }}"
    base_url: https://api.lake-compute.fivetran.com/
    catalog_bundle: analytics
```


A field from another method (`token` next to `api_key`), `database:`, `schema:`,
`attribution:`, or any key not listed above is an error rather than being ignored.

`base_url` defaults to the production endpoint, set in `dbt_charts.yml` as
`execution.lakecompute.default_base_url`. dbt v2 also reads `DBT_COMPUTE_BASE_URL`
for that default; dbt Charts does not read environment variables itself. If you
point dbt v2 at another endpoint through that variable, write
`base_url: "{{ env_var('DBT_COMPUTE_BASE_URL') }}"` so both
agree.

Lake compute runs DuckDB, so write SQL as DuckDB SQL (`dialect: lakecompute` on a
query names it). `max_query_duration_seconds` is sent to the driver as its own
per-query timeout. If the backend attaches a warning to a result, such as an export
limit that cut the rows short, the query fails with `ERR-WAREHOUSE-RESULT-WARNING`
instead of rendering a partial result.

**Through `profiles.yml`.** A `type: lakecompute` target works with
`type: dbt_profile`, without dbt Core in the picture. The target takes the same
keys as the direct source above (`method`, `token`, `base_url`, and so on), so a
target named `lake` in the `analytics` profile is used like this:

```yaml {contract=project-config}
# dbt_charts.yml
sources:
  lake:
    type: dbt_profile
    profile: analytics
    target: lake
```

`database:`, `schema:`, `threads:`, `snowflake_pat_duration_days:` and
`organization:` in the target govern what `dbt run` writes or how dbt itself
authenticates, so dbt Charts reads past them. `path:` selects dbt's local DuckDB
engine and is rejected. A target written as a list of connections, or with a
`lakecompute:` sibling key, is dbt v2's multi-connection shape, which dbt Charts
does not read yet. `attribution:` and `target_path:` on the `dbt_profile` source
are not supported for lake compute yet and raise.

If your dbt project's own target is lake compute, a query that uses `{{ ref() }}`
with no `source:` fails with `ERR-DBT-TARGET-NEEDS-SOURCE`. Declare a source like
the one above and set `source:` on the query.

## Files and APIs

CSV, Parquet, JSON, and HTTP sources do not need dbt. They are simpler local
dbt Charts source definitions for examples, prototypes, and lightweight external
data.

### CSV

A CSV source is a namespace of relations. Each key under `files:` is a table
name; the value is the path to the CSV file relative to the project root.

```yaml {contract=project-config}
# dbt_charts.yml
sources:
  sales_csv:
    type: csv
    files:
      sales: assets/data/sales.csv
```

Then query it by name:

```yaml {contract=board-root}
queries:
  sales:
    source: sales_csv
    sql: SELECT * FROM sales
```

A single source can expose multiple CSV files as separate tables:

```yaml {contract=project-config}
# dbt_charts.yml
sources:
  sales_data:
    type: csv
    files:
      orders: assets/data/orders.csv
      returns: assets/data/returns.csv
```

### JSON

```yaml {contract=project-config}
# dbt_charts.yml
sources:
  product_json:
    type: json
    files:
      products: assets/data/products.json
```

```yaml {contract=board-root}
queries:
  products:
    source: product_json
    sql: SELECT * FROM products
```

### Parquet

```yaml {contract=project-config}
# dbt_charts.yml
sources:
  events:
    type: parquet
    files:
      events: assets/data/events.parquet
```

```yaml {contract=board-root}
queries:
  event_counts:
    source: events
    sql: SELECT * FROM events
```

### Guardrails

Two limits bound a single file source's growth: `execution.file_source_max_tables`
caps the number of table entries a single `files:` map may declare (default 500),
and `execution.file_source_max_bytes` caps each table's uncompressed byte size
(default 5 GB), summed across all files matched by its path or glob. Every
format is measured the same way: the file's own bytes for CSV and JSON, and
for Parquet the uncompressed total recorded in the file's footer, so choosing
the compact format never costs you budget. Both are hard errors, not
truncation. Narrow the `files:` map, raise the limit in `dbt_charts.yml`, or
use a database connection for data at that scale. A hosted deployment may pin
its own ceiling, and a project's setting can only lower it, never raise it;
where a ceiling is what fired, the limit below is not the knob that moves:

```yaml {contract=project-config}
# dbt_charts.yml
execution:
  file_source_max_tables: 100
  file_source_max_bytes: 1000000000  # 1 GB
```

### Exploring a file source

`dct query` runs ad-hoc SQL against a file source directly, the same way it
does against a warehouse source:

```bash
dct query sales_csv 'SELECT * FROM sales LIMIT 5'
```

DuckDB has to materialize the source's files (read and parse them) before it
can answer, and the materialized tables land in an in-memory cache that dies
with the process. A *following* `dct query` invocation — a fresh process —
gets no benefit from it and re-reads the files from scratch. The warmth only
pays off inside one long-lived process that runs multiple queries against the
source, such as `dct serve`, a single render, or one `dct validate --warehouse`
sweep.

### HTTP

Unlike SQL and file queries, an HTTP query is self-contained: set `url:` (and
optional `headers:`, `method:`, `body:`) directly on the query. It has no
`source:` field; there is no named registry entry to reference.

Runs under local `dct` only; Not supported on dbtcharts.com.

```yaml {contract=board-root}
queries:
  forecast:
    type: http
    url: "https://api.example.com/forecast"
```

See [Queries](../queries.md#3-http-api-queries) for the full HTTP query field reference.

## Inline File Sources

A single CSV, JSON, or Parquet file that only one query reads doesn't need a
named registry entry; reference the file directly on `source:`, as a path
containing `/` or ending in a data-file extension:

```yaml {contract=board-root}
queries:
  sales:
    source: ./data/sales.csv
    sql: SELECT * FROM sales
```

The path resolves against the board file's own directory or the project root, whichever
exists (both existing at once is a compile error naming both). The table name is
the file's stem (`sales.csv` → table `sales`); a stem that isn't a valid SQL
identifier is a compile error rather than a silently sanitized name; rename
the file or use the named-registry form below. Only a single file is allowed
inline (no `files:` list); an inline file source is always materialized
straight from the file's git content.

Use the named-registry form (`type: csv`/`json`/`parquet` with a `files:` map
in `dbt_charts.yml`, above) instead when a file is shared across boards or a
source exposes more than one file as separate tables.

## Source Defaults

Set `source:` on a board to make all queries in that board use a default source
by name. A `charts/meta.yml` (or a directory's own `meta.yml`) can set the
same field to default every board beneath it:

```yaml {contract=board-root}
source: finance

queries:
  monthly_revenue:
    sql: SELECT month, revenue FROM finance_revenue

  sales_pipeline:
    source: sales
    sql: SELECT stage, amount FROM sales_pipeline
```

Sources are resolved from most specific to broadest:

1. Query-level `source:`
2. Board-level `source:`
3. The nearest ancestor `source:` in the `charts/meta.yml` cascade

An unknown source name is a validation error.

## Attribution

Every query dbt Charts sends carries attribution so your warehouse's cost tracking can
tell a dbt Charts query apart from ad-hoc human querying. On BigQuery it arrives as
[job labels](https://docs.cloud.google.com/bigquery/docs/adding-labels#job-label),
queryable as a real column in `INFORMATION_SCHEMA.JOBS`; on other warehouses it
arrives as a leading JSON comment on the query text.

dbt Charts sets the engine half itself; you don't configure it:

| Label | Meaning |
| --- | --- |
| `app` | Always `dbt-charts`. The one key to filter on; dbt emits `app=dbt` under the same key, so one predicate covers both. |
| `dbt_charts_version` | The `dct` version that sent the query. |
| `dbt_charts_surface` | Which entry point: `cli`, `serve`, `mcp` (the local `dct mcp serve` server), or `cloud`. |
| `dbt_charts_board` | The dashboard the query belongs to. |
| `dbt_charts_query` | The query's name within that dashboard. |
| `dbt_charts_target` | The dbt target, when the query names one. |
| `dbt_charts_tool` | The AI tool call that issued the query, such as `execute_query`. Absent for queries no tool issued. |

A host that knows *who* is asking adds three more, opaque per-request labels; no
emails or display names, since warehouse query history is broadly readable and
long-retained:

| Label | Meaning |
| --- | --- |
| `dbt_charts_actor` | Opaque ID of the person or agent who caused the query. |
| `dbt_charts_client` | Opaque ID of the software that asked: a browser session, an AI copilot turn, a connected MCP client (`connector` for Cloud's hosted connector). |
| `dbt_charts_request` | A fresh opaque ID per call, correlating this query to the host's own audit log. |

Only Cloud sets these today; it is the only host with a signed-in principal. The
CLI and `dct serve` have no notion of "who," so they omit all three rather than
inventing a value.

Like `dbt_charts_board`/`_query`/`_target`/`_tool`, only BigQuery gets `dbt_charts_actor`,
`_client`, and `_request` as real key/value labels; on every other warehouse they
ride the query comment along with the rest of the per-request payload (see below),
so finding them means matching the comment text, not filtering a column.

### Where it lands, per warehouse

Only BigQuery stores the whole payload as structured key/value. Elsewhere dbt Charts
fills the warehouse's own identity field so `app` is a column you can filter, and the
rest of the payload rides the query comment:

| Warehouse | Native field | Carries |
| --- | --- | --- |
| BigQuery | job labels (`JOBS.labels`) | everything, as key/value |
| Snowflake | `QUERY_TAG` | `app`, version, surface, as JSON |
| Databricks | query tags | `app`, version, surface, as JSON |
| Trino | `client_tags` | `app`, version, surface |
| Postgres | `application_name` | `dbt-charts` |
| Redshift, Athena, ClickHouse, DuckDB, SQLite | none | query comment only |
| Lake compute | none | nothing; `attribution:` is not supported yet |

Setting the native field costs nothing: it travels with the connection, not with each
query. If you have already set `query_tag`, `application_name`, or `client_tags`
yourself, dbt Charts leaves your value alone.

Redshift and Athena are deliberately left out: Redshift's `query_group` routes WLM
queues and Athena's `work_group` routes data limits and engine settings, so writing
either could move your queries somewhere else, too high a price for a label.
ClickHouse's `log_comment` is inert but is a setting, which a `readonly = 1` user
cannot send at all, and the query comment already lands in `system.query_log`.

### Your own labels

Add ownership labels with `attribution:` on a source. They apply to every
query against it:

```yaml {contract=project-config}
# dbt_charts.yml
sources:
  warehouse:
    type: bigquery
    project: my-gcp-project
    dataset: analytics
    attribution:
      team: architecture-analytics
      cost_center: data-platform
```

Keys and values must match BigQuery's label rules: keys `[a-z][a-z0-9_-]{0,62}`,
values `[a-z0-9_-]{0,63}`, on every warehouse, so the same source config behaves
identically everywhere. A value that doesn't match is an error, not a silently
rewritten label. The `dbt_charts_` prefix and the `app` key are reserved for the engine.

`env_var()` works here like anywhere else in a source:


```yaml {contract=project-config}
# dbt_charts.yml
sources:
  warehouse:
    type: bigquery
    project: my-gcp-project
    dataset: analytics
    attribution:
      env: "{{ env_var('DCT_ENV', 'dev') }}"
```


To find your dbt Charts spend on BigQuery:

```sql
SELECT creation_time, total_bytes_billed, user_email
FROM `region-us`.INFORMATION_SCHEMA.JOBS
WHERE creation_date = CURRENT_DATE()
  AND EXISTS (SELECT 1 FROM UNNEST(labels) l WHERE l.key = 'app' AND l.value = 'dbt-charts')
```

This works whether the query ran under a service account or an individual
developer's credentials.

## Environment Variables

Use `env_var()` in source configuration to keep credentials out of YAML files:


```yaml {contract=project-config}
# dbt_charts.yml
sources:
  analytics:
    type: postgres
    host: "{{ env_var('DB_HOST', 'localhost') }}"
    user: "{{ env_var('DB_USER') }}"
    password: "{{ env_var('DB_PASSWORD') }}"
```


Store credentials in `.env` or your deployment environment:

```bash
DB_HOST=localhost
DB_USER=analytics_user
DB_PASSWORD=secret123
```

!!! warning "Keep credentials out of boards"
    `env_var()` is for source configuration. Do not put secrets in board YAML,
    query text, or rendered output.

## Read-only Posture

dbt Charts boards read data. They never intentionally write to your warehouse,
but connection-level enforcement depends on the source type.

DuckDB and SQLite are opened with driver-level read-only settings. Every other
warehouse should use credentials that can only read data. dbt Charts also applies
an in-process SQL allowlist before execution, but SELECT-only credentials are
the warehouse-side defense.

| Warehouse | In-process enforcement | Recommended operator posture |
|---|---|---|
| DuckDB | Driver read-only mode | Handled by dbt Charts |
| SQLite | Driver read-only URI mode | Handled by dbt Charts |
| Postgres | SQL allowlist only | SELECT-only role |
| Snowflake | SQL allowlist only | SELECT-only role |
| BigQuery | SQL allowlist only | `roles/bigquery.dataViewer` or equivalent |
| Redshift | SQL allowlist only | SELECT-only IAM role or database user |
| Lake compute | SQL allowlist only | SELECT-only token or credential |
| dbt profile sources | Depends on adapter | SELECT-only profile credential |

### File access from SQL

`dct serve` runs strictly read-only: author SQL cannot reach the filesystem or
network through DuckDB, so functions like `read_csv(...)`, `read_json_auto(...)`,
`read_parquet(...)`, and `httpfs` are not available in query SQL. Point data at a
file source instead; declare it with `type: csv`, `type: json`, or `type: parquet`
and a `files:` mapping (see [Files and APIs](#files-and-apis)), then query the table
by name. dbt Charts parses the file and loads it for querying without granting SQL
any file access.

## Related

- [Queries](../queries.md) for the SQL, values, HTTP, and schema query types (dbt models are queried as plain SQL via `ref()`, not a separate query type)
- [Quick Guide](../quick-guide.md) for the shortest syntax overview

# Overview (https://docs.dbtcharts.com/charts/)

# Charts

Charts visualize your query data. Each chart references a query and defines how to display it.

**Vega-Lite foundation**: Charts render through Vega-Lite, but authored chart YAML is a typed dbt Charts surface. Use top-level dbt Charts fields (`x`, `y`, `color`, `lookup`, `value`, etc.) and the typed `style` object exclusively. Arbitrary Vega-Lite `spec`, `mark`, `encoding`, `config`, `transform`, `params`, and composition (`hconcat`/`vconcat`/`concat`/`repeat`/`resolve`) blocks are rejected on the authored surface.

A chart's **control surface** is the full set of authored **properties** available on a single chart. In dbt Charts, that surface is primarily top-level chart fields plus the typed `style` object.

---

## Basic Chart Structure

```yaml {contract=board-fragment}
charts:
  revenue_chart:
    title: "Revenue by Month"
    query: queries.sales          # References a query name
    type: bar                     # Chart type
    x: month                      # X-axis dimension
    y: total_revenue              # Y-axis metric
```

Here's a working example:

```dbt-charts-example
source: examples_db
charts:
  revenue_chart:
    query:
      sql: |
        SELECT product, category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY product, category ORDER BY revenue DESC
    type: bar
    title: Revenue by Product
    x: product
    y: revenue
rows:
  - revenue_chart
```

---

## Common Chart Types

| Type | Best For |
|------|----------|
| `line` | Time series trends |
| `bar` | Comparisons across categories |
| `area` | Stacked trends over time |
| `scatter` | Relationships between metrics |
| `pie` / `donut` | Part-to-whole comparisons |
| `heatmap` | Two-dimensional patterns |
| `histogram` | Distributions |
| `table` | Detailed data view |
| `kpi` | Single metric display |
| `callout` | Status or warning message card |
| `map` | Geographic region maps |
| `point_map` | Location markers |
| `bubble_map` | Sized location markers |

Every built-in type, the shapes that compose from them, and what to do when a shape is missing: [Chart types and extensibility](extensibility.md).

**See also:** [Bar Charts](bar-charts.md) • [Line Graphs](line-graphs.md) • [Sector Charts](sector-charts.md) • [Point Charts](point-charts.md) • [Area Charts](area-charts.md) • [Layered Charts](layered-charts.md) • [Maps](maps.md) • [Tables and Text](tables.md)

---

## Field Reference

```yaml {contract=unverified}
charts:
  <chart_id>:              # Unique identifier (must be unique within a file and across all imported files)
    title: string          # Optional
    query: string          # Required
    type: string           # Required (bar, line, area, etc.)

    # Channel fields
    x: string              # Dimension for x-axis
    y: string | [string]   # Metric(s) for y-axis
    color: string          # Field to encode as color
    size: string           # Field to encode as size
    shape: string          # Field to encode as shape

    # KPI-specific
    value: string          # KPI value binding or map fill field (column reference)
    label: string         # KPI label above the value

    # Map-specific
    geo_source: string     # Built-in geographic data source
    lookup: string         # Query field to join to geography
    latitude: string       # Point/bubble map latitude field
    longitude: string      # Point/bubble map longitude field

    # Data and links
    sort:
      by: string
      order: asc | desc
    link: string           # URL template for drill-down links ({{ x }}, {{ y }}, etc.)

    # Chart-specific presentation
    style:
      color:
        categorical:
          palette: string                # Named categorical palette
      background: string                 # Chart SVG background fill
      legend:
        visible: boolean                 # false to hide legend
      axis:
        grid:
          visible: boolean               # false to hide grid lines
      orientation: horizontal | vertical  # Bar chart orientation
      stack: none | zero | normalize | center  # Stack mode
      columns:
        column_name: {}                   # Table column config (mapping key = column name)
      # Axis, scale, legend, mark, and other style sections...

    notes: string    # AI search/context metadata; never rendered
```

Row limiting belongs on the query (`queries.<id>.limit`), not on the chart.

---

## Chart Sizing

Three fields control a chart's preferred geometry. `height` and `width` live at **chart root**, directly under `charts.<name>:`; `aspect_ratio` is a style field, under the chart's `style:`.

```yaml {contract=board-fragment}
charts:
  revenue_trend:
    query: revenue
    type: bar
    x: month
    y: total
    height: 400          # exact pixel height; wins over aspect_ratio and theme

  wide_chart:
    query: revenue
    type: line
    x: month
    y: total
    width: 800           # preferred dashboard width; the layout may allocate less
    style:
      aspect_ratio: 3.0  # wider than default; height = width / 3.0
```

- **`height`**: fixes the pixel height exactly. Bypasses `min_height`/`max_height` clamps. Not supported on `kpi`, `table`, `callout`, or `spark_bar`.
- **`width`**: pins the chart's slot in a `rows:` layout (a fixed footprint, capped at the row). In `cols:` and `grid:` layouts it requests an intrinsic width for dashboard measurement on boards with no width of their own; the layout still owns the final slot allocation.
- **`style.aspect_ratio`**: controls shape without pinning a size. The theme default is `1.5` (3:2 landscape). Not supported on the same chart types as `height`. The theme-level form `style.charts.kpi.aspect_ratio` is also rejected; the per-type theme override is unsupported on `kpi`, `table`, `callout`, and `spark_bar`.

The dashboard combines preferred widths recursively: rows and tabs use the widest child, while columns add child widths and gaps. A `style.frame.width` is the board's exact width wherever it is authored; without one, `style.frame.max_width` is the maximum the content hug can grow to. Layout rules still own the final chart allocation.

See [Board Sizing](../boards/sizing.md) for the full three-layer model (layout tile → chart root → theme default) and guidance on when to use each layer.

---

## Chart Styling

Customize chart appearance:

```yaml {contract=board-fragment}
charts:
  styled_chart:
    query: sales
    type: bar
    x: month
    y: total_revenue
    style:
      color:
        categorical:
          palette: editorial-10   # Color palette
      legend:
        visible: true             # Show legend (default)
      axis:
        grid:
          visible: true            # Show grid lines
      background: "#f8fafc"       # Chart background fill
```

**Style options:**
- `color.categorical.palette`: Color palette name (for example, `editorial-10`, `vivid-10`, `dbt-seq-blue`; see the [Palettes guide](../guides/palettes.md))
- `legend.visible`: `false` to hide the legend
- `axis.grid.visible`: `false` to hide grid lines
- `background`: SVG/CSS-compatible background fill applied behind the chart

See [Themes](../themes.md) for the built-in themes, and [Styling](../styling.md)
for color palettes.

### Value Labels

Bar, line, and scatter charts can show the numeric value on each mark. Enable per-chart via the family marks path:

```yaml {contract=unverified}
style:
  bar:           # or line: / scatter:
    marks:
      bar:       # or line: / point:
        labels:
          visible: true     # show value above each bar
          position: top     # above | top | middle | middle_aligned | bottom (bar); top | bottom | left | right | middle (line/point)
```

`format` defaults to `null` (inherits from `axis_y` format). Set a d3-format string to override. See per-chart docs for the full field list: [Bar Charts](bar-charts.md#value-labels) · [Line Graphs](line-graphs.md#value-labels) · [Point Charts](point-charts.md#value-labels).

---

## Best Practices

### Choosing Chart Types
- **Time series**: Use `line` or `area`
- **Comparisons**: Use `bar`
- **Relationships**: Use `scatter`
- **Single numbers**: Use `kpi`
- **Detailed data**: Use `table`

### Effective Color Encoding
- Use `color` to distinguish categories
- Choose accessible palettes (colorblind-friendly)
- Limit distinct colors (5-7 max)

### Filtering
- Use variables with dropdowns for cross-chart filtering
- Tooltips appear automatically on hover

See [Interactions](interactions.md) for hover tooltips and `link:` drill-down links.

---

## Previewing Charts

Preview your charts interactively:

```bash
dct serve
```

`dct serve` auto-discovers the project and prints the URL on startup. See [CLI Reference](../cli/serve.md).

### Validate First

```bash
dct validate charts/sales.yml
```

---

## Related

- [Bar Charts](bar-charts.md) - Comparison-first charts and columns
- [Line Graphs](line-graphs.md) - Line-graph style, examples, Vega-Lite mapping, and gaps
- [Sector Charts](sector-charts.md) - Pie, donut, and related arc-based charts
- [Point Charts](point-charts.md) - Dot plots, scatterplots, and other point-based charts
- [Area Charts](area-charts.md) - Filled trend and composition charts
- [Layered Charts](layered-charts.md) - Combo charts and dual-axis charts
- [Maps](maps.md) - Geographic charts and projection-aware mapping
- [Tables and Text](tables.md) - Exact-value tables, KPIs, and other data-powered text outputs
- [Interactions](interactions.md) - Hover tooltips and `link:` drill-down links
- [Queries](../queries.md) - Data sources for charts
- [Boards](../boards/index.md) - Organizing charts in dashboards
- [Variables](../variables/index.md) - Variables in query filters and inputs
- [Themes](../themes.md) - The built-in themes and how to write your own
- [Styling](../styling.md) - Color palettes and the rest of the style surface

# Bar Charts (https://docs.dbtcharts.com/charts/bar-charts/)

# Bar Charts

Bar charts encode values as lengths measured from a common baseline, which makes them one of the most fundamental tools for comparison; this family includes horizontal bar charts and vertical column charts. Horizontal bars are especially good for ranking categories with long labels, while vertical columns are especially good for showing change over simple time steps.

dbt Charts bar charts use a small set of top-level shorthand fields together with `style`. By default, `style.orientation` is `auto`: dbt Charts picks `horizontal` for **categorical x** (nominal/string labels) and `vertical` for **continuous x** (temporal, quantitative, date-like ordinal, or time-unit bucketed). The rule is type-driven, not viewport-driven: orientation reflects what the data *is*, not how wide the chart happens to be. Set `style.orientation: vertical` or `style.orientation: horizontal` to lock in a specific orientation. See [Axis Labels: Smart Layout](./axis-labels.md) for how the engine picks orientation and label tilt automatically when `style.orientation` is left at its default.

A chart's **control surface** is the full set of authored **properties** available on a single chart. In dbt Charts, that surface is primarily top-level chart fields plus a typed `style` object.

This page is intentionally family-oriented rather than exhaustive. For the implementation-backed source of truth, including default ownership and lower-level property coverage, see the [YAML Schema Reference](../reference/yaml-reference.md).

---

## Minimum Required for a Bar Chart

These are the minimum fields required to render a basic bar chart in dbt Charts. With a nominal x-axis (category strings), the default result is a horizontal bar chart; with a continuous x-axis (temporal, quantitative, or date-like ordinal), the default is a vertical column chart. See [Axis, Scale, and Orientation](#axis-scale-and-orientation) for the rule, or set `style.orientation` explicitly to override.

| dbt Charts field | Maps to Vega-Lite | Allowed values | Notes |
|---|---|---|---|
| `query` | `data.values` | Query name or query reference | Supplies the dataset. |
| `type: bar` | `mark.type: "bar"` | Literal `bar` | Selects the bar mark. |
| `x` | `encoding.x.field` | Field name | Category, discrete field, or temporal field. |
| `y` | `encoding.y.field` | Field name | Numeric measure to compare. |

### Minimum Example

```dbt-charts-example
source: examples_db
charts:
  product_revenue_columns:
    query:
      sql: |
        SELECT product, category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY product, category ORDER BY revenue DESC
    type: bar
    title: Revenue by Product
    x: product
    y: revenue
rows:
  - product_revenue_columns
```

---

## Top-Level Chart Fields

These are the top-level chart properties you set directly on a bar chart before you get into nested properties under `style`.

| dbt Charts field | Maps to Vega-Lite | Allowed values | Notes |
|---|---|---|---|
| `query` | `data.values` | Query name or query reference | Query results become the plotted dataset. Use pre-aggregated data with one row per plotted key. |
| `type: bar` | `mark.type: "bar"` | Literal `bar` | Standard bar or column chart. |
| `x` | `encoding.x.field` | Field name | Usually the category field, or a temporal field for time-unit column charts. |
| `y` | `encoding.y.field` | Field name or list of field names | Usually the numeric measure, even when the final chart is horizontal. A list creates layered multi-metric bars. |
| `title` | `title.text` | String | Chart title. |
| `notes` | metadata | String | AI search/context metadata. Never rendered. |
| `color` | `encoding.color.field` | Field name | Adds series grouping or composition. |
| `x_label` | `encoding.x.title` | String | Custom x-axis title. |
| `y_label` | `encoding.y.title` | String | Custom y-axis title. |
| `field_labels` | legend, tooltip and axis titles | Map of column to text | Display text for a column, painted as written. See [Field Labels](line-graphs.md#field-labels). |
| `format` | quantitative value-axis format | Format string | Numeric formatting for the value axis. In horizontal bars, that value axis is rendered on `x`. |
| `sort` | categorical axis sort | Sort object | Most useful for ranked bar charts. |

### Vertical Columns and Horizontal Bars

This example shows the family's two main forms side-by-side: a vertical bar chart (also called a column chart), and the same data rendered horizontally. Both pin `style.orientation` explicitly so the contrast is what's on the page; left at `auto`, this nominal x would render horizontal by default.

```dbt-charts-example
source: examples_db
queries:
  sales_by_product:
    sql: |
      SELECT product, category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY product, category ORDER BY revenue DESC
charts:
  product_revenue_columns:
    query: sales_by_product
    type: bar
    title: Revenue by Product
    x: product
    y: revenue
    style:
      orientation: vertical

  product_revenue_bars:
    query: sales_by_product
    type: bar
    title: Revenue by Product
    x: product
    y: revenue
    style:
      orientation: horizontal
rows:
  - product_revenue_columns
  - product_revenue_bars
```

### Labels and Ranking

This example keeps the chart definition compact while showing the top-level fields most readers use in practice: labels, formatting, and sorting.

```dbt-charts-example
source: examples_db
charts:
  ranked_products:
    query:
      sql: |
        SELECT product, category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY product, category ORDER BY revenue DESC
    type: bar
    title: Top Products by Revenue
    notes: A sorted product ranking shown as horizontal bars.
    x: product
    y: revenue
    x_label: Product
    y_label: Revenue
    sort:
      by: revenue
      order: desc
    style:
      orientation: horizontal
      axis_y:
        labels:
          format: currency_whole
rows:
  - ranked_products
```

### What `sort:` Does When a Category Holds Several Rows

`sort:` orders categories, and a category with a `color` series or a `y: [...]` list holds more than one row, so the sort column is folded to a single value per category before the categories can be ranked. Two rules cover it:

- **A stacked bar sorted by its own measure ranks by the stacked total.** That is the only reading of a `sort:` naming `revenue` on a `stack: zero` chart whose `y` is `revenue`: the bar's length *is* the total. A `y: [...]` list does not qualify, since no single column is the measure there.
- **Every other sort ranks by the column's own value.** A sort by an ordering key (`release_seq`, `stage_rank`) ranks by that key whatever the row count; a category holding one series does not sort ahead of a category holding three. The same holds for a **grouped** bar sorted by its measure: the fold follows whether the chart stacks, not how the bars are drawn, so with `stack: none` the categories rank by each one's smallest series rather than by the group's total. Sort by a pre-summed column in the query when you want the group total.

`sort.by` must name a column on every row of the query result; a missing column fails with [`ERR-SORT-FIELD-NOT-FOUND`](../reference/errors.md#err-sort-field-not-found) rather than rendering in natural order.

The rule is the same in both orientations, and the key column does not need to be a measure: a text or date column is an ordering too. On a multi-series bar it does cost the endpoint-label rail, which steps aside to a legend for a non-numeric `sort:` (see [When a bar falls back to a legend instead](#when-a-bar-falls-back-to-a-legend-instead)).

### Layered Multi-Metric Bars

When `y` is a list, dbt Charts creates a layered bar chart. This is most useful when the metrics share a similar scale and the comparison is more important than stacking.

```dbt-charts-example
queries:
  product_metrics:
    columns: [product, revenue, profit]
    values:
      - ["Gadget X", 18350, 4200]
      - ["Gadget Y", 30490, 7600]
      - ["Tool Z", 34900, 9100]
      - ["Widget A", 66300, 18500]
      - ["Widget B", 85680, 24100]

charts:
  layered_product_metrics:
    query: product_metrics
    type: bar
    title: Revenue and Profit by Product
    x: product
    y: [revenue, profit]
rows:
  - layered_product_metrics
```

---

## Style Fields

Use `style` for dbt Charts shorthand properties that affect presentational defaults such as legend visibility and grid lines.

| dbt Charts field | Maps to Vega-Lite | Allowed values | Notes |
|---|---|---|---|
| `style.legend.visible` | `encoding.color.legend` | `true` or `false` | Typed legend control. `false` hides the legend. |
| `style.axis.grid.visible` | axis grid visibility | `true` or `false` | `false` hides grid lines. Use `style.axis.grid.visible: false` (nested under `grid:`). |
| `style.background` | chart SVG background wrapper | Color value | Applies a chart-level background fill behind the rendered SVG. |

### Legend and Grid Lines

This example shows the small style surface for bar charts without changing the underlying data bindings.

```dbt-charts-example
source: examples_db
charts:
  category_columns_styled:
    query:
      sql: |
        SELECT category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY category ORDER BY revenue DESC
    type: bar
    title: Revenue by Category
    x: category
    y: revenue
    color: category
    style:
      stack: zero
      legend:
        visible: false
      axis:
        grid:
          visible: false
rows:
  - category_columns_styled
```

---

## Axis, Scale, and Orientation

All presentation config lives under `style`. This is where the family distinguishes default vertical columns from horizontal bars.

| dbt Charts field | Maps to Vega-Lite | Allowed values | Notes |
|---|---|---|---|
| `style.orientation` | bar orientation transform | `auto` (default), `vertical`, or `horizontal` | `auto` picks `horizontal` for categorical x, `vertical` for continuous x (temporal/quantitative/date-like ordinal); `vertical` and `horizontal` lock the orientation. |
| `style.axis_x` | `config.axisX` / `encoding.x.axis` | `AxisStyle` object | Per-axis styling (format, ticks, labels, grid, title). |
| `style.axis_y` | `config.axisY` / `encoding.y.axis` | `AxisStyle` object | Per-axis styling. |
| `style.axis_y.scale` | `config.axisY.scale` | `ScaleStyle` object | Y-axis scale config (zero, nice, domain, clamp). Use `axis_x.scale` for categorical band padding. |
| `style.stack` | `encoding.y.stack` | `"none"`, `"zero"`, `"normalize"`, `"center"` | Stacking behavior. Omit `stack` when a `color` field is present to get the default side-by-side grouped layout. Set `"none"` for grouped (side-by-side), `"zero"` for stacked-from-baseline, `"normalize"` for 100% stacked, `"center"` for diverging stacks. (Within-group spacing of grouped bars is controlled by `style.overlap`, not `stack`.) |
| `style.stack_order` | `encoding.order` | `"value"` (default), `"data"`, `"alphabetical"` | Z-order of stacked segments. `"value"` puts the largest aggregate at the baseline. `"data"` stacks series in first-appearance order: SQL row order for `color`, the listed order for `y: [a, b, ...]` (a measure null in the first rows appears later). `"alphabetical"` sorts by series name. Ignored when stacking is off or there is only one series. |
| `style.overlap` | bar `xOffset`/`yOffset` spacing | `"auto"` (default), `"none"`, `"flush"`, `"partial"`, `"full"`, or a number | Within-group spacing for grouped bars (a `color` field, not stacked). `"auto"` adapts to the series count: `partial` (25% overlap) at 2 series, `none` (small gap) at 3+. `"none"` gaps, `"flush"` touches, `"partial"` overlaps 25%, `"full"` coincides when each category holds one color (as in a waterfall) and is an error otherwise. A number is a fraction of bar width: `>0` overlaps, `0` touches, `<0` gaps. **Positive overlap is only valid for 2 series**: overlapping 3+ series buries the middle one, so it raises an error (use `none`/`flush` for 3+, or rely on `auto`). Setting any overlap with an active stack mode (`"zero"`/`"normalize"`/`"center"`) is also an error. |
| `style.grouped.padding_inner`, `style.grouped.padding_outer` | band scale `paddingInner`/`paddingOuter` | `float` (`0`–`1`) | Grouped bars only. Gap between groups and margin at both plot edges, as a share of the band step. Default `0.2` each. |
| `style.marks.bar.band_width` | `mark.width.band` | `float` (fraction of the band, `0`–`1`) | Fraction of the available band each bar fills. Lower it to thin bars out and open up whitespace between categories without changing `overlap`, which only governs spacing *within* a grouped-color band. |

| `style.marks.bar.max_size` | `mark.width` | `float` (pixels) | The thickest a bar may be. Caps a band-scale bar's `band_width` fraction on wide charts and a continuous scale's computed width; unset, category bars stay uncapped and a continuous scale caps at 20. An authored `size` wins over it. |

### Bar Width

This example thins the bars to 40% of their band, leaving visible whitespace between categories.

```dbt-charts-example
source: examples_db
charts:
  product_revenue_thin:
    query:
      sql: |
        SELECT product, SUM(revenue) AS revenue FROM ecommerce_orders GROUP BY product ORDER BY revenue DESC
    type: bar
    title: Product Revenue
    x: product
    y: revenue
    style:
      marks:
        bar:
          band_width: 0.4
rows:
  - product_revenue_thin
```

### Orientation and Axis Controls

This example uses `style` to turn a column chart into a horizontal ranking chart while also adjusting axis formatting and label space.

```dbt-charts-example
source: examples_db
charts:
  product_revenue_ranked:
    query:
      sql: |
        SELECT product, category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY product, category ORDER BY revenue DESC
    type: bar
    title: Product Revenue Ranking
    x: product
    y: revenue
    sort:
      by: revenue
      order: desc
    style:
      orientation: horizontal
      axis_x:
        labels:
          max_width: 140
      axis_y:
        scale:
          nice: true
        labels:
          format: currency_whole
rows:
  - product_revenue_ranked
```

---

## Endpoint Labels and the Top-Row Series Rail

A multi-series bar names its series **on the chart**, anchored to each segment, rather than in a side legend. This is the default on every built-in theme; you don't switch it on. Multi-series bars come from either a `color` channel or a `y: [field_a, field_b]` list; both layouts render the endpoint rail. Where the labels go depends on the orientation:

- **Vertical stacked column charts** get one label per segment in a side pane, anchored to each segment's vertical midpoint in the last column that series appears in (the rightmost, for a series that runs the full width). The chart pane and label pane sit side-by-side in an `hconcat`.
- **Horizontal stacked bar charts** get a single rail of labels above the top row of the chart: one label per series, centered horizontally on its segment's midpoint within the top categorical row. The chart pane and rail sit stacked in a `vconcat`. The bottom row's value axis still carries the numeric measure labels.

The asymmetry follows from the reading direction: vertical stacks read top-to-bottom along the measure axis, so per-segment side labels feel natural; horizontal stacks read left-to-right inside one row, so a single label rail above the top row is the direct equivalent.

| dbt Charts field | Allowed values | Notes |
|---|---|---|
| `style.endpoint_labels.visible` | `true` or `false` | Defaults to `true` on every built-in theme. Set `false` per-chart to send the series names back to a legend; set `true` to force the rail onto a shape it steps aside from (below). |

When the label pane or rail is on, the categorical legend turns off automatically: the two would encode the same series→color mapping twice. On the vertical layout, the y-axis also auto-flips to the **left** so it doesn't collide with the right-edge label pane.

On narrow cards, vertical endpoint-label text compacts to fit the available width while its automatic vertical spacing stays readable for closely ending series.

The horizontal rail has no per-label collision resolver: it measures the real, rendered position and width of every label (the actual font, at the actual pixel scale the chart draws at), and if any two adjacent labels would touch, the whole chart falls back to a legend instead of drawing a rail with overlapping text. See "When a bar falls back to a legend instead" below.

### When a bar falls back to a legend instead

The rail has to be able to name *every* series, or it names some of them and quietly misleads. An authored `sort:` is fine when it sorts by a measure: each rail anchors on the *rendered* domain, so it follows the sort rather than refusing it. Sorting by a non-numeric column is the exception: the rail places its labels from the order the sorted axis draws, dbt Charts confirms that order only for a numeric sort column, and labels placed from the wrong order name series in the wrong place, so the chart takes a legend instead. Where it can't, the chart keeps its legend, placed above the plot, untitled, reading in the same order as the bars. A bar steps aside from direct labeling when:

- **It's grouped**: explicit `stack: none`, or the grouped-by-default when `stack` is omitted and a `color` field is present. Every series' last bar rises from the same baseline to a similar height, so the labels collide into one another.
- **It has no `color` encoding and no `y: [...]` list**: a single series has nothing to name. (`y: [...]` and a `color:` column compose: one series per column value per measure, named `<value> - <measure>`; see [Multiple Measures by a Dimension](./line-graphs.md#multiple-measures-by-a-dimension). `layers:` still cannot combine with `y: [...]`.)
- **`color:` names the same field as `x:`**, or a series is missing from the column the rail anchors on (a trailing null, say). Either way some series would go unnamed.
- **It carries `multiples:`**: see [Small Multiples](./small-multiples.md).
- **The measure goes negative**: a stacked segment crossing zero has no meaningful cumulative midpoint to anchor to.
- **It's horizontal and `stack: center`**: that rail anchors on the cumulative `0..Σ` axis, which the diverging center-stack domain doesn't have.
- **It has `layers:`**: the rail walks the base chart's own series, so an overlay layer would be left anonymous.
- **It's horizontal and the rail's own labels would collide**: narrow segments, long series names, or too many series for the card width can make adjacent labels overlap. dbt Charts measures the real rendered text rather than guessing, and steps aside to a legend rather than ship a colliding rail.

Writing `style.endpoint_labels.visible: true` on the chart itself overrides all of these: an author who asks for the rail on one of these shapes gets it, or gets a rendering error naming the conflict where the shape genuinely can't carry it.

### Vertical Stacked Columns

```dbt-charts-example
source: examples_db
charts:
  region_revenue_by_category_vertical:
    query:
      sql: |
        SELECT region, category, SUM(revenue) AS revenue FROM ecommerce_orders GROUP BY region, category ORDER BY region, category
    type: bar
    title: Revenue by Region (vertical stack)
    x: region
    y: revenue
    color: category
    style:
      stack: zero
      orientation: vertical
      endpoint_labels:
        visible: true

rows:
  - region_revenue_by_category_vertical
```

### Horizontal Stacked Bars

```dbt-charts-example
source: examples_db
charts:
  region_revenue_by_category:
    query:
      sql: |
        SELECT region, category, SUM(revenue) AS revenue FROM ecommerce_orders GROUP BY region, category ORDER BY region, category
    type: bar
    title: Revenue by Region (stacked by Category)
    x: region
    y: revenue
    color: category
    style:
      stack: zero
      orientation: horizontal
      endpoint_labels:
        visible: true

rows:
  - region_revenue_by_category
```

---

## Value Labels

Show the numeric value above (or inside) each bar by enabling `style.marks.bar.labels.visible`.

```dbt-charts-example
source: examples_db
charts:
  product_revenue_labeled:
    query:
      sql: |
        SELECT product, SUM(revenue) AS revenue FROM ecommerce_orders GROUP BY product ORDER BY revenue DESC
    type: bar
    title: Product Revenue
    x: product
    y: revenue
    style:
      marks:
        bar:
          labels:
            visible: true
            position: top      # above | top | middle | middle_aligned | bottom
            format: ",.0f"     # omit to inherit axis_quantitative.format (the measure-axis format, for example, ".3~s")
            font:
              color: "#6b7280"
              size: 11
rows:
  - product_revenue_labeled
```

**Position values:**

| Value | Placement |
|-------|-----------|
| `above` | Outside, past the bar end |
| `top` | Just inside the bar's end, the theme default |
| `middle` | Centered in the bar |
| `middle_aligned` | Every label at one shared height, so a row of them reads as a line |
| `bottom` | Just inside the baseline end |

**On a stacked bar**, `middle` centers each label in its own segment rather than in the whole stack; use it when every segment carries a value. `above` has no room above an individual segment, so it renders as `top`. `middle_aligned` is not meaningful per-segment and raises an error; use `middle`.

On vertical bars, a label whose segment is too short to hold it is dropped rather than drawn across its neighbors, so a stack with one thin band shows the labels that fit and omits the one that does not.

To label plain bars inside their top but give a stack one total outside it, set `labels.stacked: false` and `total_label.visible: true`: stacked segments go unlabeled while `total_label` marks each stack, and plain bars keep their labels.

`dx`/`dy` (pixel offsets) are also available under `labels` to nudge a label off its default position. To enable labels for all bar charts at theme level, set `marks.bar.labels.visible: true` in your theme YAML.

---

## Overlays (`layers:`)

Add a `layers:` list to a bar chart to overlay additional marks, a line trend, a
scatter reference, or a second bar series on a separate y-axis. The base bar chart owns
the x-axis, frame, title, legend, and sort. Each layer adds its own mark and legend
entry.

```yaml {contract=board-fragment}
charts:
  revenue_vs_target:
    type: bar
    x: month
    y: revenue
    query: monthly
    layers:
      - type: line
        y: target
        label: Target
        axis_y:
          position: right
        style:
          marks:
            line:
              stroke:
                width: 2
```

A layer on its own axis gets an independent scale; see [Dual y-axis](layered-charts.md#dual-y-axis) for why dbt Charts warns about it and what to use instead.

Layer fields:

| Field | Description |
|-------|-------------|
| `type` | Mark type: `bar`, `line`, `area`, or `scatter` |
| `y` | Measure column for this layer |
| `label` | Legend label (defaults to the column name) |
| `color` | Data field for color encoding on this layer |
| `query` | Override the base query for this layer's data |
| `x` | X field for this layer (values extend the base x-scale) |
| `axis_y` | `{position: left|right}` plus per-side scale/format |
| `style` | Marks-only style patch, nested under the layer's mark family (for example, `marks.line.stroke.width`) |

`sort:` and x-axis chrome are base-only; layers inherit x ordering.

---

## Related

- [Charts Overview](index.md)
- [Line Graphs](line-graphs.md)
- [Layered Charts](layered-charts.md)
- [Sector Charts](sector-charts.md)

# Line Graphs (https://docs.dbtcharts.com/charts/line-graphs/)

# Line Graphs

Line graphs connect values across an ordered axis, usually time, to emphasize continuity, direction, rate of change, and overall shape; this family includes single- or multi-series lines and slope graphs. They are most useful when the main question is how something changes over time rather than how big isolated categories are.

dbt Charts line graphs use a small set of top-level shorthand fields together with `style`. In most cases, you only need `query`, `type: line`, `x`, and `y` to get started.

A chart's **control surface** is the full set of authored **properties** available on a single chart. In dbt Charts, that surface is primarily top-level chart fields plus typed `style` objects.

This page is intentionally family-oriented rather than exhaustive. For the implementation-backed source of truth, including default ownership and lower-level property coverage, see the [YAML Schema Reference](../reference/yaml-reference.md).

---

## Minimum Required for a Line Graph

These are the minimum fields required to render a basic line graph in dbt Charts.

| dbt Charts field | Maps to Vega-Lite | Allowed values | Notes |
|---|---|---|---|
| `query` | `data.values` | Query name or query reference | Supplies the dataset. |
| `type: line` | `mark.type: "line"` | Literal `line` | Selects the line mark. |
| `x` | `encoding.x.field` | Field name | Ordered dimension, usually time. |
| `y` | `encoding.y.field` | Field name | Numeric measure to plot. |

### Minimum Example

```dbt-charts-example
source: examples_db
charts:
  revenue_trend_minimal:
    query:
      sql: |
        SELECT date, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY date ORDER BY date
    type: line
    title: Daily Revenue
    x: date
    y: revenue
rows:
  - revenue_trend_minimal
```

---

## Top-Level Chart Fields

These are the top-level chart properties you set directly on a line graph before you get into nested properties under `style`.

| dbt Charts field | Maps to Vega-Lite | Allowed values | Notes |
|---|---|---|---|
| `query` | `data.values` | Query name or query reference | Query results become the plotted dataset. |
| `type: line` | `mark.type: "line"` | Literal `line` | Selects the line mark. |
| `x` | `encoding.x.field` | Field name | Usually a temporal or ordered field. |
| `y` | `encoding.y.field` | Field name or list of field names | A list creates layered multi-metric lines. |
| `title` | `title.text` | String | Chart title. |
| `notes` | metadata | String | AI search/context metadata. Never rendered. |
| `color` | `encoding.color.field` | Field name | Groups a line into multiple series. |
| `x_label` | `encoding.x.title` | String | Custom x-axis title. |
| `y_label` | `encoding.y.title` | String | Custom y-axis title. |
| `field_labels` | legend, tooltip and axis titles | Map of column to text | Display text for a column, painted as written. See [Field Labels](#field-labels). |
| `format` | `encoding.y.format` and `encoding.y.axis.format` | Format string | Numeric formatting for the y channel. |
| `sort` | categorical axis sort | Sort object | Most useful when the x-axis is categorical. |
| `projection` | top-level `projection` | Vega-Lite projection name | Available for Vega-Lite projection overrides. |

### Multi-Series Line Graph

This example adds `color` to split one line into multiple series while keeping the top-level chart definition compact.

```dbt-charts-example
source: examples_db
charts:
  revenue_by_product:
    query:
      sql: |
        SELECT DATE_TRUNC('week', date) AS week, product, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY week, product ORDER BY week, product
    type: line
    title: Revenue by Product
    x: week
    y: revenue
    color: product
rows:
  - revenue_by_product
```

### Axis Labels, Formatting, and Styling

This example shows common top-level chart fields such as labels and numeric formatting.

```dbt-charts-example
source: examples_db
charts:
  revenue_formatted:
    query:
      sql: |
        SELECT date, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY date ORDER BY date
    type: line
    title: Revenue Over Time
    x: date
    y: revenue
    x_label: Date
    y_label: Revenue
    style:
      axis_y:
        scale:
          continuous:
            zero: false
        labels:
          format: currency_whole
      axis:
        grid:
          visible: false
rows:
  - revenue_formatted
```

### Layered Multi-Metric Lines

When `y` is a list, dbt Charts creates a layered line graph. This is useful when you want to compare two measures that share the same ordered x-axis.

```dbt-charts-example
source: examples_db
charts:
  revenue_and_units:
    query:
      sql: |
        SELECT date, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY date ORDER BY date
    type: line
    title: Revenue And Units Sold
    x: date
    y: [revenue, units_sold]
rows:
  - revenue_and_units
```

A pivoted result (several measures grouped by a dimension) adds `color:` naming the dimension; see [Multiple Measures by a Dimension](#multiple-measures-by-a-dimension).

### Field Labels

Every surface that names a column (legend entries and titles, tooltip rows, axis titles) derives its text from the column name: `units_sold` becomes `units sold` (title-cased in legend titles). `field_labels` maps a column to the text to paint instead, written exactly as given. `x_label`/`y_label` and a layer's `label` still win on their own surface. A key that names no column of the chart's query is an error (checked when the query returns rows). Tables use `style.columns.<col>.label` instead.

```yaml {contract=board-root}
charts:
  revenue_and_units_labeled:
    query:
      sql: |
        SELECT date, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY date ORDER BY date
    type: line
    title: Revenue And Units Sold
    x: date
    y: [revenue, units_sold]
    field_labels:
      revenue: Revenue (USD)
      units_sold: Units shipped
rows:
  - revenue_and_units_labeled
```

---

## Style Fields

Use `style` for dbt Charts shorthand properties that affect presentational defaults such as legend visibility and grid lines.

| dbt Charts field | Maps to Vega-Lite | Allowed values | Notes |
|---|---|---|---|
| `style.legend.visible` | `encoding.color.legend` | `true` or `false` | Typed legend control. `false` hides the legend. |
| `style.axis.grid.visible` | axis grid visibility | `true` or `false` | `false` hides grid lines. Use `style.axis.grid.visible: false` (nested under `grid:`). |
| `style.background` | chart SVG background wrapper | Color value | Applies a chart-level background fill behind the rendered SVG. |

### Legend and Grid Lines

This example shows the small style surface for line graphs without changing the underlying data bindings.

```dbt-charts-example
source: examples_db
charts:
  revenue_formatted:
    query:
      sql: |
        SELECT date, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY date ORDER BY date
    type: line
    title: Revenue Over Time
    x: date
    y: revenue
    x_label: Date
    y_label: Revenue
    style:
      axis_y:
        scale:
          continuous:
            zero: false
        labels:
          format: currency_whole
      axis:
        grid:
          visible: false
rows:
  - revenue_formatted
```

---

## Axis and Scale Style

Use `style` for axis and scale properties that shape how the line graph is framed and read.

| dbt Charts field | Maps to Vega-Lite | Allowed values | Notes |
|---|---|---|---|
| `style.axis_x` | `config.axisX` / `encoding.x.axis` | `AxisStyle` object | Per-axis styling (format, ticks, labels, grid, title). |
| `style.axis_y` | `config.axisY` / `encoding.y.axis` | `AxisStyle` object | Per-axis styling. |
| `style.axis_y.scale` | `config.axisY.scale` | `ScaleStyle` object | Y-axis scale config (zero, nice, domain, clamp). |

### Axis and Scale Controls

This example uses `style` to control the y-axis scale and tick density.

```dbt-charts-example
source: examples_db
charts:
  revenue_formatted:
    query:
      sql: |
        SELECT date, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY date ORDER BY date
    type: line
    title: Revenue Over Time
    x: date
    y: revenue
    x_label: Date
    y_label: Revenue
    style:
      axis_y:
        scale:
          continuous:
            zero: false
        labels:
          format: currency_whole
      axis:
        grid:
          visible: false
rows:
  - revenue_formatted
```

### Log Scale

Set `style.axis_y.scale.continuous.type: log` to plot a quantitative axis on a logarithmic scale, useful when values span multiple orders of magnitude (for example, exponential growth). Log scales are undefined at zero and for negative numbers; dbt Charts validates the domain at compile time and raises `ERR_LOG_SCALE_REQUIRES_POSITIVE_DATA` if any data value is zero or negative. Only use `axis_y.scale.continuous.type: log` on a measure you know is strictly positive.

```dbt-charts-example
source: examples_db
charts:
  revenue_log:
    query:
      sql: |
        SELECT date, SUM(revenue) AS revenue FROM ecommerce_orders GROUP BY date ORDER BY date
    type: line
    title: Revenue Over Time (Log Scale)
    x: date
    y: revenue
    x_label: Date
    y_label: Revenue
    style:
      axis_y:
        scale:
          continuous:
            type: log
        labels:
          format: currency_whole
rows:
  - revenue_log
```

---

## Endpoint Labels

A multi-series line graph names its series **on the chart**, anchored to each line's final point, rather than in a side legend. This is the default on every built-in theme; you don't switch it on. Set `style.endpoint_labels.visible: false` to send the names back to a legend.

| dbt Charts field | Allowed values | Notes |
|---|---|---|
| `style.endpoint_labels.visible` | `true` or `false` | Defaults to `true` on every built-in theme. Set `false` per-chart to send the series names back to a legend. |

When the label pane is on, the categorical legend turns off automatically: the two would encode the same series→color mapping twice. The y-axis also auto-flips to the **left** so it doesn't collide with the right-edge label pane.

On narrow cards, endpoint-label text compacts to fit the available width while its automatic vertical spacing stays readable for closely ending series.

Endpoint labels require a multi-series chart: either a `color` channel or a `y: [field_a, field_b]` list. On single-series lines there is only one series to name, so the feature is a no-op.

`y: [...]` composes with a `color:` column: the measures are crossed with the column's values, one series per value per measure, each named `<value> - <measure>`; see [Multiple Measures by a Dimension](#multiple-measures-by-a-dimension). `layers:` still cannot combine with `y: [...]`; dbt Charts rejects that at compile time.

```dbt-charts-example
source: examples_db
charts:
  revenue_by_product:
    query:
      sql: |
        SELECT DATE_TRUNC('week', date) AS week, product, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY week, product ORDER BY week, product
    type: line
    title: Revenue by Product
    x: week
    y: revenue
    color: product
    style:
      endpoint_labels:
        visible: true

rows:
  - revenue_by_product
```

---

## Smoothing & Step Lines

`style.marks.line.curve` controls how adjacent points are joined, in place of
the default straight-segment interpolation:

| Value | Effect |
|---|---|
| `monotone` | A smooth curve that never overshoots the data; no wobble past a local min or max. A softer read than straight segments without misrepresenting the trend. |
| `step` | On a categorical (nominal/ordinal) x-axis, a full-band-width plateau per x-value instead of a diagonal segment. On a continuous (temporal/quantitative) x-axis, Vega-Lite's own native step interpolate (points at band centers). |

```dbt-charts-example
source: examples_db
charts:
  revenue_smoothed:
    query:
      sql: |
        SELECT date, SUM(revenue) AS revenue FROM ecommerce_orders GROUP BY date ORDER BY date
    type: line
    title: Daily Revenue (Smoothed)
    x: date
    y: revenue
    style:
      marks:
        line:
          curve: monotone
rows:
  - revenue_smoothed
```

### Step Lines

`curve: step` on a categorical x column draws a full-band-width plateau.
Adjacent plateaus are joined by a vertical bridge by default; set
`connect: false` to leave them as disconnected segments instead.

Disconnected plateaus end flush with the band edge; each one is its own path,
so the default round line cap would overhang every edge by half the stroke
width and close up the gap between neighboring bands. Set
`disconnected_cap: round` under `marks.line` to opt back into rounded ends.
`disconnected_width` under `marks.line` (default `0.9`) sets the share of the
band each plateau spans, so neighboring plateaus at a similar value stay
visually separate.
A `stroke.dasharray` on a disconnected step line is scaled per plateau so ink
lands on both edges: a whole number of dashes, separated by gaps, spans the
plateau. The rendered lengths therefore differ slightly from the authored
ones.
Connected step lines are unaffected: they are a single continuous path, so
`stroke.cap` still governs their two outer ends.

```dbt-charts-example
source: examples_db
charts:
  revenue_by_product_step:
    query:
      sql: |
        SELECT product, SUM(revenue) AS revenue FROM ecommerce_orders GROUP BY product ORDER BY revenue DESC
    type: line
    title: Product Revenue (Step)
    x: product
    y: revenue
    style:
      marks:
        line:
          curve: step
          connect: false
rows:
  - revenue_by_product_step
```

### Halo

Multi-series lines that cross each other can be hard to trace right at the
crossing point. `style.marks.line.halo_multiplier` draws a knockout-colored
stroke behind each line, sized relative to the line's own stroke width, so
crossings stay legible. Set it to `0` to disable the halo.

---

## Value Labels

Show the numeric value beside each data point on a line chart by enabling `style.marks.line.labels.visible`.

```dbt-charts-example
source: examples_db
charts:
  revenue_labeled:
    query:
      sql: |
        SELECT DATE_TRUNC('week', date) AS week, SUM(revenue) AS revenue FROM ecommerce_orders GROUP BY week ORDER BY week
    type: line
    title: Weekly Revenue
    x: week
    y: revenue
    style:
      marks:
        line:
          labels:
            visible: true
            position: top    # top | bottom | left | right | middle
            format: ",.1f"   # omit to inherit axis_quantitative.format
            font:
              color: "#6b7280"
              size: 11
rows:
  - revenue_labeled
```

**Position values:**

| Value | Placement |
|-------|-----------|
| `top` | Above the point, default |
| `bottom` | Below the point |
| `left` | To the left of the point |
| `right` | To the right of the point |
| `middle` | Centered on the point |

`dx`/`dy` (pixel offsets) are also available under `labels` to nudge a label off its default position. Line and point charts share the same position vocabulary and Vega-Lite mapping.

On a `curve: step` line over a categorical x, the mark is a plateau spanning the whole
band rather than a point, so `left` and `right` resolve against the band's leading and
trailing edge instead of the datum at its center, otherwise the caption would land on
top of the mark it is meant to sit beside. This tracks the real band width, so no `dx`
is needed to clear the mark at any board width or category count. Where the band is the
first or last in the domain and the preferred side has no room, that one label falls
back to `top`, keeping it inside its own band rather than over its neighbor's.
`top`, `bottom` and `middle` are unaffected: band width is horizontal, and the band's
center is the mark's center.

---

## Overlays (`layers:`)

Add a `layers:` list to a line chart to overlay additional marks: a bar for context, a
scatter reference, or a second line on a separate y-axis. The base line chart owns the
x-axis, frame, title, legend, and sort. Each layer contributes its own mark and legend
entry.

```yaml {contract=board-fragment}
charts:
  trend_with_target:
    type: line
    x: month
    y: actual
    query: monthly
    layers:
      - type: line
        y: target
        label: Target
        axis_y:
          position: right
          title: Target
        style:
          marks:
            line:
              stroke:
                width: 2
                dasharray: "4 2"
```

A layer on its own axis gets an independent scale; see [Dual y-axis](layered-charts.md#dual-y-axis) for why dbt Charts warns about it and what to use instead.

For a dual-axis example where the overlay draws from a separate query:

```yaml {contract=board-root}
queries:
  monthly_signups:
    columns: [month, signups]
    values:
      - ["2024-01", 480]
      - ["2024-02", 560]
  weekly_conversion:
    columns: [month, conversion_pct]
    values:
      - ["2024-01", 12.5]
      - ["2024-02", 14.2]
charts:
  signups_and_conversion:
    type: line
    x: month
    y: signups
    query: monthly_signups
    layers:
      - type: line
        y: conversion_pct
        label: Conversion (%)
        query: weekly_conversion
        axis_y:
          position: right
          title: Conversion (%)
          scale:
            domain: [0, 100]
```

Layer x-values from a separate query extend the base x-scale automatically; no `x_domain` field is needed or accepted.

Layer fields: `type`, `y`, `label`, `color`, `query`, `x`, `axis_y`, `style` (marks-only patch). `sort:` is base-only.

---

## Authored Surface

dbt Charts line charts are authored with `type: line` plus top-level channels such as `x`, `y`, and `color`. Arbitrary Vega-Lite `spec`, `mark`, `encoding`, `config`, `transform`, `params`, and composition blocks are rejected on the authored surface. Use top-level dbt Charts fields and the typed `style:` object.

---

## Multiple Measures by a Dimension

A pivoted result, several measures as columns grouped by a dimension, is the shape every semantic layer and most warehouse rollups produce. Add `color:` naming the dimension and each of its values is crossed with each measure: two measures by three categories draws six lines, each named `<category> - <measure>`. The legend, endpoint labels, and tooltip all read those composite names.

```dbt-charts-example
source: examples_db
charts:
  order_size_by_category:
    query:
      sql: |
        SELECT date, category, AVG(revenue) AS avg_order_value, MAX(revenue) AS largest_order FROM ecommerce_orders GROUP BY date, category ORDER BY date, category
    type: line
    title: Average And Largest Order by Category
    x: date
    y: [avg_order_value, largest_order]
    color: category
rows:
  - order_size_by_category
```

---

## Related

- [Charts Overview](index.md)
- [Layered Charts](layered-charts.md)
- [Sector Charts](sector-charts.md)

# Sector Charts (https://docs.dbtcharts.com/charts/sector-charts/)

# Sector Charts

Sector charts divide a whole into angular parts, making the total-and-parts relationship visually explicit; this family includes pie charts, donut charts, and polar-area charts. They are most useful when showing simple composition with a small number of categories, especially when the main message is share of a whole rather than precise comparison between similar values.

dbt Charts sector charts use a small set of top-level shorthand fields. In most cases, you only need `query`, `type: pie`, `theta`, and `color` to get started.

A chart's **control surface** is the full set of authored **properties** available on a single chart. In dbt Charts, that surface is primarily top-level chart fields plus the typed `style` object.

This page demonstrates every sector-specific authored capability with at least one runnable example. For the field-level source of truth (default ownership and the shared style properties every chart family inherits: palette, border, padding, font, tooltip) see the [YAML Schema Reference](../reference/yaml-reference.md).

---

## A Complete Sector Chart

The full package: a donut that reports a formatted grand total in the center and labels every slice with its category, share of the whole, and value. The rest of the page breaks these capabilities apart field by field.

```dbt-charts-example
source: examples_db
style:
  frame:
    width: 700
charts:
  revenue_share_hero:
    query:
      sql: |
        SELECT category, SUM(revenue) AS revenue FROM ecommerce_orders GROUP BY category ORDER BY revenue DESC
    type: donut
    title: Revenue by Category
    theta: revenue
    color: category
    total:
      label: Total Revenue
    style:
      total:
        value:
          format: "$,.0f"
      marks:
        slice:
          labels:
            template: "{{ '{:.0%}'.format(percent) }} {{ category }}\n{{ '${:,.0f}'.format(revenue) }}"
rows:
  - revenue_share_hero
```

---

## Minimum Required for a Sector Chart

These are the minimum fields required to render a basic sector chart in dbt Charts.

| dbt Charts field | Maps to Vega-Lite | Allowed values | Notes |
|---|---|---|---|
| `query` | `data.values` | Query name or query reference | Supplies the dataset. |
| `type: pie` | `mark.type: "arc"` | Literal `pie` | Selects the standard pie form. |
| `theta` | `encoding.theta.field` | Field name | Numeric field that sets wedge size. |
| `color` | `encoding.color.field` | Field name | Category field that splits the whole into slices. |

### Minimum Example

```dbt-charts-example
source: examples_db
style:
  frame:
    width: 700
charts:
  revenue_share_minimal:
    query:
      sql: |
        SELECT category, SUM(revenue) AS revenue FROM ecommerce_orders GROUP BY category ORDER BY revenue DESC
    type: pie
    title: Revenue Share by Category
    theta: revenue
    color: category
rows:
  - revenue_share_minimal
```

---

## Top-Level Chart Fields

These are the top-level chart properties you set directly on a sector chart before you get into nested properties under `style`.

| dbt Charts field | Maps to Vega-Lite | Allowed values | Notes |
|---|---|---|---|
| `query` | `data.values` | Query name or query reference | Query results become the plotted dataset. |
| `type` | `mark.type: "arc"` | `pie` or `donut` | `donut` is shorthand for a pie with an inner radius (see `style.inner_radius`). |
| `theta` | `encoding.theta.field` | Field name | Required wedge-size field. |
| `color` | `encoding.color.field` | Field name | Category field that splits the whole into slices. |
| `title` | `title.text` | String | Chart title. |
| `subtitle` | `title.subtitle` | String | Secondary line displayed under the title. |
| `notes` | metadata | String | AI search/context metadata. Never rendered. |
| `link` | drill-down URL | URL template string | Click-through target; `{{ column }}` tokens interpolate per slice. |
| `total` | center total slot | `{visible, label}` | Donut center total: the summed value with an optional caption. The number format is styled separately at `style.total.value.format`. |
| `labels` | per-slice text | `{template, where}` | Direct per-slice labels. `template` is a Jinja string over each row's columns plus the injected `percent`, `value`, `color`, and `total`; `where` is a Jinja expression that filters which slices are labeled. Omitting `labels` applies the default two-line template: `percent` and the slice name on the first line, `value` on the second. |
| `height` | chart viewport height | Positive number (pixels) | Explicit chart height. Overrides `style.aspect_ratio` and the theme cascade when set. |
| `width` | chart viewport width | Positive number (pixels) | Chart width. Pins the chart's slot in a `rows:` layout (capped at the row); in `cols:` and `grid:` it contributes to the dashboard's intrinsic width and the layout owns the final slot. |

### Title, Subtitle, and Drill-Down Link

`title` and `subtitle` render above the chart. `notes` and `link` are non-visual: `notes` feeds AI search and tooling (never rendered), and `link` turns each slice into a click-through (here into that category's page). (The center total and its formatting are shown in [A Complete Sector Chart](#a-complete-sector-chart) above.)

```dbt-charts-example
source: examples_db
style:
  frame:
    width: 700
charts:
  revenue_share_composition:
    query:
      sql: |
        SELECT category, SUM(revenue) AS revenue FROM ecommerce_orders GROUP BY category ORDER BY revenue DESC
    type: pie
    title: Product Mix
    subtitle: Fiscal year to date
    notes: Share of total revenue by product category.
    link: "/category/{{ category }}"
    theta: revenue
    color: category
    style:
      marks:
        slice:
          labels:
            template: "{{ category }}"
rows:
  - revenue_share_composition
```

### Slice Label Templates

Override the default template with `style.marks.slice.labels.template`. Following the default's convention, lead with `percent`. Three donuts on the same data: a compact percent-and-name line, a name over a currency-formatted value, and a `where`-filtered label that names only the largest slices.

```dbt-charts-example
source: examples_db
style:
  frame:
    width: 700
queries:
  by_category:
    sql: |
      SELECT category, SUM(revenue) AS revenue FROM ecommerce_orders GROUP BY category ORDER BY revenue DESC
charts:
  labels_compact:
    query: by_category
    type: donut
    title: Percent and Name
    theta: revenue
    color: category
    total:
      visible: false
    style:
      marks:
        slice:
          labels:
            template: "{{ '{:.0%}'.format(percent) }} {{ category }}"

  labels_currency:
    query: by_category
    type: donut
    title: Name and Value
    theta: revenue
    color: category
    total:
      visible: false
    style:
      marks:
        slice:
          labels:
            template: "{{ category }}\n{{ '${:,.0f}'.format(revenue) }}"

  labels_filtered:
    query: by_category
    type: donut
    title: Largest Slices Only
    theta: revenue
    color: category
    total:
      visible: false
    style:
      marks:
        slice:
          labels:
            template: "{{ category }}"
            where: "percent >= 0.3"
rows:
  - labels_compact
  - labels_currency
  - labels_filtered
```

---

## Style Fields

Use `style` for the sector-specific presentational surface: ring geometry, slice paint, and the center-total paint. Shared style properties every chart inherits (palette, border, padding, font, tooltip) live in the [YAML Schema Reference](../reference/yaml-reference.md).

| dbt Charts field | Maps to Vega-Lite | Allowed values | Notes |
|---|---|---|---|
| `style.inner_radius` | `mark.innerRadius` | `0`–`1` | Hole-to-disk ratio. `0` (or omitted) is a solid pie; `type: donut` defaults it to `0.6`. Set it explicitly for any other ring thickness. |
| `style.aspect_ratio` | viewport ratio | Positive number | Width ÷ height of the chart viewport. |
| `style.marks.slice` | arc mark paint | `{opacity, gap, corner_radius, stroke, labels}` | Per-slice mark paint and layout. |
| `style.legend.position` | legend or table placement | `{edge, align}` | Where the key sits: `edge` is `left`, `right`, `top` or `bottom`; `align` is `start`, `center` or `end` along that edge. Unset, the key sits right or below depending on width. A pie key never overlays the wheel. |
| `style.total` | center total paint | `{value, label}` | Typography of the donut center total's number (`value`, which also carries its `format`) and caption (`label`). |

### Ring Thickness

`style.inner_radius` sets any hole-to-disk ratio beyond the `donut` default of `0.6`. `0.3` is a thick ring; values near `1` are a thin band.

```dbt-charts-example
source: examples_db
style:
  frame:
    width: 700
charts:
  revenue_share_ring:
    query:
      sql: |
        SELECT category, SUM(revenue) AS revenue FROM ecommerce_orders GROUP BY category ORDER BY revenue DESC
    type: pie
    title: Thick Ring
    theta: revenue
    color: category
    total:
      visible: false
    style:
      inner_radius: 0.3
      marks:
        slice:
          labels:
            template: "{{ category }}"
rows:
  - revenue_share_ring
```

### Viewport

`style.aspect_ratio` reshapes the chart viewport: its width ÷ height. Above `1` is wider than tall.

```dbt-charts-example
source: examples_db
style:
  frame:
    width: 700
charts:
  revenue_share_viewport:
    query:
      sql: |
        SELECT category, SUM(revenue) AS revenue FROM ecommerce_orders GROUP BY category ORDER BY revenue DESC
    type: pie
    title: Wide Viewport
    theta: revenue
    color: category
    style:
      aspect_ratio: 1.6
      marks:
        slice:
          labels:
            template: "{{ category }}"
rows:
  - revenue_share_viewport
```

### Slice Paint

`style.marks.slice` paints the arcs: here noticeably rounded corners and a wide angular gap between slices.

```dbt-charts-example
source: examples_db
style:
  frame:
    width: 700
charts:
  revenue_share_slice_paint:
    query:
      sql: |
        SELECT category, SUM(revenue) AS revenue FROM ecommerce_orders GROUP BY category ORDER BY revenue DESC
    type: donut
    title: Rounded, Gapped Slices
    theta: revenue
    color: category
    total:
      visible: false
    style:
      marks:
        slice:
          corner_radius: 10
          gap: 0.05
          labels:
            template: "{{ category }}"
rows:
  - revenue_share_slice_paint
```

### Center-Total Styling

`style.total` styles the center-total typography. Here the total value is painted in a distinct accent color.

```dbt-charts-example
source: examples_db
style:
  frame:
    width: 700
charts:
  revenue_share_total_style:
    query:
      sql: |
        SELECT category, SUM(revenue) AS revenue FROM ecommerce_orders GROUP BY category ORDER BY revenue DESC
    type: donut
    title: Accented Total
    theta: revenue
    color: category
    total:
      label: Total
    style:
      total:
        value:
          format: "$,.0f"
          font:
            color: "#2563eb"
      marks:
        slice:
          labels:
            template: "{{ category }}"
rows:
  - revenue_share_total_style
```

---

## Slice Count and Density

How a sector chart labels itself is **automatic and data-and-width aware**; you do not author it. As slice count rises or the chart narrows, direct labels stop fitting, so the renderer switches presentation. Understanding the transitions is the difference between a chart that reads cleanly and one that collapses into unreadable callouts.

The rules, at a glance:

- Wedges under **8%** of the whole keep their slice and hover tooltip but drop their direct label: small slices don't get to crowd the disk.
- Once the number of labelable wedges exceeds what fits around the disk (about 4 at a typical width, fewer when narrow), the chart renders as a donut plus an **attached table** that carries slice identity, color, and value.
- Very narrow charts always use the attached table.

### Small Slices Drop Their Label

Four slices, one of them under 8%. The small wedge still renders (and its value is in the tooltip), but it gets no direct label rather than cluttering the disk.

```dbt-charts-example
source: examples_db
style:
  frame:
    width: 700
queries:
  long_tail:
    type: values
    columns: [segment, revenue]
    values:
      - ["Enterprise", 50]
      - ["Mid-Market", 30]
      - ["SMB", 15]
      - ["Trial", 5]
charts:
  small_slices:
    query: long_tail
    type: donut
    title: Small Slices Suppressed
    theta: revenue
    color: segment
    total:
      visible: false
    style:
      marks:
        slice:
          labels:
            template: "{{ segment }}"
rows:
  - small_slices
```

### High Cardinality Attaches a Table

Eight products is more than fits as direct callouts, so the chart renders the donut with an attached table instead, each row keyed by slice color, with the value alongside.

```dbt-charts-example
source: examples_db
style:
  frame:
    width: 700
charts:
  by_product:
    query:
      sql: |
        SELECT product, SUM(units_sold) AS units FROM ecommerce_orders GROUP BY product ORDER BY units DESC
    type: donut
    title: Units Sold by Product
    theta: units
    color: product
rows:
  - by_product
```

---

## Explicit Height and Width

`height` and `width` pin the chart's viewport in pixels, overriding `style.aspect_ratio` and the theme cascade. Use them when a sector chart needs a fixed footprint rather than one derived from the surrounding layout.

```dbt-charts-example
source: examples_db
style:
  frame:
    width: 400
charts:
  revenue_share_fixed_size:
    query:
      sql: |
        SELECT category, SUM(revenue) AS revenue FROM ecommerce_orders GROUP BY category ORDER BY revenue DESC
    type: pie
    title: Fixed 320x320 Viewport
    theta: revenue
    color: category
    height: 320
    width: 320
rows:
  - revenue_share_fixed_size
```

---

## Key Placement

`style.legend.position` places the key: the legend when one is shown (`style.legend.visible: true`), or the attached table when the chart attaches one. Here the legend sits left of the wheel and is centered down its height.

```dbt-charts-example
source: examples_db
style:
  frame:
    width: 900
charts:
  by_product_left:
    query:
      sql: |
        SELECT product, SUM(units_sold) AS units FROM ecommerce_orders GROUP BY product ORDER BY units DESC
    type: donut
    title: Legend Left, Centered
    theta: units
    color: product
    style:
      legend:
        visible: true
        position:
          edge: left
          align: center
rows:
  - by_product_left
```

---

## Field Labels

The legend title and tooltip rows derive their text from the column name. `field_labels` maps a column to the text to paint instead, written exactly as given; the donut's center total reads `Total <label>`. See [Field Labels](line-graphs.md#field-labels).

```dbt-charts-example
source: examples_db
charts:
  revenue_share_labeled:
    query:
      sql: |
        SELECT category, SUM(revenue) AS revenue FROM ecommerce_orders GROUP BY category ORDER BY revenue DESC
    type: donut
    title: Revenue Share
    theta: revenue
    color: category
    field_labels:
      revenue: Net revenue (USD)
      category: Product line
rows:
  - revenue_share_labeled
```

---

## Authored Surface

dbt Charts sector charts are authored with `type: pie` or `type: donut` plus top-level channels such as `theta` and `color`, the top-level `total`/`labels` fields, and the typed `style:` object. Arbitrary Vega-Lite `spec`, `mark`, `encoding`, `config`, `transform`, `params`, and composition blocks are rejected on the authored surface.

---

## Related

- [Charts Overview](index.md)
- [Line Graphs](line-graphs.md)
- [Maps](maps.md)

# Point Charts (https://docs.dbtcharts.com/charts/point-charts/)

# Point Charts

Point charts encode values primarily through the position of points, often on one or two common scales; this family includes dot plots, lollipop charts, scatterplots, beeswarm, and strip plots. They are especially useful when precision, comparison, distribution, or relationships matter, with dot plots and lollipops excelling at ranked comparisons and scatterplots excelling at showing association between two variables.

dbt Charts point charts currently map most directly to scatterplots and dot-plot-style charts. The canonical type is `type: scatter`: it uses Vega-Lite point marks under the hood and supports the familiar point-chart channels such as `color`, `size`, and `shape`.

A chart's **control surface** is the full set of authored **properties** available on a single chart. In dbt Charts, that surface is primarily top-level chart fields plus a typed `style` object.

This page is intentionally family-oriented rather than exhaustive. For the implementation-backed source of truth, including default ownership and lower-level property coverage, see the [YAML Schema Reference](../reference/yaml-reference.md).

---

## Minimum Required for a Point Chart

These are the minimum fields required to render a basic point chart in dbt Charts. In practice, that minimum usually means a scatterplot, so `type: scatter` is the most natural starting point.

| dbt Charts field | Maps to Vega-Lite | Allowed values | Notes |
|---|---|---|---|
| `query` | `data.values` | Query name or query reference | Supplies the dataset. |
| `type: scatter` | `mark.type: "point"` | Literal `scatter` | Recommended starting point for scatterplots and dot-plot-style point charts. |
| `x` | `encoding.x.field` | Field name | First position field. |
| `y` | `encoding.y.field` | Field name | Second position field. |

### Minimum Example

```dbt-charts-example
queries:
  campaign_efficiency:
    columns: [ad_spend, pipeline_value]
    values:
      - [18, 140]
      - [22, 165]
      - [26, 182]
      - [31, 205]
      - [34, 214]
      - [39, 246]

charts:
  spend_vs_pipeline:
    query: campaign_efficiency
    type: scatter
    title: Ad Spend vs Pipeline Value
    x: ad_spend
    y: pipeline_value
rows:
  - spend_vs_pipeline
```

---

## Top-Level Chart Fields

These are the top-level chart properties you set directly on a point chart before you get into nested properties under `style`.

| dbt Charts field | Maps to Vega-Lite | Allowed values | Notes |
|---|---|---|---|
| `query` | `data.values` | Query name or query reference | Query results become the plotted dataset. |
| `type: scatter` | `mark.type: "point"` | Literal `scatter` | Canonical point-chart type. |
| `x` | `encoding.x.field` | Field name | First position field. Often quantitative, but categorical x fields also support dot-plot-style charts. |
| `y` | `encoding.y.field` | Field name | Second position field. Often quantitative in scatterplots and categorical in dot plots. |
| `title` | `title.text` | String | Chart title. |
| `notes` | metadata | String | AI search/context metadata. Never rendered. |
| `color` | `encoding.color.field` | Field name | Category or grouping field. |
| `size` | `encoding.size.field` | Field name | Quantitative field mapped to point size. |
| `shape` | `encoding.shape.field` | Field name | Category field mapped to symbol shape. |
| `x_label` | `encoding.x.title` | String | Custom x-axis title. |
| `y_label` | `encoding.y.title` | String | Custom y-axis title. |
| `field_labels` | legend, tooltip and axis titles | Map of column to text | Display text for a column, painted as written. See [Field Labels](line-graphs.md#field-labels). |
| `format` | quantitative y-axis format | Format string | Numeric formatting for the quantitative `y` axis. Use `style.axis_x` when you need x-axis formatting too. |
| `sort` | categorical axis sort | Sort object | Most useful for dot plots and other ordered categorical comparisons. |

### Size and Category Grouping

This example shows the most common top-level point-chart additions after `x` and `y`: color for grouping and size for magnitude.

```dbt-charts-example
queries:
  segment_performance:
    columns: [avg_deal_size, win_rate, segment, open_pipeline]
    values:
      - [18000, 0.22, "SMB", 45]
      - [24000, 0.26, "SMB", 58]
      - [52000, 0.31, "Mid-Market", 72]
      - [61000, 0.34, "Mid-Market", 86]
      - [120000, 0.41, "Enterprise", 108]
      - [138000, 0.44, "Enterprise", 124]
      - [195000, 0.37, "Strategic", 140]
      - [215000, 0.40, "Strategic", 156]

charts:
  segment_scatter:
    query: segment_performance
    type: scatter
    title: Deal Size vs Win Rate by Segment
    x: avg_deal_size
    y: win_rate
    color: segment
    size: open_pipeline
    x_label: Average Deal Size
    y_label: Win Rate
    style:
      axis_x:
        labels:
          format: currency_whole
      axis_y:
        labels:
          format: percent_whole
rows:
  - segment_scatter
```

### Dot Plot

This example uses the same point-chart family to create a dot plot, where the y-axis is categorical and the x-axis carries the quantitative comparison.

```dbt-charts-example
queries:
  response_times:
    columns: [team, median_response_hours]
    values:
      - ["Onboarding", 1.8]
      - ["Support", 2.4]
      - ["Success", 3.1]
      - ["Renewals", 4.0]
      - ["Escalations", 5.3]

charts:
  team_response_dots:
    query: response_times
    type: scatter
    title: Median Response Time by Team
    x: median_response_hours
    y: team
    x_label: Hours
    y_label: Team
    sort:
      by: median_response_hours
      order: desc
    style:
      axis_x:
        labels:
          format: ".1f"
rows:
  - team_response_dots
```

---

## Style Fields

Use `style` for dbt Charts shorthand properties that affect presentational defaults such as legend visibility and grid lines.

| dbt Charts field | Maps to Vega-Lite | Allowed values | Notes |
|---|---|---|---|
| `style.legend.visible` | `encoding.color.legend` | `true` or `false` | Typed legend control. `false` hides the legend. |
| `style.axis.grid.visible` | axis grid visibility | `true` or `false` | `false` hides grid lines. Use `style.axis.grid.visible: false` (nested under `grid:`). |
| `style.background` | chart SVG background wrapper | Color value | Applies a chart-level background fill behind the rendered SVG. |

### Legend and Grid Lines

This example keeps the same basic scatter structure while showing the small `style` surface for point charts.

```dbt-charts-example
queries:
  experiment_results:
    columns: [confidence, lift, cohort]
    values:
      - [0.62, 0.07, "Baseline"]
      - [0.68, 0.10, "Baseline"]
      - [0.73, 0.12, "Baseline"]
      - [0.66, 0.14, "Guided"]
      - [0.71, 0.17, "Guided"]
      - [0.77, 0.19, "Guided"]

charts:
  experiment_scatter:
    query: experiment_results
    type: scatter
    title: Confidence vs Lift
    x: confidence
    y: lift
    color: cohort
    style:
      legend:
        visible: false
      axis:
        grid:
          visible: false
      axis_x:
        labels:
          format: percent_whole
      axis_y:
        labels:
          format: percent_whole
rows:
  - experiment_scatter
```

---

## Axis and Scale Style

Use `style` for axis and scale properties that shape how a point chart is framed and read.

| dbt Charts field | Maps to Vega-Lite | Allowed values | Notes |
|---|---|---|---|
| `style.axis_x` | `config.axisX` / `encoding.x.axis` | axis object | Per-axis styling (labels, ticks, grid, title, scale). |
| `style.axis_y` | `config.axisY` / `encoding.y.axis` | axis object | Per-axis styling. |
| `style.axis_x.scale` | `config.axisX.scale` | scale object | X-axis scale config (domain, nice, clamp). |
| `style.axis_y.scale` | `config.axisY.scale` | scale object | Y-axis scale config (zero, domain, nice, clamp). |

### Axis Formatting and Scale Bounds

This example shows the most common `style` work on point charts: formatting axes and trimming the visible scale range to the comparison that matters.

```dbt-charts-example
queries:
  product_health:
    columns: [activation_rate, retention_rate]
    values:
      - [0.52, 0.67]
      - [0.58, 0.71]
      - [0.63, 0.74]
      - [0.69, 0.78]
      - [0.74, 0.83]
      - [0.81, 0.88]

charts:
  health_scatter:
    query: product_health
    type: scatter
    title: Activation Rate vs Retention Rate
    x: activation_rate
    y: retention_rate
    style:
      axis_x:
        labels:
          format: percent_whole
        scale:
          continuous:
            zero: false
      axis_y:
        labels:
          format: percent_whole
        scale:
          continuous:
            zero: false
rows:
  - health_scatter
```

---

### Value Labels

Show the numeric value beside each point on a scatter chart by enabling `style.marks.point.labels.visible`. `style.marks.point.color` recolors the dots of a single-series scatter; with a `color` channel the series palette colors them.

```yaml {contract=board-root}
queries:
  product_health:
    columns: [activation_rate, retention_rate]
    values:
      - [0.52, 0.67]
      - [0.58, 0.71]

charts:
  health_scatter:
    query: product_health
    type: scatter
    x: activation_rate
    y: retention_rate
    style:
      marks:
        point:
          color: "#c2410c"
          labels:
            visible: true
            position: top
            format: percent_whole
rows:
  - health_scatter
```

**Position values:**

| Value | Placement |
|-------|-----------|
| `top` | Above the point, default |
| `bottom` | Below the point |
| `left` | To the left of the point |
| `right` | To the right of the point |
| `middle` | Centered on the point |

Point and line charts share the same position vocabulary and Vega-Lite mapping.

---

### Multi-Metric Points

When `y` is a list, dbt Charts folds the measures into one color-coded series of points sharing the same x-axis. This is useful for comparing two measures against the same categories, though every additional measure is just another point at the same x distinguished only by color, so it reads best with a handful of categories rather than a dense continuous axis.

```dbt-charts-example
queries:
  team_actual_vs_target:
    columns: [team, actual, target]
    values:
      - ["Onboarding", 82, 90]
      - ["Support", 76, 85]
      - ["Success", 91, 88]
      - ["Renewals", 68, 80]
      - ["Escalations", 95, 92]

charts:
  actual_vs_target:
    query: team_actual_vs_target
    type: scatter
    title: Actual vs Target Score by Team
    x: team
    y: [actual, target]
rows:
  - actual_vs_target
```

---

## Mark Fields

dbt Charts scatter charts are authored with `type: scatter` plus top-level channels such as `x`, `y`, `color`, `size`, and `shape`. Arbitrary Vega-Lite `spec`, `mark`, `encoding`, `config`, `transform`, `params`, and composition blocks are rejected on the authored surface. Use top-level dbt Charts fields and the typed `style:` object.

---

## Related

- [Charts Overview](index.md)
- [Bar Charts](bar-charts.md)
- [Area Charts](area-charts.md)

# Area Charts (https://docs.dbtcharts.com/charts/area-charts/)

# Area Charts

Area charts show magnitude with filled shapes, usually under a line or across stacked layers, so they emphasize both trend and accumulated bands; this family includes simple area charts, stacked area charts, and streamgraph-style variants. They are most useful when you want viewers to see changing totals or composition over time, though they trade away some comparison precision compared with line graphs and bar charts.

dbt Charts area charts use a small set of top-level shorthand fields together with `style`. In most cases, you only need `query`, `type: area`, `x`, and `y` to get started. Adding `color` creates **overlapping** semi-transparent series by default; use `style.stack: "zero"` (or `true`) to switch to stacked bands. Area charts are especially useful when total accumulation or composition carries meaning.

A chart's **control surface** is the full set of authored **properties** available on a single chart. In dbt Charts, that surface is primarily top-level chart fields plus typed `style` objects.

This page is intentionally family-oriented rather than exhaustive. For the implementation-backed source of truth, including default ownership and lower-level property coverage, see the [YAML Schema Reference](../reference/yaml-reference.md).

---

## Minimum Required for an Area Chart

These are the minimum fields required to render a basic area chart in dbt Charts.

| dbt Charts field | Maps to Vega-Lite | Allowed values | Notes |
|---|---|---|---|
| `query` | `data.values` | Query name or query reference | Supplies the dataset. |
| `type: area` | `mark.type: "area"` | Literal `area` | Selects the area mark. |
| `x` | `encoding.x.field` | Field name | Ordered dimension, usually time. |
| `y` | `encoding.y.field` | Field name | Numeric measure to plot as filled magnitude. |

### Minimum Example

```dbt-charts-example
queries:
  weekly_signups:
    columns: [week, signups]
    values:
      - ["2026-01-05", 120]
      - ["2026-01-12", 165]
      - ["2026-01-19", 150]
      - ["2026-01-26", 205]
      - ["2026-02-02", 230]
      - ["2026-02-09", 260]

charts:
  signup_area:
    query: weekly_signups
    type: area
    title: Weekly Signups
    x: week
    y: signups
rows:
  - signup_area
```

---

## Top-Level Chart Fields

These are the top-level chart properties you set directly on an area chart before you get into nested properties under `style`.

| dbt Charts field | Maps to Vega-Lite | Allowed values | Notes |
|---|---|---|---|
| `query` | `data.values` | Query name or query reference | Query results become the plotted dataset. |
| `type: area` | `mark.type: "area"` | Literal `area` | Selects the area mark. |
| `x` | `encoding.x.field` | Field name | Usually a temporal or ordered field. |
| `y` | `encoding.y.field` | Field name or list of field names | A list creates layered multi-metric areas. |
| `title` | `title.text` | String | Chart title. |
| `notes` | metadata | String | AI search/context metadata. Never rendered. |
| `color` | `encoding.color.field` | Field name | Creates overlapping area series by default; combine with `style.stack: "zero"` to stack bands. |
| `x_label` | `encoding.x.title` | String | Custom x-axis title. |
| `y_label` | `encoding.y.title` | String | Custom y-axis title. |
| `field_labels` | legend, tooltip and axis titles | Map of column to text | Display text for a column, painted as written. See [Field Labels](line-graphs.md#field-labels). |
| `format` | `encoding.y.format` and `encoding.y.axis.format` | Format string | Numeric formatting for the y channel. |
| `sort` | categorical axis sort | Sort object | Most useful when the x-axis is categorical. |
| `projection` | top-level `projection` | Vega-Lite projection name | Available for Vega-Lite projection overrides. |

### Stacked Composition over Time

This example uses `color` plus `style.stack: "zero"` to split one area chart into stacked category bands so readers can see both total volume and changing composition over time. Without `style.stack`, the series overlap as semi-transparent silhouettes instead.

```dbt-charts-example
queries:
  channel_mix:
    columns: [month, channel, signups]
    values:
      - ["2026-01-01", "Organic", 90]
      - ["2026-01-01", "Paid", 40]
      - ["2026-01-01", "Partner", 18]
      - ["2026-02-01", "Organic", 105]
      - ["2026-02-01", "Paid", 48]
      - ["2026-02-01", "Partner", 22]
      - ["2026-03-01", "Organic", 118]
      - ["2026-03-01", "Paid", 52]
      - ["2026-03-01", "Partner", 29]
      - ["2026-04-01", "Organic", 134]
      - ["2026-04-01", "Paid", 58]
      - ["2026-04-01", "Partner", 34]
      - ["2026-05-01", "Organic", 146]
      - ["2026-05-01", "Paid", 63]
      - ["2026-05-01", "Partner", 38]

charts:
  stacked_area:
    query: channel_mix
    type: area
    title: Signup Mix by Channel
    x: month
    y: signups
    color: channel
    style:
      stack: "zero"
rows:
  - stacked_area
```

### Stacked Area Recipe

When `style.stack` is non-false (`"zero"`, `true`, `"normalize"`, or `"center"`), dbt Charts automatically applies the **stacked recipe**: solid fills (opacity 1.0) with a 1-pixel background-color perimeter stroke separating adjacent bands. This is the same idiom as the stacked-bar border knockout: the separator is the chart background bleeding through the stroke, not a separately painted line, so it reads correctly on any background color.

The default overlap recipe (translucent fill + halo) is suppressed for stacked charts because bands in a stack never cross, so the halo undercoat provides no benefit.

Theme authors can override the stacked recipe via `style.charts.marks.area.stacked`:

```yaml {contract=board-root}
style:
  charts:
    marks:
      area:
        stacked:
          opacity: 1.0
          stroke:
            color: theme.background
            width: 1.5
          halo_multiplier: 0.0
```

A single-series area also takes this recipe in full, even with `style.stack` left at its default `"none"`. A chart counts as single-series when it has no `color`, no `layers:`, and no `y:` list of two or more measures. With one band there is nothing to overlap and nothing for a trend line to sit on top of, so a single-series area gets the same solid fill, background-color separator stroke, and halo turned off as a real stacked chart.

This means `style.charts.marks.area.opacity` and `style.charts.marks.line.stroke`, which configure the *multi*-series overlap recipe's fill and top-edge trend line, are ignored on a single-series area. Use `style.charts.marks.area.stacked.opacity` to set its fill opacity and `style.charts.marks.area.stacked.stroke` to style its edge.

### Streamgraph Baseline

This example uses `style.stack: center` to shift a stacked area chart to a centered baseline, producing a streamgraph-style view.

Endpoint labels work on a centered baseline: each label anchors to its band's midpoint at the final x position, so the series names sit on the bands instead of in a side legend. That matters more here than on most charts: streamgraph bands share no common baseline, so a legend forces the reader to match colors across the page.

```dbt-charts-example
queries:
  listening_mix:
    columns: [month, genre, listeners]
    values:
      - ["2026-01-01", "Ambient", 42]
      - ["2026-01-01", "Indie", 58]
      - ["2026-01-01", "Jazz", 33]
      - ["2026-02-01", "Ambient", 48]
      - ["2026-02-01", "Indie", 62]
      - ["2026-02-01", "Jazz", 36]
      - ["2026-03-01", "Ambient", 54]
      - ["2026-03-01", "Indie", 59]
      - ["2026-03-01", "Jazz", 41]
      - ["2026-04-01", "Ambient", 61]
      - ["2026-04-01", "Indie", 55]
      - ["2026-04-01", "Jazz", 45]
      - ["2026-05-01", "Ambient", 57]
      - ["2026-05-01", "Indie", 51]
      - ["2026-05-01", "Jazz", 49]
      - ["2026-06-01", "Ambient", 50]
      - ["2026-06-01", "Indie", 46]
      - ["2026-06-01", "Jazz", 53]

charts:
  listening_streamgraph:
    query: listening_mix
    type: area
    title: Listening Mix by Genre
    x: month
    y: listeners
    color: genre
    style:
      stack: center
rows:
  - listening_streamgraph
```

### Labels, Formatting, and Style

This example shows common top-level chart fields such as labels and numeric formatting, and it also serves as the shared example for basic style and axis-setting controls. An area with `zero: false` warns that its fill is cropped; `warnings_ignore` silences the warning.

```dbt-charts-example
queries:
  monthly_revenue:
    columns: [month, revenue]
    values:
      - ["2026-01-01", 420000]
      - ["2026-02-01", 455000]
      - ["2026-03-01", 480000]
      - ["2026-04-01", 510000]
      - ["2026-05-01", 548000]
      - ["2026-06-01", 592000]

charts:
  revenue_area:
    query: monthly_revenue
    type: area
    title: Monthly Revenue
    x: month
    y: revenue
    x_label: Month
    y_label: Revenue
    style:
      legend:
        visible: false
      axis:
        grid:
          visible: false
      axis_y:
        scale:
          continuous:
            zero: false
        labels:
          format: currency_whole
rows:
  - revenue_area
```

### Layered Multi-Metric Areas

When `y` is a list, dbt Charts creates layered area charts. This is useful when you want to compare two measures on the same x-axis, though overlap usually makes this a less precise choice than layered lines.

```dbt-charts-example
queries:
  revenue_and_forecast:
    columns: [month, actual, forecast]
    values:
      - ["2026-01-01", 420000, 405000]
      - ["2026-02-01", 455000, 438000]
      - ["2026-03-01", 480000, 470000]
      - ["2026-04-01", 510000, 500000]
      - ["2026-05-01", 548000, 540000]
      - ["2026-06-01", 592000, 575000]

charts:
  layered_areas:
    query: revenue_and_forecast
    type: area
    title: Actual vs Forecast Revenue
    x: month
    y: [actual, forecast]
rows:
  - layered_areas
```

---

## Style Fields

Use `style` for dbt Charts shorthand properties that affect presentational defaults such as legend visibility and grid lines.

| dbt Charts field | Maps to Vega-Lite | Allowed values | Notes |
|---|---|---|---|
| `style.legend.visible` | `encoding.color.legend` | `true` or `false` | Typed legend control. `false` hides the legend. |
| `style.axis.grid.visible` | axis grid visibility | `true` or `false` | `false` hides grid lines. Use `style.axis.grid.visible: false` (nested under `grid:`). |
| `style.background` | chart SVG background wrapper | Color value | Applies a chart-level background fill behind the rendered SVG. |
| `style.marks.area.curve` | area interpolation | `linear` (default), `monotone`, `step` | Same interpolation options as line graphs; see [Smoothing & Step Lines](line-graphs.md#smoothing-step-lines). No `connect` option on area (unlike line): a disconnected step area is just a bar chart via the wrong primitive. |

### Legend and Grid Lines

This example reuses the labels-and-formatting chart so you can see the style changes without introducing a second dataset.

```dbt-charts-example
queries:
  monthly_revenue:
    columns: [month, revenue]
    values:
      - ["2026-01-01", 420000]
      - ["2026-02-01", 455000]
      - ["2026-03-01", 480000]
      - ["2026-04-01", 510000]
      - ["2026-05-01", 548000]
      - ["2026-06-01", 592000]

charts:
  revenue_area:
    query: monthly_revenue
    type: area
    title: Monthly Revenue
    x: month
    y: revenue
    x_label: Month
    y_label: Revenue
    style:
      legend:
        visible: false
      axis:
        grid:
          visible: false
      axis_y:
        scale:
          continuous:
            zero: false
        labels:
          format: currency_whole
rows:
  - revenue_area
```

---

## Axis and Scale Style

Use `style` for axis and scale properties that shape how the area chart is framed and read.

| dbt Charts field | Maps to Vega-Lite | Allowed values | Notes |
|---|---|---|---|
| `style.axis_x` | `config.axisX` / `encoding.x.axis` | `AxisStyle` object | Per-axis styling (format, ticks, labels, grid, title). |
| `style.axis_y` | `config.axisY` / `encoding.y.axis` | `AxisStyle` object | Per-axis styling. |
| `style.axis_y.scale` | `config.axisY.scale` | `ScaleStyle` object | Y-axis scale config (zero, nice, domain, clamp). |
| `style.stack` | `encoding.y.stack` | `true`, `false`, `"zero"`, `"normalize"`, `"center"` | Stacking behavior. `"center"` for streamgraphs. |
| `style.stack_order` | `encoding.order` | `"value"` (default), `"data"`, `"alphabetical"` | Band order from the baseline up. `"value"` puts the largest total at the baseline. `"data"` stacks series in first-appearance order: SQL row order for `color`, the listed order for `y: [a, b, ...]` (a measure null in the first rows appears later). `"alphabetical"` sorts by series name. Ignored when stacking is off or there is only one series. |

### Axis and Scale Controls

This example reuses the labels-and-formatting chart so the effect of `style` stays easy to isolate.

```dbt-charts-example
queries:
  monthly_revenue:
    columns: [month, revenue]
    values:
      - ["2026-01-01", 420000]
      - ["2026-02-01", 455000]
      - ["2026-03-01", 480000]
      - ["2026-04-01", 510000]
      - ["2026-05-01", 548000]
      - ["2026-06-01", 592000]

charts:
  revenue_area:
    query: monthly_revenue
    type: area
    title: Monthly Revenue
    x: month
    y: revenue
    x_label: Month
    y_label: Revenue
    style:
      legend:
        visible: false
      axis:
        grid:
          visible: false
      axis_y:
        scale:
          continuous:
            zero: false
        labels:
          format: currency_whole
rows:
  - revenue_area
```

---

## Endpoint Labels

A multi-series area chart names its series **on the chart**, anchored to each band's final value, rather than in a side legend. This is the default on every built-in theme; you don't switch it on. Set `style.endpoint_labels.visible: false` to send the names back to a legend.

| dbt Charts field | Allowed values | Notes |
|---|---|---|
| `style.endpoint_labels.visible` | `true` or `false` | Defaults to `true` on every built-in theme. Set `false` per-chart to send the series names back to a legend. |

When the label pane is on, the categorical legend turns off automatically: the two would encode the same series→color mapping twice. The y-axis also auto-flips to the **left** so it doesn't collide with the right-edge label pane.

On narrow cards, endpoint-label text compacts to fit the available width while its automatic vertical spacing stays readable for closely ending series.

Endpoint labels require a multi-series chart: either a `color` channel or a `y: [field_a, field_b]` list. On single-series areas there is only one series to name, so the feature is a no-op.

`y: [...]` composes with a `color:` column: the measures are crossed with the column's values, one series per value per measure, each named `<value> - <measure>` (see [Multiple Measures by a Dimension](./line-graphs.md#multiple-measures-by-a-dimension)). `layers:` still cannot combine with `y: [...]`; dbt Charts rejects that at compile time.

```dbt-charts-example
queries:
  channel_mix:
    columns: [month, channel, signups]
    values:
      - ["2026-01-01", "Organic", 90]
      - ["2026-01-01", "Paid", 40]
      - ["2026-01-01", "Partner", 18]
      - ["2026-02-01", "Organic", 105]
      - ["2026-02-01", "Paid", 48]
      - ["2026-02-01", "Partner", 22]
      - ["2026-03-01", "Organic", 118]
      - ["2026-03-01", "Paid", 52]
      - ["2026-03-01", "Partner", 29]
      - ["2026-04-01", "Organic", 134]
      - ["2026-04-01", "Paid", 58]
      - ["2026-04-01", "Partner", 34]
      - ["2026-05-01", "Organic", 146]
      - ["2026-05-01", "Paid", 63]
      - ["2026-05-01", "Partner", 38]

charts:
  stacked_area_with_endpoint_labels:
    query: channel_mix
    type: area
    title: Signup Mix by Channel
    x: month
    y: signups
    color: channel
    style:
      endpoint_labels:
        visible: true

rows:
  - stacked_area_with_endpoint_labels
```

---

## Overlays (`layers:`)

Add a `layers:` list to an area chart to overlay additional marks, a line for a
reference trend, a scatter for individual points, or a second series on a separate
y-axis. The base area chart owns the x-axis, frame, title, legend, and sort. Each layer
contributes its own mark and legend entry.

```yaml {contract=board-fragment}
charts:
  revenue_with_forecast_line:
    type: area
    x: month
    y: revenue
    query: monthly
    style:
      stack: "zero"
    layers:
      - type: line
        y: forecast
        label: Forecast
        style:
          marks:
            line:
              stroke:
                width: 2
                dasharray: "4 2"
```

Layer fields: `type`, `y`, `label`, `color`, `query`, `x`, `axis_y`, `style` (marks-only patch). `sort:` is base-only; layer x-values extend the base x-scale.

---

## Stacking a `y:` List in Listed Order

Stacked bands default to the largest total at the baseline. Set `style.stack_order: data` to stack a `y:` list in the order you wrote it: here `subscriptions` sits at the baseline even though `services` is larger.

```dbt-charts-example
queries:
  revenue_by_line:
    columns: [month, subscriptions, services, hardware]
    values:
      - ["2026-01-01", 40000, 90000, 15000]
      - ["2026-02-01", 46000, 92000, 14000]
      - ["2026-03-01", 53000, 95000, 16000]

charts:
  listed_order_areas:
    query: revenue_by_line
    type: area
    x: month
    y: [subscriptions, services, hardware]
    style:
      stack: zero
      stack_order: data
rows:
  - listed_order_areas
```

---

## Authored Surface

dbt Charts area charts are authored with `type: area` plus top-level channels such as `x`, `y`, and `color`. Arbitrary Vega-Lite `spec`, `mark`, `encoding`, `config`, `transform`, `params`, and composition blocks are rejected on the authored surface. Use top-level dbt Charts fields and the typed `style:` object.

---

## Related

- [Charts Overview](index.md)
- [Line Graphs](line-graphs.md)
- [Point Charts](point-charts.md)

# Maps (https://docs.dbtcharts.com/charts/maps/)

# Maps

Maps encode data through geographic position, using region fills, symbols, or other marks tied to real places. They are most useful when location itself is part of the meaning, with filled-region maps working best for values aggregated by area and symbol maps working best for counts, events, or magnitudes at specific places.

dbt Charts maps are configured primarily through top-level geographic fields such as `geo`, `geo_source`, `lookup`, `value`, `projection`, `latitude`, `longitude`, and `size`. In practice, that means this family relies much more on map-specific top-level configuration than on large `mark`, `encoding`, or `style` passthrough surfaces.

A chart's **control surface** is the full set of authored **properties** available on a single chart. In dbt Charts, that surface is primarily top-level chart fields plus the typed `style` object.

This page is intentionally family-oriented rather than exhaustive. For the implementation-backed source of truth, including default ownership and lower-level property coverage, see the [YAML Schema Reference](../reference/yaml-reference.md).

Map joins are exact-key joins. Your `lookup` field must match the geographic source's key values exactly, including formatting details such as leading zeros, abbreviations, or code systems. If a region is unexpectedly missing, the first thing to check is whether the query key format matches the map source key format.

---

## Minimum Required for a Filled-Region Map

These are the minimum fields required to render a basic filled-region map in dbt Charts. Other map forms have different minimums: a symbol map (`type: point_map`) needs coordinate fields, and a proportional symbol map (`type: bubble_map`) needs coordinates plus a `size` field. `projection` is optional for all of them because dbt Charts uses a source-appropriate default when you do not specify one.

| dbt Charts field | Maps to Vega-Lite | Allowed values | Notes |
|---|---|---|---|
| `query` | lookup data values | Query name or query reference | Supplies the data that will be joined to the geographic features. |
| `type: map` | `mark.type: "geoshape"` | Literal `map` | Selects the filled-region map form. |
| `geo.source` | geographic data URL and format | Built-in geo source name or custom GeoJSON/TopoJSON URL | Chooses the boundary shapes to render. |
| `lookup` | geoshape lookup join key | Field name | Field in your query data that joins to the geographic source. The values must match the source key format exactly. |
| `value` | `encoding.color.field` | Field name | Quantitative field used to fill regions. Prefer densities, rates, or percentages over raw totals. |

### Minimum Map Example

```dbt-charts-example
queries:
  new_england_population_density:
    columns: [state_code, population_density]
    values:
      - ["9", 742]
      - ["23", 44]
      - ["25", 901]
      - ["33", 154]
      - ["44", 1022]
      - ["50", 68]

charts:
  new_england_population_density_map:
    query: new_england_population_density
    type: map
    title: New England Population Density
    geo:
      source: us-states
    lookup: state_code
    value: population_density
    projection:
      type: mercator
      center: [-71.8, 43.8]
      scale: 2200
rows:
  - new_england_population_density_map
```

---

## Top-Level Chart Fields

These are the top-level chart properties you set directly on a map before reaching for smaller nested properties. This is where dbt Charts exposes most of the meaningful map surface.

| dbt Charts field | Maps to Vega-Lite | Allowed values | Notes |
|---|---|---|---|
| `query` | lookup data values | Query name or query reference | Data to join to regions or plot as points. |
| `type: map` | `mark.type: "geoshape"` | Literal `map` | Canonical map type. Renders an outline map or a filled-region map depending on the fields provided. |
| `type: point_map` | `mark.type: "circle"` | Literal `point_map` | Symbol map for events or places at exact coordinates. |
| `type: bubble_map` | `mark.type: "circle"` | Literal `bubble_map` | Proportional symbol map with quantitative sizing. |
| `title` | `title.text` | String | Chart title. |
| `notes` | metadata | String | AI search/context metadata. Never rendered. |
| `geo` | geographic source config | Object with `source`, optional `key`, optional `feature` | Primary map source config. |
| `geo_source` | geographic source selector | `us-states`, `us-counties`, `world-countries`, `world-50m`, `sf-neighborhoods`, `nyc-neighborhoods`, `chicago-neighborhoods`, `la-neighborhoods` | Convenience shorthand for selecting a built-in background or map source. |
| `lookup` | geoshape lookup join key | Field name | Query field used to join your data to the geographic features. The values must match the source key format exactly. |
| `value` | `encoding.color.field` | Field name | Region fill value field. In practice, filled-region maps usually work best with densities, rates, or percentages rather than raw totals. |
| `color` | `encoding.color.field` | Field name | Bubble/point color field, or region fill shorthand when `value` is omitted. |
| `projection` | top-level `projection` | `mercator`, `albersUsa`, `equalEarth`, `naturalEarth1`, `orthographic`, `stereographic`, `albers`, `conicEqualArea`, `equirectangular`, or projection object | Overrides the source default projection. |
| `latitude` | `encoding.latitude.field` | Field name | Point-map latitude field. Auto-detected from common names when omitted. |
| `longitude` | `encoding.longitude.field` | Field name | Point-map longitude field. Auto-detected from common names when omitted. |
| `size` | `encoding.size.field` | Field name | Quantitative size field for bubble maps. Mark area scales proportionally with the value (zero-anchored range), not radius. |
| `collapse` | `encoding.size: {aggregate: "count"}` | `true` / `false` (default `false`) | point_map/bubble_map only. Collapses marks sharing an exact latitude/longitude into one mark, area-proportional to the count. Mutually exclusive with `size`, and with a `color` channel; it would widen the count's implicit groupby beyond latitude/longitude. |

### Map Form Minimums

This quick reference shows the minimum fields for each major map form. Use it to choose the right starting shape before you add projection, color schemes, or other refinements.

| Map form | Minimum dbt Charts fields | Notes |
|---|---|---|
| `map` | `query`, `type: map`, `geo.source`, `lookup`, `value` | Filled-region map joined to geographic features. |
| `map` (outline) | `type: map`, `geo.source` | Base outline map. Add `query`, `lookup`, and `value` only if you want data-driven fills. |
| `point_map` | `query`, `type: point_map`, `latitude`, `longitude` | Symbol map for exact locations. Add `geo_source` if you want a geographic backdrop. |
| `bubble_map` | `query`, `type: bubble_map`, `latitude`, `longitude`, `size` | Proportional symbol map with quantitative sizing. Add `geo_source` if you want a geographic backdrop. |

### Filled-Region Maps and Bubble Maps

This example shows the family's two main forms using the same New England geography: a filled-region map for region-level density and a bubble map for magnitudes at exact locations.

```dbt-charts-example
queries:
  new_england_population_density:
    columns: [state_code, population_density]
    values:
      - ["9", 742]
      - ["23", 44]
      - ["25", 901]
      - ["33", 154]
      - ["44", 1022]
      - ["50", 68]

  new_england_cities:
    columns: [city, lat, lng, revenue, store_type]
    values:
      - ["Boston", 42.3601, -71.0589, 980000, "Flagship"]
      - ["Providence", 41.8240, -71.4128, 520000, "Boutique"]
      - ["Portland", 43.6591, -70.2568, 410000, "Boutique"]
      - ["Hartford", 41.7658, -72.6734, 460000, "Outlet"]
      - ["Burlington", 44.4759, -73.2121, 290000, "Boutique"]
      - ["Manchester", 42.9956, -71.4548, 380000, "Outlet"]

charts:
  new_england_population_density_map:
    query: new_england_population_density
    type: map
    title: New England Population Density
    geo:
      source: us-states
    lookup: state_code
    value: population_density
    projection:
      type: mercator
      center: [-71.8, 43.8]
      scale: 2200

  new_england_revenue_bubbles:
    query: new_england_cities
    type: bubble_map
    title: New England Store Revenue by City
    latitude: lat
    longitude: lng
    size: revenue
    color: store_type
    geo_source: us-states
    projection:
      type: mercator
      center: [-71.8, 43.8]
      scale: 2200
rows:
  - new_england_population_density_map
  - new_england_revenue_bubbles
```

### Symbol Maps with a Regional Backdrop

This example shows how a regional symbol map can reuse the same New England projection without requiring proportional sizing.

```dbt-charts-example
queries:
  new_england_locations:
    columns: [name, lat, lng, location_type]
    values:
      - ["Boston", 42.3601, -71.0589, "Commercial Core"]
      - ["Portland", 43.6591, -70.2568, "Port City"]
      - ["Providence", 41.8240, -71.4128, "College City"]
      - ["Burlington", 44.4759, -73.2121, "Regional Hub"]

charts:
  new_england_point_map:
    query: new_england_locations
    type: point_map
    title: New England City Locations
    geo_source: us-states
    latitude: lat
    longitude: lng
    color: location_type
    projection:
      type: mercator
      center: [-71.8, 43.8]
      scale: 2200
rows:
  - new_england_point_map
```

### Basemap

`basemap` gives a point or bubble map a styled geographic background layer, an
alternative to `geo_source` for when you also want to control the background fill and
stroke directly, rather than accepting the theme default.

| dbt Charts field | Maps to Vega-Lite | Allowed values | Notes |
|---|---|---|---|
| `basemap.source` | background geoshape layer source | Same values as `geo_source` | Selects the boundary shapes for the background layer. |
| `basemap.fill` | background layer `mark.fill` | Color value | Background geography fill color. Falls back to the theme's neutral geoshape fill when omitted. |
| `basemap.stroke` | background layer `mark.stroke` | Color value | Background geography boundary stroke color. |

```dbt-charts-example
queries:
  new_england_cities:
    columns: [city, lat, lng]
    values:
      - ["Boston", 42.3601, -71.0589]
      - ["Providence", 41.8240, -71.4128]
      - ["Portland", 43.6591, -70.2568]

charts:
  new_england_cities_styled_basemap:
    query: new_england_cities
    type: point_map
    title: New England Cities
    latitude: lat
    longitude: lng
    basemap:
      source: us-states
      fill: "#f5f5f5"
      stroke: "#cccccc"
    projection:
      type: mercator
      center: [-71.8, 43.8]
      scale: 2200
rows:
  - new_england_cities_styled_basemap
```

---

## Style Fields

Use `style` for map presentation properties that are intentionally simpler than full Vega-Lite control.

| dbt Charts field | Maps to Vega-Lite | Allowed values | Notes |
|---|---|---|---|
| `style.color.gradient.palette` | `encoding.color.scale.scheme` | Vega-Lite color-scheme name | Most relevant for filled-region maps, where the fill scale carries the main value encoding. |
| `style.background` | chart SVG background wrapper | Color value | Applies a chart-level background fill behind the final rendered map SVG. Distinct from `geo_source`, which adds a geographic background layer for point and bubble maps. |

### Color Scheme

This example keeps the same New England geography and join logic fixed while changing the map palette.

```dbt-charts-example
queries:
  new_england_unemployment:
    columns: [state_code, unemployment]
    values:
      - ["9", 4.1]
      - ["23", 3.6]
      - ["25", 4.3]
      - ["33", 3.2]
      - ["44", 4.0]
      - ["50", 2.8]

charts:
  new_england_unemployment_map:
    query: new_england_unemployment
    type: map
    title: New England Unemployment Rate
    geo:
      source: us-states
    lookup: state_code
    value: unemployment
    projection:
      type: mercator
      center: [-71.8, 43.8]
      scale: 2200
    style:
      color:
        gradient:
          palette: viridis
rows:
  - new_england_unemployment_map
```

---

## Related

- [Charts Overview](index.md)
- [Sector Charts](sector-charts.md)
- [Point Charts](point-charts.md)

# Tables and Text (https://docs.dbtcharts.com/charts/tables/)

# Tables and Text

Tables present values directly in rows and columns, making lookup, exact reading, and dense comparison possible; this family includes plain text tables, colored tables, and spark tables. They are most useful when the reader needs exact numbers, many values at once, or a structured reference view rather than a strongly shaped visual pattern.

This page will also cover other data-powered text-like outputs that are not really Vega-Lite charts at all, such as KPI blocks, large single-value callouts, and future narrative or AI-generated summary text. In other words, this family is not just about tables as rows and columns; it is about text-oriented outputs that are driven by data and are often used when exact reading, summarization, or direct communication matters more than visual encoding.

A chart's **control surface** is the full set of authored **properties** available on a single chart. In dbt Charts, that surface is primarily top-level chart fields plus a typed `style` object.

This page is intentionally family-oriented rather than exhaustive. For the implementation-backed source of truth, including table, KPI, spark, and `spark_bar` property coverage, see the [YAML Schema Reference](../reference/yaml-reference.md).

---

## Table Charts

Use `type: table` when exact values, scanning, and dense comparison matter more than mark-based trend reading.

### Minimum Required for a Table

| dbt Charts field | Maps to renderer behavior | Allowed values | Notes |
|---|---|---|---|
| `query` | table data rows | Query name or query reference | Supplies the dataset. |
| `type: table` | table SVG renderer | Literal `table` | Selects the table renderer. |

### Table-Specific Style

Table-specific style fields go **directly** under `style:` (for example, `style.row_numbers.visible`, `style.columns`). Chart-level `style:` is typed as `TableChartStylePatch`; its fields sit at the root of the chart's `style:` block. Using `style.table.*` nesting raises a validation error (`extra inputs are not permitted`).

| dbt Charts field | Maps to renderer behavior | Allowed values | Notes |
|---|---|---|---|
| `style.columns` | per-column display config | Mapping of column name → config object | Styling only: configures labels, formatting, width, alignment, header links, and inline sparks for the columns it names; every column the query returns renders whether or not it is listed, in the query's own order. Hide a column with `visible: false`; use `column_name: {}` for a bare column with defaults. |
| `style.column_defaults` | table-wide column defaults | `TableColumnDefaultsConfig` object | Sets `width`, `align`, `format`, `background`, and `font` for all columns; per-column entries override field-by-field. |
| `style.header_overflow` | header overflow behavior | `clip`, `truncate`, `wrap-two` (default), or `wrap` | Controls how long table headers clip, truncate with ellipsis, or wrap. Headers wrap to two lines unless you set this. |
| `style.background` | chart SVG background wrapper | Color value | Applies a chart-level background fill behind the rendered table SVG. |
| `style.column_layout.width_similarity_threshold` | column cluster equalization threshold | Float `0.0`–`1.0` (default `0.8`) | Auto-width columns whose min/max ratio ≥ this value are snapped to a shared width before budget allocation. `0.8` = within ~20% get equalized; `1.0` = disabled (pure proportional); `0.0` = all auto-columns equal. |
| `style.symbol_mode` | currency-prefix / magnitude-suffix placement on numeric columns | `anchors` (theme default) or `all` | `anchors` shows the full formatted value only on the **first data row** and on summary/total rows, stripping the prefix from plain middle rows; the anchor rows carry the unit so the reader doesn't need it repeated on every line. The magnitude suffix (K/M/B) also strips from middle rows when the column's values share one common magnitude (see Number Formatting below); otherwise it stays on every row, since it then still carries per-row value. `all` shows the full formatted value (prefix + number + suffix) on every row. |

To disable column equalization for a chart that needs strict proportional sizing (for example, a revenue waterfall where the column widths carry meaning) set the threshold to `1.0`:

```yaml {contract=table-chart-style}
style:
  column_layout:
    width_similarity_threshold: 1.0  # disable equalization; use strict proportional widths
```

Every built-in theme defaults `symbol_mode` to `anchors`: a currency or percent symbol only at the top and bottom of a numeric column. To show the symbol on every row instead, set `symbol_mode: all`:

```yaml {contract=table-chart-style}
style:
  symbol_mode: all  # "$1,234" on every row instead of just the first data row and the total row
```

### Row Presentation (`style.row`)

The `style.row` block controls body-row defaults and per-role overrides for summary and total rows. The singular `row` name avoids confusion with the board-level `rows:` layout key.

| dbt Charts field | Maps to renderer behavior | Allowed values | Notes |
|---|---|---|---|
| `style.row.role` | column id for per-row role | Column name (string) | Per-row value: `value`, `summary`, or `total`. |
| `style.row.height` | body row height (px) | Number | Body row height. |
| `style.row.divider.visible` | draw row separators | `true`, `false` | Row separators are off by default. |
| `style.row.divider.width` | row separator width (px) | Number | Row separator width. |
| `style.row.divider.color` | row separator color | Color value | Sets the row separator color; overrides the theme default. |
| `style.row.roles.summary.font.weight` | summary row font weight | `"400"`, `"500"`, `"600"`, `"700"` | Summary-row font weight. |
| `style.row.roles.summary.background` | summary row fill | Color value | Fill behind summary rows. |
| `style.row.roles.total.font.weight` | total row font weight | `"400"`, `"500"`, `"600"`, `"700"` | Total-row font weight. |
| `style.row.roles.total.background` | total row fill | Color value | Fill behind total rows. |

```yaml {contract=table-chart-style}
style:
  row:
    role: kind              # column whose per-row value is the role
    height: 15
    divider:
      visible: true
      width: 2
      color: "#D32F2F"
    roles:
      summary:
        font:
          weight: "500"
      total:
        font:
          weight: "700"
        background: "#F5F5F5"
```

### Row Numbers (`style.row_numbers`)

The `style.row_numbers` block injects a synthetic leading column that numbers data rows 1, 2, 3, ..., the same presentation as Excel, Google Sheets, and Looker's `show_row_numbers`. The column is transparent to `style.columns` (authors don't list it), to `conditional_formatting` rules keyed by column name (no rules target it), and to the data pipeline (it is a chart-layer concern, not a query column).

| dbt Charts field | Maps to renderer behavior | Allowed values | Notes |
|---|---|---|---|
| `style.row_numbers.visible` | toggle on/off | `true` or `false` | Default `false`; off unless set. |
| `style.row_numbers.header` | column header text | String | Default `"#"`. |
| `style.row_numbers.align` | cell text alignment | `left` or `right` | Default `right`, matching numeric convention. |

```yaml {contract=table-chart-style}
style:
  row_numbers:
    visible: true   # minimum v1 opt-in
    header: "#"     # defaults; include to override
    align: right
```

**Pagination behavior**: numbering is continuous across pages. Page 2 of a 100-per-page table starts at row 101; it never resets to 1. The column width sizes against the *total* row count (not the per-page count), so page 1 and page 5 of a 200-row table have the same row-number column width.

**Summary / total rows**: the row-number cell is blank on rows tagged as `summary` or `total` (via `style.row.role`). The sequence counts data rows only.

### Table Pagination

Tables support client-side row pagination via `style.pagination`. This controls how many rows are visible per page; it is a presentation concern, distinct from query-level `limit` which controls how many rows are *fetched*.

| dbt Charts field | Maps to renderer behavior | Allowed values | Notes |
|---|---|---|---|
| `style.pagination` | enables row paging | Object | Use the object form shown below. |
| `style.pagination.enabled` | toggle pagination on/off | `true` or `false` | Defaults to `true` when pagination is present. |
| `style.pagination.page_rows` | rows per page | Positive integer or `null` | Optional; defaults to 20. A ceiling: a page never holds more rows than the tile height fits. `null` means unlimited: the tile height alone sizes the page. |

Use the full object form:

```yaml {contract=table-chart-style}
style:
  pagination:
    enabled: true
    page_rows: 25
```

**Design note**: `style.pagination` is purely presentational. Use query-level `limit` when the intent is to *fetch* fewer rows. The Looker migration exporter maps `limit_displayed_rows` / `num_rows` to `style.pagination.page_rows`, preserving the distinction between data truncation and UI paging.

### Conditional Formatting (`conditional_formatting`)

Tables (and KPIs) support cell-level conditional styling through the **chart-level `conditional_formatting:` block**, keyed by query column name, with a `when:` list evaluated top-to-bottom like spreadsheet rules. This is the canonical mechanism for changing a cell's `background`, `font.color`, or `font.weight` based on a *predicate* over its value (thresholds, equality, a default catch-all). There is no separate `cell_style` field on `style.columns[]`; conditional decisions live here. (`style.columns[].background`/`.font` can also resolve per-row from another column's raw value with no predicate involved; see [Per-row style from another column](#per-row-style-from-another-column) below.)

| Predicate | Meaning |
|---|---|
| `gte: <number>` | value is greater than or equal to |
| `gt: <number>` | value is strictly greater than |
| `lte: <number>` | value is less than or equal to |
| `lt: <number>` | value is strictly less than |
| `eq: <value>` | value equals (string or number) |
| `default: true` | catch-all; place last |

Each `when` entry can set `background` (color), `font.color` (color), `font.weight` (`"400"` … `"700"`), and `glyph` (a character prepended to the cell value). Rules are evaluated per-row, per-column, in list order; every matching rule (other than `default: true`) contributes its style keys, and later matches win over earlier ones for a given key: the last `gte:` you list beats an earlier one that also matches.

```yaml {contract=board-fragment}
charts:
  cf_revenue_table:
    type: table
    query: product_category_revenue
    conditional_formatting:
      revenue:
        when:
          - gte: 50000
            background: "#dcfce7"
            font:
              color: "#166534"
              weight: "bold"
          - gte: 30000
            background: "#e0f2fe"
          - default: true
            background: "#fef3c7"
      category:
        when:
          - eq: Electronics
            background: "#ede9fe"
          - eq: Accessories
            background: "#cffafe"
          - default: true
            background: "#f4f4f5"
```

#### Glyph tone

A rule that sets `glyph` can color it either way: `glyph_color` takes a raw color, or `tone` names a semantic role (`positive`, `negative`, `warning`, `info`) that resolves through the theme's tone palette. Prefer `tone`; it adapts across themes, and it is the same vocabulary KPI cards use. Both require `glyph`; an explicit `glyph_color` wins if you set both.

```yaml {contract=board-fragment}
charts:
  tone_revenue_table:
    type: table
    query: product_category_revenue
    conditional_formatting:
      revenue:
        when:
          - gte: 50000
            glyph: "▲"
            tone: positive
          - lt: 30000
            glyph: "▼"
            tone: negative
          - default: true
            glyph: "●"
            tone: info
```

`tone` colors the glyph only; it does not repaint the cell's text or background. Use `font.color` and `background` for those, or `scale:` for a continuous gradient.

**Why chart-level, not column-level**: rules are keyed by column name inside the `conditional_formatting` block, which keeps `style.columns[]` focused on layout (label, format, width, align, link, spark) and conditional decoration discoverable in one place. Authors who think "I want red below zero on the revenue column" find one block instead of digging into per-column blocks.

For value-driven gradients (continuous color across a numeric range), see the `scale:` config, separate from `when:` rules. Both compose under `conditional_formatting`.

### Table Column Config

`style.column_defaults` sets shared defaults applied to every rendered column, listed in `style.columns` or not. Per-column entries override field-by-field:

```yaml {contract=table-chart-style}
style:
  column_defaults:
    width: 36
    align: center
  columns:
    c1: {}
    c2: {}
    c3:
      background: "#fee2e2"  # overrides background; width/align come from defaults
```

When all columns share the same presentation (width, alignment), you only write the defaults once and use empty config objects for columns that only inherit defaults.

Set `style.header.visible: false` to hide the header row; no header height is reserved:

```yaml {contract=table-chart-style}
style:
  header:
    visible: false
```

`style.columns` is **styling only**: it configures the columns it names and never selects which columns render, or in what order.

**Column order comes from the query's `SELECT` list** (or the pivot spec's, when `rows:`/`columns:`/`values:` are authored); reordering `style.columns` keys has no effect on where a column renders. To move a column, reorder the `SELECT` list. This is the single most common table-authoring mistake: `style.columns` is where every other per-column knob lives (`label`, `format`, `align`, `visible`), so reordering its keys looks like the obvious way to reorder columns, and it silently does nothing. (Exception: a zero-row result has no query order to fall back on, so its empty-state headers render in `style.columns`' own key order instead.)

Every column the query returns is displayed; naming a subset in `style.columns` styles that subset and nothing else. To remove a column from the render, set `visible: false` on it: the column disappears entirely and the remaining columns close up around it; its values stay available to `link:` templates and column-ID style references. Columns that only exist to feed styling (see [Per-row style from another column](#per-row-style-from-another-column)) are hidden automatically, unless they have their own `style.columns` entry, which is a display signal and shows the column. Keep display-data selection in the query's `SELECT`; a column the table should never see shouldn't be queried at all unless a link or style input needs it.

Each `style.columns.<column_name>` entry can set:

- `visible`: `false` hides the column while keeping its per-row values available to `link:` templates and style-input references; defaults to `true`
- `label`
- `format`
- `width`: hard pin to an exact pixel value or percentage (for example, `200` or `"20%"`). Cannot be combined with `max_width:`.
- `max_width`: cap on auto-sized text columns (see below). Cannot be combined with `width:`.
- `align`
- `header_link`
- `link`: cell-level hyperlink; supports a static URL, a column ID (uses per-row value), or a template with `{{ column_id }}` placeholders. A column formatted `email` or `url` (see [text formats](../styling.md)) links without one; an authored `link:`, a foreign-key drill and a filter link each win over it, and empty cells stay plain text
- `spark`: draw a miniature chart in the cell instead of the value's text (see [Inline Spark Columns](#inline-spark-columns))
- `swatch`: render the cell as a small color chip instead of text (see below)
- `background`: a hex color (or `transparent`/`none`), or a column ID (uses per-row value; see below)
- `font`: `font.color` and `font.weight` accept a column ID the same way `background` does

`style.column_defaults` supports `width`, `align`, `format`, `background`, and `font`. Data-dependent fields (`link`, `header_link`, `spark`, `swatch`, `scale`, `glyph`) are not available as defaults.

### Spanners

`spanners:` draws a label over a run of adjacent columns, so a shared category is written once instead of in every column label. It adds one header row above the column headers; the label is centered over exactly the columns it names, with a rule beneath them. Columns that no spanner names (and the row-number column) get a blank, unruled cell in that row.

```yaml {contract=board-root}
queries:
  by_region:
    type: values
    columns: [region, q1_revenue, q2_revenue, q1_heads, q2_heads]
    values:
      - [West, 812, 904, 31, 34]
      - [East, 654, 701, 24, 25]
charts:
  regional:
    query: by_region
    type: table
    spanners:
      - label: Revenue
        columns:
          - q1_revenue
          - q2_revenue
      - label: Headcount
        columns:
          - q1_heads
          - q2_heads
    style:
      columns:
        q1_revenue:
          label: Q1
        q2_revenue:
          label: Q2
        q1_heads:
          label: Q1
        q2_heads:
          label: Q2
rows:
  - regional
```

- `spanners` is a chart-root list; each entry takes `label` and `columns` (at least one column name).
- Spanners never reorder columns. The columns of one spanner must be adjacent in the query's `SELECT` order; reorder the query to group them.
- A column belongs to at most one spanner, and every name must be a query column. Any violation is an error that names the offending columns.
- A column hidden with `style.columns.<column>.visible: false` leaves its spanner and the span narrows; a spanner whose columns are all hidden is dropped. Adjacency is judged on the columns that remain visible.
- Spanners are single-level and use the header font. They cannot be combined with the pivot channels (`rows:`, `columns:`, `values:`), which draw their own spanners from the pivot dimensions.

### Per-row style from another column

`background`, `font.color`, and `font.weight` resolve **column-ID-first**, the same way `link` does above: if the configured value matches one of the query's column names, the cell uses *that row's* value in the named column instead of treating the string as a literal. This lets a helper column computed by the query drive per-row cell styling directly, with no `when:` predicate. A column consumed this way is hidden from the render automatically, its values are paint, not display data, with no `visible:` authoring needed. Two exceptions: `link:` source columns are not auto-hidden (hide those explicitly with `visible: false`), and a consumed column with its own `style.columns` entry renders; an explicit entry is a display signal.

```yaml {contract=table-chart-style}
style:
  columns:
    account:
      background: status_color   # per-row: uses each row's status_color value, not the literal string "status_color"
```

If the configured value doesn't match a column name, it's used as a literal: a hex string (`transparent`/`none` also accepted) for `background`, or `"bold"` / `"400"` … `"700"` for `font.weight`. Neither field raises on an unrecognized value: an unresolvable color (a mistyped column name, or an unsupported literal like a CSS color name) silently paints no background instead, an unrecognized `font.color` silently leaves the cell's default ink color, and an unrecognized weight silently falls back to the default text weight; check the rendered output rather than relying on a compile-time error. The same applies to a NULL or empty helper-column value: the cell renders unstyled, with no error.

Precedence: a matching `conditional_formatting` `when:` rule on the same column overrides the column-ID value; with no match, the column-ID value stands. **Don't combine column-ID `background`/`font.color` with `scale:` on the same column**: `scale:` reads the *unresolved* configured string as its own base value, so a column-ID reference (not a real color) fails `scale:`'s color check and silently discards the background/color for every row, not just unmatched ones.

This is a narrower mechanism than `conditional_formatting` (above): it always uses the *raw value* of another column, with no predicate. Reach for `conditional_formatting` when the styling decision depends on a threshold or comparison; reach for this when the query already emits the exact style value per row.

### Color Swatch Columns

Set `swatch: true` on a column whose cell values are CSS color strings (for example, `"#3164a3"`) to render each cell as a small rounded color square instead of text. This is useful for series-keyed tables, a "Series" or "Color" column where each row's swatch matches that row's color elsewhere on the board:

```yaml {contract=table-chart-style}
style:
  columns:
    kind:
      label: Color
      swatch: true
```

The column's underlying data must already be CSS color strings; `swatch` only changes how the cell renders, not the query.

### Inline Spark Columns

Set `spark:` on a column to draw a miniature chart inside each cell instead of the value's text. The shorthand is a variant name; the full form is a block with `type:` plus options:

```yaml {contract=table-chart-style}
style:
  columns:
    monthly_trend:
      spark: line
    quota_pct:
      spark:
        type: bar-normalize
        max: 100
        color: "#22c55e"
```

The query delivers each spark's data, one cell per row, already shaped for the variant: `line`, `area`, and `columns` read an array of numbers; `bar`, `bar-normalize`, and `column` read a single number. On a single-number variant, a null cell renders blank and a non-numeric cell falls back to its text, so one spark config can cover a table that mixes text and numeric rows.

| `spark.type` | Draws | Cell value | Scaling |
|---|---|---|---|
| `line` | mini line chart | array | the array's own range |
| `area` | filled mini line chart | array | the array's own range |
| `columns` | one vertical bar per array element | array | the array's own range |
| `bar` | one horizontal bar, no background track | number | width relative to the column's largest absolute value, or to `max:` when set |
| `bar-normalize` | one horizontal bar over a background track | number | width as a share of `max:` (theme default when unset); reads as "% of ceiling" |
| `column` | one narrow vertical bar, bottom-anchored, no track | number | height as a share of `max:` (theme default when unset); `bar-normalize` turned upright |

Variant names mirror `chart.type`: a full-size vertical bar chart is `type: bar`, while the in-cell mark that draws many vertical bars is `columns` (plural, because each cell renders several). Use `bar` for magnitude and `bar-normalize` for percentages: draw a track only when there is a meaningful 100%.

| dbt Charts field | Maps to renderer behavior | Allowed values | Notes |
|---|---|---|---|
| `spark.type` | variant | `line`, `area`, `bar`, `bar-normalize`, `column`, `columns` | Default `line`. |
| `spark.color` | mark color | CSS color | Defaults to the theme's spark color; `bar`, `bar-normalize`, and `column` default to the theme's spark bar color. |
| `spark.width` | mark width in pixels | Positive integer | Defaults to the cell width (`column` to the theme's narrow column width); capped to the cell. |
| `spark.height` | mark height in pixels | Positive integer | Defaults from the row height; capped to it. |
| `spark.last_visible` | dot on the last point | `true` or `false` | `line` and `area`. |
| `spark.min_max_visible` | dots on the min and max points | `true` or `false` | `line` only. |
| `spark.fill_opacity` | fill opacity | 0–1 | `area` only. |
| `spark.max` | scaling ceiling | Number | `bar-normalize` and `column` clamp the value to it; `bar` uses it in place of the column's data max. |
| `spark.thresholds` | fill color by value | Mapping of number → CSS color | `bar`, `bar-normalize`, `column`. The bar takes the color of the highest threshold its value reaches; below the lowest threshold it keeps the theme's spark bar color. Ignored when `color:` is set. |
| `spark.background` | background track color | CSS color | `bar-normalize` only. |
| `spark.border_radius` | corner radius of the bar and track, in pixels | Number | `bar`, `bar-normalize`, `column`. |
| `spark.value_visible` | numeric label beside the bar | `true` or `false` | `bar` and `bar-normalize`. |
| `spark.value_suffix` | text appended to that label | String, for example, `"%"` | Only shown with `value_visible: true`. |
| `spark.negative_color` | paint negative values with the theme's `tones.negative` color | `true` or `false` | `bar`, `column`, `columns`; default `false`. No effect on `bar-normalize` or on a column with no negative values. |

```yaml {contract=table-chart-style}
style:
  columns:
    quota_pct:
      label: Quota
      spark:
        type: bar-normalize
        max: 100
        value_visible: true
        value_suffix: "%"
        thresholds:
          0: "#ef4444"
          70: "#f59e0b"
          85: "#22c55e"
    monthly_trend:
      label: 6-Month Trend
      spark:
        type: line
        last_visible: true
```

**Negative values.** `bar`, `column`, and `columns` grow from a midline once a negative value is present: positives grow right or up, negatives grow left or down. For `bar` and `column` that decision is made per table column, so every row shares one anchor; `columns` decides from its own array. A column with no negatives keeps the full-width or full-height layout. `bar-normalize` never splits: its track is a fixed "% of max" ruler, so negative values clamp to zero.

**Preparing data.** The query owns the series: aggregate it in SQL with `ARRAY_AGG(value ORDER BY month)` (DuckDB, PostgreSQL, BigQuery) or `ARRAY_AGG(value) WITHIN GROUP (ORDER BY month)` (Snowflake), sorted chronologically for time series. Keep arrays to roughly 10–30 points; more turns the spark to mud. For a distribution, pre-bin in the query and render the bucket counts as `columns`; binning belongs to the query, not the render.

### Auto-sizing: compact vs text columns

The table auto-sizer classifies each column as **compact** or **text** based on its measured content demand:

- **Compact** columns (demand ≤ 220px, or spark columns) are pinned to their measured demand. Short enums, numbers, dates, and short strings are compact by default.
- **Text** columns (demand > 220px) compete proportionally for the remaining budget after compact columns are pinned.

This means a freeform notes or description column no longer squashes every compact column down to unreadably narrow widths. The compact columns keep their natural size; the text column gets whatever is left.

When compact columns' total demand exceeds the available width the table accepts overflow (horizontal scroll) rather than squishing; clipping is honest, mid-word wrapping is not.

When the board has no `width`, the same measured width sets the board's width, so an unpinned table is never clipped. Set `style.preferred_width` on the table to pin it instead. Tables inside `cols:` still split the row equally; only a table alone in a row, or in `rows:`, sets the board's width.

#### `max_width:`: capping a text column

Use `max_width:` on a text column to prevent it from growing beyond a ceiling even when there is spare budget:

```yaml {contract=table-chart-style}
style:
  columns:
    csm_name: {}
    account: {}
    arr:
      format: "$,.0f"
    next_steps:
      max_width: 400   # cap the freeform text column; compact columns absorb the remainder
```

`max_width:` accepts an integer (pixels) or a CSS-style percentage string (`"30%"`). It is mutually exclusive with `width:`; setting both raises a validation error at compile time.

When a text column is capped below its natural budget share, the leftover budget is redistributed to the compact columns proportionally, so the table always fills its tile.

### Number Formatting

Numeric columns with no explicit `format:` are formatted at render time using the engine-predefined `number` format, so large numbers read compactly instead of at full precision. `number` uses `.3~s` (three significant figures with an SI magnitude suffix and trailing-zero trim), which renders `452342060.87` as `452M`, `20640228.74` as `20.6M`, and a fraction like `0.671` as `0.67` (never an SI milli suffix).

When a column's values share one common magnitude (most rows land in the millions, say) the column declares that magnitude once instead of repeating it on every row: the top (or summary) row shows the suffix and the rest show bare, digit-aligned numbers at the same scale, the same way a chart axis shows one magnitude label for its whole tick ladder. A column whose values span very different magnitudes, or that doesn't compact at all, keeps today's per-row formatting.

To show a column at full precision, or in any other style, set `format:` on that column entry with a d3 numeric spec (or a predefined name such as `number_full` for plain comma-grouped decimals):

```yaml {contract=table-chart-style}
style:
  columns:
    arr:
      format: "$,.0f"   # "$452,342,061"; explicit format overrides the SI default
    order_id:
      format: number_full   # predefined name; plain comma-grouped decimals
```

An explicit column `format:` always wins over the default. Assigning a temporal format (a predefined time spec such as `time_short`, or an explicit strftime string such as `"%b %Y"`) to a numeric column raises an error at render time; this is the reverse of the date-column check below. A date-like value delivered as a string (a bare year like `"2024"`, for example, a mixed date column with a year-only outlier row) is exempt: it renders as-is rather than raising, the same as any other date-like cell.

A column with no `format:` whose name looks like money or a percentage (`revenue`, `win_rate`, `amount_usd`) raises `WARN-LIKELY-CURRENCY-OR-PERCENT-MISSING-FORMATTER`, since the default prints it without a `$` or `%`. A KPI headline gets the same check against `style.value.format`. `dct render --format text` previews table cells through each column's format, so the formatted value shows there.

### Date and Datetime Formatting

Date and datetime values from the warehouse (`DATE`, `TIMESTAMP`, `TIMESTAMPTZ` columns) are formatted at render time using the engine-predefined `date_short` format; no SQL-side `strftime` is required. `date_short` renders `2024-05-19` as `19 May 2024`.

To override the format for a specific column, set `format:` on that column entry using a strftime-style spec (containing a `%`-prefixed directive such as `%B` or `%W`, anywhere in the string):

```yaml {contract=table-chart-style}
style:
  columns:
    event_date:
      label: "Event Date"
      format: "%B %d, %Y"   # "May 19, 2024"
```

Assigning a non-strftime format spec (such as a d3 numeric format like `",.0f"`) to a date column raises an error at render time; use a strftime spec or omit `format:` to use the predefined `date_short` format.

Date columns are right-aligned and excluded from text-wrap layout automatically. Timezone-aware datetimes are converted to UTC before formatting, so the displayed date (and time, for a spec with a time directive) is always consistent regardless of the server's local timezone.

---

## KPI Charts

Use `type: kpi` when the output is fundamentally one important value rather than a plotted series.

### Minimum Required for a KPI

| dbt Charts field | Maps to renderer behavior | Allowed values | Notes |
|---|---|---|---|
| `query` | KPI data row | Query name or query reference | Supplies the dataset. |
| `type: kpi` | KPI renderer | Literal `kpi` | Selects the KPI renderer. |
| `value` | KPI value binding | Column reference (string column name) | Chooses the value to display. |

`style.value.format` is especially important for KPIs because it controls how that single value is rendered. Content (`value`, `label`, `glyph`, `support`) sits at the chart root; layout and typography (`style.variant`, `style.support.format`, `style.support.tone`, and each slot's `font`) sit under `style:`.

---

## Callout Charts

Use `type: callout` for a bordered message card inside a dashboard tile. Callouts do not run queries; they are static content with semantic coloring driven by `style.tone:`.

Runtime chart failures (query errors, data-shape mismatches, render failures) also render as callout cards with explicit `tone: negative`, using the same renderer and `style.charts.callout` structure defaults.

### Minimum Required for a Callout

| dbt Charts field | Maps to renderer behavior | Allowed values | Notes |
|---|---|---|---|
| `type: callout` | Callout renderer | Literal `callout` | Selects the callout renderer. |
| `message` | Body text | String | Required. Wraps inside the tile width. |
| `title` | Heading | String | Optional heading above `message`. |
| `style.tone` | Palette role | `info`, `positive`, `negative`, `warning` | Optional. Defaults to `info`. |

```yaml {contract=board-root}
charts:
  migration_warning:
    type: callout
    title: Migration warning
    message: >
      Two tiles could not be migrated automatically. Review the source
      dashboard before publishing.
    style:
      tone: warning

rows:
  - migration_warning
```

Theme defaults live under `style.charts.callout` (padding, border, title/message typography). Per-chart `style.tone:` selects which palette role supplies `background`, `border`, and text colors (`info.*`, `positive.*`, `negative.*`, or `warning.*`).

---

## Spark Bar Charts

`type: spark_bar` is a compact ranked text-plus-bar chart used by inspector-style
summaries. For authored dashboards, prefer a table with an inline spark column
(`spark.type: bar` or `spark.type: bar-normalize`) when you need custom column
order, formatting, row styling, or conditional formatting.

When you do use `type: spark_bar`, the bars run horizontally, so the axes are
the reverse of a vertical chart: `x` is the **numeric** column whose magnitude
sets each bar's length, and `y` is the label column naming each bar. A
non-numeric `x` is an error. `label:` and `value:` are not accepted on
`spark_bar` charts.

With only nonnegative values, every bar grows from the track's left edge. If a
visible row has a negative value, all visible rows share a midpoint: negative
bars grow left, positive bars grow right, and widths scale to the largest
absolute finite visible value. Non-finite values do not draw a fill.

```yaml {contract=board-fragment}
charts:
  owners_ranked:
    type: spark_bar
    query: owner_counts
    x: objects
    y: owner
```

### Spark-Bar Style

| dbt Charts field | Maps to renderer behavior | Allowed values | Notes |
|---|---|---|---|
| `style.max_bars` | row cap | Integer | Maximum number of visible rows before truncation. |
| `style.spark_bar.label.visible` | left label visibility | `true` or `false` | Set `false` to hide labels beside the bars (default: `true`). |
| `style.spark_bar.count.visible` | right count visibility | `true` or `false` | Set `false` to hide right-side numeric counts (default: `true`). |
| `style.spark_bar.bar.height` | row/bar height | Integer | Controls compactness of the display. |
| `style.spark_bar.bar.color` | bar fill color | Color value | Spark-bar paint surface. |
| `style.spark_bar.bar.background` | bar track color | Color value | Spark-bar background/track paint surface. |

---

## Related

- [Charts Overview](index.md)
- [Point Charts](point-charts.md)
- [Chart Interactions](interactions.md)

# Small Multiples (https://docs.dbtcharts.com/charts/small-multiples/)

# Small Multiples

Small multiples repeat one chart grammar across the values of a field, so every
panel shares the same encoding and scale and only the data differs. They answer
"show me this same chart, one per region" without hand-building a chart per
value.

Add a chart-level `multiples:` property to any cartesian chart (`area`, `bar`,
`line`, `scatter`, `heatmap`). It names a `rows` field, a `columns` field, or
both; at least one is required. The query still owns the data; `multiples:`
only says which field partitions it into panels.

## Row stack (`rows`)

A `rows` field stacks one panel per value in a single column. The panel's
identity reads as a label to the left of each row, not as a per-panel title.

```yaml {contract=board-root}
queries:
  monthly:
    columns: [month, region, revenue]
    values:
      - [Jan, West, 120]
      - [Feb, West, 140]
      - [Jan, East, 80]
      - [Feb, East, 90]
charts:
  revenue_by_region:
    type: area
    query: monthly
    x: month
    y: revenue
    multiples:
      rows: region
```

## Column strip (`columns`)

A `columns` field lays the panels out side by side, one per value, with the
value labeled along the top edge:

```yaml {contract=board-root}
queries:
  monthly:
    columns: [month, region, revenue]
    values:
      - [Jan, West, 120]
      - [Feb, West, 140]
      - [Jan, East, 80]
      - [Feb, East, 90]
charts:
  revenue_by_region:
    type: area
    query: monthly
    x: month
    y: revenue
    multiples:
      columns: region
```

## Grid (`rows` + `columns`)

Set both to lay the panels out as a matrix: `rows` down the left edge,
`columns` across the top:

```yaml {contract=board-root}
queries:
  monthly:
    columns: [month, region, product, revenue]
    values:
      - [Jan, West, Widgets, 120]
      - [Jan, West, Gadgets, 60]
      - [Jan, East, Widgets, 80]
      - [Jan, East, Gadgets, 40]
charts:
  revenue_grid:
    type: area
    query: monthly
    x: month
    y: revenue
    multiples:
      rows: region
      columns: product
```

## Shared vs. independent scale

By default every panel shares one measure scale, so the panels are directly
comparable: a tall panel really is larger than a short one. This is almost
always what you want.

To give each panel its own scale instead (useful when you care about the
*shape* of each series rather than its level) add `scale: independent`:

```yaml {contract=chart-body}
multiples:
  rows: region
  scale: independent   # shared (default) | independent
```

## Shared axes

Under the default `scale: shared`, a small-multiples set draws one shared measure
axis for the whole set rather than repeating a full axis on every panel. When
there is more than one column the shared scale is also drawn on the far edge, so
panels on the right stay readable without tracing back to a single axis on the
left. A horizontal bar is the exception: its y axis carries the categories, so
it is not mirrored. Set `style.axis_y.mirror` explicitly to force that far-edge
axis on or off.

Independent scales and a both-edge axis are contradictory: mirroring one shared
scale to both edges is meaningless when each panel has its own scale, so
combining `scale: independent` with `style.axis_y.mirror: true` is rejected at
compile time.

`scale: independent` changes this: each panel computes and draws its own measure
axis, since there is no longer one shared scale for a single axis to represent.
This applies to the chart's measure axis, normally y, but on a horizontal bar,
where the measure is drawn on x instead, `scale: independent` frees x there.

## Rules

- `multiples:` requires at least one of `rows` or `columns`; set both for a grid.
- Structurally available on the cartesian families only: `area`, `bar`,
  `line`, `scatter`, `heatmap`.
- A chart cannot combine `multiples:` with a `support_table:`: the attached table
  has no per-panel meaning.
- Endpoint labels and `multiples:` cannot coexist either: the label rail names
  series for a single panel, and a faceted chart has no single panel for it to
  sit beside. You do not normally have to do anything about this: on `bar`,
  `line`, and `area` (the families that carry the endpoint-label rail),
  setting `multiples:` turns the endpoint-label default off and moves the
  color legend above the panels to name the series instead, so one legend
  reads across the whole grid. `scatter` and `heatmap` have no endpoint-label
  rail to begin with, so faceting them leaves their legend where it was. Only
  a chart that *opts in* to `style.endpoint_labels.visible: true` alongside
  `multiples:` is rejected.
- An own-query overlay `layers:` entry (one authoring its own `query:`, not
  reusing the base chart's) is rejected when that query returns the
  `rows`/`columns` field; Vega-Lite has no mechanism to hand a different
  inline dataset to each panel of one layered spec, so per-panel layer data
  cannot be honored and the chart refuses to render rather than repeat it
  wrongly. A layer whose query does *not* return that field is unaffected: it
  renders identically in every panel, which is correct for a chart-wide
  reference (a target line across the whole grid, for example).

## Related

- [Chart types](types.md)
- [Axis labels](axis-labels.md)
- [YAML reference](../reference/yaml-reference.md)

# Layered Charts (https://docs.dbtcharts.com/charts/layered-charts/)

# Layered Charts

`bar`, `line`, `area`, and `scatter` charts accept a `layers:` field to overlay
additional marks (for example a bar and a line) on one shared x-axis.
They're the way to build combo charts and **dual-axis charts**, where two
series with very different scales (say, revenue in dollars and a conversion
rate in percent) each get their own y-axis instead of one squashing the other.

There is no separate `type: layered`; the base chart is a real chart type
(`bar`, `line`, `area`, or `scatter`) that sets the primary mark, `x`, `y`, and
`query`; additional marks go in `layers:`.

---

## Minimum Required for a Combo Chart

| dbt Charts field | Notes |
|---|---|
| `type` | `bar`, `line`, `area`, or `scatter`; the base (primary) mark. |
| `x` | Shared x-axis column across the base and every layer. |
| `y` | Base chart's own y column. |
| `layers` | List of overlay layers. Each layer needs its own `type` (`bar`, `line`, `area`, or `scatter`) and `y`. |

### Minimum Example

```yaml {contract=board-root}
queries:
  monthly_funnel:
    columns: [month, revenue, conversion_pct]
    values:
      - ["2026-01", 42000, 3.1]
      - ["2026-02", 51000, 3.4]
      - ["2026-03", 68000, 4.2]
      - ["2026-04", 60000, 3.9]

charts:
  revenue_vs_conversion:
    query: monthly_funnel
    type: bar
    title: Revenue vs. Conversion Rate
    x: month
    y: revenue
    layers:
      - type: line
        y: conversion_pct
rows:
  - revenue_vs_conversion
```

Without any extra configuration, the base chart and its layers share a single
y-axis, which works fine when the series are on a similar scale, but
squashes one series flat when they aren't (as with revenue vs. a percentage
above).

---

## Dual Y-Axis

Each layer can pin its y-axis to a side with `axis_y.position: left` or
`right`. Pinning any layer gives the layers their own independent scales. A
layer pinned to one side puts the base chart's axis on the other.

!!! warning "Two scales can show a relationship that isn't there"
    Each axis is ranged on its own, so where the marks cross, which one sits
    higher, and how closely they track come from the axis ranges, not the
    data. dbt Charts warns about this with `WARN-DUAL-AXIS-COMPETING-SCALES`.
    Alternatives:

    - Show each measure in its own chart, stacked so they share the x-axis.
    - Index both series to a common start (for example 100) in the query so
      they share one axis.
    - Use a scatter to show how one measure moves with the other.
    - For the same quantity in another unit (°F/°C, $/€), remove the layer and
      relabel the chart's opposite edge with `style.axis_y.mirror` and an
      `expr` that converts the value, such as
      `format(datum.value * 1.8 + 32, '.0f')`: one scale, two unit labels.
    - When your audience expects the form, list the code in the chart's
      `warnings_ignore:`.

```dbt-charts-example
queries:
  monthly_funnel:
    columns: [month, revenue, conversion_pct]
    values:
      - ["2026-01", 42000, 3.1]
      - ["2026-02", 51000, 3.4]
      - ["2026-03", 68000, 4.2]
      - ["2026-04", 60000, 3.9]

charts:
  revenue_vs_conversion:
    query: monthly_funnel
    type: bar
    title: Revenue vs. Conversion Rate
    x: month
    y: revenue
    y_label: Revenue ($)
    layers:
      - type: line
        y: conversion_pct
        axis_y:
          position: right
          title: Conversion (%)
rows:
  - revenue_vs_conversion
```

| dbt Charts field | Allowed values | Notes |
|---|---|---|
| `layers[].axis_y.position` | `left` or `right` | Which side this layer's y-axis renders on. |
| `layers[].axis_y.title` | String | Axis title override for this layer's side. |
| `layers[].axis_y.scale.domain` | `[min, max]` | Pins this layer's y range. When any layer sets `position`, marks outside it are clipped at the plot edge and a warning names the layer. With a single shared axis the base scale wins and this domain is ignored. |
| `layers[].axis_y.scale.clip` | `true` (default) or `false` | `false` lets the marks run past the plot instead of clipping them. |

Setting only `title` (no `position`) keeps a single shared axis. Setting
`position` on any layer, whichever side, makes the scales independent.

---

## Layer Fields

Each entry under `layers:` accepts:

| Field | Notes |
|---|---|
| `type` | `bar`, `line`, `area`, or `scatter`. |
| `y` | Layer's y column (required). |
| `x` | Layer's own x-values, extending the base x-scale. Defaults to the base chart's `x`. |
| `query` | Overrides the base chart's query for this layer; lets a layer plot a different table/query (for example, actuals vs. targets). |
| `label` | Legend label for this layer's series. |
| `color` | Data channel (bare field name) for per-datum color. |
| `axis_y` | `position` (`left`/`right`) and `title`; see [Dual Y-Axis](#dual-y-axis) above. |
| `style` | Marks-only style patch for this layer. |

Vega-Lite `encoding:` is not allowed inside a layer; use the typed channels
above instead.

---

## Group an Overlay by Color

Set a layer's `color` to a column from that layer's query to draw one colored
series per value. This is useful when the base chart shows a total while the
overlay breaks a target or benchmark out by region, team, or segment.

```dbt-charts-example
queries:
  monthly_revenue:
    columns: [month, revenue]
    values:
      - ["2026-01", 42000]
      - ["2026-02", 51000]
      - ["2026-03", 68000]
  regional_targets:
    columns: [month, target, region]
    values:
      - ["2026-01", 40000, East]
      - ["2026-01", 38000, West]
      - ["2026-02", 50000, East]
      - ["2026-02", 47000, West]
      - ["2026-03", 65000, East]
      - ["2026-03", 61000, West]

charts:
  revenue_vs_regional_targets:
    query: monthly_revenue
    type: bar
    title: Revenue and Regional Targets
    x: month
    y: revenue
    layers:
      - type: line
        query: regional_targets
        y: target
        color: region
rows:
  - revenue_vs_regional_targets
```

The line layer is grouped by `region`; its East and West series receive
separate colors and legend entries. The base revenue bars remain a separate
series in the same legend.

---

## Trend Lines

Fit a trend line in SQL and overlay it as a `line` layer. This is the
recommended way to add one, not a workaround: the query layer already owns
aggregation and grain, so a fitted regression is just another computed
series, the same as a rolling average or a `GROUP BY`. Keeping the fit in SQL
also means the trend line always reflects the exact rows the base chart
plots, since both come from the same source data.

Most warehouses ship a linear-regression aggregate for this: `REGR_SLOPE(y, x)`
and `REGR_INTERCEPT(y, x)` compute the slope and intercept of the
least-squares line over `(x, y)` pairs, and both work as window functions
with `OVER ()`, so the fit and the per-row detail come out of one query.
DuckDB, Postgres, and Snowflake support them natively. BigQuery and Redshift
ship neither; there, spell the fit out in plain arithmetic, which works on
both:

```sql
slope     = (AVG(x*y) - AVG(x)*AVG(y)) / (AVG(x*x) - AVG(x)*AVG(x))
intercept = AVG(y) - slope * AVG(x)
```

On BigQuery you can use `COVAR_POP(y, x) / VAR_POP(x)` for the slope instead.
Redshift has no covariance aggregate at all — it lists `COVAR_POP` alongside
the `REGR_*` family among the PostgreSQL functions it does not support — so
the arithmetic form above is the one to use there.

```dbt-charts-example
source: db

queries:
  monthly_revenue:
    sql: |
      SELECT month, revenue
      FROM dundersign_serving.monthly_metrics
      ORDER BY month

  revenue_trend:
    sql: |
      WITH indexed AS (
        SELECT
          month,
          revenue,
          ROW_NUMBER() OVER (ORDER BY month) AS month_index
        FROM dundersign_serving.monthly_metrics
      )
      SELECT
        month,
        REGR_INTERCEPT(revenue, month_index) OVER ()
          + REGR_SLOPE(revenue, month_index) OVER () * month_index AS trend_revenue
      FROM indexed
      ORDER BY month

charts:
  revenue_vs_trend:
    query: monthly_revenue
    type: line
    title: Revenue vs. Trend
    x: month
    y: revenue
    style:
      axis_y:
        labels:
          format: currency_whole
    layers:
      - type: line
        query: revenue_trend
        y: trend_revenue
        label: Trend
rows:
  - revenue_vs_trend
```

`revenue_trend` numbers each row with `ROW_NUMBER()` rather than a date
function, since date-arithmetic syntax differs by warehouse. It then fits a
straight line against that index and plots the fitted values as their own
series, sharing the base chart's `month` x-axis via `query:` on the layer (see
[Layer Fields](#layer-fields) above). Point this pattern at any query with a
stable grain and it travels unchanged.

A built-in trend option is being explored separately. This SQL-and-layer
pattern is correct today, and will remain a valid, lower-level way to
compute a trend series even after a built-in option ships.

---

## Target & Reference Lines

dbt Charts automatically draws certain reference lines on bar, line, area, scatter, and layered charts; you don't author these, but it helps to know when they appear so they aren't mistaken for a data mark:

| Reference line | When it appears |
|---|---|
| Zero baseline | Bar charts get one whenever the visible y-range includes zero, which it normally does, since a bar's length is measured from zero; a bar chart cannot turn it off, and `zero: false` on one is an error unless the bars float (`y_start`). Line, area, and scatter charts get one on the same condition; turn it off with `style.axis_y.scale.continuous.zero: false`, which refits the range to the data (an area chart warns that its fill is cropped). No chart gets one when the visible y-range excludes zero, whether you pinned the range yourself with `scale.continuous.domain` or the chart fitted it to data that never reaches zero: there is no position on the plot to draw it at. A bar layer inside a layered chart follows the shared scale the same way rather than overriding it. On a [dual-axis](#dual-y-axis) chart, the base and each layer pinned to the opposite side are evaluated independently against their own data by these same rules; a layer sharing the base's side doesn't draw a separate one. A normalize-stacked (`stack: normalize`) chart shows 0%/100% lines instead (see below); a streamgraph (`stack: center`) chart and a chart under `multiples: {scale: independent}` show neither. On a horizontal bar this line renders as a vertical rule on the x channel, but it is still governed by `style.axis_y`, the axis that carries the measure regardless of orientation. Suppress it on its own with `grid.threshold.visible: false`, which leaves the axis's other gridlines in place. |
| 0% / 100% top lines | Normalize-stacked bar and area charts (`stack: normalize`), in place of the plain zero baseline. |
| 100% unity line (measure axis) | Bar, line, area, scatter, and layered charts formatted as a percent (`axis_y.labels.format: percent_whole` or similar), when the chart's effective measure domain reaches 1.0; the common guide for retention, conversion, and NRR charts stored as ratios. |
| 0 / 100% lines on a quantitative x axis | Independent of the measure axis above: any chart with its own quantitative x column (for example a scatter plotting one ratio against another) earns its own zero baseline when 0 falls inside the x-domain, and its own unity line when x is itself percent-formatted and the x-domain reaches 1.0. A horizontal bar's x is already the measure axis covered by the rows above, so it never gets a second, independent x rule. |

These reference lines pick up their color and stroke width from the relevant axis's `grid.threshold` (see [Grid Lines](../styling.md#grid-lines)): `style.axis_y.grid.threshold` for the measure-axis rows above, `style.axis_x.grid.threshold` for the independent quantitative-x rows. Each family can be suppressed on its own axis with `grid.threshold.visible: false`, without touching that axis's other gridlines; a blanket `grid.visible: false` on the same axis suppresses the reference line too.

There is currently no way to author a fixed, arbitrary threshold or target line (for example a sales quota drawn as a flat line across the whole chart) beyond the automatic reference lines above.

---

## Related

- [Charts Overview](index.md)
- [Bar Charts](bar-charts.md)
- [Line Graphs](line-graphs.md)
- [More Chart Types](more-types.md)

# Chart types and extensibility (https://docs.dbtcharts.com/charts/extensibility/)

# Chart types and extensibility

dbt Charts ships a fixed set of chart types, and many more shapes compose from
them. This page lists both, then covers what to do when the shape you want is
not there.

---

## The seventeen chart types

Every chart names one of these with `type:`. Sixteen are built in; `custom` is
your own, drawn by a template. An unknown name fails validation.

| Type | What it draws | Docs |
|---|---|---|
| `bar` | Bars, vertical or horizontal, grouped or stacked | [Bar charts](bar-charts.md) |
| `histogram` | Auto-binned bars | [More chart types](more-types.md#histogram) |
| `line` | Lines over an ordered axis | [Line graphs](line-graphs.md) |
| `area` | Filled lines, stacked or not | [Area charts](area-charts.md) |
| `scatter` | Points, with optional size and color | [Point charts](point-charts.md) |
| `heatmap` | A color-coded matrix | [More chart types](more-types.md#heatmap) |
| `pie` | Sectors of a whole | [Sector charts](sector-charts.md) |
| `donut` | Sectors with a hole | [Sector charts](sector-charts.md) |
| `kpi` | One value, large | [Chart types](types.md#kpi-display) |
| `callout` | An annotated value card | [Chart types](types.md) |
| `table` | Rows and columns | [Tables](tables.md) |
| `geoshape` | Geographic shapes | [Maps](maps.md) |
| `map` | Filled regions | [Maps](maps.md) |
| `point_map` | Location markers | [Maps](maps.md) |
| `bubble_map` | Sized location markers | [Maps](maps.md) |
| `spark_bar` | An inline mini bar chart | [More chart types](more-types.md) |
| `custom` | Draws your own template; ready-made templates for Sankey, funnel, gauge, and more | [Custom charts](custom.md), [Custom chart examples](custom-examples.md) |

All sixteen built-in types on one board, grouped by family, from the Playground's
[chart families](https://play.dbtcharts.com/?example=charts%2Fchart-families.yml)
example:

```dbt-charts-example {format=render-only}
title: Chart families
queries:
  product_revenue:
    source: examples_db
    sql: |
      SELECT product, SUM(revenue) AS revenue
      FROM ecommerce_orders
      GROUP BY product
      ORDER BY revenue DESC
  region_category_revenue:
    source: examples_db
    sql: |
      SELECT region, category, SUM(revenue) AS revenue
      FROM ecommerce_orders
      GROUP BY region, category
      ORDER BY region, category
  region_category_category_share:
    source: examples_db
    sql: |
      SELECT
        region,
        category,
        SUM(revenue) / SUM(SUM(revenue)) OVER (PARTITION BY region)
          AS category_share
      FROM ecommerce_orders
      GROUP BY region, category
      ORDER BY region, category
  company_growth:
    source: examples_db
    sql: |
      SELECT company, growth_rate
      FROM company_revenue
      ORDER BY growth_rate DESC
  monthly_active_users:
    source: db
    sql: |
      SELECT month, active_users
      FROM dundersign_serving.monthly_metrics
      WHERE month > (SELECT MIN(month) FROM dundersign_serving.monthly_metrics)
        AND month < (SELECT MAX(month) FROM dundersign_serving.monthly_metrics)
      ORDER BY month
  weekly_revenue_by_category:
    source: examples_db
    sql: |
      SELECT DATE_TRUNC('week', date) AS week, category, SUM(revenue) AS revenue
      FROM ecommerce_orders
      GROUP BY week, category
      ORDER BY week, category
  order_scatter:
    source: examples_db
    sql: |
      SELECT category, units_sold, revenue
      FROM ecommerce_orders
  company_growth_margin:
    source: examples_db
    sql: |
      SELECT company, region, growth_rate, margin, headcount
      FROM company_revenue
  category_revenue:
    source: examples_db
    sql: |
      SELECT category, SUM(revenue) AS revenue
      FROM ecommerce_orders
      GROUP BY category
      ORDER BY revenue DESC
  document_status:
    source: dundersign_db
    sql: |
      SELECT status, COUNT(*) AS document_count
      FROM documents
      GROUP BY status
      ORDER BY document_count DESC
  region_product_revenue:
    source: examples_db
    sql: |
      SELECT region, product, SUM(revenue) AS revenue
      FROM ecommerce_orders
      GROUP BY region, product
      ORDER BY region, product
  monthly_revenue:
    source: db
    sql: |
      SELECT month, strftime(month, '%b %Y') AS month_label, revenue
      FROM dundersign_serving.monthly_metrics
      WHERE month > (SELECT MIN(month) FROM dundersign_serving.monthly_metrics)
        AND month < (SELECT MAX(month) FROM dundersign_serving.monthly_metrics)
      ORDER BY month
  sales_summary:
    source: examples_db
    sql: |
      SELECT SUM(revenue) AS revenue, SUM(units_sold) AS units_sold
      FROM ecommerce_orders
  recent_orders:
    source: examples_db
    sql: |
      SELECT date, product, category, region, revenue, units_sold
      FROM ecommerce_orders
      ORDER BY date DESC, revenue DESC
      LIMIT 8
  new_england_density:
    columns: [state_code, population_density]
    values:
      - ["9", 742]
      - ["23", 44]
      - ["25", 901]
      - ["33", 154]
      - ["44", 1022]
      - ["50", 68]
  new_england_stores:
    columns: [city, lat, lng, revenue]
    values:
      - ["Boston", 42.3601, -71.0589, 980000]
      - ["Providence", 41.8240, -71.4128, 520000]
      - ["Portland", 43.6591, -70.2568, 410000]
      - ["Hartford", 41.7658, -72.6734, 460000]
      - ["Burlington", 44.4759, -73.2121, 290000]
      - ["Manchester", 42.9956, -71.4548, 380000]
charts:
  vertical_bar:
    query: monthly_revenue
    type: bar
    title: Monthly revenue
    subtitle: "type: bar draws vertical columns for a date-based x axis"
    x: month
    y: revenue
    style:
      orientation: vertical
      axis_y:
        labels:
          format: currency_whole
  horizontal_bar:
    query: product_revenue
    type: bar
    title: Top products by revenue
    subtitle: "style.orientation: horizontal ranks long category labels"
    x: product
    y: revenue
    sort:
      by: revenue
      order: desc
    style:
      orientation: horizontal
      axis_y:
        labels:
          format: currency_whole
  grouped_bar:
    query: region_category_revenue
    type: bar
    title: Revenue by region and category
    subtitle: "a color field with no style.stack groups bars side by side"
    x: region
    y: revenue
    color: category
    style:
      axis_y:
        labels:
          format: currency_whole
  stacked_bar:
    query: region_category_revenue
    type: bar
    title: Revenue by region, stacked by category
    subtitle: "style.stack: zero stacks bars from one shared baseline"
    x: region
    y: revenue
    color: category
    style:
      stack: zero
      axis_y:
        labels:
          format: currency_whole
  stacked_bar_normalized:
    query: region_category_category_share
    type: bar
    title: Category mix of revenue by region
    subtitle: "style.stack: normalize shows each category's share of the total"
    x: region
    y: category_share
    color: category
    style:
      stack: normalize
      axis_y:
        labels:
          format: percent_whole
  mirror_bar:
    query: company_growth
    type: bar
    title: Quarterly revenue growth by company
    subtitle: "bars run either side of zero once a value turns negative"
    x: company
    y: growth_rate
    sort:
      by: growth_rate
      order: desc
    style:
      orientation: horizontal
      axis_y:
        labels:
          format: percent_delta
  line_single:
    query: monthly_active_users
    type: line
    title: Active users over time
    subtitle: "type: line traces one series across a date-based x axis"
    x: month
    y: active_users
  line_multi:
    query: weekly_revenue_by_category
    type: line
    title: Weekly revenue by category
    subtitle: "color: draws one line per category, each named on the chart"
    x: week
    y: revenue
    color: category
    style:
      axis_y:
        labels:
          format: currency_whole
  area_stacked:
    query: weekly_revenue_by_category
    type: area
    title: Composition of weekly revenue
    subtitle: "style.stack: zero shows changing composition over time"
    x: week
    y: revenue
    color: category
    style:
      stack: zero
      axis_y:
        labels:
          format: currency_whole
  scatter_basic:
    query: order_scatter
    type: scatter
    title: Revenue vs. units sold
    subtitle: "type: scatter plots two measures against each other"
    x: units_sold
    y: revenue
    color: category
    x_label: Units Sold
    y_label: Revenue
    style:
      axis_y:
        labels:
          format: currency_whole
  bubble_scatter:
    query: company_growth_margin
    type: scatter
    title: Growth, margin, and headcount by company
    subtitle: "size: maps a third measure to point area"
    x: growth_rate
    y: margin
    size: headcount
    color: region
    x_label: Growth rate
    y_label: Margin
    style:
      axis_x:
        labels:
          format: percent_whole
      axis_y:
        labels:
          format: percent_whole
  pie_basic:
    query: category_revenue
    type: pie
    title: Revenue share by category
    subtitle: "type: pie divides a whole into angular slices"
    theta: revenue
    color: category
  donut_basic:
    query: document_status
    type: donut
    title: Documents by status
    subtitle: "type: donut is a pie with a hole in the middle"
    theta: document_count
    color: status
  heatmap_basic:
    query: region_product_revenue
    type: heatmap
    title: Revenue by region and product
    subtitle: "color: encodes the value as a shaded cell instead of a bar"
    x: region
    y: product
    color: revenue
  spark_revenue:
    query: monthly_revenue
    type: spark_bar
    title: Revenue trend
    subtitle: "type: spark_bar is a compact inline trend, no axes"
    x: revenue
    y: month_label
  histogram_revenue:
    query: order_scatter
    type: histogram
    title: Order revenue distribution
    subtitle: "type: histogram bins a continuous field"
    x: revenue
  revenue_kpi:
    query: sales_summary
    type: kpi
    label: Total revenue
    value: revenue
  reading_callout:
    type: callout
    title: Read with care
    message: >
      Units are shipped, not ordered. Returns are netted out the following
      month, so the latest month reads low until it closes.
    style:
      tone: warning
  orders_table:
    query: recent_orders
    type: table
    title: Recent orders
    subtitle: "type: table lists rows with formatted columns"
  density_map:
    query: new_england_density
    type: map
    title: Population density
    subtitle: "type: map (also geoshape) fills regions by a value"
    geo:
      source: us-states
    lookup: state_code
    value: population_density
  store_points:
    query: new_england_stores
    type: point_map
    title: Store locations
    subtitle: "type: point_map marks exact coordinates"
    latitude: lat
    longitude: lng
    geo_source: us-states
  store_bubbles:
    query: new_england_stores
    type: bubble_map
    title: Store revenue
    subtitle: "type: bubble_map sizes each marker by a value"
    latitude: lat
    longitude: lng
    size: revenue
    geo_source: us-states
rows:
- text: |
    dbt Charts draws every chart type below from the same small set of
    typed fields, `x`, `y`, `color`, `theta`, `value`, and a typed `style`
    block. All sixteen built-in types are here, each in a natural business
    use, grouped by family.
- title: Bars
  rows:
  - cols:
    - vertical_bar
    - horizontal_bar
    - grouped_bar
  - cols:
    - stacked_bar
    - stacked_bar_normalized
    - mirror_bar
  - cols:
    - histogram_revenue
- title: Lines and areas
  rows:
  - cols:
    - line_single
    - line_multi
    - area_stacked
- title: Points
  rows:
  - cols:
    - scatter_basic
    - bubble_scatter
- title: Sectors and grids
  rows:
  - cols:
    - pie_basic
    - donut_basic
    - heatmap_basic
- title: Values and tables
  rows:
  - cols:
    - revenue_kpi
    - reading_callout
    - spark_revenue
  - cols:
    - orders_table
- title: Maps
  rows:
  - cols:
    - density_map
    - store_points
    - store_bubbles
```

---

## Composed charts

A composed chart is a shape you ask for by name that has no `type:` of its own.
Each is built from the types above plus layers, overlays and styling, and each
stays a plain, typed board file. The
[composed chart shapes](https://play.dbtcharts.com/?example=charts%2Fcomposed-chart-shapes.yml)
example in the Playground shows these side by side:

| Shape | Built from |
|---|---|
| Lollipop | A thin `bar` with a point layered on its end |
| Bullet | A `bar` measure over banded target bars |
| Slope | A `line` with two ordered categories on the x axis |
| Bump | A `line` of ranks over time |
| Dot plot | A `scatter` with a category on one axis |
| Streamgraph | An `area` with `style.stack: center`, a shared centered baseline |

```dbt-charts-example {format=render-only}
title: Composed chart shapes
notes: shapes an author asks for by name that dbt Charts has no `type:` for. Each cell is the
  natural recipe for one of them, rendered so the verdict is a picture and not an opinion.
queries:
  # Hand-shaped so the streamgraph reads like one: bursts, S-curves, a fade
  # and steady baselines, each on its own schedule.
  flows:
    source: examples_db
    sql: |
      WITH series AS (
        SELECT
          t,
          DATE '2024-01-01' + (CAST(t AS INTEGER) * 7) AS date,
          unnest(['Holiday Rush', 'Word of Mouth', 'Summer Fling', 'Slow Bleed',
                  'Steady Staples', 'Background Noise', 'New Arrival']) AS category
        FROM generate_series(0, 51) AS s(t)
      )
      SELECT
        date,
        category,
        ROUND(CASE category
          WHEN 'Holiday Rush' THEN 400 * EXP(-POWER((t - 45) / 3.5, 2))
          WHEN 'Summer Fling' THEN 260 * EXP(-POWER((t - 24) / 8.0, 2))
          WHEN 'Word of Mouth' THEN 300 / (1 + EXP(-0.22 * (t - 30)))
          WHEN 'New Arrival' THEN 220 / (1 + EXP(-0.30 * (t - 40)))
          WHEN 'Slow Bleed' THEN 260 / (1 + EXP(0.18 * (t - 14)))
          WHEN 'Steady Staples' THEN 150 + 12 * SIN(t * 0.35) + 6 * SIN(t * 0.9 + 1.3)
          WHEN 'Background Noise' THEN 60 + 12 * SIN(t * 0.21) + 7 * SIN(t * 0.53 + 0.7) + 5 * SIN(t * 1.31 + 2.1)
        END, 2) AS revenue
      FROM series
      ORDER BY date, category
  entities:
    source: examples_db
    sql: |
      SELECT
        'Region ' || chr((64 + e)::INTEGER)                        AS category,
        round(30 + 55 * abs(sin(e * 1.7)), 1)                      AS value,
        round(50 + 30 * abs(cos(e * 1.1)), 1)                      AS target,
        round(20 + 40 * abs(sin(e * 0.9)), 1)                      AS value_2019,
        round(35 + 50 * abs(sin(e * 1.4)), 1)                      AS value_2024,
        round(28 + 45 * abs(cos(e * 0.6)), 1)                      AS value_2029,
        round(30 + 55 * abs(sin(e * 1.7)) - 12, 1)                 AS low,
        round(30 + 55 * abs(sin(e * 1.7)) + 12, 1)                 AS high
      FROM generate_series(1, 8) t(e)
      ORDER BY e
  # Bullet's qualitative ranges: three cumulative bands per category, stacked to
  # build the background the value bar is read against.
  bullet_bands:
    source: examples_db
    sql: |
      SELECT 'Unit ' || chr((64 + e)::INTEGER) AS category, band, size, ord
      FROM generate_series(1, 5) t(e)
      CROSS JOIN (VALUES ('Poor', 45.0, 1), ('Satisfactory', 25.0, 2), ('Good', 30.0, 3))
        AS b(band, size, ord)
      ORDER BY e, ord
  bullet_measures:
    source: examples_db
    sql: |
      SELECT
        'Unit ' || chr((64 + e)::INTEGER)          AS category,
        round(45 + 40 * abs(sin(e * 1.3)), 1)      AS actual,
        round(70 + 15 * abs(cos(e * 0.8)), 1)      AS goal
      FROM generate_series(1, 5) t(e)
      ORDER BY e
  dots:
    source: examples_db
    sql: |
      WITH base AS (
        SELECT
          'Region ' || chr((64 + e)::INTEGER)          AS category,
          round(20 + 40 * abs(sin(e * 0.9)), 1)        AS v2019,
          round(35 + 50 * abs(sin(e * 1.4)), 1)        AS v2024,
          round(28 + 45 * abs(cos(e * 0.6)), 1)        AS v2029
        FROM generate_series(1, 8) t(e)
      )
      SELECT category, '2019' AS series, v2019 AS value, v2019 AS rank_by FROM base
      UNION ALL
      SELECT category, '2024', v2024, v2019 FROM base
      UNION ALL
      SELECT category, '2029', v2029, v2019 FROM base
      ORDER BY rank_by DESC, series
  pairs:
    source: examples_db
    sql: |
      SELECT 'Region ' || chr((64 + e)::INTEGER) AS entity, 'Before' AS period, 1 AS ord,
             round(20 + 40 * abs(sin(e * 0.9)), 1) AS value
      FROM generate_series(1, 6) t(e)
      UNION ALL
      SELECT 'Region ' || chr((64 + e)::INTEGER), 'After', 2,
             round(35 + 50 * abs(sin(e * 1.4)), 1)
      FROM generate_series(1, 6) t(e)
      ORDER BY ord, entity
  ranks:
    source: examples_db
    sql: |
      SELECT entity, year, rank
      FROM (VALUES
        ('Region A', 2019, 1),
        ('Region B', 2019, 2),
        ('Region C', 2019, 3),
        ('Region D', 2019, 4),
        ('Region E', 2019, 5),
        ('Region F', 2019, 6),
        ('Region A', 2020, 1),
        ('Region B', 2020, 2),
        ('Region E', 2020, 3),
        ('Region C', 2020, 4),
        ('Region D', 2020, 5),
        ('Region F', 2020, 6),
        ('Region A', 2021, 1),
        ('Region E', 2021, 2),
        ('Region B', 2021, 3),
        ('Region C', 2021, 4),
        ('Region D', 2021, 5),
        ('Region F', 2021, 6),
        ('Region E', 2022, 1),
        ('Region A', 2022, 2),
        ('Region B', 2022, 3),
        ('Region D', 2022, 4),
        ('Region C', 2022, 5),
        ('Region F', 2022, 6),
        ('Region E', 2023, 1),
        ('Region A', 2023, 2),
        ('Region B', 2023, 3),
        ('Region D', 2023, 4),
        ('Region F', 2023, 5),
        ('Region C', 2023, 6)
      ) AS t(entity, year, rank)
      ORDER BY year, rank
charts:
  lollipop:
    query: entities
    type: bar
    title: Lollipop
    subtitle: "type: bar thinned to a stem with a scatter layer on the same measure."
    x: category
    y: value
    style:
      orientation: vertical
      legend:
        visible: false
      color:
        categorical:
          palette:
          - category[2].deep
          - category[2].deep
      marks:
        bar:
          band_width: 0.04
    layers:
    - type: scatter
      y: value
      style:
        marks:
          point:
            size: 190
            filled: true
  bullet:
    query: bullet_bands
    type: bar
    title: Bullet
    subtitle: "stacked qualitative bands, a narrow value bar layer, and a step-band goal marker. Vertical only: the canonical horizontal bullet cannot draw the goal marker, because the step band is measured along the horizontal axis."
    x: category
    y: size
    color: band
    style:
      orientation: vertical
      stack: zero
      # The bands are a semantic ramp, so they stack in the query's own order
      # (poor, satisfactory, good) rather than the default ascending-by-value.
      stack_order: data
      # The chart is about the measures, not the backdrop, so the legend leads
      # with them; the bands then follow top-down as they stack.
      legend:
        values:
        - Actual
        - Goal
        - Good
        - Satisfactory
        - Poor
      # Slots follow the color domain (poor, satisfactory, good, actual, goal),
      # so the three band grays run dark -> light as the band improves: worse
      # bands carry more ink, and the ramp reads as one sequence.
      color:
        categorical:
          palette:
          - "#6E7378"
          - "#A8ADB3"
          - "#D5D8DC"
          - "#16181B"
          - "#16181B"
    layers:
    - type: bar
      query: bullet_measures
      y: actual
      label: Actual
      style:
        marks:
          bar:
            band_width: 0.35
    - type: line
      query: bullet_measures
      y: goal
      label: Goal
      style:
        marks:
          line:
            curve: step
            connect: false
  slope:
    query: pairs
    type: line
    title: Slope
    subtitle: "type: line with a two-category x and color: on the entity."
    x: period
    y: value
    color: entity
    style:
      axis_x:
        title:
          visible: false
        grid:
          visible: true
          color: "#B8BCC4"
          width: 1.5
      axis_y:
        title:
          visible: false
        grid:
          visible: true
  bump:
    query: ranks
    type: line
    title: Bump
    subtitle: "type: line on a rank measure with a descending axis_y.scale.continuous.domain."
    x: year
    y: rank
    color: entity
    style:
      axis_x:
        title:
          visible: false
      axis_y:
        scale:
          continuous:
            domain: [6, 1]
  streamgraph:
    query: flows
    type: area
    title: Streamgraph
    subtitle: "type: area with style.stack: center, so the bands share a centered baseline instead of the axis."
    x: date
    y: revenue
    color: category
    style:
      stack: center
  dot_plot:
    query: dots
    type: scatter
    title: Dot plot
    subtitle: "type: scatter over long-format rows with color: on the series, no layers, so the measure axis stays the measure axis when the chart is rotated."
    x: value
    y: category
    color: series
    sort:
      by: rank_by
      order: desc
    style:
      axis_x:
        title:
          visible: false
      axis_y:
        title:
          visible: false
rows:
- cols:
  - lollipop
  - bullet
  - slope
- cols:
  - bump
  - dot_plot
  - streamgraph
```

The building blocks are documented on their own pages:
[layered charts](layered-charts.md) for stacking marks on one chart,
[small multiples](small-multiples.md) for repeating one chart across a
dimension, and [interactions](interactions.md) for the controls around them.

---

## When a shape is missing

Try these roughly in order.

**Compose it.** Most editorial shapes are a known type plus a layer or a
style. Start from the closest built-in type and read
[layered charts](layered-charts.md) before assuming you need something new.

**Draw it with a template.** `type: custom` draws a chart from a Jinja SVG
template that reads the query rows and the board's style. Sankey diagrams,
funnels, gauges, radial bars, XmR charts, pictograms, waffles, and radar
charts all have ready-made templates. See [Custom charts](custom.md) and
[Custom chart examples](custom-examples.md).

**Draw it in a text block.** A `text:` block is Markdown, so it can carry an
image, including an SVG you rendered elsewhere:

```yaml {contract=board-fragment}
text: |
  ![Sankey of signups to paid](assets/signup-sankey.svg)
```

See [Images](../boards/content.md#images).

**Turn on raw HTML.** On boards you host yourself, `html_policy: trusted-raw`
at the board root lets a `text:` block carry raw HTML through a tag allowlist.
The allowlist covers structure, headings, inline text, lists, tables and
images. `<svg>`, `<canvas>`, `<script>` and `<style>` are dropped. dbt Charts
Cloud caps the policy below this tier, so raw HTML does not render there. See
[HTML policy](../boards/html-policy.md).

**Render it somewhere else.** `dct render` exports a board to SVG, PNG, PDF or
HTML, so a board can be one piece of a larger page. See
[Output formats](../cli/render.md#output-formats).

**Ask for the type.** If a shape keeps coming up, open an issue at
[dbt-labs/dbt-charts](https://github.com/dbt-labs/dbt-charts/issues) with a
sketch of it. The list above grows from those requests.

Arbitrary Vega-Lite (`spec`, `mark`, `encoding`, `transform`, and the
composition operators) is rejected on the authored surface on purpose: every
board stays a typed, reviewable file that renders the same everywhere. A
custom chart keeps that promise: its template is a file in the project, its
channels and options are declared and validated, and its output is checked SVG.

# Axis Scales: Log, Pow, and Symlog (https://docs.dbtcharts.com/charts/axis-scales/)

# Axis Scales: Log, Pow, and Symlog

dbt Charts's default measure-axis scale is linear. When a metric spans several
orders of magnitude (population counts, payload masses, request latencies)
a linear scale compresses small values into an unreadable sliver near zero.
Set `scale.continuous.type` on the measure axis to switch to a logarithmic, power, or
symmetric-log scale instead.

## `type: log`

`axis_y.scale.continuous.type: log` is first-class on `line` and `area` charts: dbt Charts
validates the authoring surface (see below) and lets Vega-Lite own tick
placement natively (log-decade ticks, computed from the data, never a fixed
tick count).

A log scale is undefined at and below zero, so it is rejected whenever the
y-axis data contains a value that is 0 or negative; see `ERR-LOG-SCALE-REQUIRES-POSITIVE-DATA`
in the [error reference](../reference/errors.md). If your data can include 0 or
negative values, use `type: symlog` instead; it behaves like a log scale away
from zero but stays defined through it.

```dbt-charts-example
source: examples_db
queries:
  populations:
    type: values
    columns: [year, population]
    values:
      - ["1800", 990000000]
      - ["1900", 1650000000]
      - ["1950", 2536000000]
      - ["2000", 6127000000]
      - ["2025", 8200000000]
charts:
  world_population_log:
    query: populations
    type: line
    title: World Population (log scale)
    x: year
    y: population
    style:
      axis_y:
        scale:
          continuous:
            type: log
rows:
  - world_population_log
```

`log.base` sets the log base (default: Vega-Lite's 10):

```yaml {contract=chart-body}
style:
  axis_y:
    scale:
      continuous:
        type: log
        log:
          base: 2
```

## `type: pow` / `type: sqrt` / `type: symlog`

These scale types reach Vega-Lite the same way `type: log` does, but without
a first-class tick story; dbt Charts passes them straight through and does not
validate or specialize tick placement for them the way it does for `log`.
`pow.exponent` configures `pow`; `symlog.constant` configures `symlog`. Unlike
`log`, their domains can include 0, so (verified) they don't hit the
`log`-specific area-mark rendering issue below and need no explicit domain.

```yaml {contract=chart-body}
style:
  axis_y:
    scale:
      continuous:
        type: pow
        pow:
          exponent: 0.5
```

## Tick cadence on a quantitative axis

Two fields under `style.axis_x.ticks` control how densely a quantitative axis
is ticked. They answer different questions, and only one of them is exact.

`ticks.count` asks for a number of ticks. Vega-Lite treats it as a target and
rounds to the nearest round-numbered ladder, so you get *about* this many:

```yaml {contract=chart-body}
style:
  axis_x:
    ticks:
      count: 4
```

`ticks.step` names the interval instead, and it is a floor Vega cannot go
finer than: `step: 1000` on a 0–4k axis ticks at exactly `0 / 1k / 2k / 3k /
4k`:

```yaml {contract=chart-body}
style:
  axis_x:
    ticks:
      step: 1000
```

Reach for `step` over an explicit `scale.values: [0, 1000, 2000, 3000, 4000]`
ladder. A `values` list freezes the axis against the data you had when you
wrote it: the day a customer count passes 4,000 the ladder silently stops
covering the data. `step` is a floor, not a list; Vega keeps choosing round
numbers above it, and the axis keeps covering the range as it grows.

The two compose: `count` sets the target, `step` the floor.

On a **temporal** x-axis `step` means a multiple of a calendar grain and needs
`ticks.time_unit` alongside it; see
[Time axes](./time-axes.md#tick-cadence-step-anchored-time_unit-step). On an
**ordinal** or **categorical** x-axis the domain is discrete, so there is no
tick interval to set, including a horizontal bar's `axis_x`, which is its
category axis (the measure lives on `axis_y`). Authoring `ticks.step` on any of
those raises rather than doing nothing.

## Rules

A handful of authoring combinations are rejected at compile time rather than
silently producing a misleading chart:

| Rule | Why |
|---|---|
| `log.base` requires `type: log` (same for `pow.exponent`/`type: pow`, `symlog.constant`/`type: symlog`) | These params are meaningless without the matching scale type. |
| `type: log` + `zero: true` | A log domain cannot include 0. |
| `type: log` + a `domain` bound at or below 0 | A log scale is undefined at and below 0. |
| `log.base` at or below 0, or equal to 1 | No logarithm exists in those bases. |
| `type: log` on a `bar` chart | A bar's length encodes magnitude from zero; meaningless on a log scale. Use `type: symlog` on the bar chart, or switch to `line` or `area` for a log scale. |
| `type: log` + `axis_y.ticks.count` | A target tick count is meaningless on a log axis; Vega-Lite computes log-decade ticks natively. |
| `axis_x.ticks.step` without `ticks.time_unit` on a non-quantitative x-axis | A bare `step` is a *numeric* tick interval; only a quantitative scale has one. Add `ticks.time_unit` on a temporal axis; on a discrete axis, remove it. |

See the [YAML Schema Reference](../reference/yaml-reference.md#basescalestyle) for
the full scale style field list.

# Custom charts (https://docs.dbtcharts.com/charts/custom/)

# Custom charts

When no built-in type draws the shape you need, `type: custom` lets you draw it
yourself. A custom chart is an SVG template: a [Jinja](https://jinja.palletsprojects.com/)-style
file that turns the chart's query rows into SVG shapes, rendered by the dbt Charts
engine (see [The template dialect](#the-template-dialect)). The template reads the
board's style, so a custom chart picks up the theme's colors and fonts and
follows a theme switch like any built-in chart.

Try the built-in types and [composed charts](extensibility.md#composed-charts)
first. A built-in chart gets axes, legends, hover, sizing rules, and visual
warnings for free; a custom chart draws only what its template draws.

For ready-made templates (Sankey, funnel, gauge, radial bar, XmR, isotype,
waffle, and radar), see [Custom chart examples](custom-examples.md).

---

## A first custom chart

A template can live inline, under `svg:`. This one draws a Playfair-style
balance chart: two lines with the gap between them filled and labeled, a form
no built-in type draws. Its header declares the channels it reads:

```dbt-charts-example
charts:
  trade_balance:
    type: custom
    query:
      columns: [year, exports, imports]
      values:
        - [1700, 60, 40]
        - [1710, 75, 50]
        - [1720, 80, 55]
        - [1730, 110, 60]
        - [1740, 125, 80]
        - [1750, 150, 95]
        - [1760, 170, 115]
        - [1770, 200, 130]
    svg: |
      {#---
      description: Two lines with the gap between them filled and labeled.
      channels:
        x:
          description: Column holding the period.
        y:
          description: The upper line's column, then the lower line's.
          multiple: true
      ---#}
      {% set up = channels.y[0] %}{% set lo = channels.y[1] %}
      {% set n = rows | length %}{% set pad = 40 %}
      {% set ymax = [rows | map(attribute=up) | max, rows | map(attribute=lo) | max] | max * 1.1 %}
      <g font-family="{{ style.font.family }}" font-size="{{ style.font.size }}" fill="{{ style.font.color }}">
        <polygon fill="{{ style.tones.positive }}" fill-opacity="0.3"
          points="{% for r in rows %}{{ pad + loop.index0 * (width - 2 * pad) / (n - 1) }},{{ height - pad - r[up] / ymax * (height - 2 * pad) }} {% endfor %}{% for r in rows | reverse %}{{ pad + (n - 1 - loop.index0) * (width - 2 * pad) / (n - 1) }},{{ height - pad - r[lo] / ymax * (height - 2 * pad) }} {% endfor %}"/>
        <polyline fill="none" stroke="{{ style.accent }}" stroke-width="2"
          points="{% for r in rows %}{{ pad + loop.index0 * (width - 2 * pad) / (n - 1) }},{{ height - pad - r[up] / ymax * (height - 2 * pad) }} {% endfor %}"/>
        <polyline fill="none" stroke="{{ style.muted }}" stroke-width="2"
          points="{% for r in rows %}{{ pad + loop.index0 * (width - 2 * pad) / (n - 1) }},{{ height - pad - r[lo] / ymax * (height - 2 * pad) }} {% endfor %}"/>
        {% for r in rows %}
        <text x="{{ pad + loop.index0 * (width - 2 * pad) / (n - 1) }}" y="{{ height - pad / 3 }}"
              text-anchor="middle">{{ r[channels.x] }}</text>
        {% endfor %}
        {% set mid = rows[n // 2] %}
        <text x="{{ pad + (n // 2) * (width - 2 * pad) / (n - 1) }}"
              y="{{ height - pad - (mid[up] + mid[lo]) / 2 / ymax * (height - 2 * pad) }}"
              text-anchor="middle" dy="0.35em" font-style="italic">Balance in our favor</text>
        <text x="{{ width - pad }}" y="{{ height - pad - rows[n - 1][up] / ymax * (height - 2 * pad) - 8 }}"
              text-anchor="end" fill="{{ style.accent }}">{{ up }}</text>
        <text x="{{ width - pad }}" y="{{ height - pad - rows[n - 1][lo] / ymax * (height - 2 * pad) + 22 }}"
              text-anchor="end" fill="{{ style.muted }}">{{ lo }}</text>
      </g>
    x: year
    y: [exports, imports]
rows:
  - trade_balance
```

The template writes SVG content only. dbt Charts draws the title and
subtitle, clips the template's output to its drawing box (`width` x `height`),
and places it on the board.

---

## Template files

Inline templates suit a one-off chart. To reuse a chart across boards, put the
template in your project's `templates/` folder, next to `dbt_charts.yml`, and
name it with `template:`:

```text
my_project/
├── dbt_charts.yml
├── charts/
│   └── funnel.yml
└── templates/
    └── funnel.svg.j2
```

```yaml {contract=board-root}
queries:
  activation_funnel:
    columns: [stage, users]
    values:
      - [Visited site, 48210]
      - [Started signup, 12940]
      - [Upgraded, 740]
charts:
  activation:
    type: custom
    template: funnel
    query: activation_funnel
    title: Activation funnel
    x: stage
    y: users
rows:
  - activation
```

`template: funnel` reads `templates/funnel.svg.j2`. A chart sets exactly one of
`template:` or `svg:`.

### Finding templates

`dct describe` reads a template's header, so you never open the file to learn
what it takes:

```bash
dct describe templates/sankey.svg.j2   # one template
dct describe templates/                # every template in the folder
```

Each template prints its description, its channels (required or optional, and
whether a list is allowed), and its options (type, default, description).
`dct describe --json` returns the same under a `template` key. Describing a
board shows, for each custom chart, the template it uses and that template's
description. A `template:` name with no file lists the templates the project
does have, and an unsupported `type:` such as `sankey` names the matching
template when the project has one.

### Channels and options

A template file declares what it takes in a header: a Jinja comment that opens
with `{#---` and closes with `---#}`, holding YAML. It has two parts.

**Channels** are the chart's data columns, named with the same channel fields
built-in charts use: `x`, `y`, `color`, `size`, `shape`, `theta`, and `value`.
A chart sets them at its root, exactly as it would on a bar or pie chart. Pick
the channel that matches the role: a category along a funnel is `x` and its
count is `y`, the way a bar chart reads; a part of a whole is `color` and
`theta`, the way a pie reads.

**Options** are everything else the template can be told: a format, a maximum,
a symbol. A chart sets them under `options:`.

```jinja
{#---
description: Funnel of ordered stages, one row per stage in query order.
channels:
  x:
    description: Column naming each stage.
  y:
    description: Column holding the count that reached each stage.
options:
  value_format:
    type: string
    default: ",.0f"
  label_width:
    type: number
    default: 120
---#}
```

```yaml {contract=chart-body}
type: custom
template: funnel
x: stage
y: users
options:
  label_width: 140
```

A channel or option without a `default` is required; `default: null` makes it
optional with no value, which a template tests with `{% if options.target %}`.
A channel declared with `multiple: true` takes a list of columns
(`y: [disease, wounds]`) and always reaches the template as a list. A template
with no header, an inline one included, takes no channels and no options.

The chart must match the header. A channel or option the header doesn't
declare, a missing required one, or a value of the wrong type is a validation
error, so a typo fails when the board compiles rather than drawing something
wrong. Every channel, and every `column` option, is also checked against the
query's result columns when the chart renders.

| Option `type` | Accepts |
|---|---|
| `column` | The name of a column in the chart's query, for a secondary role such as a gauge's target. |
| `columns` | A list of column names. |
| `string` | Any text. |
| `number` | Any number. |
| `integer` | A whole number. |
| `boolean` | `true` or `false`. |
| `color` | A color: hex, a CSS color name, or a palette token. |

---

## What a template sees

| Name | What it holds |
|---|---|
| `rows` | The query result, one mapping per row: `{{ r.revenue }}` or `{{ r[channels.y] }}`. A chart with no `query:` gets no rows. |
| `columns` | The result's column names, in order. |
| `channels` | The columns the chart set for each declared channel: `channels.x` is a column name, or a list for a `multiple` channel; an optional channel left unset is `none`. |
| `options` | The chart's options, with the header's defaults filled in. |
| `width`, `height` | The drawing box in pixels: inside the card padding, below the title. See [Where the drawing lands](#where-the-drawing-lands). |
| `uid` | A prefix unique to this chart. Use it for `id` values (gradients, clip paths, symbols) so two charts on one board never share an id. |
| `style` | The board's style, resolved. See [Style](#style). |
| `variables` | The board's variable values for this render: `variables.region`. A query that reads a variable already returns filtered rows; this is for labels and titles the template draws itself. |
| `math` | `math.sin`, `math.cos`, `math.tan`, `math.asin`, `math.acos`, `math.atan2`, `math.sqrt`, `math.log`, `math.exp`, `math.floor`, `math.ceil`, `math.pi`, `math.tau`. Angles are in radians. |

And these helpers:

| Helper | Returns |
|---|---|
| `value \| format(spec)` | The value formatted with a [d3-format](https://d3js.org/d3-format) spec, the same formats `format:` takes elsewhere: `{{ 0.432 \| format('.1%') }}` gives `43.2%`. |
| `text_width(text, size, weight)` | The width in pixels of `text`, a string, in the board's font at `size` pixels: `text_width(r.name, style.font.size)`. Turn a number into text first, with `\| string` or `\| format(...)`. `weight` is optional and defaults to 400. It takes any weight `style` can carry: a whole number from 1 to 1000 such as `600`, or a CSS keyword such as `bold` or `normal`, so `style.charts.title.font.weight` works whatever the theme sets. Use it to fit or wrap labels. |
| `color_for(value, column)` | The board's pinned color for that column and value, from `style.charts.category_colors`, so a pinned category matches the built-in charts on the board. A value with no pin gets the next color of the categorical palette, in the order the template asks; the same value always gets the same color within a chart, and running out of palette colors is an error. |
| `href(row)` | The chart's `link:` for that row, with every `{{ channel }}` placeholder filled from the row. See [Links](#links). |
| `raise_error(message)` | Stops the render and shows `message` in the chart's place. Use it to reject data the template cannot draw. |

Templates use strict variables: a misspelled column, option, or style key
is an error that names the template and line, not an empty string.

Query values arrive as the warehouse returns them. Some warehouses return
decimals, so convert before doing arithmetic with floats:
`{{ (r.revenue | float) * scale }}`.

---

## Style

`style` has the same structure as the [`style:` block](../styling.md) you
author on a board or in a theme, after the theme, the board's `style:`, and
every inherited value are merged. So a key you can set is a key a template can
read, at the same path:

| In a template | What it is |
|---|---|
| `style.background` | The board background. |
| `style.font.family`, `style.font.color`, `style.font.size` | Body text. |
| `style.muted`, `style.accent` | Secondary text and the accent color. |
| `style.tones.positive`, `.negative`, `.warning`, `.info` | Status colors. |
| `style.charts.color.categorical.palette` | The categorical palette built-in charts use, as a list of colors. |
| `style.charts.color.categorical.single_series_palette[0]` | The color of a single-series chart. |
| `style.charts.axis.grid.color` | Gridlines and tracks. |
| `style.charts.axis.labels.font` | Axis label text. |
| `style.charts.title.font` | Chart title text. |
| `style.palettes.<role>` | Each palette role, resolved: a list of colors for a categorical, sequential, or diverging palette, and a mapping of named stops (`solid`, `bg`, `border`, `text`, ...) for a tone. |

Every color is a resolved hex value. The one difference from what you author
is `palettes:`: you name a palette (`category: editorial-10`), and the
template sees its colors.

Read colors and fonts from `style` rather than writing them into the
template, and the chart follows every theme, dark ones included, without
changes. The [examples](custom-examples.md) never hard-code a color.

To pin a category's color across every chart on a board, built-in or custom,
use `style.charts.category_colors` and read it in the template with
`color_for(value, column)`:

```yaml {contract=board-root}
style:
  charts:
    category_colors:
      qualification:
        values:
          Graduates: "#2b59a8"
          Certificated: "#d33a32"
```

---

## Links

A custom chart takes `link:` like every other chart. A link with no channel
placeholder wraps the whole drawing in one anchor, so the chart is clickable
with no change to the template:

```yaml {contract=chart-body}
type: custom
template: funnel
link: /boards/activation
```

A link with placeholders is per row: `link: /boards/stage/{{ x }}` fills
`{{ x }}` from the column the `x` channel binds, and the template decides
which marks carry it by wrapping them in an anchor:

```jinja
{% for r in rows %}
<a href="{{ href(r) }}"><rect .../></a>
{% endfor %}
```

A per-row link is drawn only where the template calls `href`, so a template
that never calls it with such a link fails the chart rather than quietly
dropping the link. A board path resolves against the host like any chart
link; `http`, `https` and `mailto` URLs pass through; any other scheme is
refused.

---

## Fonts

`style.font.family` is the board's font stack, and `style.charts.title.font`,
`style.charts.axis.labels.font` and the other font blocks carry the family,
size, weight and color the built-in charts use. A template that writes
`font-family="{{ style.font.family }}"` paints the board font, and an export
embeds that font the way it does for every other chart. `text_width` measures
in the same font, at the weight you pass it.

---

## Where the drawing lands

The engine draws the title and subtitle, then places the template's output
in a group translated below them, inside the card's padding. `width` and
`height` are that box, so a template draws from `(0, 0)` to `(width, height)`
and never allows for the title or the padding itself. Anything drawn outside
that box is clipped, so it cannot paint over the title. A chart with no `title:`
hands the template the full card height.

---

## What a template may draw

A template's output must be well-formed SVG built from drawing elements:
shapes (`rect`, `circle`, `ellipse`, `line`, `polyline`, `polygon`, `path`),
text (`text`, `tspan`, `textPath`), grouping (`g`, `defs`, `symbol`, `use`),
paint (`linearGradient`, `radialGradient`, `stop`, `pattern`, `clipPath`,
`mask`, `marker`), `title` and `desc`, and `a` with an `href` the
[link rules](#links) accept.

The output is checked before it reaches the board, and anything outside that
set is an error that names the element or attribute. Nothing is silently
removed. Not allowed:

- `<script>`, `<foreignObject>`, `<style>`, `<image>`, and animation
  elements such as `<animate>` and `<set>`
- filters (shadow, blur) and raster images: neither fits the sandboxed,
  vector-only output, so `<filter>` is refused along with `<image>`
- event attributes such as `onclick`
- the board's own hooks: `role`, `aria-*` and `data-*` attributes, and class
  names starting with `role-` or `dbt-`, which the page's runtimes read
- a paint attribute (`fill`, `stroke`, `stop-color`, ...) that is not a color,
  `none`, `currentColor` or `url(#id)`
- elements nested more than 64 levels deep
- references out of the page: outside `<a>`, `href` must be a `#id` reference
  (`href="#{{ uid }}-person"`), and `url(...)` must be `url(#id)`
  (`fill="url(#{{ uid }}-fade)"`)
- comments, processing instructions, and CDATA sections
- CSS escapes (a backslash in an attribute) and CSS functions other than
  `url(#id)` that load a resource, such as `image-set()`

Values written with `{{ }}` are escaped, so a label containing `<` or `&` draws
as text.

A `<title>` inside a shape becomes the browser's native tooltip: delayed,
unstyled, and absent on touch and in PNG or PDF exports. It is not the board's
tooltip card.

---

## The template dialect

The engine renders templates with [minijinja](https://github.com/mitsuhiko/minijinja),
a Jinja implementation with no reflection into the host, so a template can
reach only the names listed above. Blocks, loops, macros, `namespace()`,
`dict()` with `**` merging, and the common filters all work as in Jinja. The
difference is that values have filters, not Python methods:

| Instead of | Write |
|---|---|
| `text.split(",")` | `text \| split(",")` |
| `d.get(k, 0)` | `d[k] if k in d else 0` |
| `d.keys()`, `d.values()` | `d \| items \| map(attribute=0)`, `... \| map(attribute=1)` |
| `x \| round(0, "ceil")` | `math.ceil(x)` |
| `"%d" % n` | `n \| format('d')` |

A syntax the engine does not accept fails when the board compiles, naming the
line. Two budgets bound a template, and crossing either fails the chart, never
the board: a runaway loop ends on an instruction budget, and the output is
capped by the project's `execution.max_template_output_bytes`.

---

## Writing good templates

**Let the query do the math.** Jinja is good at loops and text, and slow and
awkward at algorithms. Sorting, ranking, running totals, shares, and binning
belong in SQL. The XmR example computes its limits in the template only
because they are a few sums; a layout that needs iteration is a sign the
shape should be a built-in type.

**Validate the data.** Check what the template depends on and stop with
`raise_error` when it is wrong: a gauge with more than one row, a Sankey whose
flows loop back, a negative value in a waffle.

**Use `uid` for every id.** A board renders many charts into one document, so
an id like `fade` would collide when a template is used twice.

**Leave room for text.** Measure labels with `text_width` instead of guessing,
and keep a fixed margin for labels that sit outside the marks.

---

## Errors

| Code | When |
|---|---|
| `ERR-CUSTOM-TEMPLATE` | The template file is missing, its header is not valid YAML, or the template has a syntax error. |
| `ERR-CUSTOM-FIELDS` | A channel or option the header doesn't declare, a missing required one, or a value of the wrong type. |
| `ERR-CUSTOM-RENDER` | The template failed while drawing: a missing column, an undefined name, or a `raise_error` call. |
| `ERR-CUSTOM-SVG` | The output is not well-formed SVG, or uses an element or attribute that is not allowed. |

# Custom chart examples (https://docs.dbtcharts.com/charts/custom-examples/)

# Custom chart examples

Eight [custom chart](custom.md) templates, each a shape people ask for that
dbt Charts has no built-in `type:` for. Copy a template into your project's
`templates/` folder, then point a chart at it with `template:`.

Every template here reads its colors and fonts from `style`, so each one
follows the board's theme. The Playground's
[custom charts](https://play.dbtcharts.com/?example=custom%2Fcustom-charts.yml)
example puts all eight on one board, plus an inline one.

---

## Sankey

**Best for:** flows between stages, where one stage splits into several and
several merge into one: visitors to plans, budget sources to uses.

The query is an edge list, one row per flow. Nodes sit in columns by their
longest path from a starting node, and every node with no outgoing flow ends
in the last column. Flows that loop back stop the render with an error.

```dbt-charts-example
charts:
  signup_sankey:
    type: custom
    template: sankey
    title: Where visitors go
    query:
      columns: [source, target, visitors]
      values:
        - [Visits, Signup, 4200]
        - [Visits, Bounced, 9800]
        - [Signup, Trial, 3100]
        - [Signup, Abandoned, 1100]
        - [Trial, Paid, 1300]
        - [Trial, Churned, 1800]
        - [Paid, Annual, 500]
        - [Paid, Monthly, 800]
    x: [source, target]
    value: visitors
rows:
  - signup_sankey
```

??? example "templates/sankey.svg.j2"

    ```jinja
    --8<-- "examples/playground/templates/sankey.svg.j2"
    ```

This template lays the diagram out itself, which is about as much logic as a
template should hold. It does not reorder nodes to reduce crossings.

---

## Funnel

**Best for:** how many reach each step of a process, and where they drop off.

One row per stage, in order. Bars are centered and sized by count; the band
between two bars carries the share that made it to the next stage.

```dbt-charts-example
charts:
  activation:
    type: custom
    template: funnel
    title: Activation funnel
    query:
      columns: [stage, users]
      values:
        - [Visited site, 48210]
        - [Started signup, 12940]
        - [Verified email, 9120]
        - [Created a board, 5310]
        - [Invited a teammate, 2180]
        - [Upgraded, 740]
    x: stage
    y: users
    options:
      label_width: 140
rows:
  - activation
```

??? example "templates/funnel.svg.j2"

    ```jinja
    --8<-- "examples/playground/templates/funnel.svg.j2"
    ```

---

## Gauge

**Best for:** one number against a known range, such as a score or a
utilization rate.

The query returns one row. `bands` splits the track into zones colored with
the theme's negative, warning, and positive tones, and the value's arc takes
the color of the zone it ends in. `target` draws a tick.

```dbt-charts-example
charts:
  nps_gauge:
    type: custom
    template: gauge
    title: Net promoter score
    query:
      columns: [nps, goal]
      values:
        - [72.4, 80]
    style:
      aspect_ratio: 1.8
    value: nps
    options:
      max: 100
      target: goal
      bands: "50,75"
      label: Target 80
      value_format: ".0f"
rows:
  - nps_gauge
```

??? example "templates/gauge.svg.j2"

    ```jinja
    --8<-- "examples/playground/templates/gauge.svg.j2"
    ```

---

## Radial bar

**Best for:** a short ranked list shown compactly, where the shape matters
more than reading exact values.

One ring per row, outermost first, so sort the query by value. Each ring
sweeps clockwise from twelve o'clock, three quarters of a turn at the largest
value. Ring colors come from `color_for`, so a channel pinned under
`style.charts.category_colors` keeps its board color.

```dbt-charts-example
charts:
  channel_rings:
    type: custom
    template: radial_bar
    title: Sessions by channel
    query:
      columns: [channel, sessions]
      values:
        - [Search, 18400]
        - [Direct, 12900]
        - [Social, 8300]
        - [Email, 6100]
        - [Partners, 2900]
    style:
      aspect_ratio: 1
    x: channel
    y: sessions
rows:
  - channel_rings
```

??? example "templates/radial_bar.svg.j2"

    ```jinja
    --8<-- "examples/playground/templates/radial_bar.svg.j2"
    ```

Radial bars exaggerate the outer rings: the same value draws a longer arc on
an outer ring than on an inner one. Prefer a bar chart when the comparison
must be exact.

---

## XmR chart

**Best for:** telling routine variation from a real change in a process
metric over time.

An XmR (individuals and moving range) chart plots each period's value with
its mean and natural process limits, at 2.66 times the average moving range
on either side of the mean. Below it, the moving range chart plots the change
from one period to the next. The template flags points outside the limits in
the theme's negative tone, and runs of eight or more points on one side of
the mean in its warning tone.

```dbt-charts-example
charts:
  defect_xmr:
    type: custom
    template: xmr
    title: Defects per thousand units
    query:
      columns: [month, defects_per_k]
      values:
        - [Jan, 41.2]
        - [Feb, 43.0]
        - [Mar, 40.1]
        - [Apr, 44.9]
        - [May, 42.3]
        - [Jun, 39.8]
        - [Jul, 43.6]
        - [Aug, 41.7]
        - [Sep, 30.4]
        - [Oct, 42.8]
        - [Nov, 44.1]
        - [Dec, 40.6]
        - [Jan, 47.9]
        - [Feb, 46.2]
        - [Mar, 48.8]
        - [Apr, 46.5]
        - [May, 47.1]
        - [Jun, 49.4]
        - [Jul, 46.8]
        - [Aug, 48.2]
        - [Sep, 42.0]
        - [Oct, 43.3]
    x: month
    y: defects_per_k
rows:
  - defect_xmr
```

??? example "templates/xmr.svg.j2"

    ```jinja
    --8<-- "examples/playground/templates/xmr.svg.j2"
    ```

---

## Isotype pictogram

**Best for:** counts a general audience should grasp at a glance.

Isotype was developed in 1920s Vienna by Otto Neurath, Marie Neurath, and
Gerd Arntz. One symbol always stands for the same quantity, so readers compare
amounts by counting, and color splits each block into groups. This example
follows chart VI of a 1938 Isotype book, one figure for every 1,250 teachers
in England and Wales.

Each row is one block and group. `per_row_column` gives each block its own
width, and the pinned `category_colors` keep the original's blue, red, green,
and black.

```dbt-charts-example
style:
  charts:
    category_colors:
      qualification:
        values:
          Graduates: "#2b59a8"
          Certificated: "#d33a32"
          Specialists: "#2e9a6a"
          Uncertificated: "#2a2a2a"
charts:
  teachers_isotype:
    type: custom
    template: isotype
    title: Teachers in public elementary and secondary schools, 1938
    query:
      columns: [school, qualification, teachers, per_row]
      values:
        - [Elementary men, Graduates, 6250, 3]
        - [Elementary men, Certificated, 38750, 3]
        - [Elementary men, Specialists, 2500, 3]
        - [Elementary men, Uncertificated, 1250, 3]
        - [Elementary women, Graduates, 3750, 7]
        - [Elementary women, Certificated, 103750, 7]
        - [Elementary women, Specialists, 2500, 7]
        - [Elementary women, Uncertificated, 21250, 7]
        - [Secondary men, Graduates, 12500, 1]
        - [Secondary men, Specialists, 1250, 1]
        - [Secondary women, Graduates, 8750, 1]
        - [Secondary women, Certificated, 1250, 1]
        - [Secondary women, Specialists, 2500, 1]
        - [Secondary women, Uncertificated, 1250, 1]
    style:
      aspect_ratio: 1
    x: school
    color: qualification
    y: teachers
    options:
      per_symbol: 1250
      unit: teachers
      per_row_column: per_row
rows:
  - teachers_isotype
```

??? example "templates/isotype.svg.j2"

    ```jinja
    --8<-- "examples/playground/templates/isotype.svg.j2"
    ```

`symbol: square` and `symbol: circle` draw plain unit charts. The person
figure is defined once as a `<symbol>` and placed with `<use>`, with its id
prefixed by `uid`.

---

## Waffle

**Best for:** parts of a whole, read as whole percentages.

A 10 by 10 grid where each square is one percent. Shares round to whole
squares by largest remainder, so the grid always holds exactly 100.

```dbt-charts-example
charts:
  warehouse_waffle:
    type: custom
    template: waffle
    title: Projects by warehouse
    query:
      columns: [warehouse, projects]
      values:
        - [Snowflake, 412]
        - [BigQuery, 298]
        - [Databricks, 187]
        - [Redshift, 96]
        - [Postgres, 61]
        - [DuckDB, 38]
    color: warehouse
    theta: projects
rows:
  - warehouse_waffle
```

??? example "templates/waffle.svg.j2"

    ```jinja
    --8<-- "examples/playground/templates/waffle.svg.j2"
    ```

---

## Radar

**Best for:** comparing a few items' profiles across several measures that
share one scale, such as review scores out of ten.

The query is long: one row per spoke and series. Spokes go clockwise from
twelve o'clock in query order, and each series draws a closed outline in its
`color_for` color. Every spoke runs from zero to `max` (the largest value when
unset), so rescale measures to a common unit in the query first. A series
missing a spoke, or with two rows for one, stops the render with an error.

```dbt-charts-example
charts:
  plan_radar:
    type: custom
    template: radar
    title: Plan review scores
    query:
      columns: [category, plan, score]
      values:
        - [Speed, Starter, 6]
        - [Reliability, Starter, 7]
        - [Support, Starter, 4]
        - [Integrations, Starter, 5]
        - [Ease of use, Starter, 9]
        - [Price, Starter, 9]
        - [Speed, Enterprise, 9]
        - [Reliability, Enterprise, 9]
        - [Support, Enterprise, 8]
        - [Integrations, Enterprise, 9]
        - [Ease of use, Enterprise, 6]
        - [Price, Enterprise, 4]
    style:
      aspect_ratio: 1.2
    x: category
    y: score
    color: plan
    options:
      max: 10
      rings: 5
rows:
  - plan_radar
```

??? example "templates/radar.svg.j2"

    ```jinja
    --8<-- "examples/playground/templates/radar.svg.j2"
    ```

A radar's area grows with the square of its values and depends on the order
of the spokes, so read it for shape, not size. Prefer a grouped bar chart when
the comparison must be exact, and keep to two or three series.

# Chart Interactions (https://docs.dbtcharts.com/charts/interactions/)

# Chart Interactions

Charts support hover interactions with tooltips and click-through via the
`link:` field, which turns chart elements into clickable **drill-down links**.

---

## Hover Tooltips

Charts automatically display tooltips when hovering over data points. Tooltips show the values for the hovered element.

```yaml {contract=board-fragment}
charts:
  sales_chart:
    title: "Hover for Details"
    query: queries.sales
    type: bar
    x: month
    y: total_revenue
```

### Hover emphasis

Hovering a chart makes the part the tooltip describes easier to find.

- **Bars, histograms, pie and donut slices, and heatmap cells:** the marks the
  tooltip is not describing recede. They keep their shape and position but
  blend toward the chart background, so the bar (or grouped cluster, stacked
  column, slice, or cell) under the cursor stands out.
- **Lines, areas, and scatter points:** a dot marks each datum the tooltip
  describes, and a neutral line drawn from the theme's grays drops from it to
  the plot's baseline. On a stepped line, the dot sits in the middle of the
  step.

Value labels printed on a bar recede along with their bar. Every other label
stays lit: direct labels, a donut's center total, and series labels never
recede. In small multiples, only the panel under the cursor recedes.

Nothing about the rendered chart changes until you hover. Turn it off
board-wide with `style.charts.hover_emphasis.visible`:

```yaml {contract=board-fragment}
style:
  charts:
    hover_emphasis:
      visible: false
```

A chart whose color encodes a value (a continuous color scale) never recedes,
whether or not its legend is shown, because a receded color would read as a
different value on that scale. Charts colored by category recede normally.

---

## Cross-File Query References

You can reference queries from external files using the `file.yml#query_name` syntax:

```yaml {contract=unverified}
charts:
  sales_chart:
    query: shared_queries.yml#monthly_revenue  # External file reference
    type: bar
    x: month
    y: revenue
```

This is useful for:
- **Sharing queries** across multiple dashboards
- **Keeping doc examples short** by referencing common queries
- **Organizing large projects** with separate query definition files

Paths are resolved relative to the current file's directory.

---

## Drill-Down Links (`link:`)

Set `link:` on a chart to turn each data point into a clickable link. The
value is a URL template. Four channel placeholders are substituted with
the clicked row's value for that channel: `{{ x }}`, `{{ y }}`,
`{{ color }}`, `{{ theta }}`. Other Jinja-style `{{ ... }}` expressions
pass through unchanged; use them for static strings only, not field
names or variable references.

```yaml {contract=board-fragment}
charts:
  sales_by_region:
    query: queries.sales
    type: bar
    x: region
    y: revenue
    link: "/regions/{{ x }}"   # {{ x }} becomes the clicked region
```

Board-root paths (`/path/…`) are automatically rewritten for `dct serve` and
Cloud; the same YAML works in both environments.

### In-page variable updates

A `link:` starting with `?` updates a dashboard variable without navigating
away. Use this for cross-chart filtering within the same board:

```yaml {contract=board-fragment}
charts:
  by_category:
    query: revenue_by_category
    type: bar
    x: category
    y: revenue
    link: "?selected_category={{ x }}"   # updates the selected_category variable
```

`link:` works on chart types that render individual data elements per row
under the Vega-Lite pipeline: bar, line, area, point, and other
VL-backed marks.

### KPI charts

KPI charts also support `link:`. The value is a static URL; clicking the
KPI value navigates to it.

### Tables

Tables support `link:` at both the chart root and per column, and the two are
distinct affordances:

- A chart-root `link:` makes the **whole row** clickable. It renders as one
  row-wide selection band that highlights on hover; clicking anywhere on the
  row (except a cell that has its own link) navigates to the row destination.
- A column `link:` in `style.columns` makes **that column's cells** clickable
  links, rendered inline and inked. A cell link always wins the click over the
  row band beneath it.

```yaml {contract=board-fragment}
charts:
  tickets_table:
    type: table
    query: open_tickets
    link: "/zendesk/tickets/detail?id={{ ticket_id }}"   # whole-row link
    style:
      columns:
        status:
          link: "/zendesk/backlog/?status={{ status }}"  # this column's cells link here
        ticket_id:
          label: Ticket
          # no column link; clicking it follows the whole-row link
```

A column `link` is a per-cell link on that column only. It does not fall
through to other columns; plain columns with no column link are not inked as
links; they are just part of the clickable row when a chart-root `link:` is
set. Summary and total rows never get the row band.

---

## Related

- [Linking Between Boards](../boards/linking.md) - Board path syntax and resolution
- [Charts Overview](index.md) - Chart field reference
- [Variables](../variables/index.md) - Using variables with charts
- [Expressions](../variables/expressions.md) - Using expressions in query filters

# Axis Labels (https://docs.dbtcharts.com/charts/axis-labels/)

# Axis Labels

dbt Charts keeps the encoded axis time unit stable while adapting crowded x-axis
labels. Bucketed temporal axes first choose the finest fitting label format,
then thin visibility, then tilt the labels that remain. Font size does not
change.

## Automatic layout

The renderer resolves label layout from the axis type, available width, and
formatted label widths:

| Axis | Automatic behavior |
|---|---|
| Quantitative x-axis | Keep labels horizontal and let Vega-Lite place ticks (override the density with [`ticks.count` or `ticks.step`](./axis-scales.md#tick-cadence-on-a-quantitative-axis)) |
| Bucketed temporal x-axis | Choose the finest fitting calendar vocabulary, thin its visibility if needed, then tilt |
| Cyclic temporal x-axis | Drop alternating labels, then tilt if needed |
| Categorical x-axis | Keep every label, then tilt if needed |
| Horizontal bar category axis | Keep labels horizontal |

Daily axes and detected weekly axes first use compact day-number labels.
Daily labels can step from every day to Mondays, then to month text, on bar,
step, line, and area charts alike. Continuous line, area, and scatter axes
measure the whole calendar span, so days with no row don't change their labels.
Weekly labels step from every week to month text. Continuous weekly line and
area axes keep Vega's tick positions but label each Sunday boundary with the
represented ISO Monday bucket. After that vocabulary is chosen, visibility
thinning follows meaningful calendar periods. Monthly text, for example, can
appear only at quarter-opening months. The fiscal year start month anchors
quarter and year boundaries.

Automatic format promotion changes the default tick cadence but not the encoded
data grain. Later width-dependent visibility thinning changes only which labels
are visible. It does not change:

- the encoding `time_unit`,
- the underlying ticks, or
- the chart data.

An explicitly authored `labels.time_unit` is different: it selects both the
label vocabulary and the default tick cadence. For example,
`labels.time_unit: yearquarter` on monthly data emits quarter labels and quarter
ticks. Author `axis_x.ticks` to override that default on a continuous temporal
axis.

If the thinned labels still collide, dbt Charts tries the configured
`tilt_increments` from the shallowest angle to the steepest.

## Configure overlap resolution

`labels.overlap` has two boolean switches. Their execution order is fixed:
`skip`, then `tilt`.

```yaml {contract=chart-body}
style:
  axis_x:
    labels:
      overlap:
        skip: true
        tilt: true
```

Disable tilt to keep retained labels horizontal:

```yaml {contract=chart-body}
style:
  axis_x:
    labels:
      overlap:
        skip: true
        tilt: false
```

Disable both strategies to keep every label visible even when labels collide:

```yaml {contract=chart-body}
style:
  axis_x:
    labels:
      overlap:
        skip: false
        tilt: false
```

An explicit `labels.angle` takes precedence and bypasses automatic overlap
resolution:

```yaml {contract=chart-body}
style:
  axis_x:
    labels:
      angle: -45
```

## Temporal labels

`axis_x.time_unit` controls the data encoding grain. The resolved
`labels.time_unit` controls the label text format and default tick cadence,
whether it was authored or chosen automatically. Automatic daily labels use the
finest fitting format on every daily axis; weekly labels use the same compact
vocabulary on continuous line and area axes. Width-dependent visibility
thinning after format selection changes neither the format nor ticks.

```yaml {contract=chart-body}
style:
  axis_x:
    time_unit: yearmonth
    fiscal_year_start_month: 3
    labels:
      time_unit: yearmonth
```

For this axis, labels still use month text. When space is tight, only the
fiscal-quarter opening months are shown: March, June, September, and December.
The axis remains monthly.

Cyclic units such as `monthofyear`, `dayofweek`, and `hourofday` do not have a
coarser chronological period. They use alternating-label thinning before tilt.

See [Time Axes](time-axes.md) for time-unit detection, formatting, and fiscal
calendar behavior.

## Tilt candidates

Themes configure the angles considered after thinning with
`tilt_increments`:

```yaml {contract=board-root}
style:
  charts:
    axis_x:
      labels:
        tilt_increments: [0, -30, -45, -60, -90]
```

Order matters. dbt Charts uses the first angle whose projected width fits. This
is a theme-level knob; chart authors normally use `labels.angle` when they need
one exact rotation.

## Bar orientation

With `style.orientation: auto`, categorical bar charts render horizontally.
Their category labels move to the y-axis and remain horizontal. Temporal,
quantitative, and time-unit-bucketed bars remain vertical.

Set an orientation explicitly to override that choice:

```yaml {contract=board-root}
charts:
  revenue_by_state:
    type: bar
    x: state_name
    y: revenue
    style:
      orientation: vertical
```

## Other label controls

Hide labels:

```yaml {contract=chart-body}
style:
  axis_y:
    labels:
      visible: false
```

Control truncation:

```yaml {contract=chart-body}
style:
  axis_x:
    labels:
      max_width: 240
```

Add a minimum gap between adjacent labels:

```yaml {contract=chart-body}
style:
  axis_x:
    labels:
      min_gap: 24
```

## Mirrored Y-Axis

Set `style.axis_y.mirror: true` on a wide cartesian chart to draw the y-scale
on both the left and right edges. Both edges share the same scale and ticks.
This is a readability aid, not a second scale.

```dbt-charts-example
source: examples_db
charts:
  revenue_wide:
    query:
      sql: |
        SELECT date, SUM(revenue) AS revenue
        FROM ecommerce_orders
        GROUP BY date
        ORDER BY date
    type: line
    title: Daily Revenue
    x: date
    y: revenue
    style:
      axis_y:
        mirror: true
rows:
  - revenue_wide
```

Pass an object instead of `true` to relabel the mirrored edge:

```yaml {contract=chart-body}
style:
  axis_y:
    mirror:
      format: ".0%"
```

`format` and `expr` are mutually exclusive. Neither changes the scale or tick
placement.

`format` also accepts an object with `spec`, `prefix` and `suffix` keys for
a unit the board's [`regional:`](../styling.md#regional-settings) currency
cannot express, such as a second currency; see
[the object form](../styling.md#a-format-with-its-own-prefix-or-suffix-the-formatconfig-object-form)
in the styling guide.

This differs from a [layered chart](layered-charts.md) with independent left
and right axes. A mirrored axis draws one scale twice.

# Chart Color Channels (https://docs.dbtcharts.com/charts/color-channels/)

# Chart Color Channels

dbt Charts supports `color` as the primary data channel at chart root.
`color` accepts a bare field name (string) to encode a column as series grouping.
Static colors and gradient scales go under `style.color`.

Discrete, rule-driven styling lives in a separate top-level
`conditional_formatting:` block on the chart, available on `type: table`
and `type: kpi` only (see
[Conditional (threshold)](#conditional-threshold) below).

## Shorthand

A plain string binds a column to the color channel:

```yaml {contract=chart-body}
color: segment
```

This is the only accepted form at chart root. `color` does not accept `{column: ...}`, `{value: ...}`, or `{scale: ...}` at chart root; use `style.color` for static paint or gradient scale.

## Literal

Fix a channel to a static color via `style.color.static`:

```yaml {contract=chart-body}
style:
  color:
    static: "#1aff3c"
```

## Gradient scale

Map a numeric column to a continuous color range via `style.color.gradient`:

```yaml {contract=chart-body}
color: revenue
style:
  color:
    gradient:
      palette: ["#ffffff", "#0000ff"]
      min: 0
      max: 1000000
```

Omit `min`/`max` to scale from data: by default the domain is widened to round
bounds and every round tick is labeled on the legend; set `nice: false` for the
exact data extent instead. `palette` must be `list[str]` for color channels.

## Conditional (threshold)

Available on `type: table` and `type: kpi` only.

Discrete, rule-driven styling goes under the chart-level
`conditional_formatting:` block, indexed by column name. Each column entry
carries a single `when:` list of rules; each rule has exactly one predicate
and one or more style outputs (`background`, `font`):

| Predicate | Shape | Matches |
|-----------|-------|---------|
| `eq: x`   | any scalar | values equal to `x` (bool/int cross-match guarded) |
| `ne: x`   | any scalar | values not equal to `x` |
| `lt` / `lte` / `gt` / `gte` | number | one-sided numeric comparison (non-numeric never matches) |
| `between: [low, high]` | two numbers, `low <= high` | closed inclusive range |
| `in: [v1, v2, ...]` | non-empty list | equality against any list element |
| `is_null: true`   | boolean | null/None values |
| `is_null: false`  | boolean | any non-null value (including `0`, `""`, `false`) |
| `default: true`   | boolean | catch-all; fires when no other rule matched |

```yaml {contract=unverified}
type: table
conditional_formatting:
  arr:
    when:
      - gt: 1000000
        background: "#166534"
        font: {color: "#ffffff", weight: bold}
      - between: [0, 1000000]
        background: "#dcfce7"
      - is_null: true
        background: "#e5e7eb"
      - default: true
        background: "#fee2e2"
        font: {color: "#991b1b"}
```

Non-default rules are evaluated in list order; later matches override
earlier ones for overlapping style keys. A `default: true` rule must be the
last entry in its `when:` list and only fires when no other rule matched
for the current row; it is a true fallback, not a last-match-wins override.
Without a `default:`, rows that match nothing fall back to the chart's
un-conditional styling.

## Channel reference

| Channel | Chart types | Value type |
|---|---|---|
| `color` | All | `str` (color) |
| `background` | KPI, table | `str` (color) |
| `opacity` | All | `float [0, 1]` |
| `stroke.color` | Bar, line, area, arc | `str` (color) |
| `stroke.width` | Bar, line, area | `float` |

## Tables

On `type: table`, the table renderer reads `conditional_formatting` rules
directly from the chart-level block at render time; there is no per-column
`when:` shape under `style.columns`. Per-channel `color.scale` /
`background.scale` still lower to `style.columns[<column>].scale` because
scale is a continuous encoding the renderer interpolates per cell.

## KPI channels

On `type: kpi`, `color` controls the value text color and `background`
controls the card fill; both support literal and gradient modes via the
per-channel shape. Rule-driven overrides (mix of background and font
color/weight per threshold) go under `conditional_formatting:`; rules on the
`support.value` column instead style the support row (`font.color`, `glyph`,
`glyph_color`, `tone`). Provide
explicit `min`/`max` in gradient scale for KPIs; auto-domain over a
single row always collapses.

## Precedence

`chart.<channel>` (data-bound) wins over `chart.style.<channel>` (literal).
Using a data-bound form under `chart.style.<channel>` is a validation error.
On `type: table`/`type: kpi`, `conditional_formatting` rules apply on top
of the per-channel encoding for matching rows.

A KPI's support row colors below its `conditional_formatting` outputs, which
win over everything:

- support value: `style.support.font.color`, then `style.support.tone`, then muted ink
- support glyph: `style.support.glyph.font.color`, then `style.support.tone`,
  then `style.support.font.color`, then muted ink
- headline glyph and affix: their own `font.color`, then the headline value's ink

## Legend

When `color` is bound to a series column, dbt Charts renders a legend mapping
each distinct value to its swatch. Two `style.legend` fields tune the legend
itself without touching the color scale:

- `symbol_limit`: caps the number of legend entries shown. Useful for a
  high-cardinality series that would otherwise overflow the legend area.
- `values`: an explicit list pinning which entries appear in the legend and
  in what order, overriding the default order dbt Charts infers from the color
  scale's domain. This only reorders/filters the legend itself; it does not
  filter which rows are plotted on the chart. `values: []` renders an empty
  legend; it does not fall back to the default order the way an omitted
  `values:` does.

Each entry in `values` can be spelled either the way the legend renders it,
or as the underlying column/measure name: case, `-`/`_`/space differences
all resolve to the same entry (`net_revenue`, `Net Revenue`, and
`net-revenue` all select the same series). A dimensionless wide
`y: [...]` chart's legend text always matches its y-axis title, so
either the raw column name or that display text works there too. When
the chart also authors `color:` as a dimension the measures cross with,
each entry is a `<dimension value> - <measure label>` composite instead:
author that composite spelling (the dimension value paired with either
the raw or the display measure name). The bare measure name alone is
ambiguous across dimension values and will not resolve.

An entry that doesn't match anything, or matches more than one domain
entry, is dropped and reported with a warning naming what it tried and
the real domain. If every authored entry misses, the legend falls back
to its full default order instead of rendering empty.

This resolution covers every nominal/ordinal `color:` field on the
families above, including a wide `y: [...]` chart and an overlay's
`layers:` labels. A `point_map`/`bubble_map`'s legend, a temporal
(date/timestamp) or boolean `color:` column's legend, and an all-null
`color:` column (inferred as numeric, the same as any other quantitative
column) are not resolved: `values` there is used exactly as authored,
with no matching and no diagnostic on a miss. Neither is an overlay
whose base `y` isn't quantitative: its shared color scale is never
built, so `legend.values` passes through verbatim there too.

```dbt-charts-example
queries:
  revenue_by_channel:
    columns: [month, channel, revenue]
    values:
      - ["2026-01", "Organic", 42000]
      - ["2026-01", "Paid", 18000]
      - ["2026-01", "Referral", 9000]
      - ["2026-02", "Organic", 47000]
      - ["2026-02", "Paid", 21000]
      - ["2026-02", "Referral", 8500]

charts:
  channel_revenue:
    query: revenue_by_channel
    type: bar
    title: Revenue by Channel
    x: month
    y: revenue
    color: channel
    style:
      legend:
        values: ["Paid", "Organic", "Referral"]  # pin legend order
        symbol_limit: 5
rows:
  - channel_revenue
```

# Time Axes (https://docs.dbtcharts.com/charts/time-axes/)

# Time Axes

dbt Charts auto-detects the chronological grain of date columns and renders
bucketed-time axes as **ordinal** (evenly-spaced category bands) by default.
Bar, line, and area charts all follow the same rule: the band scale gives
bars their full width, aligns line dots with bar centers, and keeps
support-table column spacing uniform, without any per-chart-type patches.

You can override the detected grain, use explicit time-part units, disable
bucketing entirely, or opt back into a continuous temporal scale for the rare
cases that need it.

For how time-axis labels themselves are laid out (when they tilt, when they
drop, when a continuous time axis bar chart stays vertical even when crowded),
see [Axis Labels: Smart Layout](./axis-labels.md).

## Auto-detection

When `x` is a date/datetime column on a `bar`, `line`, or `area` chart,
dbt Charts inspects the distinct values and picks a grain via two coexisting
detection paths: **calendar-date predicates** (for ISO date/datetime values) and
**labeled string patterns** (for period key strings). Both paths produce a VL
`timeUnit`; the column must use one path exclusively; mixed shapes error.

### Calendar-date predicate path

| Detected grain | Recognized when |
|---|---|
| `year` | All distinct values fall on January 1, or sit whole years apart |
| `yearquarter` | All fall on the 1st of Jan / Apr / Jul / Oct, or sit whole quarters apart |
| `yearmonth` | All fall on the 1st of any month, or sit whole months apart |
| `yearweek` | All fall on the same weekday, a week or two apart |
| `yearmonthdate` | All values are at midnight and no coarser cadence fits (daily) |
| *(none, continuous)* | Any value has nonzero hours/minutes/seconds |

Spacing counts as much as position: month-end closes, quarter-end closes and
invoices dated the 15th all name their real grain even though no value lands on
a bucket start. A cadence is only accepted while each value still gets a bucket
to itself: one off-cadence date among month-end snapshots drops the series back
to daily rather than folding two rows into one month.

### Continuous sub-day axes

A continuous axis with times of day ticks on the clock: 1, 5, 10, 15 or 30
minutes, or 1, 2, 3, 6 or 12 hours, whichever is the finest step that leaves
each label room at the chart's width. Every whole hour is labeled with its hour
(`10am`, `Noon`); the ticks between show only their minutes (`:15`, `:30`).
Spans too long for 12-hour steps, and values carrying a UTC offset, keep the
renderer's own ticks. `ticks.count` and `ticks.time_unit` override the ladder.

### Labeled period-key path

Warehouse exports often return period keys as strings rather than dates. dbt Charts
recognizes these stable shapes directly:

| Pattern | Example | Detected grain |
|---|---|---|
| `YYYY-Www` (ISO week-year) | `2024-W32` | `yearweek` |
| `W[eek ]N YYYY` | `W32 2024`, `Week 32 2024` | `yearweek` |
| `YYYY-Qn` (canonical quarter) | `2024-Q3` | `yearquarter` |
| `Qn YYYY` | `Q3 2024` | `yearquarter` |
| `YYYYQn` | `2024Q3` | `yearquarter` |
| `YYYY-MM` | `2024-01` | `yearmonth` |
| `Mon YYYY` (English month) | `Jan 2024` | `yearmonth` |
| `MM/YYYY` (US month/year) | `01/2024` | `yearmonth` |
| `FYnnnn` (fiscal year key) | `FY2024` | `year` (mapped to Jan 1) |
| `MM/DD/YYYY` (US month/day/year) | `01/15/2024` | `yearmonthdate` |
| `Mon DD[,] YYYY` | `Jan 15, 2024` | `yearmonthdate` |

**Scope:** These patterns detect calendar quarters (Q1 = Jan–Mar, Q2 = Apr–Jun,
Q3 = Jul–Sep, Q4 = Oct–Dec) and always anchor `FY` strings' `year` grain at
Jan 1. To author a fiscal year/quarter that starts in a different month, set
`style.axis_x.fiscal_year_start_month`; see
[Fiscal-quarter offset](#fiscal-quarter-offset) below.

**US-only formats:** `MM/YYYY` and `MM/DD/YYYY` are parsed as US month/day order.
European day-first ambiguity is not detected; set `time_unit` explicitly if your
warehouse returns day-first slash-delimited dates.

**Not supported:** `H1 YYYY` / `YYYY-H1` half-year strings (no Vega-Lite
`timeUnit` for half-year buckets). These are treated as unparseable; use
`time_unit: year` explicitly.

### Year-shape path (bare year INTEGER or `YYYY` string)

dbt marts routinely store the year as a plain `INTEGER` (`launch_year`) or a
display `VARCHAR` (`"2024"`) rather than a date. dbt Charts detects a year-shaped
`x` column: **every** non-null value is an integer in `1700–2100`, or a string
matching `^\d{4}$` in that range, and treats it as the `year` grain, exactly as
if you had cast it to a `DATE`. No `make_date(...)` cast and no
`axis_x.time_unit` are needed:

- On a `bar` chart the years render as evenly-spaced vertical bands with `%Y`
  ("2024") tick labels; no `~s` SI suffix ("2.02k") and no auto-flip to
  horizontal that a plain `VARCHAR` category would trigger.
- On a `line`/`area` chart they render on a continuous temporal scale (see the
  scale-type section below).

The detection is value-only; the column *name* is never consulted, so a
`revenue_bucket` column holding `2010, 2011, …` is treated the same as one named
`year`. Non-year integers (counts, ids, ratings) stay quantitative. An authored
`axis_x.type` or `axis_x.scale.continuous.type` always overrides the inference.

### Emitted scale type

Each detected bucket becomes an evenly-spaced band on an `ordinal` x-axis for
`bar`/`column` charts; `line`/`area` charts emit a continuous `temporal` scale
(a trend line reads over real time). Bar width, line-dot alignment, and
support-table column spacing all follow band geometry automatically. Either
default is overridden by an authored `axis_x.type`.

## Authoring

Override the detected grain or disable bucketing via `style.axis_x.time_unit`:

```yaml {contract=board-root}
charts:
  monthly_revenue:
    type: bar
    x: month
    y: revenue
    style:
      axis_x:
        time_unit: yearmonth   # explicit override
```

Valid values:

| Value | Meaning |
|---|---|
| `auto` | Default; auto-detect from data |
| `year` | Force year bucketing |
| `yearquarter` | Force quarter bucketing |
| `yearmonth` | Force month bucketing |
| `yearweek` | Force ISO-week bucketing |
| `yearmonthdate` | Force daily bucketing |
| `monthofyear` | Extract month-of-year (`Jan` ... `Dec`) |
| `dayofweek` | Extract day-of-week |
| `dayofmonth` | Extract day-of-month |
| `dayofyear` | Extract day-of-year |
| `hourofday` | Extract hour-of-day |
| `none` | Disable bucketing; continuous temporal scale |

dbt Charts uses long-form names for time-part units, then maps them to Vega-Lite
primitives at emission time: `monthofyear` -> `month`, `dayofweek` -> `day`,
`dayofmonth` -> `date`, `dayofyear` -> `dayofyear`, and `hourofday` -> `hours`.

### Bucketing places rows; it does not aggregate them

A row belongs to the bucket its date falls inside, so a period reported at its
last instant (`LAST_DAY(month)` month-ends, quarter-ends, a fixed day of the
month) plots in its own bucket and needs no change to your SQL.

What a coarser grain will not do is combine rows. Two rows inside one bucket
(monthly rows under `yearquarter`, daily rows under `yearmonth`) have no single
value to plot, so dbt Charts raises
[`ERR-GAP-FILL-BUCKET-COLLISION`](../reference/errors.md) rather than picking
one and discarding the rest. Aggregate to the grain in the query.

### Fiscal-quarter offset

`year` and `yearquarter` bucketing default to the calendar convention (year
starts January, Q1 = Jan–Mar). Businesses whose fiscal year starts in a
different month set `style.axis_x.fiscal_year_start_month` (1=Jan..12=Dec):

```yaml {contract=board-root}
charts:
  fiscal_quarterly_revenue:
    type: bar
    x: quarter
    y: revenue
    style:
      axis_x:
        time_unit: yearquarter
        fiscal_year_start_month: 4   # fiscal Q1 = Apr-Jun
```

The offset shifts bucket boundaries, Q1..Q4 numbering, and the axis label's
year-boundary line break together; there is no separate "fiscal" mode to
keep in sync. It applies on both ordinal (bar, or `line`/`area` with
`curve: step-band`) and continuous-temporal (`line`/`area`) scales: at a
non-default offset, dbt Charts always buckets fiscally in Python rather than
handing the field to Vega-Lite's native `timeUnit`, since Vega-Lite's own
`timeUnit` transform has no fiscal-offset concept and would silently
re-bucket to calendar-aligned boundaries.

## Scale type: default depends on mark

For a bucketed-calendar grain the default scale type depends on the mark:
`bar`/`column` default to `ordinal` (evenly-spaced bands, one per bucket);
`line`/`area`/`scatter` default to `temporal` (a continuous time scale so a
trend reads over real calendar time and irregular gaps are preserved, and a
scatter point sits at its real position rather than snapping to a band).

The `bar`/`column` default is a starting point, not a guarantee: a band axis
owes one slot per bucket across the whole span, so on data that is sparse for
its detected grain those bands become an unreadable comb. Past a density
budget (60 buckets) an
auto-detected grain is dropped and the axis resolves `temporal`. That holds for
every grain detection picks on its own, coarse or fine: twelve readings a decade
apart honestly detect `year`, yet would owe the axis ten empty year bands for
every bar. `line`/`area`/`scatter` are never re-typed this way, since they stay
`temporal` regardless of density, but an over-budget grain is still dropped for
them too. The axis paints one gridline and label per bucket whether or not the
mark bands to it, so a sparse grain falls back to Vega-Lite's own
continuous-temporal ticks rather than a solid gray stripe of gridlines. An
authored `time_unit` is never dropped.

If a bar chart renders on a continuous time axis you did not ask for, this is
why — pin it with `axis_x.type: ordinal`, or coarsen the grain in the query and
name it with `axis_x.time_unit` (a coarser `time_unit` alone will not combine
the rows; see above).

Override either with `axis_x.type`:

```yaml {contract=chart-body}
style:
  axis_x:
    type: temporal   # force a continuous time scale (for example, on a bar chart)
```

| `axis_x.type` | Scale | When to use |
|---|---|---|
| `auto` (default) | Ordinal for `bar`/`column` unless the data is too sparse for its grain, then temporal; always temporal for `line`/`area`/`scatter` | The common case |
| `ordinal` | Ordinal (explicit) | Force bands on a line/area/scatter, or document bar intent |
| `temporal` | Continuous temporal | Force a time scale on a bar; irregular sampling |

`time_unit: none` always produces a continuous temporal scale regardless of
`axis_x.type`.

Heatmap's x is always a nominal grid dimension (one band per column,
regardless of mark or bucket count) so it sits outside this ordinal/temporal
choice entirely. It still gets the same label vocabulary and visibility
thinning described above and in [Axis Labels](./axis-labels.md): the domain
value stays the raw bucket key (so cells keep chronological order), and only
the painted label text follows the calendar cadence.

### Extending the visible range past the data: `scale.continuous.type` + `scale.continuous.domain`

`axis_x.scale.continuous.type: temporal` is a second spelling of the same escape hatch,
for authors who reach for the scale block rather than the axis-level `type`
field. It's required before an authored `scale.continuous.domain` of ISO dates can pin
the visible range past the data extent: a domain only means anything on a
continuous scale:

```yaml {contract=chart-body}
style:
  axis_x:
    scale:
      continuous:
        type: temporal
        domain: ["1955-01-01", "2026-01-01"]   # pads the axis before/after the data
```

Authoring `scale.continuous.domain` on a date axis **without** `scale.continuous.type: temporal`
(or `axis_x.type: temporal`) raises a compile error rather than silently
collapsing every mark: Vega-Lite reads a 2-element domain on the default
ordinal (band) scale as exactly two category values, not a `[low, high]`
range, so every mark lands on the domain's first "category."

## Tick cadence: step-anchored `time_unit` + `step`

`style.axis_x.ticks.count` (see [Axis Labels](./axis-labels.md)) asks Vega-Lite
for a target *number* of ticks, a plausible-sounding integer that VL treats
as advisory, and that has no relationship to your domain's actual calendar
width. Reaching a clean "every 5 years" cadence with `count` means guessing
which integer happens to produce 5-year spacing on your particular date
range.

`style.axis_x.ticks.time_unit` (with an optional `step`) names the cadence
directly instead: *"ticks at every 5 years, anchored on multiples of 5"*,
the same way an author says "quarterly" or "every other month".

```yaml {contract=chart-body}
style:
  axis_x:
    ticks:
      time_unit: year
      step: 5   # every 5 years; 1900, 1905, 1910, ...
```

`time_unit` alone (no `step`) is equivalent to `step: 1`; one tick per unit.
dbt Charts maps the calendar grain to Vega-Lite's native `axis.tickCount:
{interval, step}` (`year` → `year`, `yearquarter` → `quarter`, `yearmonth` →
`month`); d3 (VL's tick engine) anchors ticks on multiples of `step`,
including odd steps, with no date materialization on dbt Charts's side.

Constraints:

- **`time_unit` accepts `year`, `yearquarter`, or `yearmonth` only**: the
  grains whose mapped d3 interval (year/quarter/month) anchors cleanly.
  Day/week cadences give irregular spacing (d3's own documented caveat) and
  are out of scope.
- **Continuous temporal `axis_x` only.** The axis must resolve to a
  continuous temporal scale (see [Scale type](#scale-type-default-depends-on-mark)
  above); an ordinal bucketed axis (for example, a low-density monthly bar chart)
  has no VL tick-count concept to pass this through to, and raises rather
  than silently doing nothing.
- **On a temporal axis, `step` requires `time_unit`.** A bare number names no
  calendar unit, so a temporal axis raises rather than guessing one. (On a
  *quantitative* x-axis a bare `step` is the numeric tick interval; see
  [Axis & scales](./axis-scales.md#tick-cadence-on-a-quantitative-axis).)
- **Mutually exclusive with `ticks.count`.** They are two different ways to
  express tick cadence; author one or the other, not both.
- **`axis_y` is rejected.** The measure axis is never temporal in dbt Charts's
  cartesian model.
- **No anchor override.** Ticks always anchor on multiples of `step`
  (d3's own default); there is no field to shift the anchor off that grid.
- **Endpoint control belongs to `labels.values`** (see [Axis Labels](./axis-labels.md))
  ; this surface only controls tick/grid density, not which labels render.

```dbt-charts-example
queries:
  index_series:
    columns: [year, index]
    values:
      - ["2006-01-01", 245.0]
      - ["2007-01-01", 251.0]
      - ["2008-01-01", 260.4]
      - ["2009-01-01", 265.9]
      - ["2010-01-01", 272.0]
      - ["2011-01-01", 279.0]
      - ["2012-01-01", 282.2]
      - ["2013-01-01", 288.6]
      - ["2014-01-01", 296.4]
      - ["2015-01-01", 306.1]
      - ["2016-01-01", 308.7]
      - ["2017-01-01", 313.5]
      - ["2018-01-01", 316.1]
      - ["2019-01-01", 326.6]
      - ["2020-01-01", 336.2]
      - ["2021-01-01", 338.3]
      - ["2022-01-01", 351.6]
      - ["2023-01-01", 365.3]
      - ["2024-01-01", 375.5]
      - ["2025-01-01", 385.4]

charts:
  index_line:
    query: index_series
    type: line
    title: Index
    x: year
    y: index
    style:
      axis_x:
        ticks:
          time_unit: year
          step: 5
rows:
  - index_line
```

## Gap handling: synthesized rows for missing buckets

Ordinal scales only render bands for values that exist in the data. If your query
returns months `Jan`, `Mar`, and `Apr` (February skipped because there were no
events), Vega-Lite silently drops the February slot and the resulting chart
looks like Jan → Mar → Apr with equal spacing, indistinguishable from a
chart where February genuinely follows January.

When the engine detects a bucketed-calendar grain (`year`, `yearquarter`,
`yearmonth`, `yearweek`, `yearmonthdate`) on an ordinal x-axis, it
automatically synthesizes rows for every missing bucket between the minimum
and maximum date in the data window, ensuring every slot is rendered. When a
`filter_date_range()` provably bounds the axis, the window is the filtered range
instead (see [Range-pinned axes](#range-pinned-axes)).

The `fill` field on `axis_x` controls what value is inserted for
synthesized rows:

| Value | Effect |
|---|---|
| `"null"` | Missing measure columns receive `null`. Lines and areas break at `null`. **Theme default.** Write it as a quoted string (`fill: "null"`); a bare `fill: null` is rejected. |
| `zero` | Missing measure columns receive `0`. Event-count charts where a missing bucket means zero events. |
| `linear` | Straight-line values between observed neighbors (interior gaps only). |
| `step-after` | Looker **Step (after)**: forward-fill from the last observed bucket. |
| `step-before` | Looker **Step (before)**: each gap takes the next observed bucket’s value. |
| `step-center` | Looker **Step (center)**: hold left value until the gap midpoint, then the right value. |
| `curve` | Smooth S-curve (smoothstep) between neighbors; softer than `linear`, same endpoints. |

`linear`, `step-*`, and `curve` fill **interior** synthetic buckets only; each `color`
/ stack series is filled independently.

**Scatter default:** `style.charts.axis_x.fill` is the global default for
bar/line/area. The theme pins `style.charts.scatter.axis_x.fill: null` so that
a *theme-level* change to the global fill does not connect gaps on point
charts. An explicit fill you author yourself, board-wide
(`style.charts.axis_x.fill`) or on a single chart (`style.axis_x.fill`), still
takes effect on scatter, so set it per-chart or per-family if you want scatter
to keep its honest, ungap-filled dots.

```yaml {contract=board-root}
charts:
  weekly_signups:
    type: line
    x: week
    y: signups
    style:
      axis_x:
        fill: "null"   # explicit null-fill override (bare null = cascade-inherit; quote to pin)

  weekly_orders:
    type: bar
    x: week
    y: order_count
    style:
      axis_x:
        fill: zero    # missing weeks show as zero-height bars

  monthly_revenue_on_weekly_grid:
    type: area
    x: week
    y: revenue
    style:
      axis_x:
        fill: linear   # smooth bridge across sparse samples
```

**Multi-series charts:** The engine cross-joins every bucket in the window
with every dimension value observed in the data. "Observed" means only
values that appear in the query result; if a new dimension value appears
partway through the window, synthetic rows before its first appearance
carry `null`/`0` measures for that value only.

**Escape hatches:** Gap-fill is skipped entirely when:

- `axis_x.type: temporal` (continuous scale; VL handles irregular gaps visually)
- `time_unit: none` (non-bucketed continuous axis)
- A non-bucketed grain is detected (`monthofyear`, `dayofweek`, etc.)

## Range-pinned axes

A board with a `daterange` variable filters its queries with
[`filter_date_range()`](../variables/expressions.md#date-range-filtering). When the
chart's `x` column is provably the column that filter constrains, the chart knows
the range the viewer picked and draws the axis across all of it. Without this,
the axis shrinks to the first and last bucket that happened to have rows.


```yaml {contract=board-root}
variables:
  date_range:
    input: daterange

queries:
  weekly_orders:
    sql: |
      SELECT
        date_trunc('week', created_at) AS week,
        count(*) AS orders
      FROM dundersign.orders
      WHERE {{ filter_date_range('created_at', date_range) }}
      GROUP BY 1
      ORDER BY 1
    source: my_postgres

charts:
  weekly_orders:
    query: weekly_orders
    type: bar
    x: week
    y: orders
    style:
      axis_x:
        fill: zero

rows:
  - weekly_orders
```


With the range set to March 2026, the axis runs from the week containing March 1
to the week containing March 31, even if orders only exist in the middle weeks.

- **Band (ordinal) axes**: the empty
  buckets at the range's edges get slots, exactly as interior gaps already do
  (see [Gap handling](#gap-handling-synthesized-rows-for-missing-buckets)).
  They are filled by `style.axis_x.fill` the same way: `"null"` (the default)
  draws nothing, `zero` draws zero-height bars, `step-after` carries the last
  value forward. Nothing is added to the query's own result.
- **Continuous temporal axes** (an authored `type: temporal`, or a series
  past the band budget): the x scale domain runs from the start of the bucket
  containing the range's start. It ends at the start of the bucket containing the
  range's end for lines and areas, whose marks sit at the bucket start, and at
  that bucket's end for bars. With no bucket it ends after the last day.

### When it applies

Only when the engine can prove the link from the rendered SQL. The `x` column must
come from the filtered column through date-preserving steps only (the column
itself, an alias, a `CAST` to a date or timestamp, or a date truncation such as
`date_trunc('week', created_at)`, through any number of CTEs and joins), and the
`filter_date_range()` must be an `AND`-ed condition in the `WHERE` of the select
that reads it. The axis behaves as it did before when:

- `x` derives from a different column than the one filtered.
- `x` is `EXTRACT(month ...)`, a day of week, arithmetic, an aggregate, or a
  date shifted by a time zone or modifier: it no longer names a point in the range.
- `style.axis_x.time_unit` is a time part (`monthofyear`, `dayofweek`,
  `dayofmonth`, `hourofday`...): its axis is not a calendar.
- The filter sits under `OR` or `NOT`, or the same column carries two
  `filter_date_range()` calls.
- The query is a `UNION`, uses `SELECT *` over the filtered table, has an
  unqualified column in a join, or otherwise cannot be traced.
- The chart has layers reading their own queries, or a layer plots its own `x`.
- The query's source is a file source or a `dbt_profile` source, or the query
  composes `{{ queries.X.cache }}`.
- The query names no source and sets no `dialect:`, so there is no SQL dialect to
  read it in.
- A bound is computed from the range rather than stated by it (for example
  `DATE '2026-03-01' - INTERVAL '1' YEAR`), or a plotted date falls outside the
  range-spanning axis.
- A range bound is a string ISO 8601 parsing rejects (such as `2026/03/01`): the
  filter still runs, but no range is recorded.
- Spanning the range would put the band axis past 60 empty buckets.
- The range's bounds are datetime values (not dates or date strings): a whole-day
  axis would show the hours they exclude as empty.
- The variable is unset: no range, no pin.

### Overriding it

An authored
[`scale.continuous.domain`](#extending-the-visible-range-past-the-data-scalecontinuoustype--scalecontinuousdomain)
(with `type: temporal`) always wins, and the range is ignored.

## Supported source formats per grain

### `year`

| Source format | Example |
|---|---|
| ISO date at Jan 1 | `2024-01-01` |
| Python `date` object | `date(2024, 1, 1)` |
| Fiscal-year key | `FY2024` (mapped to Jan 1) |

**Recommended SQL:** `date_trunc('year', date) AS year` (produces ISO dates for
auto-detection). `EXTRACT(YEAR FROM date)` returns an integer column which is
typed quantitative, not temporal.

### `yearquarter`

| Source format | Example |
|---|---|
| ISO date at quarter start | `2024-01-01`, `2024-04-01`, `2024-07-01`, `2024-10-01` |
| Canonical quarter label | `2024-Q1`, `2024-Q2`, `2024-Q3`, `2024-Q4` |
| Quarter-first label | `Q1 2024`, `Q2 2024` |
| Compact quarter label | `2024Q1`, `2024Q2` |

**Recommended SQL:** `date_trunc('quarter', date) AS quarter` (produces ISO
dates), or `CONCAT(YEAR, '-Q', QUARTER) AS quarter` for labeled exports.

### `yearmonth`

| Source format | Example |
|---|---|
| ISO date at month start | `2024-01-01`, `2024-02-01`, … |
| Python `date` at month start | `date(2024, 1, 1)` |
| Year-month string | `2024-01`, `2024-12` |
| English month-name string | `Jan 2024`, `February 2024` (3-letter abbreviation only) |
| US month/year slash | `01/2024`, `12/2024` |

**Recommended SQL:** `date_trunc('month', date) AS month`

**Display:** Smart default applies `%b %Y` → `Jan 2024` on the ordinal axis via
`axis.formatType: "time"`. Override with `style.axis_x.labels.format`.

### `yearweek`

| Source format | Example |
|---|---|
| ISO date at week start (Monday) | `2024-01-01`, `2024-01-08`, … |
| ISO week-year label | `2024-W01`, `2024-W32` |
| Spelled week label | `W32 2024`, `Week 32 2024` |

**Recommended SQL:** `date_trunc('week', date) AS week` (produces ISO dates), or
`CONCAT(ISO_YEAR, '-W', LPAD(ISO_WEEK, 2, '0')) AS week` for labeled exports.

**Note:** ISO week-start is Monday. US Sunday-start weeks are out of scope.

**Default label cadence:** Measured. On a bucket-aligned column chart with room
for them, every week is labeled with the day of month it starts on. The
three-letter month appears on a second row under the first week of each month:

```text
 6  13  20  27   3  10  17  24   3  10  17  24  31
Jan'25          Feb             Mar
```

The first visible label always carries the year. On continuous line and area
axes, Vega's weekly scale positions ticks on Sunday; dbt Charts labels each tick
with the represented ISO Monday bucket without moving the tick. When the day
numbers no longer fit, labels promote to month text and default ticks follow the
month openers. Further thinning can show fewer month labels without removing
ticks. The weekly encoding grain remains unchanged throughout.

### `yearmonthdate` (daily)

| Source format | Example |
|---|---|
| ISO date | `2024-01-15` |
| ISO datetime at midnight | `2024-01-15T00:00:00` |
| Python `date` / `datetime` (midnight) | `date(2024, 1, 15)` |
| US month/day/year slash | `01/15/2024` |
| English day-name string | `Jan 15, 2024`, `Jan 15 2024` |

**Recommended SQL:** `date::DATE` or `date_trunc('day', date)`

**Default label cadence:** A short bucket-aligned column chart labels every day
with its day of month and puts month context on a second row. As the labels stop
fitting, the cadence steps first to Mondays (still shown as day numbers) and then
to month text. Default ticks follow a format promotion, but later
visibility-only thinning leaves them alone.

## Time-Part Units

Use time-part units when the question compares a recurring calendar part rather
than elapsed time. The x column should still be a real date or timestamp; Vega-
Lite extracts the requested part. Time-part units remain on a temporal scale
(they represent cyclic comparison, not ordered buckets).

```yaml {contract=board-root}
charts:
  revenue_by_month_of_year:
    type: bar
    x: order_date
    y: revenue
    style:
      axis_x:
        time_unit: monthofyear

  orders_by_day_of_week:
    type: bar
    x: order_ts
    y: order_count
    style:
      axis_x:
        time_unit: dayofweek
```

`time_unit: auto` does not infer time-part intent from field names. If you want
seasonality, day-of-week, or hour-of-day behavior, author the time part
explicitly.

## Failures

dbt Charts fails loud (raises an error) when:

- ≥10% of distinct values are unparseable as dates or recognized label patterns.
  Fix the query or cast the column.
- A column contains **mixed shapes**, for example, some values are `2024-W32` (week
  labels) and others are `2024-01-15` (ISO dates), or week labels alongside
  quarter labels. Set `style.axis_x.time_unit` explicitly for ambiguous columns.

Use `style.axis_x.time_unit: none` for raw event data with sub-daily
timestamps; detection returns continuous temporal automatically, but the
explicit override documents intent.

## Axis labels

`style.axis_x.time_unit` controls the data bucket sent to Vega-Lite.
`style.axis_x.labels.time_unit` controls label vocabulary when authored.
Automatic label vocabulary can adapt to the domain and chart width; the
encoding time unit never changes.

```yaml {contract=chart-body}
style:
  axis_x:
    time_unit: yearmonth
    labels:
      time_unit: yearquarter
```

When `labels.time_unit` is omitted, dbt Charts measures bucket-aligned daily and
weekly labels against the available width. Daily labels try every day, then
Mondays, then month text. Weekly labels try every week, then month text. The
encoding grain and chart data remain unchanged, while default ticks follow a
promoted display grain at the first source bucket that opens each period.
Continuous line and area axes remain continuous; weekly ticks still use the
compact Monday-bucket label described above. An authored label time unit pins
its vocabulary regardless of width.

An authored `labels.time_unit: yearquarter` uses `Q1`–`Q4`, including fiscal
quarter numbering, and makes quarter boundaries the default tick cadence. On a
continuous temporal axis, an authored `axis_x.ticks.count` or
`axis_x.ticks.interval` overrides that default.

Label density after display-grain selection is a separate render-time
decision. When labels do not fit, dbt Charts skips labels while preserving the
resolved vocabulary. Monthly labels therefore thin to fiscal-quarter openers:
`Jan`/`Apr`/`Jul`/`Oct` for a January fiscal year, or
`Mar`/`Jun`/`Sep`/`Dec` for a March fiscal year. Width-driven visibility
thinning does not change ticks or gridlines.

If the thinned labels still do not fit, dbt Charts tries the configured
`labels.tilt_increments`. The order is always skip, then tilt, and the existing
`labels.overlap.skip` and `labels.overlap.tilt` switches control those steps.
The fiscal opener is the phase anchor. The first visible label always includes
the year, even when that label is not itself a fiscal-year opener.

Set `labels.time_unit: none` to disable dbt Charts's smart label expression and
let Vega-Lite format the axis.

A date axis already labels itself by grain (`Jan 2024` for `yearmonth`, and so
on), so set `style.axis_x.labels.format` only when you want a different form
than the grain default. Here, numeric `01/2024` instead of `Jan 2024`:

```yaml {contract=chart-body}
style:
  axis_x:
    time_unit: yearmonth
    labels:
      format: "%m/%Y"
```

For label-density tuning (when monthly labels feel too cramped even without
bounding-box overlap) see [Label density](../styling.md#label-density).

# Overview (https://docs.dbtcharts.com/boards/)

# Boards

Boards are the fundamental building blocks of dbt Charts. They are containers that define what to render (charts, text), how to render it (layout type), and where to place it. Since boards can contain other boards, you can nest them infinitely to create complex, structured layouts.

---

## Basic Board Structure

A board defines layout and content. The layout is determined by the presence of type-specific keys (for example, `rows`, `cols`, `grid`, `tabs`).

```dbt-charts-example
# A simple board with rows (vertical stack)
source: examples_db
title: "Sales Overview"

queries:
  sales_by_category:
    sql: |
      SELECT category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY category ORDER BY revenue DESC
  sales_by_date:
    sql: |
      SELECT date, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY date ORDER BY date

charts:
  revenue:
    query: sales_by_category
    type: bar
    x: category
    y: revenue
  orders:
    query: sales_by_date
    type: line
    x: date
    y: units_sold
  trend:
    query: sales_by_date
    type: line
    x: date
    y: revenue

rows:
  - title: "KPIs"
    cols: # Horizontal stack
      - revenue
      - orders

  - title: "Trends"
    rows: # Nested vertical stack
      - trend
```

---

## Core Concepts

### Layout Types

Boards support four layout types that determine how children are arranged:

| Layout | Key | Description |
|--------|-----|-------------|
| **Rows** | `rows:` | Vertical stack (default) |
| **Cols** | `cols:` | Horizontal side-by-side |
| **Grid** | `grid:` | Flexible grid with positioning |
| **Tabs** | `tabs:` | Tabbed interface |

See [Layouts](layouts.md) for detailed examples of each type.

### Recursive Structure

Boards can contain charts OR other boards. This recursive structure means you can nest and vary layouts infinitely to create complex designs.

```yaml {contract=unverified}
title: "Company Dashboard"
rows:
  - title: "Sales"
    cols:
      - title: "Q1"
        rows: ...
      - title: "Q2"
        rows: ...

  - title: "Marketing"
    rows: ...
```

---

## Field Reference

```yaml {contract=unverified}
# Board fields
title: string              # Optional display title
notes: string                # Optional AI search metadata; never appears in the rendered board (Cloud shows it in the dashboard-card hover)

# Layout (choose one)
rows: [items]              # Vertical stack
cols: [items]              # Horizontal stack
grid:                      # Grid layout
  columns: number
  items: [grid_items]
tabs:                      # Tabbed interface
  items: [tab_items]

# Content
text: string            # Markdown content block
charts:                    # Chart definitions
  <chart_id>: {...}
queries:                   # Query definitions
  <query_id>: {...}
variables:                 # Variable definitions
  <var_id>: {...}

# Styling
style:
  background: string       # Background color (hex, rgb, or named color)
  border: string           # CSS border shorthand (for example, "3px solid #667eea")
  # border:                # Or nested block for radius + color + width separately
  #   radius: number       #   Border radius in px (for example, 12)
  #   color: string        #   Border color
  #   width: number        #   Border width in px
  font:
    color: string          # Text color (hex, rgb, or named color)
```

---

## Board Styling

Boards support styling properties that control their visual appearance. Styles are applied to nested boards to create visual hierarchy and organization.

### Style Properties

```yaml {contract=board-fragment}
rows:
  - title: "Styled Section"
    style:
      background: "#f5f5f5"        # Background color
      border:
        color: "#667eea"           # Border color
        width: 2                   # Border width (px)
        radius: 12                 # Rounded corners (px)
      font:
        color: "#667eea"           # Text color
    cols:
      - chart1
      - chart2
```

### Available Style Properties

| Property | Type | Description | Example |
|----------|------|-------------|---------|
| `background` | string | Background color (hex, rgb, or named color) | `"#f5f5f5"`, `"rgb(255, 0, 0)"`, `"white"` |
| `border` | string or mapping | CSS border shorthand, or nested block with `color`, `width`, `radius` | `"2px solid #667eea"` or `{color: "#667eea", width: 2, radius: 12}` |
| `font.color` | string | Text color for prose and titles (to color titles alone, use `style.title.font.color`) | `"#667eea"`, `"#333"`, `"red"` |

### Styling Examples

**Colored Border with Rounded Corners:**
```yaml {contract=board-root}
rows:
  - title: "Main Container"
    style:
      border:
        color: "#667eea"
        width: 3
        radius: 12
      font:
        color: "#667eea"
    cols:
      - text: "This section has a colored border and rounded corners."
```

**Background with Border:**
```yaml {contract=board-fragment}
rows:
  - title: "Highlighted Section"
    style:
      background: "#fff3cd"
      border:
        color: "#ffc107"
        width: 1
        radius: 8
    rows:
      - chart1
      - chart2
```

**Nested Styling:**
```yaml {contract=board-root}
rows:
  - title: "Outer Container"
    style:
      border:
        color: "#764ba2"
        width: 2
        radius: 8
    cols:
      - title: "Inner Section"
        style:
          border:
            color: "#9c27b0"
            width: 1
            radius: 6
          font:
            color: "#9c27b0"
        text: "Nested boards can have their own styles."
```

### Style Inheritance

A child board inherits its parent's style, including `frame`, `layout` and `gap`, whether or not it sets its own `style:`. `padding`, `margin`, `footer`, `timestamp` and `background` are per board and never inherited.

---

## Focusing a Single Chart

To get one chart on its own, append a single line to the bottom of any board:

```yaml {contract=unverified}
chart_focus: <chart_id>
```

That renders just that chart in its own minimal layout, dropping every other chart and any variable it doesn't depend on; useful for embedding a single chart on another page, or exporting it standalone (SVG/PNG) without exporting the whole board around it. Nothing above it has to change:

```dbt-charts-example
title: "Sales Overview"

source: examples_db
queries:
  sales_by_category:
    sql: |
      SELECT category, SUM(revenue) AS revenue FROM ecommerce_orders GROUP BY category ORDER BY revenue DESC

charts:
  revenue:
    query: sales_by_category
    type: bar
    x: category
    y: revenue
  orders:
    query: sales_by_category
    type: kpi
    value: revenue

rows:
  - revenue
  - orders

# Append this one line and only the revenue chart renders:
# no other part of the board changes. Delete it to get the board back.
chart_focus: revenue
```

Only `revenue` renders. `orders` is dropped, and so is the board's own `title:`; a focused view has no board-level title. The focused chart renders at its own width, as if it were the only chart on a board with no width: its authored `width:`, else its preferred width (a table hugs its columns). It does not keep the slot it had on the dashboard, and an authored board `frame.width` does not carry over.

`chart_focus` is a root-level key, so it takes effect wherever you put it in the root board's file; the bottom just keeps it to one appended line. Setting it on a nested board is a no-op.

---

## Metadata Fields

A few root-level fields describe a board without changing how it renders:

| Field | Description |
|-------|-------------|
| `tags` | List of strings for categorizing boards. `dct search` filters by tag (a board matches only when it has all requested tags). |

```yaml {contract=board-root}
title: "Weekly Revenue"
tags: [sales, weekly, revenue]
```

---

## Related

- [Layouts](layouts.md) - Rows, cols, grid, and tabs
- [Content](content.md) - Markdown and mixed content
- [Sizing](sizing.md) - Width and height control
- [Imports](imports.md) - Reusability and file imports
- [Examples](examples.md) - Advanced layout patterns
- [Charts](../charts/index.md) - Chart configuration
- [Themes](../themes.md) - The built-in themes and how to write your own
- [Styling](../styling.md) - Colors, fonts, borders, and formats

# Board Layouts (https://docs.dbtcharts.com/boards/layouts/)

# Board Layouts

The layout of a board determines how its children (charts and nested boards) are arranged. dbt Charts supports four layout types.

---

## Rows (Vertical Stack)

Items are arranged vertically, one after another. This is the default structure for top-level boards.

```dbt-charts-example
source: examples_db
title: "Sales Dashboard"

queries:
  sales_by_category:
    sql: |
      SELECT category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY category ORDER BY revenue DESC
  sales_by_date:
    sql: |
      SELECT date, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY date ORDER BY date
  sales_by_product:
    sql: |
      SELECT product, category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY product, category ORDER BY revenue DESC

charts:
  revenue_by_category:
    query: sales_by_category
    type: bar
    title: "Revenue by Category"
    x: category
    y: revenue
  orders_trend:
    query: sales_by_date
    type: line
    title: "Orders Over Time"
    x: date
    y: units_sold
  products_breakdown:
    query: sales_by_product
    type: pie
    title: "Product Breakdown"
    theta: revenue
    color: product

rows:
  - revenue_by_category
  - orders_trend
  - products_breakdown
```

**Use rows when:**
- Content should flow vertically
- Building mobile-friendly layouts
- Creating scrollable dashboards

---

## Cols (Horizontal Stack)

Items are arranged horizontally, side-by-side.

```dbt-charts-example
source: examples_db
title: "Comparison View"

queries:
  sales_by_product:
    sql: |
      SELECT product, category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY product, category ORDER BY revenue DESC
  sales_by_date:
    sql: |
      SELECT date, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY date ORDER BY date
  sales_summary:
    sql: |
      SELECT SUM(revenue) AS revenue, SUM(units_sold) AS units_sold, COUNT(DISTINCT category) AS category_count FROM ecommerce_orders

charts:
  revenue:
    query: sales_by_product
    type: bar
    title: "Revenue"
    x: product
    y: revenue
  orders:
    query: sales_by_date
    type: line
    title: "Orders"
    x: date
    y: units_sold
  growth:
    query: sales_summary
    type: kpi
    label: "Total Revenue"
    value: revenue

cols:
  - revenue
  - orders
  - growth
```

**Use cols when:**
- Comparing metrics side-by-side
- Creating sidebars
- Building wide-screen layouts

---

## Grid Layout

Items are arranged in a flexible grid. Items flow automatically into the next available space, but you can control their position and size using `col`, `row`, `width` and `height`.

```dbt-charts-example
source: examples_db
title: "Grid Dashboard"

queries:
  sales_summary:
    sql: |
      SELECT SUM(revenue) AS revenue, SUM(units_sold) AS units_sold, COUNT(DISTINCT category) AS category_count FROM ecommerce_orders
  sales_by_product:
    sql: |
      SELECT product, category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY product, category ORDER BY revenue DESC
  sales:
    sql: |
      SELECT * FROM ecommerce_orders

charts:
  kpi1:
    query: sales_summary
    type: kpi
    label: "Total Revenue"
    value: revenue
  kpi2:
    query: sales_summary
    type: kpi
    label: "Units Sold"
    value: units_sold
  kpi3:
    query: sales_summary
    type: kpi
    label: "Categories"
    value: category_count
  main_chart:
    query: sales_by_product
    type: bar
    title: "Revenue by Product"
    x: product
    y: revenue
  sales_table:
    query: sales
    type: table
    title: "Sales Data"

grid:
  columns: 24
  items:
    - item: kpi1
      width: 8
    - item: kpi2
      width: 8
    - item: kpi3
      width: 8
    - item: main_chart
      width: 24
    - item: sales_table
      width: 24
```

### Grid Features

- **Flow**: Items without `col,row` fill the next available space
- **Pinning**: Items with `col,row` are fixed to that position
- **Default span**: An item that sets neither `width` nor `height` spans one column and one row
- **Overlapping**: Multiple items can occupy the same cells
- **Row height**: Grid rows size to their content: set a per-item `height` in row units to make an item taller
- **Gap**: Spacing between cells is set by `style.layout.grid.gap`, in pixels

**Note**: Sizing properties (`width`, `height`, `col`, `row`) are defined on the layout item, not the chart itself.

---

## Tab Layout

Organize items into tabs. Each item in the `items` list is a nested board that defines the content for that tab.

```dbt-charts-example
source: examples_db
title: "Multi-Tab Dashboard"

queries:
  sales_by_category:
    sql: |
      SELECT category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY category ORDER BY revenue DESC
  sales_by_date:
    sql: |
      SELECT date, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY date ORDER BY date
  sales:
    sql: |
      SELECT * FROM ecommerce_orders

charts:
  summary:
    query: sales_by_category
    type: bar
    title: "Summary Chart"
    x: category
    y: revenue
  revenue_trend:
    query: sales_by_date
    type: line
    title: "Revenue Trend"
    x: date
    y: revenue
  orders_trend:
    query: sales_by_date
    type: line
    title: "Orders Trend"
    x: date
    y: units_sold
  details:
    query: sales
    type: table
    title: "Detailed Table"

tabs:
  items:
    - title: "Overview"
      rows:
        - summary

    - title: "Trends"
      cols:
        - revenue_trend
        - orders_trend

    - title: "Details"
      rows:
        - details
```

**Use tabs when:**
- Managing dashboard density
- Organizing related views
- Hiding content until needed

---

## Details (Collapsible Sections)

A `rows`/`cols` section or a grid item's `item:` board can be made collapsible by adding `details`. This renders a clickable summary bar that expands/collapses the content; no JavaScript needed.

A tab item rejects `details`, as do inline chart items and the grid item wrapper; to collapse content inside a tab, put a `details` section in the tab's `rows:`.

```yaml {contract=board-root expect=error code=ERR-EXTRA-FIELD}
tabs:
  items:
    - title: Overview
      details:
        summary: Show more
      rows:
        - text: Content
```

```dbt-charts-example
source: examples_db
title: "Dashboard with Details"

queries:
  sales_by_category:
    sql: |
      SELECT category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY category ORDER BY revenue DESC
  sales:
    sql: |
      SELECT * FROM ecommerce_orders

charts:
  summary:
    query: sales_by_category
    type: bar
    title: "Revenue Summary"
    x: category
    y: revenue
  breakdown:
    query: sales
    type: table
    title: "Full Data"

rows:
  - summary

  - details:
      summary: "Show Raw Data"
      expanded_title: "Hide Raw Data"
    rows:
      - breakdown
```

**Use details when:**
- Hiding secondary content behind a toggle
- Reducing dashboard clutter
- Progressive disclosure of complex data

---

## Choosing a Layout

| Layout | Best For |
|--------|----------|
| **Rows** | Simple vertical flow, mobile, scrolling |
| **Cols** | Comparing metrics, sidebars |
| **Grid** | Precise control, dense dashboards |
| **Tabs** | Multiple views, reducing clutter |
| **Details** | Collapsible sections, progressive disclosure |

---

## Related

- [Boards Overview](index.md) - Basic board structure
- [Sizing](sizing.md) - Width and height control
- [Examples](examples.md) - Complex layout patterns

# Board Content (https://docs.dbtcharts.com/boards/content/)

# Board Content

Boards can contain narrative content using the `content` field. This is useful for adding context, explanations, or summary text alongside your data.

---

## Basic Content

Add content at the top level of a board:

```yaml {contract=board-fragment}
title: "Executive Summary"
text: |
  ## Q4 Performance
  Revenue is up **15%** quarter-over-quarter.
rows:
  - revenue_chart
```

The board's `title:` already renders as an `<h1>`, so start your body text at `##` (h2) or as a paragraph; don't repeat the title with a leading `# Title`, or it will render twice. To change which heading level titles render at (for example, when embedding a board inside a page that already owns H1/H2), see [Title Heading Levels](#title-heading-levels) below.

---

## Nested Content

Use content in nested boards to create rich, document-like layouts:

```yaml {contract=board-root}
rows:
  - text: |
      ## Monthly Analysis
      Here is the breakdown of our performance by region.

  - cols:
      - text: |
          ### Key Takeaways
          - North region is leading
          - South region needs attention

      - text: |
          ### Action Items
          1. Increase ad spend in South
          2. Optimize North inventory
```

---

## Mixed Content Layouts

Combine content blocks with charts for rich, document-like dashboards:

```dbt-charts-example
source: examples_db
title: "Sales Report"

charts:
  revenue_chart:
    query:
      sql: |
        SELECT category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY category ORDER BY revenue DESC
    type: bar
    title: "Revenue by Category"
    x: category
    y: revenue
    color: category

rows:
  - text: |
      This report shows **Q4 performance** across product categories.

  - cols:
      - revenue_chart

      - text: |
          ### Key Takeaways
          - **Electronics**: Top performer
          - **Accessories**: Growing steadily
          - **Tools**: Stable revenue
```

---

## Markdown Features

Because `content` is Markdown, you can use all standard Markdown features:

### Tables

```yaml {contract=board-root}
text: |
  | Metric | Value | Notes |
  | --- | --- | --- |
  | Revenue | $4.2M | `SUM(revenue)` over the last quarter |
  | Margin | 32% | Consistent with forecast |
```

### Images

Drop in logos, diagrams, or badges:

```yaml {contract=board-root}
text: |
  # dbt-powered Insights
  ![dbt logo](https://upload.wikimedia.org/wikipedia/commons/7/7a/DBT_logo.svg)
  Our revenue model is compiled with dbt.
```

A project image (`.png`, `.jpg`, `.jpeg`, `.gif`, `.svg`, `.webp`, `.bmp`) is embedded directly in the render, so it shows up the same way in SVG/PNG/PDF export, `dct serve`, and Cloud, with no separate asset hosting to set up. Its path takes one of two forms:

- A relative path resolves against the directory of the file it is written in: the board's own file, or the file an imported board or chart comes from.
- A path starting with `/` resolves from the project's `charts/` directory, the directory `dct serve` serves.

```yaml {contract=board-root}
text: |
  ![Company Logo](img/logo.png)
  ![Brand mark](/assets/brand.svg)
```

The image fills its column at its own aspect ratio. `http(s)://` and `data:` image URLs work too and are never fetched over the network at render time. A project image's path is written out, not built by a template: `{% if %}` can choose between whole images, and alt text can be templated, but a `{{ }}` path that renders to a project file renders as an error. A templated `http(s)://` URL is fine. A path that doesn't exist, or that isn't one of the supported image types, renders as an error naming the path and the directory it was looked for in; a relative path that only exists under `charts/` says to write it with a leading `/`.

An image also renders inline, wherever it sits: mid-sentence, in a heading, a list item, or a table cell. A table of thumbnails is one markdown table:

```yaml {contract=board-root}
text: |
  | Logo | Company |
  | --- | --- |
  | ![Acme](img/acme.png) | Acme Corp |
  | ![Globex](img/globex.png) | Globex Inc |
```

### Callouts & Quotes

```yaml {contract=board-root}
text: |
  > :sparkles: Markdown lets you mix prose, tables, inline `code`,
  > and callouts in a single content block.
```

### Links

```yaml {contract=board-root}
text: |
  Want a deeper dive? [Open the dbt docs](https://docs.getdbt.com/)
  or [view another board](../guides/getting-started.md).
```

### Inline Code

```yaml {contract=board-root}
text: |
  Reference variables like `{{ selected_month }}` or
  metric names like `total_revenue`.
```

---

## Title Heading Levels

`style.title.level` controls the H-level (H1–H6) used for board and chart titles.

```yaml {contract=board-root}
# Default: compute from the count of titled ancestors.
# A titled root board is H1, a titled child section is H2, and so on.
# Bare layout wrappers (no title) do not advance the counter.
style:
  title:
    level: auto
```

```yaml {contract=board-root}
# Lock the level to a specific heading, useful for embedded boards where
# H1/H2 are already owned by the outer page. This board and all descendants
# start from H3; titled children render at level + 1, and bare wrappers
# inherit the locked level unchanged.
style:
  title:
    level: 3
```

---

## Query values in text and titles

`text:`, board `title:`, and a chart's `title`, `subtitle`, KPI `label` and callout `title` and `message` read query results through `queries.<name>`. The query is defined under `queries:` like any other; text runs after it executes.

```yaml {contract=board-root}
queries:
  summary:
    columns: [net_revenue, vs_plan, churn]
    values:
      - [4210000.5, 0.042, null]
  top_regions:
    columns: [region, revenue]
    values:
      - [EMEA, 1800000]
      - [AMER, 1500000]
      - [APAC, 910000]
text: |
  {% set s = queries.summary.one %}
  Net revenue is **{{ s.net_revenue | format('currency') }}**,
  {{ 'ahead of' if s.vs_plan >= 0 else 'behind' }} plan by
  {{ s.vs_plan | abs | format('percent') }}.

  Churn: {{ 'not available' if s.churn is none else s.churn | format('percent') }}.

  Top regions:
  {% for r in queries.top_regions.rows %}
  - **{{ r.region }}**: {{ r.revenue | format('currency') }}
  {% endfor %}

  Leading: {{ queries.top_regions.rows | map(attribute='region') | join(', ') }}.
  {{ queries.top_regions.rows | length }} regions; {{ queries.top_regions.rows[0].region }} leads.
```

Renders as:

```markdown
Net revenue is **$4.21mn**, ahead of plan by 4.2%.

Churn: not available.

Top regions:
- **EMEA**: $1.8mn
- **AMER**: $1.5mn
- **APAC**: $910k

Leading: EMEA, AMER, APAC.
3 regions; EMEA leads.
```

| Form | Meaning |
|---|---|
| `queries.q.one.col` | Scalar. Requires exactly 1 row. |
| `queries.q.rows` | List of rows. `for`, `length`, `[i]`, `map` and `join` work. `[i]` past the end is an error, and so is `first`, `last`, `min`, `max` or `random` on an empty list. |
| `queries.q.columns` | Column names. `[i]` past the end is an error. |
| `row.col`, `row['col']` | Raw cell value. A column named `items` or `values` is that column. |
| `v \| format(spec)` | Formats `v` with a preset, a board format alias, or a d3 or strftime string. Large numbers use narrative notation (`$4.21mn`, `910k`); an alias that sets `notation:` keeps its own. |
| `{{ queries.q.one.col }}` | Python `str()` of the raw value (`4210000.5`). Nothing is formatted implicitly. |

- `.one` raises unless the query returned exactly one row. Use `LIMIT 1` or `.rows[0]` to pick a row; `.rows[0]` on a query with no rows is an error too. There is no `.first`.
- A NULL cell is `none`. Guard with `x is none` before comparing; `x > 0.05` on NULL is an error.
- In text and titles, `format` replaces Jinja's printf-style `format` filter. It takes exactly one spec; `{{ '%.1f' | format(x) }}` is an error.
- A column whose name starts with `_` is read with a subscript, `row['_fivetran_synced']`; `row._fivetran_synced` is an error.
- Reference queries by literal name: `queries.name` or `queries['name']`. `queries[var]`, `queries | list` and `{% set q = queries %}` are errors.
- Unknown queries and non-literal use fail at compile (`dct validate`). Row-count, column and NULL errors fail at render: a board title or `text:` error is the board's error, and a chart's text error shows in that chart's card while the rest of the board renders.
- An imported chart's text reads the queries of the file the chart is defined in.
- A board whose title reads query data or uses `format` is as wide as prose, one readable line (`style.text.column.max_chars` characters, 75 by default), not as wide as the title.

### Titles and chart text

```yaml {contract=board-root}
title: "Q3 revenue {{ queries.summary.one.net_revenue | format('currency') }}"
queries:
  summary:
    columns: [net_revenue, vs_plan]
    values:
      - [4210000.5, 0.042]
  by_region:
    columns: [region, revenue]
    values:
      - [EMEA, 1800000]
      - [AMER, 1500000]
charts:
  regions:
    query: by_region
    type: bar
    x: region
    y: revenue
    title: "{{ queries.by_region.rows | length }} regions"
    subtitle: "{{ queries.summary.one.vs_plan | format('percent_delta') }} vs plan"
  headline:
    query: summary
    type: kpi
    value: net_revenue
    label: "Net revenue ({{ 'ahead' if queries.summary.one.vs_plan >= 0 else 'behind' }})"
rows:
  - headline
  - regions
```

The board title reads "Q3 revenue $4.21mn", the bar chart's title "2 regions" with subtitle "+4.2% vs plan", and the KPI label "Net revenue (ahead)".

---

## Raw HTML Content

Set `html_policy: trusted-raw` at the board root to render `text:` as raw HTML.
See [HTML Policy](html-policy.md) for the full tier table, security notes, and
guidance on when to use each tier.

---

## Content Tips

- Use **tables** to align KPIs and explainers side by side
- Add `> blockquotes` as callouts for assumptions or warnings
- Drop `[links](...)` to help viewers jump to related docs
- Embed inline `` `code` `` to reference variables or query snippets
- Combine headings, lists, and images for mini write-ups

---

## Related

- [Boards Overview](index.md) - Basic board structure
- [Layouts](layouts.md) - Organizing content with layouts
- [HTML Policy](html-policy.md) - Raw HTML tiers and security notes
- [Examples](examples.md) - Complex layout patterns

# Linking Between Boards (https://docs.dbtcharts.com/boards/linking/)

# Linking Between Boards

Connect boards with Markdown links or chart `link:` fields. dbt Charts rewrites
both at render time so the same YAML works in both `dct serve` and Cloud.

## Drill down from charts and tables

Charts and tables support a `link:` field that turns each data element into a
clickable link: navigating to another board or updating a variable in-place.
Board-root paths are resolved the same way as Markdown links.

```yaml {contract=board-fragment}
charts:
  tickets_by_status:
    type: bar
    query: tickets
    x: status
    y: count
    link: "/zendesk/tickets/list?status={{ x }}"   # {{ x }} = clicked bar's status
```

For tables, `link:` can be set at the chart root (applied to every cell) or
overridden per column in `style.columns`:

```yaml {contract=board-fragment}
charts:
  tickets_table:
    type: table
    query: open_tickets
    link: "/zendesk/tickets/detail?id={{ ticket_id }}"   # default for all cells
    style:
      columns:
        status:
          link: "/zendesk/backlog/?status={{ status }}"  # overrides root for this column
        ticket_id:
          visible: false   # feeds the row link only; never a display column
```

See [Chart Interactions](../charts/interactions.md) for the full `link:` reference.

## Root-relative paths

Paths start with `/` and are relative to the **dashboard namespace root**;
not the file system. You never type a storage prefix like `charts/`.

```yaml {contract=board-root}
text: |
  [Open tickets](/zendesk/tickets/list?status=open)
  [Ticket detail](/zendesk/tickets/detail?id={{ ticket_id }})
```

`/zendesk/tickets/list` resolves to the board stored at
`charts/zendesk/tickets/list.yml` (same path in Cloud; both use `charts/`).

## Relative paths

`../` and `./` resolve against the **current board's directory**.

If you are on `zendesk/tickets/list`:

| Link | Resolves to |
|------|-------------|
| `./detail` | `zendesk/tickets/detail` |
| `../overview` | `zendesk/overview` |

```yaml {contract=board-root}
text: |
  [Detail view](./detail?id={{ ticket_id }})
  [Back to overview](../overview)
```

## Query parameters and variables

Query strings on links map directly to
[dashboard variables](../variables/index.md). This is how you pass context
between boards:

```yaml {contract=board-root}
text: |
  [See ticket](/zendesk/tickets/detail?id={{ ticket_id }}&status={{ status }})
```

## Suffix stripping

You can optionally include `.md`, `.yml`, or `.yaml` suffixes; dbt Charts
strips them automatically:

```yaml {contract=board-root}
text: |
  [Tickets](/zendesk/tickets/list.md)
```

resolves identically to `/zendesk/tickets/list`.

## External links

Links starting with `http://`, `https://`, `mailto:`, or `#` are **never
rewritten** and pass through unchanged.

In [dbt Charts Cloud](../cloud/git-workflow.md), board links also inherit
the current branch scope.

## URL aliases & parameterized routes

`aliases:` is a root-level list of absolute URL paths that 302-redirect to this
board's canonical file-path URL. Each entry must start with `/`; trailing
slashes are normalized automatically.

```yaml {contract=board-root}
aliases:
  - /old-reports/
  - /legacy/sales/
```

Rules:

- Every alias must be absolute: it starts with a leading `/`. A relative
  entry fails validation on that board.
- An alias must not collide with a real board file path; `dct serve` raises
  an error at startup if it does.
- Each alias must be unique across the project: two boards claiming the same
  alias is a startup error under `dct serve`. dbt Charts Cloud has no startup
  step to raise it, so there a duplicate resolves to the first board by slug;
  do not rely on a collision being reported for you.

### Parameterized aliases

An alias may contain a `<name>` capture segment. A request matching the
pattern 302-redirects to the board's canonical URL with the captured segment
appended as a query parameter of the same name, which the board then reads
as a variable. This gives a single detail board a clean per-entity URL:

```yaml {contract=board-root}
# charts/milestone.yml  (canonical URL: /milestone)
aliases:
  - /milestones/<name>
variables:
  name:
    input: select
    options:
      query: milestone_options
      column: slug
```

`/milestones/m3-public-launch` redirects to `/milestone/?name=m3-public-launch`,
and `milestone.yml` renders with `name` bound to `m3-public-launch`.

- A capture name matches exactly one non-empty path segment (no `/`). Use a
  capture name that matches the variable you want it to fill.
- A real board file always wins over a pattern alias, so `/milestones/` (a
  list board) and `/milestones/<name>` (the detail redirect) coexist without
  conflict.
- Plain aliases (no `<name>`) redirect as before; only aliases with a capture
  are treated as patterns.

### Aliasing a data or inspector route

The `/data/...` and `/inspector/...` paths are reserved for the built-in
schema browser. An `aliases:` entry can still claim one of these paths: the
alias redirect takes precedence over the generated system route, letting a
board override what that URL serves.

```yaml {contract=board-root}
# charts/warehouse_orders.yml
aliases:
  - /data/warehouse/public/orders
```

[dbt Charts Cloud](../cloud/index.md) offers a **Make this a board** button
that does this for you from a generated `/data/` or `/inspector/` view.

## Auto-linking table rows

Set `auto_link: true` at the board root to have every table chart with no
explicit `link:` automatically link each row to its canonical detail page:
`/data/<source>/<schema>/<table>/detail/`:

```yaml {contract=board-fragment}
auto_link: true

charts:
  orders_table:
    type: table
    query: orders
  totals_table:
    type: table
    query: totals
    link: false      # this one stays unlinked
```

Default is off. Explicit `link:` on a chart or column always wins over
`auto_link`; set `link: false` on a chart to suppress the auto-link for that
one table without disabling `auto_link` board-wide.

## List / detail convention

Teams can standardize recognizable path segments for common board roles:

- `…/list`: filtered overview or table
- `…/detail`: single-entity board (variables in query, for example, `?id=`)

This is a naming convention, not enforced by dbt Charts.

# HTML Policy (https://docs.dbtcharts.com/boards/html-policy/)

# HTML Policy

The `html_policy` field controls how raw HTML inside a board's `text:` blocks
is handled. By default, dbt Charts escapes HTML as plain text. You can opt into
raw HTML rendering by setting `html_policy` at the board root.

---

## Tiers

| Value | What it allows | When to use |
|---|---|---|
| `none` | HTML is escaped and rendered as plain text. | Default. No raw HTML reaches the browser. |
| `safe-subset` | Reserved for a parser-checked allowlist. **Not yet enforced**; currently renders as `none`. | Do not use in current releases; future enforcement will differ from today's behavior. |
| `trusted-raw` | A fixed set of structural, inline, list, table, and media tags passed through a parser-based sanitizer. | Layouts or widgets that Markdown cannot express, on dashboards you fully control. |

A deployment can cap the effective tier below what the board requests; Cloud, for example, caps at `safe-subset`. A compile-time warning fires when this happens.

---

## `none` (default)

HTML in a `text:` block is escaped and shown as literal characters:

```yaml {contract=board-root}
text: |
  Revenue grew **15%** quarter-over-quarter.
  <strong>bold?</strong> (these tags print as text, not HTML).
```

---

## `trusted-raw`

Set at the board root to render `text:` as raw HTML:

```yaml {contract=board-root}
html_policy: trusted-raw
text: |
  <div style="display: flex; gap: 16px; align-items: center;">
    <span style="font-size: 2rem; font-weight: 700;">$4.2M</span>
    <span style="color: #16a34a;">+15% QoQ</span>
  </div>
```

### What passes through

`trusted-raw` runs HTML through a parser-based allowlist. Only an enumerated
set of tags is allowed; everything else is dropped. The allowed set covers:

- **Structural**: `div`, `span`, `section`, `article`, `aside`, `header`,
  `footer`, `main`, `nav`, `details`, `summary`
- **Headings**: `h1` through `h6`
- **Inline**: `p`, `a`, `strong`, `em`, `code`, `mark`, `abbr`, `time`,
  and their semantic siblings
- **Lists**: `ul`, `ol`, `li`, `dl`, `dt`, `dd`
- **Tables**: `table`, `thead`, `tbody`, `tfoot`, `tr`, `th`, `td`,
  `caption`, `colgroup`, `col`
- **Media**: `img`, `figure`, `figcaption`
- **Preformatted**: `pre`, `blockquote`, `hr`

Tags not on this list, including `<script>`, `<iframe>`, `<video>`,
`<canvas>`, `<svg>`, `<input>`, and `<style>`, are dropped entirely. The
parser walk also closes `javascript:` hrefs and unquoted event handlers, so
those vectors are not available even on allowed tags.

The one residual risk: inline `style` attributes pass through without CSS
parsing. An author can write `style="position:fixed"` and it takes effect.
This is by design (`trusted-raw` is sanitized HTML, not a sandbox), but it
means HTML you did not author can manipulate page layout. Review `text:`
blocks in boards you import.

### When to use `trusted-raw`

Use it only when all of these are true:

- The board is a first-party dashboard you authored and control.
- No `text:` block contains user-supplied values or dashboard variables you
  have not reviewed.
- The HTML layout or widget you need cannot be expressed in Markdown.

### Why the tier is named `trusted-raw`

The name states the requirement up front: this is raw HTML that you are
declaring trustworthy. A name like `allow_html` reads as a plain feature
toggle; `trusted-raw` is the assertion you are making when you enable it.
Streamlit's `unsafe_allow_html` follows the same naming intent: the
risk is in the name, not in a docstring you might not read first.

---

## `safe-subset`: forthcoming

`safe-subset` is reserved for a future release that will enforce a stricter
allowlist (no inline `style`, tighter attribute set). Until that enforcement
ships, `safe-subset` behaves identically to `none`; it does **not** route
to raw HTML rendering. Do not rely on it for HTML output today.

---

## Inheritance and scope

`html_policy` applies to the board that declares it and is inherited by inline
nested boards (`text:` rows and inline `rows:`/`cols:`/`grid:` boards) unless
they declare their own. Tabs always inherit; wrap tab content in a nested
`rows:` board to set a different tier. Boards imported from another file do not
inherit it; they use their own `html_policy`. A deployment ceiling caps nested
boards too.

```yaml {contract=board-root}
html_policy: trusted-raw
text: |
  <strong>Root-level raw HTML works.</strong>

rows:
  - text: |
      <strong>Inline nested boards inherit html_policy, so this renders too.</strong>
  - html_policy: none
    text: |
      <strong>This row opts out; the tags print as text.</strong>
```

---

## Related

- [Content](content.md): Markdown text blocks, images, tables, and callouts
- [Boards](index.md): Board structure and layout
- [YAML Reference](../reference/yaml-reference.md): `html_policy` field entry

# Board Sizing (https://docs.dbtcharts.com/boards/sizing/)

# Board Sizing

dbt Charts uses a three-layer sizing model. Understanding which layer owns what prevents most sizing surprises.

---

## The Three Layers

| Layer | Where | What it controls |
|-------|-------|-----------------|
| **Layout tile** | `rows:` / `cols:` / `grid:` entry | The slot the chart renders into |
| **Chart root** | `charts.<name>.width` / `height` | Fixed height; width that pins the slot in `rows:` and measures the dashboard in `cols:`/`grid:` |
| **Chart style** | `charts.<name>.style.aspect_ratio` | Aspect-ratio-derived height for this chart |
| **Theme default** | `style.charts.aspect_ratio` in the board/theme cascade | Global fallback |

### Priority

1. An explicit `height:` on a **`rows:` tile** is a **ceiling**. The row never
   reserves space its content does not use; it shrinks to fit. (If the content needs
   *more*, a bar chart with too many categories to stay readable, say, the content
   wins and a warning names the chart.) This is a `rows:` rule only: `cols:`,
   `grid:` and `tabs:` tiles are unchanged, and an oversized `height:` on one of
   those still reserves the space it was given.
2. If the tile has no explicit height, chart-root `height:` wins.
3. Chart-style `aspect_ratio:` is used next (computes `height = width / aspect_ratio`).
4. The theme default `style.charts.aspect_ratio` is the final fallback.

The layout owns each chart's final width in `cols:` and `grid:` layouts, where chart-root `width:` only contributes to the dashboard's intrinsic width. In a `rows:` layout, chart-root `width:` pins the chart's slot (a fixed footprint, capped at the row) and a layout-item `width:` on a rows entry does the same, with a percentage meaning a fraction of the row.

---

## Default Behavior

### Width Rule

dbt Charts measures the layout's preferred width recursively:

- Rows and tabs use their widest child.
- Columns add their child widths and gaps.
- Grids derive track widths from each item's span.
- Nested dashboards repeat the same calculation.
- A table contributes the width its columns need (capped by each column's
  `max_width:`), so a wide table gets a wide board and a narrow one a narrow
  board. `style.preferred_width` on the table itself pins its width instead. A
  `style.charts.table.preferred_width` set on the board or theme is only the
  estimate used before data is known. A paginated table is never narrower than
  its "Rows a-b of N" label and page controls.
- The board's own content sets a minimum, present only when the board has it:
  its title on a single line, the footer row (attribution, plus the timestamp
  when it sits in the footer), and the widest unbreakable word of any text
  (a markdown table needs every column wide enough for its longest word). A
  board that would hug narrower grows to fit, up to `style.frame.max_width`.

This measurement runs only when no `width` is set. `style.frame.width` (or root
`width:`), authored on the board, in a template it extends, or in a project's
`meta.yml`, is the board's exact width: the layout distributes it and charts fill
their slots. Without one, the board shrinks to its intrinsic width, bounded by
`style.frame.max_width` (the theme's 1200 by default; a project's `meta.yml` can
change it), so a single KPI never turns into a full-width card. A dashboard with no
charts keeps that bound. A chart's own `width:` in a `rows:` layout stays a fixed
footprint: the slot pins to it (capped at the row) even when the board is wider.

That intrinsic width sets the board's proportions, not its final on-screen size. Viewed as an HTML page (`dct serve`, `dct render --format html`) the board scales to fill the window width and keeps its aspect ratio, so these measurements govern relative density (how much room each chart gets, how large type reads against its plot) rather than pixels in the browser.

After that outer width is chosen, existing layout allocation rules still apply. For example, items in a columns layout split the available width evenly, whatever their measured widths:
- In a `cols` layout with 2 items, each gets 50%
- In a `cols` layout with 3 items, each gets 33.3%

### Height Rule

Heights are derived from **width ÷ aspect ratio** for plot-style charts (bar, line, area, etc.).
The global default aspect ratio is `1.5` (3:2), set in the base theme under `style.charts.aspect_ratio`.  Override it in any board via `style.charts.aspect_ratio` or at the individual chart level with `aspect_ratio:`.
Some chart types override this: for example, `pie` and `arc` default to **1.0** (square), and map types default to **1.2**.

**Exceptions: chart-root height is ignored for these types:**

- **KPI**: fixed compact height (renderer owns sizing)
- **Table**: data-driven height based on actual row count
- **Callout**: fixed compact height
- **Spark bar**: fixed height

The aspect-ratio-derived height is clamped between `min_height` and `max_height`. The board/theme defaults are `style.charts.min_height` (150px) and `style.charts.max_height` (376px — the height a chart gets when it splits a default-width board, so a full-width chart is capped at its siblings’ height rather than growing taller than them). Individual charts can override these clamps with per-chart `style: {min_height: ..., max_height: ...}`; see [Chart height clamps](#chart-height-clamps) below.

In a `cols` layout, all items share the **same height** (the tallest item's height).

---

## Unequal Widths with Nesting

Use nested lists as a shorthand for nested boards. A nested list automatically inherits the layout type (rows or cols) of its parent.

### 50% / 25% / 25% Split

To make the first chart take up half the width (50%) and the next two share the remaining half (25% each), nest them in a list:

```dbt-charts-example
source: examples_db
title: "Asymmetric Layout"

queries:
  sales_by_category:
    sql: |
      SELECT category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY category ORDER BY revenue DESC
  sales_summary:
    sql: |
      SELECT SUM(revenue) AS revenue, SUM(units_sold) AS units_sold, COUNT(DISTINCT category) AS category_count FROM ecommerce_orders

charts:
  main_chart:
    query: sales_by_category
    type: bar
    title: "Main Chart (50%)"
    x: category
    y: revenue
  kpi1:
    query: sales_summary
    type: kpi
    label: "Side Chart 1 (25%)"
    value: revenue
  kpi2:
    query: sales_summary
    type: kpi
    label: "Side Chart 2 (25%)"
    value: units_sold

# 50% / 25% / 25% split using nested cols
cols:
  - main_chart
  - cols:
      - kpi1
      - kpi2
```

### Complex Nesting

```dbt-charts-example
source: examples_db
title: "Complex Dashboard"

queries:
  sales_summary:
    sql: |
      SELECT SUM(revenue) AS revenue, SUM(units_sold) AS units_sold, COUNT(DISTINCT category) AS category_count FROM ecommerce_orders
  sales_by_category:
    sql: |
      SELECT category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY category ORDER BY revenue DESC
  sales_by_product:
    sql: |
      SELECT product, category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY product, category ORDER BY revenue DESC
  sales_by_date_category:
    sql: |
      SELECT date, category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY date, category ORDER BY date, category

charts:
  kpi1:
    query: sales_summary
    type: kpi
    label: "Revenue"
    value: revenue
  kpi2:
    query: sales_summary
    type: kpi
    label: "Units Sold"
    value: units_sold
  mini1:
    query: sales_by_category
    type: bar
    title: "Mini Chart 1"
    x: category
    y: revenue
  mini2:
    query: sales_by_product
    type: bar
    title: "Mini Chart 2"
    x: product
    y: units_sold
  main:
    query: sales_by_date_category
    type: line
    title: "Main Analysis"
    x: date
    y: revenue
    color: category

rows:
  - cols:
      - kpi1
      - kpi2
      - cols:
          - mini1
          - mini2
  - main
```

---

## Authoring Chart Size

**Chart root** holds the two fixed-geometry fields:

- **`height: <px>`**: exact pixel height. Wins over `aspect_ratio` and theme defaults. Bypasses `min_height` / `max_height` clamps.
- **`width: <px>`**: in a `rows:` layout, pins the chart's slot (a fixed footprint, capped at the row). In `cols:` and `grid:` layouts it is a preferred width used to measure the dashboard, and the layout owns the final slot.

**`style:`** holds aspect-ratio sizing fields (and all paint: colors, fonts, marks):

- **`style.aspect_ratio: <float>`**: shape without a fixed pixel size. `height = width / aspect_ratio`.
- **`style.min_height: <px>`**: floor for the computed height.
- **`style.max_height: <px>`**: ceiling for the computed height.

`height` and `width` belong at chart root, not in `style:`; putting them there raises a validation error.

### Choosing between chart-root height and a layout tile height

```yaml {contract=board-fragment}
# Chart-root height; the chart requests 400px;
# the layout honors it unless the tile has its own height.
charts:
  inventory_overview:
    query: inventory
    type: bar
    x: category
    y: count
    height: 400

# Layout tile height; the slot is at most 600px. If the chart inside needs less,
# the row shrinks to it rather than leaving an empty band.
rows:
  - height: 600
    rows:
      - inventory_overview
```

Use **chart-root `height`** when the chart itself has a natural size independent of its context (for example, a detail chart that always needs 400px to be readable).

Use a **layout tile height** to cap how tall a row may get: everything in that row is bounded by it (for example, a KPI row that must not grow taller than the charts below it).

!!! note "A `rows:` height is an upper bound, not a reservation"

    Authoring `height: 120` on a KPI row does not guarantee a 120px row. If the KPIs
    only need 81px, the row is 81px and the board tightens up. This is deliberate:
    reserving space the content does not use leaves a dead band inside the row, which
    reads as a much larger gap to whatever comes next.

    If you want breathing room between rows, set it as spacing rather than as an
    oversized row height.

    This applies to `rows:` only. `cols:`, `grid:` and `tabs:` tiles are unchanged;
    a `height:` there still reserves exactly what it asks for, so an oversized one
    leaves the empty band described above.

### Rejected shape

```yaml {contract=board-root expect=error code=ERR-EXTRA-FIELD}
# REJECTED: height/width under style: is not supported
charts:
  bad:
    type: bar
    style:
      height: 400      # ← raises a validation error; move height to chart root
```

---

## Explicit Sizing

### Chart height

Set `height` on a chart to fix its pixel height explicitly. This bypasses aspect-ratio sizing and ignores `min_height` / `max_height` clamps.

```yaml {contract=board-fragment}
charts:
  revenue:
    type: bar
    query: revenue_by_month
    x: month
    y: revenue
    height: 500   # fixed at 500px
```

Set `aspect_ratio` to control the shape without fixing an exact pixel size:

```yaml {contract=board-fragment}
charts:
  revenue:
    type: bar
    query: revenue_by_month
    x: month
    y: revenue
    style:
      aspect_ratio: 2.5   # wider-than-default; height = width / 2.5
```

### Chart height clamps

`min_height` and `max_height` cap the aspect-ratio-derived height. Board/theme defaults cascade from `style.charts.min_height` and `style.charts.max_height`. Override them per chart under `style:`:

```yaml {contract=board-fragment}
charts:
  stock_levels:
    type: bar
    query: stock_levels
    x: product_name
    y: stock_quantity
    style:
      aspect_ratio: 1.5
      min_height: 80    # floor for this chart only; overrides board/theme default
      max_height: 200   # ceiling for this chart only; overrides board/theme default
```

Explicit `chart.height` bypasses `min_height` / `max_height`; when you set an exact pixel height, the clamps do not apply.

### Height on Rows

Set explicit height on row items:

```yaml {contract=board-fragment}
rows:
  - height: "120px"
    cols:
      - kpi1
      - kpi2
      - kpi3

  - main_chart  # Takes remaining height
```

### Grid Sizing

In grid layouts, use `width` and `height` on items:

```yaml {contract=board-fragment}
grid:
  columns: 24
  items:
    - item: kpi1
      width: 8      # 8 of 24 columns
    - item: kpi2
      width: 8
    - item: main_chart
      width: 16
      height: 2     # 2 rows tall
    - item: sidebar
      width: 8
      height: 2
```

---

## Sizing Patterns

### KPI Row + Main Chart

```yaml {contract=board-fragment}
rows:
  - height: "100px"
    cols: [kpi1, kpi2, kpi3]
  - main_chart
```

### Sidebar Layout

```yaml {contract=board-fragment}
cols:
  - cols:           # 66% main content
      - chart1
      - chart2
  - sidebar_chart   # 33% sidebar
```

### Header + Body + Footer

```yaml {contract=board-fragment}
rows:
  - height: "80px"
    text: "# Dashboard Title"
  - main_content    # Flexible middle
  - height: "60px"
    text: "Footer text"
```

---

## Configuration

### Theme defaults (board/theme cascade)

These keys set the **theme default** layer; they apply to every chart that does not provide a chart-root override.

| Key | Default | Description |
|-----|---------|-------------|
| `style.charts.aspect_ratio` | `1.5` | Global width:height ratio for plot-style charts |
| `style.charts.min_height` | `150` | Minimum chart height (px) when aspect-ratio drives sizing |
| `style.charts.max_height` | `376` | Maximum chart height (px) when aspect-ratio drives sizing |
| `style.charts.<type>.aspect_ratio` | none | Per-type override (for example, `pie: 1.0`, `map: 1.2`). Not supported on `kpi`, `table`, `callout`, or `spark_bar`; those chart types own their own sizing contracts. |

`height` and `width` cannot be set in the theme; they are per-chart explicit overrides only (see below).

### Chart-root fields (per chart, under `charts.<name>:`)

| Field | Description |
|-------|-------------|
| `height` | Exact pixel height. Wins over `aspect_ratio` and theme. Bypasses `min_height`/`max_height`. |
| `width` | Width in pixels. Pins the chart's slot in a `rows:` layout (capped at the row); in `cols:`/`grid:` it contributes to the dashboard's intrinsic width and the layout owns the final slot. |

### Per-chart style fields (under `charts.<name>.style:` or in the theme under `style.charts.*`)

| Field | Description |
|-------|-------------|
| `aspect_ratio` | Shape without a fixed pixel size. `height = width / aspect_ratio`. |
| `min_height` | Floor for this chart only; overrides theme `style.charts.min_height`. |
| `max_height` | Ceiling for this chart only; overrides theme `style.charts.max_height`. |

`aspect_ratio`, `min_height`, and `max_height` are valid both at chart level (`style: {aspect_ratio: 2.0}`) and in the theme (`style.charts.aspect_ratio`). `height` and `width` are chart-root-only; they are not valid under `style:`.

These three fields are not supported on `kpi`, `table`, `callout`, or `spark_bar` charts; those families use renderer-owned or layout-owned sizing contracts rather than the aspect-ratio cascade. Authoring `style.aspect_ratio` on a kpi or table chart, or `style.charts.kpi.aspect_ratio` in the theme, is rejected with a validation error.

---

## Card Gap

By default, cards (charts and content blocks) render edge-to-edge; no gap
between them. Set `card_gap: true` at the board root to add spacing between
every card on the board:

```yaml {contract=board-fragment}
title: "Spaced-Out Dashboard"
card_gap: true

rows:
  - revenue
  - orders
```

The actual pixel value comes from the theme (`style.frame.card_gap`), not from
the board: `card_gap` is a per-board on/off switch, the theme owns how big the
gap is. `card_gap` is root-only: setting it on a nested board raises a
validation error, because spacing is a whole-board layout decision, not a
per-section one.

---

## Related

- [Boards Overview](index.md) - Basic board structure
- [Layouts](layouts.md) - Layout types
- [Examples](examples.md) - Complex layout patterns

# Board Imports & Dynamic Layouts (https://docs.dbtcharts.com/boards/imports/)

# Board Imports & Dynamic Layouts

Build modular dashboards by importing other board files as layout items.

---

## Importing Files

Include the entire content of another board file by using its path as a layout
item. This is useful for splitting large dashboards into smaller, manageable
files.

Two rules govern the path:

- **The `.yml` (or `.yaml`) extension is required.** It is what marks the item as
  a file import at all. A layout item without it is read as a chart name.
- **The path is relative to the importing file's own directory.** For a board
  sitting directly in `charts/`, that is `charts/`. A board in
  `charts/sales/overview.yml` imports its sibling as `_header.yml`, not
  `sales/_header.yml`.

```yaml {contract=board-root}
# File: charts/main_dashboard.yml
title: "Company Overview"
rows:
  - composition/_report-base.yml   # imports charts/composition/_report-base.yml
  - composition/_dark-brand.yml    # imports charts/composition/_dark-brand.yml
```

!!! note "How this compares to `extends:`"

    Both anchor a relative path the same way: against the authoring file's own
    directory. What differs is when an entry counts as a path at all: `extends:`
    treats one as a path only if it contains `/` or ends `.yml`/`.yaml`, and
    resolves a bare name as a theme or a project-root board instead. A layout
    item has no such fallback; see below.

### A board's own rows, cols or tags replace inherited ones

A board that sets `rows:`, `cols:`, `grid:`, `tabs:` or `tags:` replaces what it
inherits from a `meta.yml` or an `extends:` parent; nothing is appended. A board
that sets none of them keeps the inherited layout and tags. A layout of another
kind (`cols:` over a parent's `rows:`) replaces the inherited one too. Whenever a
`meta.yml`, an extended board or the board itself replaces a value that is not
empty, the board warns `WARN-INHERITED-LAYOUT-REPLACED`, naming the replacing
file and the source. To share rows between boards, move
them into a partial and import it from each board.

### Dropping the extension does not work

There is no bare-filename form. Omitting the extension does not import anything;
the item falls through to chart-name lookup and the board fails to compile:

```yaml {contract=board-root expect=error code=ERR-UNRESOLVED-REFERENCE}
# File: charts/main_dashboard.yml
rows:
  - composition/_report-base   # no .yml; read as a chart name, not a file
```

```text
ERR-UNRESOLVED-REFERENCE  Reference 'composition/_report-base' not found in layout item.
```

### Partial Files

Files starting with `_` are commonly used for components that aren't meant to be viewed alone:

```text
charts/
├── main_dashboard.yml      # Main entry point
├── _header_section.yml     # Partial: header
├── _sales_kpis.yml         # Partial: sales KPIs
├── _marketing_kpis.yml     # Partial: marketing KPIs
└── _footer.yml             # Partial: footer
```

---

## Templated Import Paths

An import path may contain Jinja, so the partial a board includes can come from a
variable rather than being written inline:

```yaml {contract=board-root}
# File: charts/main_dashboard.yml
variables:
  brand:
    default: _report-base
rows:
  - composition/{{ brand }}.yml
```

**The choice is fixed at compile time.** The path is resolved while the layout is
being built, from the variable's declared `default:`, so a plain defaulted
variable is what this feature takes. It is a way to parameterize a board across
projects or environments, *not* a runtime switch: an interactive `input:` control
cannot change which file gets imported, because runtime values are applied after
the layout is already fixed.

!!! warning "Whole files only"

    An import brings in an entire file. There is no way to pull a single named
    section out of another board; no anchor syntax, no `board.section_id`
    spelling. To share one section, put that section in its own file and import
    it from both places.

---

## Use Cases

### Shared Headers/Footers

```yaml {contract=board-root}
# charts/_header.yml
text: |
  # Company Dashboard
  Last updated: {{ now }}
style:
  background: "#1e40af"
  font:
    color: white
```

```yaml {contract=unverified}
# charts/any_dashboard.yml
rows:
  - _header.yml
  - main_content
  - _footer.yml
```

### Reusable KPI Rows

```yaml {contract=board-fragment}
# charts/_standard_kpis.yml
cols:
  - revenue_kpi
  - orders_kpi
  - growth_kpi
```

```yaml {contract=unverified}
# charts/sales.yml
rows:
  - _standard_kpis.yml
  - sales_specific_content
```

```yaml {contract=unverified}
# charts/marketing.yml
rows:
  - _standard_kpis.yml
  - marketing_specific_content
```

### Component Library

```yaml {contract=board-root}
# charts/components/_metric_card.yml
# A board in charts/ imports it as components/_metric_card.yml; a board in
# charts/sales/ imports it as ../components/_metric_card.yml.
id: metric_card
style:
  background: "#f3f4f6"
  padding: "16px"
cols:
  - text: "{{ title }}"
  - text: "{{ value }}"
```

---

## Palette Swatches

A swatch row is just cells with a `color()` background. `color("<palette>.<n>")`
addresses any stop-list palette by 1-indexed position; see
[Palette Resolver](../guides/palette-resolver.md).

```dbt-charts-example
title: "Palette Swatches"
rows:
  - cols:
      - text: " "
        width: "60px"
        style: {background: "vivid-10.1"}
      - text: " "
        width: "60px"
        style: {background: "vivid-10.2"}
      - text: " "
        width: "60px"
        style: {background: "vivid-10.3"}
      - text: " "
        width: "60px"
        style: {background: "vivid-10.4"}
      - text: " "
        width: "60px"
        style: {background: "vivid-10.5"}
      - text: " "
        width: "60px"
        style: {background: "vivid-10.6"}
    height: "60px"
```

---

## Best Practices

### File Organization

```text
charts/
├── main.yml                # Entry points
├── sales.yml
├── marketing.yml
│
├── _components/            # Shared components
│   ├── _header.yml
│   ├── _footer.yml
│   └── _kpi_row.yml
│
├── partials/               # reusable imported sections
│   ├── numeric.yml         # Numeric column visualization
│   ├── date.yml            # Date column visualization
│   └── categorical.yml     # Categorical visualization
│
└── _queries/               # Shared queries
    └── _common_queries.yml
```

### Naming Conventions

- Use `_` prefix for partials that aren't standalone files
- Use descriptive names: `_sales_kpis.yml` not `_kpis.yml`
- Group related partials in folders
- Name partials by what they visualize: `numeric.yml`, `date.yml`

### When to Extract to Partials

Extract to a partial when:
- Content is used in 2+ places
- Section is large and complex
- You want to test a section in isolation
- The same section is needed under more than one board

---

## Related

- [Boards Overview](index.md) - Basic board structure
- [Examples](examples.md) - Complex layout patterns
- [Variables](../variables/index.md) - Variable definitions and templating
- [Queries](../queries.md) - External query references

# Boards Shipped in a dbt Package (https://docs.dbtcharts.com/boards/packages/)

# Boards Shipped in a dbt Package

A dbt package can ship its own boards alongside its models and macros. Once
the package is installed, its boards are discovered automatically, the same
way `ref('zendesk', 'zendesk__ticket_metrics')` reaches that package's models
today. There is nothing to configure.

---

## Where a package puts its boards

A package that ships boards puts them in its own `charts/` directory, at the
package's root, the same place your own project puts its boards:

```
dbt_zendesk/                     # the package, as dbt deps installs it
├── charts/
│   ├── overview.yml
│   └── meta.yml
├── models/
│   └── ...
└── dbt_project.yml
```

`dbt deps` copies that into your project's `dbt_packages/` directory:

```
my_project/
├── charts/                      # your own boards
│   └── home.yml
├── dbt_packages/
│   └── dbt_zendesk/
│       └── charts/              # the package's boards — discovered automatically
│           ├── overview.yml
│           └── meta.yml
└── dbt_project.yml
```

`dct serve`, `dct validate`, `dct render`, and `dct impact` all discover a
package's `charts/` directory the moment `dbt deps` installs it — no config
key opts a package in or out.

## How package boards appear

A package's boards are namespaced by the package's directory name under
`dbt_packages/` — the same name dbt derived from the package's own `name:`
when `dbt deps` installed it. `dbt_packages/zendesk/charts/overview.yml`
serves at `/zendesk/overview/`, the same way `charts/home.yml` serves at `/`.
A package board's own index (`dbt_packages/zendesk/charts/index.yml`) serves
at the bare package path, `/zendesk/`.

If a host `charts/zendesk/` directory (or `charts/zendesk.yml` file) and an
installed `zendesk` package both exist, `dct serve` refuses to start: the
namespace is claimed twice and there's no principled way to pick a winner.
Rename one side.

## Boards are read-only

`dbt_packages/` is regenerated by `dbt deps` and is not meant to be hand-edited
— dbt itself gitignores it. Writing to a package board through any dbt Charts
surface (the editor, `write_file`, `dct migrate`) fails outright rather than
silently landing an edit `dbt deps` would later overwrite. To change a
package's boards, change the package.

## Sourcing a package board's queries

A package ships with no `source:` of its own — it doesn't know your project's
source names. Instead, a package board's queries resolve against your
project's own default source, set the same way any board's does: `source:` in
your host `charts/meta.yml`.

```yaml {contract=board-root}
# File: charts/meta.yml
source: warehouse
```

With that in place, every package board compiles unmodified. A package board
that names its own `source:` explicitly resolves it against your project's
`dbt_charts.yml` the normal way, and fails with the same
`ERR-SOURCE-REQUIRED`/unknown-source errors a host board would if it doesn't
exist.

A package's own `meta.yml` still applies for everything that isn't a source
name — style defaults, shared queries, lint suppressions — layered *inside*
your host `charts/meta.yml`, so a package default never silently overrides a
project-wide one.

## Picking up a package update

`dct serve` notices a `dbt deps` re-run the same way it notices an edit under
`charts/` — no restart needed. A [Linking Between Boards](linking.md) `link:`
from one of your own boards into a package board that a later `dbt deps`
removes (the package dropped or renamed it) reads as a stale link, the same as
linking to any board that no longer exists.

## Scope

- **Hub and git packages only.** A `local:`-installed package is a symlink
  into another directory on disk, outside your project root — the same
  containment guard that keeps a board from reading a file outside the
  project excludes it. This is a package-developer workflow, not something a
  package's users hit; ship the package as a real hub or git dependency and
  it works normally.
- **`packages-install-path` overrides are not honored.** Discovery assumes
  the default `dbt_packages/` location.
- **Cloud does not discover package boards yet.** Cloud reads a project's
  `charts/` directory from its own git-backed store and doesn't run
  `dbt deps`, so it can't see `dbt_packages/` until it can install packages
  itself — tracked separately.

---

## Related

- [Boards Overview](index.md) - Basic board structure
- [Linking Between Boards](linking.md) - `link:` fields and Markdown links
- [Board Imports](imports.md) - Composing boards from files within one project

# Board Examples (https://docs.dbtcharts.com/boards/examples/)

# Board Examples

Advanced layout patterns and comprehensive examples.

---

## Marketing Command Center

A complex dashboard combining multiple layout types, content, and charts:

```dbt-charts-example
source: examples_db
title: "Marketing Command Center"

queries:
  sales_summary:
    sql: |
      SELECT SUM(revenue) AS revenue, SUM(units_sold) AS units_sold, COUNT(DISTINCT category) AS category_count FROM ecommerce_orders
  sales_by_date:
    sql: |
      SELECT date, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY date ORDER BY date
  sales_by_category:
    sql: |
      SELECT category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY category ORDER BY revenue DESC
  sales_by_product:
    sql: |
      SELECT product, category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY product, category ORDER BY revenue DESC
  sales:
    sql: |
      SELECT * FROM ecommerce_orders

charts:
  spend:
    query: sales_summary
    type: kpi
    label: "Total Revenue"
    value: revenue
  clicks:
    query: sales_summary
    type: kpi
    label: "Total Units"
    value: units_sold
  roi:
    query: sales_summary
    type: kpi
    label: "Categories"
    value: category_count
  spend_trend:
    query: sales_by_date
    type: line
    title: "Revenue Over Time"
    x: date
    y: revenue
  channel_mix:
    query: sales_by_category
    type: bar
    title: "Category Mix"
    x: category
    y: revenue
  funnel:
    query: sales_by_product
    type: bar
    title: "Product Funnel"
    x: product
    y: units_sold
  conversion:
    query: sales
    type: table
    title: "Sales Table"
  campaigns:
    query: sales
    type: table
    title: "Campaign Table"
  creative1:
    query: sales_by_date
    type: bar
    x: date
    y: revenue
  creative2:
    query: sales_by_category
    type: bar
    x: category
    y: units_sold
  creative3:
    query: sales_by_product
    type: pie
    theta: revenue
    color: product

rows:
  # Section 1: Top Level KPIs
  - height: "120px"
    cols:
      - spend
      - clicks
      - roi

  # Section 2: Main Trends (Split 50/50)
  - cols:
      - spend_trend
      - channel_mix

  # Section 3: Funnel Analysis
  - rows:
      - text: |
          **Funnel Performance**
          Analyzing conversion rates by product
      - cols:
          - funnel
          - conversion

  # Section 4: Detailed Reports (Tabs)
  - tabs:
      items:
        - title: "Campaigns"
          rows:
            - campaigns

        - title: "Creatives"
          cols:
            - creative1
            - creative2
            - creative3
```

---

## Nested Grids

Create sophisticated layouts by combining multiple layout types:

```dbt-charts-example
source: examples_db
title: "Complex Dashboard"

queries:
  sales_summary:
    sql: |
      SELECT SUM(revenue) AS revenue, SUM(units_sold) AS units_sold, COUNT(DISTINCT category) AS category_count FROM ecommerce_orders
  sales_by_category:
    sql: |
      SELECT category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY category ORDER BY revenue DESC
  sales_by_product:
    sql: |
      SELECT product, category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY product, category ORDER BY revenue DESC
  sales_by_date_category:
    sql: |
      SELECT date, category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY date, category ORDER BY date, category

charts:
  kpi1:
    query: sales_summary
    type: kpi
    label: "Revenue"
    value: revenue
  kpi2:
    query: sales_summary
    type: kpi
    label: "Units Sold"
    value: units_sold
  mini1:
    query: sales_by_category
    type: bar
    title: "Mini Chart 1"
    x: category
    y: revenue
  mini2:
    query: sales_by_product
    type: bar
    title: "Mini Chart 2"
    x: product
    y: units_sold
  main:
    query: sales_by_date_category
    type: line
    title: "Main Analysis"
    x: date
    y: revenue
    color: category

rows:
  - cols:
      - kpi1
      - kpi2
      - cols:
          - mini1
          - mini2
  - main
```

---

## Document-Style Report

```dbt-charts-example
source: examples_db
title: "Analytical Report"

queries:
  sales_by_category:
    sql: |
      SELECT category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY category ORDER BY revenue DESC
  sales_by_date_product:
    sql: |
      SELECT DATE_TRUNC('week', date) AS week, product, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY week, product ORDER BY week, product

charts:
  revenue_by_category:
    query: sales_by_category
    type: bar
    title: "Revenue by Category"
    x: category
    y: revenue
  trends:
    query: sales_by_date_product
    type: line
    title: "Trend Analysis"
    x: week
    y: revenue
    color: product

rows:
  - text: |
      # First-Half Performance Report
      The first half of 2024 showed **strong growth** across all key metrics.
      The following visualizations break down the performance by category.

  - cols:
      - revenue_by_category

      - text: |
          ### Key Insights
          - **Electronics**: Leading category, lifted by Widget B's climb
          - **Accessories**: Accelerating since the Gadget X launch in March
          - **Tools**: Steady, with Tool A easing off

  - trends
```

---

## Best Practices

### Logical Grouping

Use boards to group related charts together. This improves readability and organization.

### Layout Selection

| Layout | Best For |
|--------|----------|
| **Rows** | Simple vertical flow, mobile, scrolling |
| **Cols** | Side-by-side comparisons, sidebars |
| **Grid** | Precise control, dense dashboards |
| **Tabs** | Managing density, hiding content until needed |

### Modularity

Extract complex boards into separate files (starting with `_` for partials) and include them by referencing their filename.

### Performance

- Keep individual boards focused
- Use tabs to lazy-load complex sections
- Split large dashboards into multiple files

---

## Related

- [Boards Overview](index.md) - Basic board structure
- [Layouts](layouts.md) - Layout types in detail
- [Content](content.md) - Adding narrative content
- [Sizing](sizing.md) - Width and height control
- [Imports](imports.md) - File imports and reusability

# Overview (https://docs.dbtcharts.com/cli/)

# CLI Reference

The `dct` command-line interface is the primary surface for working with dbt Charts. Every dashboard operation (validating board YAML, browsing your warehouse, rendering charts, running the local server, configuring AI assistants) runs through `dct`.

This section documents every command, its flags, and the typical workflows that combine them.

## Getting help

```bash
dct --help               # Top-level command list
dct <command> --help     # Per-command flags and examples
dct --version            # Print version + install path
```

If output looks stale or unexpected, `dct --version` is the first thing to check. If `dct` can't reach your data, run [`dct doctor`](doctor.md).

## Command catalog

### Authoring & validation

| Command | Purpose |
|---|---|
| [`validate`](validate.md) | Fast YAML schema + cross-reference validation, no DB, no execute |
| [`migrate`](migrate.md) | Rewrite supported older YAML syntax to the current grammar |
| [`describe`](describe.md) | Describe a dashboard's queries / charts / variables |

### Data discovery

| Command | Purpose |
|---|---|
| [`search`](search.md) | Search dashboards by keyword with ranked results |
| [`impact`](impact.md) | Which boards reference a column; the rename blast-radius lookup |

### Query inspection

| Command | Purpose |
|---|---|
| [`query`](query.md) | Execute a named board query or raw SQL; add `--validate` to lint |

### Rendering & serving

| Command | Purpose |
|---|---|
| [`render`](render.md) | Render a board to SVG, HTML, PNG, PDF, JSON, YAML, or terminal |
| [`serve`](serve.md) | Start the local dbt Charts server with live board routes |
| [`playground`](playground.md) | Interactive playground with YAML editor and live preview |

### Project setup & scaffolding

| Command | Purpose |
|---|---|
| [`init`](init.md) | Bootstrap a dbt Charts project, plus AI / editor integrations |
| [`docs`](docs.md) | Browse dbt Charts YAML reference docs offline, or look up a render-warning code |
| [`skills`](skills.md) | List packaged agent skills or show one by name |
| [`doctor`](doctor.md) | Diagnose why `dct` can't reach your data: install method, project, `profiles.yml`, per-source adapters |

### AI integration

| Command | Purpose |
|---|---|
| [CLI and MCP for AI assistants](ai-cli-and-mcp.md) | When to use the CLI vs MCP for AI assistants |
| [`mcp`](mcp.md) | MCP (Model Context Protocol) server commands for AI assistant integration |

### Cloud

| Command | Purpose |
|---|---|
| [`cloud`](cloud.md) | Connect a project, wire up a warehouse, and render — [dbt Charts Cloud](../cloud/index.md) from the terminal |

## Common options

Most commands accept the same project-resolution and output-formatting flags.

### `--project-dir PATH`

Project root for resolving relative paths. If not provided, `dct` walks up from the current directory looking for `dbt_charts.yml` or `dbt_project.yml`.

```bash
dct validate --project-dir /path/to/dbt/project
dct query warehouse "SELECT 1" --project-dir /path/to/project
```

Use this when:

- Running `dct` from outside the project directory
- Working with multiple projects from one shell
- CI/CD pipelines where project path varies

Can also be set via the `DCT_PROJECT_DIR` environment variable; the flag wins when both are set.

```bash
export DCT_PROJECT_DIR=/path/to/project
dct validate                           # equivalent to --project-dir /path/to/project
dct render charts/sales.yaml --project-dir /other/project  # flag wins
```

### `--dbt-project-dir PATH`

Links an external dbt project, one that does not sit next to `dbt_charts.yml` (a separate repo, or a sibling directory in a monorepo). dct is entirely read-only with respect to dbt: it never invokes the dbt CLI, only reads `dbt_project.yml`, `profiles.yml`, and `target/manifest.json` off the linked directory for `ref()`/`source()` resolution and dbt-profile-based warehouse connections.

```bash
dct render charts/sales.yaml --project-dir . --dbt-project-dir ../my_dbt_project
```

Resolution order (first match wins):

1. `--dbt-project-dir` flag
2. `DBT_PROJECT_DIR` environment variable (dbt-core's own variable name, so a shell already configured for the dbt CLI needs no extra setup)
3. `dbt_project_dir:` key in `dbt_charts.yml`, resolved relative to that file's directory
4. The dct project root itself (today's sibling default: `dbt_project.yml` next to `dbt_charts.yml`)

```yaml {contract=project-config}
# dbt_charts.yml
dbt_project_dir: ../my_dbt_project
```

### `--no-send-anonymous-usage-stats`

Root option, placed before the command: `dct --no-send-anonymous-usage-stats render ...`. Turns off the anonymous usage statistics `dct` sends to dbt Labs for that run. `DO_NOT_TRACK=1` in the environment does the same for every run. See [Telemetry](../reference/telemetry.md) for what is sent and every opt-out.

```bash
dct --no-send-anonymous-usage-stats validate
export DO_NOT_TRACK=1                  # opt out everywhere
```

### `--json`

Most read-shaped commands (`search`, `describe`, `docs`, `skills`, `query`, `validate`) support `--json` for stable, agent-consumable output.

```bash
dct query mydb "SELECT table_name FROM INFORMATION_SCHEMA.TABLES" --json | jq '.data'
dct validate charts/sales.yaml --json
```

The JSON shape is contract-stable; pipe into `jq` for any cross-cutting query the curated verbs don't anticipate.

### `--var KEY=VALUE`

For commands that compile or execute a board (`render`, `query`, sometimes `serve`), variable values can be supplied repeatedly:

```bash
dct render charts/sales.yaml --var region=West --var category=Electronics
dct query charts/sales.yaml revenue --var region=West
```

## Exit codes

All commands follow standard Unix exit codes:

- `0`: success
- `1`: error (validation failed, compilation error, file not found, etc.)
- `2`: bad CLI arguments (Typer / Click convention)

Suitable for use in scripts and CI/CD pipelines:

```bash
#!/bin/bash
if dct validate charts/ --strict; then
  echo "All dashboards valid"
else
  echo "Validation failed"
  exit 1
fi
```

## Environment variables

dbt Charts respects dbt environment variables:

| Variable | Purpose |
|---|---|
| `DBT_PROFILES_DIR` | Custom profiles directory (default: `~/.dbt`) |
| `DBT_TARGET` | Default target for `dct serve` |
| `DBT_PROJECT_DIR` | Links an external dbt project directory for all commands that accept `--dbt-project-dir` (overridden by the flag); see [`--dbt-project-dir`](#-dbt-project-dir-path) above |

dbt Charts-specific variables:

| Variable | Purpose |
|---|---|
| `DCT_PROJECT_DIR` | Default project directory for all commands that accept `--project-dir` (overridden by the flag) |
| `DCT_PORT` | Default port for `dct serve` (overridden by `--port`) |
| `DCT_DEFAULT_THEME` | Runtime override for the `dct serve` default theme; all boards without an explicit `theme:` inherit the resolved value. Resolution at startup: env var > the project's `dbt_charts.yml` top-level `theme:` key > shipped default (`clarity`). Set at serve startup; restarts are required to pick up changes. Examples: `neon` (dark), `paper` (warm), `vivid`. To pin a project's default theme in source control, set `theme: <name>` in `dbt_charts.yml`. |
| `DCT_MAX_WORKERS` | Default `--max-workers` for `dct render` and `dct serve` (max parallel query workers; default 8 from config). Overridden by the flag. No effect on DuckDB, which serializes access regardless. |
| `DCT_CACHE_PATH` | Default `--cache` path for `dct render` and `dct serve`: keeps the query-result cache in this DuckDB file instead of the per-user file. Also turns the cache on for `dct mcp serve`, which runs uncached without it. Overridden by the flag; mutually exclusive with `--no-cache`. |
| `DCT_HTML_POLICY_CEILING` | Deployment ceiling for `html_policy` (`none`, `safe-subset`, `trusted-raw`); a board or project config requesting a higher tier is downgraded to this value. Default: unset (falls through to `markdown.html_policy_ceiling` in config, default `trusted-raw`). dbt Charts Cloud hard-pins this to `safe-subset`. |
| `DCT_MAX_ROWS_CEILING` | Deployment ceiling for query result row count; a project's own `execution.max_rows` can only lower the effective limit, never raise it above this. Exceeding it truncates the result with a warning, not a hard error. Default: unset (no ceiling; config default 1,000,000). |
| `DCT_MAX_RESULT_BYTES_CEILING` | Deployment ceiling for a single query result's serialized byte size; a project's own `execution.max_result_bytes` can only lower it. Exceeding it truncates the result with a warning, not a hard error. Default: unset (no ceiling; config default 50MB). dbt Charts Cloud hard-pins this to 10MB. |
| `DCT_FILE_SOURCE_MAX_TABLES_CEILING` | Deployment ceiling for the number of table entries a file source's `files:` map may declare; a project's own `execution.file_source_max_tables` can only lower it. Exceeding it is a hard error. Default: unset (no ceiling; config default 500). |
| `DCT_FILE_SOURCE_MAX_BYTES_CEILING` | Deployment ceiling for a file-source relation's uncompressed byte size; a project's own `execution.file_source_max_bytes` can only lower it. Exceeding it is a hard error. Default: unset (no ceiling; config default 5GB). dbt Charts Cloud hard-pins this to 50MB. |
| `DCT_MAX_TEMPLATE_OUTPUT_BYTES_CEILING` | Deployment ceiling for one board render's cumulative Jinja-emitted template output; a project's own `execution.max_template_output_bytes` can only lower it. Exceeding it is a hard error, never a truncation. Default: unset (no ceiling; config default 50MB). dbt Charts Cloud hard-pins this to 10MB. |

## Workflow examples

### Author → check → preview

```bash
# 1. Edit a board
vim charts/sales.yaml

# 2. Fast structural validation (no DB hit)
dct validate charts/sales.yaml

# 3. Full validation including warehouse references
dct render charts/sales.yaml --format json

# 4. Inspect a single query
dct query charts/sales.yaml revenue

# 5. Render to terminal for quick check
dct render charts/sales.yaml --format terminal

# 6. Serve interactively
dct serve
```

### Explore an unfamiliar warehouse

```bash
# 1. What schemas and tables exist?
dct query analytics "SELECT table_schema, table_name FROM INFORMATION_SCHEMA.TABLES"

# 2. What columns does a table have?
dct query analytics "SELECT column_name, data_type FROM INFORMATION_SCHEMA.COLUMNS WHERE table_name = 'orders'"

# 3. Find every column that looks like a timestamp
dct query analytics "SELECT table_name, column_name FROM INFORMATION_SCHEMA.COLUMNS WHERE column_name LIKE '%\_at' ESCAPE '\'"

# 4. Search dashboards that already use it
dct search "orders"
```

### CI pipeline

```bash
# Validate all dashboards before deployment
dct validate charts/ --strict

# Render dashboards as deployable artifacts
for board in charts/*.yml; do
  dct render "$board" --format html --output "dist/$(basename "$board" .yml).html"
done
```

### Wire up an AI assistant

```bash
# CLI-first: install skills to agent directories (see ai-cli-and-mcp.md)
dct init skills              # .agents/skills/ for Cursor/Codex + Claude Code skills dir

# Optional: also configure MCP for MCP-aware clients
dct init mcp                 # auto-detect Cursor, VS Code, Claude Code, Codex, …
dct init ci                  # GitHub Actions workflow validating boards on PRs

# Or run the MCP server directly for any MCP-aware client
dct mcp serve
```

## Related

- [Getting Started Guide](../guides/getting-started.md): create your first board
- [CLI and MCP for AI assistants](ai-cli-and-mcp.md): when to use the CLI vs MCP with AI assistants
- [YAML Style Guide](../guides/yaml-style-guide.md): authoring conventions
- [Troubleshooting](../guides/troubleshooting.md): common errors and fixes
- [YAML Schema Reference](../reference/yaml-reference.md): complete board schema

# init (https://docs.dbtcharts.com/cli/init/)

# `dct init`

Bootstrap a dbt Charts project, plus its AI and editor integrations.

```bash
dct init [OPTIONS]
dct init [OPTIONS] COMMAND [ARGS]
```

Without a subcommand, `dct init` runs the interactive bootstrap wizard. With a subcommand, it targets a specific integration.

## Subcommands

| Command | Purpose |
|---|---|
| [`dct init skills`](#dct-init-skills) | Install dbt Charts workflow skills to agent skill directories |
| [`dct init mcp`](#dct-init-mcp) | Wire dbt Charts into an AI assistant via MCP (Cursor, Claude Code, ChatGPT, etc.) |
| [`dct init ci`](#dct-init-ci) | Scaffold a GitHub Actions workflow that validates your boards on every PR |
| [`dct init code`](#dct-init-code-dct-init-vscode) | Install the dbt Charts extension into VS Code |
| [`dct init vscode`](#dct-init-code-dct-init-vscode) | Alias for `dct init code` |
| [`dct init cursor`](#dct-init-cursor) | Install the dbt Charts extension into Cursor |

## Top-level options

| Flag | Description |
|---|---|
| `--project-dir PATH` | Project directory. Overrides the wizard's default root selection. |
| `--force`, `-f` | Overwrite existing scaffold files. |
| `--yes`, `-y` | Accept all defaults without prompting. Editor extensions are not installed unless `--vscode` / `--cursor` is passed. |
| `--skills` / `--no-skills` | Write dbt Charts workflow skills into this project's agent skill directories. Recommended in a git repository. |
| `--mcp` / `--no-mcp` | Set up MCP server for AI assistants. |
| `--vscode` / `--no-vscode` | Install dbt Charts extension into VS Code. Without either flag: prompted on a TTY when `code` is on `PATH`; skipped under `--yes` or without a TTY. |
| `--cursor` / `--no-cursor` | Install dbt Charts extension into Cursor. Without either flag: prompted on a TTY when `cursor` is on `PATH`; skipped under `--yes` or without a TTY. |

## Examples

```bash
# Interactive wizard
dct init

# Accept all defaults (no editor extensions)
dct init --yes

# Accept all defaults and install the VS Code extension
dct init --yes --vscode

# Skip MCP setup
dct init --no-mcp

# Install workflow skills and MCP, no editor extensions
dct init --no-vscode --no-cursor
```

## Project root resolution

`dct init` resolves its scaffold target in this order:

1. `--project-dir` or `DCT_PROJECT_DIR`
2. The detected dbt Charts or dbt project root, when `dbt_charts.yml` or `dbt_project.yml` exists at or above the current directory
3. Git root, when no `dbt_charts.yml` or `dbt_project.yml` exists above the current directory but a `.git/` directory does
4. Current directory, when no project marker or git root is found

In the bare-git-repo case, the interactive wizard shows both paths and asks whether to scaffold at the git root instead of the current subdirectory. The default is the git root. `dct init --yes` takes that same default without prompting.

## `dct init skills`

Install dbt Charts workflow skills for file-based agent auto-discovery. Writes CLI-rendered skill files, namespaced under a `dct-` prefix (`dct-board-build/`, `dct-board-design/`, ...), to `.agents/skills/` (Cursor, Codex, Copilot) and/or the Claude Code skills directory. Without `--project-dir`, the install root is the git root enclosing the current directory (or the dbt Charts project root if there's no git repo), so monorepos with nested projects don't accumulate divergent skill copies. Pass `--project-dir` to install into that project instead; it must name a directory that holds a dbt Charts or dbt project, and errors with a suggestion otherwise rather than resolving upward. Pass `--global` to install into your user-level skill directories instead (Claude Code's, and `~/.agents/skills/` for Codex), so any new project on this machine picks up the skills without a per-repo install. On a machine with neither agent configured it writes nothing and exits 1; `--dir PATH` names an explicit destination. Does not configure MCP or modify `AGENTS.md` / `CLAUDE.md`.

The `dct-` prefix keeps our skills out of the way of any other skill your project or another tool installs under the same directory. Gitignore ours with a single glob (`.agents/skills/dct-*/`, or the same `dct-*/` pattern under the Claude Code skills directory) without touching anyone else's. Every install always overwrites: re-run `dct init skills` after `pip install -U dbt-charts` to pick up new or updated skill bodies, and a skill the wheel no longer ships is removed on the next run.

```bash
dct init skills [OPTIONS] [TARGET]
```

### Arguments

| Argument | Description |
|---|---|
| `TARGET` | Install target: `agents` (Cursor/Codex/Copilot), `codex`, or `claude`. Omit to auto-detect. |

### Options

| Flag | Description |
|---|---|
| `--all` | Install to every detected skill directory. |
| `--dir PATH` | Explicit destination directory. |
| `--global` | Install into your user-level skill directories (Claude Code's, and `~/.agents/skills` for Codex) instead of a repository. |
| `--check` | Dry run: show what would be installed without writing files. |
| `--project-dir PATH` | Install into this project directory instead of walking up to the enclosing git root. |

### Examples

```bash
dct init skills                 # Detect targets and install
dct init skills agents          # .agents/skills/ only (Cursor, Codex, Copilot)
dct init skills claude          # Claude Code skills directory only
dct init skills --all           # Every detected target directory
dct init skills --dir PATH      # Explicit destination
dct init skills --global        # User-level: Claude Code's skills dir and/or ~/.agents/skills
dct init skills --check         # Dry run
```

## `dct init mcp`

Add dbt Charts to your AI client's MCP configuration. Configures the MCP server only. Run [`dct init skills`](#dct-init-skills) separately to install workflow skills to agent file directories.

```bash
dct init mcp [OPTIONS] [CLIENT]
```

### Arguments

| Argument | Description |
|---|---|
| `CLIENT` | One of: `cursor`, `vscode`, `claude`, `claude-code`, `codex`, `copilot`, or `print`. Omit to auto-detect installed clients. |

### Options

| Flag | Description |
|---|---|
| `--all` | Write MCP config files for every supported client. |
| `--force`, `-f` | Overwrite existing dbt Charts config. |
| `--project-dir PATH` | Path to the dbt Charts or dbt project the MCP server should target. Embedded into the generated server entry. |

### Project root resolution

`dct init mcp` walks up from the current directory looking for `dbt_charts.yml` or `dbt_project.yml`. Pass `--project-dir` to override. When the project root diverges from the AI client's workspace (for example, a project nested under a larger repo), the generated server entry includes `--project-dir <abs-path>` so the server still starts in the right place.

### Examples

```bash
dct init mcp                              # Auto-detect clients + project
dct init mcp cursor                       # Configure Cursor only
dct init mcp claude-code                  # Configure Claude Code
dct init mcp --all                        # Write every supported config file
dct init mcp --project-dir ./analytics    # Target a specific project dir
dct init mcp print                        # Print config JSON (for manual setup)
```

## `dct init ci`

Scaffold a GitHub Actions workflow that runs [`dct validate`](validate.md) on every pull request that touches your boards.

```bash
dct init ci [OPTIONS]
```

The workflow is written **at the repository root** (the only place GitHub reads workflows from) as `.github/workflows/dbt-charts.yml` for a project at the root, or `.github/workflows/dbt-charts-<project-path>.yml` for a nested project, so each project in a monorepo owns its own gate. It is safe to re-run: an existing file is never overwritten without `--force`. A directory that is not inside a dct/dbt project, or a project with no git repository above it, fails loudly instead of scaffolding a gate that could never fire.

### Options

| Option | Description |
|---|---|
| `--force`, `-f` | Overwrite an existing workflow file |
| `--project-dir PATH` | Target a specific project root instead of walking up from the current directory |

### Nested dbt roots

Your dbt project is often *not* at the repository root; a monorepo may hold several, nested in subdirectories. GitHub's `paths:` filters are always resolved relative to the repository root, so a hand-written `charts/**` filter silently never matches a nested project, and the gate looks green because it never ran.

`dct init ci` resolves the repository root and the project root separately and qualifies every path with the project's repo-relative path. For a project at `analytics/transform_bi`:

```yaml {contract=unverified}
on:
  pull_request:
    paths:
      - 'analytics/transform_bi/charts/**'
      - 'analytics/transform_bi/dbt_charts.yml'

jobs:
  validate:
    defaults:
      run:
        working-directory: analytics/transform_bi
```

A project at the repository root omits `working-directory` entirely.

### What it checks

The scaffolded workflow is **structural**: `dct validate` checks board YAML shape, enums, references, and unknown keys without running a single query, so the job needs no warehouse credentials and runs on any runner.

To also validate dbt `ref()` and `source()` calls against your models, add a parse step before the validate step:

```yaml {contract=unverified}
      - name: Parse the dbt project
        run: |
          dbt deps
          dbt parse
```

That writes `target/manifest.json`, which `dct validate` reads to resolve refs, catching a renamed or deleted model without connecting to your warehouse (`dbt parse` needs a `profiles.yml`, but does not query). Without it, refs are reported as a `WARN-DBT-MANIFEST-MISSING` warning rather than checked.

The manifest also powers the model-column drift check: a board query reading a column a model's own SQL no longer produces fails validation with `ERR-DBT-MODEL-COLUMN-MISSING`, a rename caught before `dbt run` rebuilds the warehouse, still with no connection. The full CI ladder, tier by tier, is in [Validating Boards in CI](../guides/ci.md).

### Examples

```bash
dct init ci                            # Scaffold for the detected project
dct init ci --project-dir ./analytics  # Target a specific dbt root
dct init ci --force                    # Overwrite the existing workflow
```

## `dct init code` / `dct init vscode`

Install the dbt Charts extension into VS Code. Adds YAML schema, completion, and live-preview integration; see [VS Code & Cursor Extension](../editor-extension.md).

```bash
dct init code
dct init vscode    # alias
```

## `dct init cursor`

Install the dbt Charts extension into Cursor.

```bash
dct init cursor
```

## Related

- [CLI and MCP for AI assistants](ai-cli-and-mcp.md): when to use the CLI vs MCP
- [`dct mcp serve`](mcp.md): start the MCP server directly
- [`dct skills`](skills.md): view the packaged skills that get installed

# validate (https://docs.dbtcharts.com/cli/validate/)

# `dct validate`

Fast YAML schema and cross-reference validation. **No DB hit, no execute** (by default). Use it for sub-second checks in editors, pre-commit hooks, and CI. Add `--warehouse` to extend validation to the warehouse layer.

```bash
dct validate [OPTIONS] [PATH]
```

## Arguments

| Argument | Description |
|---|---|
| `PATH` | Path to board YAML file or directory. Defaults to `charts/` when omitted. |

## Options

| Flag | Description |
|---|---|
| `--project-dir PATH` | Project root for resolving relative paths. |
| `--json` | Output as JSON. |
| `--strict` / `--no-strict` | Exit 1 on warnings. Default: off. |
| `--warehouse` | Validate queries against the warehouse using the cheapest per-adapter mechanism (see below). Requires resolvable credentials. |

## Examples

```bash
dct validate                        # Validate all boards in charts/
dct validate charts/                 # Validate all boards in a directory
dct validate charts/sales.yml        # Validate one file
dct validate charts/sales.yml --json
dct validate charts/sales.yml --strict
dbt parse && dct validate            # Validate with manifest-backed ref checks
dct validate charts/sales.yml --warehouse   # Warehouse-level validation
```

When given a directory, `dct validate` globs `**/*.yml` and `**/*.yaml`, skipping any file whose name starts with `_` (partials and templates).

Text output says each warning code once per board: the code with a count (`WARN-FANOUT-RISK ×3`), the charts or queries it applies to, the message and fix once, and the first location with `(+N more)`. Errors list every location. `--json` keeps one object per instance.

## What it validates

- YAML syntax
- Schema conformance (every field, every chart family, every query shape)
- Cross-references inside the board (chart `query:` names exist, `rows:` references exist, variable references resolve)
- Variable defaults and types
- Field-level constraints (enums, ranges, mutually exclusive options)
- Structural SQL lint on named `queries:` entries (cartesian joins, missing join predicates); emitted as warnings; exit code 1 with `--strict`. Inline chart queries are skipped.
- `ref()`/`source()` names exist in the dbt manifest (when a manifest is present at `target/manifest.json`)
- Model column drift (manifest present): each dbt model's output columns are derived statically from its SQL, and every query column reaching that model through `ref()` is checked against them: a renamed or dropped column fails with `ERR-DBT-MODEL-COLUMN-MISSING` before `dbt run` rebuilds the warehouse. A model or query whose columns cannot be derived (`SELECT *`, macros in projection position, seeds, snapshots) is reported as a warning, never silently passed.

## `--warehouse` validation { #warehouse-validation }

Adds a warehouse-level check per query using the cheapest available mechanism:

| Adapter | Mechanism | What it checks |
|---|---|---|
| DuckDB | `DESCRIBE` | Validity + result column schema; schema only, no billing |
| csv/json/parquet | `DESCRIBE` | Result column schema only — not validity: the source must materialize its files first (read and parse them), and a materialization failure is reported unchecked, not invalid |
| BigQuery | Native dry-run | Validity + result column schema; unbilled (`QueryJobConfig(dry_run=True)`) |
| Postgres | `EXPLAIN` | Validity only; the query parses, binds and plans; no result schema (`WARN-COLUMN-CHECK-UNAVAILABLE`) |
| Redshift | `EXPLAIN` | Validity only, as above |
| Snowflake | `EXPLAIN` | Validity only, as above; compiled by the cloud services layer, no running warehouse needed |
| Everything else | None | **Nothing**; reported as unchecked (`WARN-WAREHOUSE-CHECK-UNAVAILABLE`) |

The last row is the important one: an adapter with no primitive that runs without executing the query is reported as *unchecked*, not as passing. `--warehouse` will never run your query at full cost to find out whether it works. Databricks sits in that row deliberately even though it has an `EXPLAIN`: Spark returns planner errors as plan text instead of failing the statement, so an `EXPLAIN` check there would report a broken query as valid.

Two other things report as unchecked, each with the reason in the warning message:

- a query composing another query's cached result (`{{ queries.x.cache }}`): that result only exists at render time, so no warehouse has heard of it
- a warehouse that could not be *reached* (bad host, expired credentials): a fault raised before any SQL reaches the warehouse says nothing about your query, so it is never reported as an invalid query

A query naming no source is different: it is a project configuration fault, not a per-query warning, so it is reported as an error and stops the sweep immediately instead of being reported as unchecked.

Under `--strict`, every one of those warnings exits 1; that is the mode to use in CI when "unchecked" is not good enough.

When column schema is available (DuckDB, csv/json/parquet, BigQuery; the `EXPLAIN` adapters prove validity but return no schema), `--warehouse` also checks that every chart's channel fields (`x`, `y`, `color`, `theta`, etc., including those on `layers:`) reference a column the query actually returns.

`--warehouse` is additive: the full stateless pass above runs first and its findings are always reported. Queries are checked exactly as `dct render` would run them (dbt `ref()`s resolved, `setup_sql` on the same connection, board variable defaults applied) so a check never fails on SQL your render would never send.

## What it does **not** check (without `--warehouse`)

- Whether referenced dbt models / tables actually exist **in the warehouse**
- Whether queries execute successfully
- Whether columns return rows
- Chart-render output

For those, use [`dct validate --warehouse`](#warehouse-validation) or [`dct render`](render.md).

## Related

- [`dct describe`](describe.md): describe a dashboard's queries, charts, variables, and layout
- [Error Handling Guide](../guides/error-handling.md)

# migrate (https://docs.dbtcharts.com/cli/migrate/)

# `dct migrate`

Update board YAML to the latest released version. Use it after upgrading dbt
Charts when a dashboard reports that it uses older YAML syntax. The command
recognizes syntax from the YAML shape; authors never write a version field
themselves. `dct migrate` writes one automatically -- an informational
`_schema_version:` field, added as the file's first line with a comment
marking it as auto-written -- so a later parse failure can report that a
file targets a newer dbt Charts than the one reading it.

```bash
dct migrate [OPTIONS] [PATH]...
```

## Arguments

| Argument | Description |
|---|---|
| `PATH...` | Board YAML file or directory to migrate. Omit paths to scan the project root. |

## Options

| Flag | Description |
|---|---|
| `--dry-run` | Report the files that would change without writing them. |
| `--project-dir PATH` | Project root for resolving paths. |

## Preview and Apply a Migration

Start with a dry run, review the change in your working tree, then rerun without
`--dry-run` to write it.

```bash
dct migrate --dry-run
dct migrate
git diff
```

For a targeted migration, pass a board file or a directory:

```bash
dct migrate charts/revenue.yml
dct migrate charts/
```

The command prints a summary of updated files, files that already use current
syntax, and files that need manual repair. It exits with status `1` when any
file cannot be migrated; files with independent, successful migrations are
still written.

## What Gets Rewritten

A file that already matches the latest *released* grammar is left unchanged,
even if it was created with an older dbt Charts release. Otherwise dbt Charts
looks for constructs that supported grammars have since retired, starting
from the oldest one still kept, and applies every safe, structural migration
between the grammar those constructs belong to and the latest released one --
never further: `dct migrate` never introduces syntax from an unreleased,
in-development version, even when one is already in flight for the next
release. A file carrying leftovers from two different grammars starts at the
older of the two.

Keys dbt Charts has added since a grammar was frozen are usually left alone;
they are simply newer than the retired construct sitting next to them. One
exception is worth knowing: when such a key shares its name with a long-standing
field elsewhere in the grammar, it can still stop a retired key beside it from
being rewritten. The file is reported as using unsupported syntax rather than
migrated; removing the newer key and re-running migrates it.

For example, the retired `style.board:` block is renamed to `style.frame:`:

```yaml {contract=unverified}
# Before
style:
  board:
    width: 1200
```

```yaml {contract=board-root}
# After
style:
  frame:
    width: 1200
```

This recognition is not a claim about when you wrote the file. It only answers
which grammar the retired constructs still in it came from.

### When `dct migrate` cannot finish a file

A file that carries both the old and the new spelling of a key, or an
unrelated error beside a retired key, is not rewritten. `dct validate` still
names the successor of each retired key:

```text
Unknown field 'zero' at charts.rev.bar.style.axis_y.grid.
`zero` was renamed to `threshold` in 0.7.0. Rename the key.
```

## Manual Repair

`dct migrate` only performs declared, lossless structural changes. It stops for
a file when a change would alter meaning, discard information, or conflict with
an already-present destination key. The error names the conflicting path. For a
file that migrates but still does not match the current grammar, the error names
where validation stopped: a container rather than the exact key, since
`dct migrate` has no parser pass behind it; run `dct validate` for the precise
location. Make that repair yourself, then run `dct validate` to check the
result.

```bash
dct migrate charts/revenue.yml
# Repair the path reported by the command.
dct validate charts/revenue.yml
```

The command does not make backups or offer rollback. Keep your dashboards in
version control and use `git diff` to review the rewrite; use `git revert` if
you need to undo a committed migration.

## Related

- [`dct validate`](validate.md): check the migrated dashboard
- [YAML Style Guide](../guides/yaml-style-guide.md): authoring conventions
- [CLI Reference](index.md): all `dct` commands

# render (https://docs.dbtcharts.com/cli/render/)

# `dct render`

Render a dashboard to SVG, HTML, PNG, PDF, JSON, YAML, or terminal output.

```bash
dct render [OPTIONS] {boards}...
```

Use `"-"` as the sole `BOARDS` argument to read YAML from stdin; useful for AI agents and shell pipelines that don't want to write a temp file.

## Arguments

| Argument | Description |
|---|---|
| `BOARDS` | One or more paths to board YAML files, or `"-"` to read YAML from stdin. (required) |

A relative path is read from your working directory first, the way any shell command reads it, so `dct render proj/board.yml --project-dir proj` works from the parent of `proj`. A relative path that does not exist there is read against the project instead, including its `charts/` directory, so `dct render sales.yml` finds `charts/sales.yml` from anywhere inside the project.

Every board renders inside a project: a directory holding a `dbt_charts.yml`. An empty file is enough, which is all a board of inline `values` data needs.

## Options

| Flag | Description |
|---|---|
| `--output PATH` | Output file path. Default: board name with extension (`.thumb.svg` for `thumbnail`). Use `"-"` to write to stdout. |
| `--format TEXT` | Output format: `svg`, `html`, `png`, `pdf`, `thumbnail`, `terminal`, `json`, `text`, `text-data`, `yaml`, `data`. Default: `svg`. |
| `--project-dir PATH` | Project directory for resolving relative paths. |
| `--var KEY=VALUE` | Variable value (repeatable). |
| `--chart TEXT` | Render only this chart (by chart id). Valid only with a single board argument or stdin; rejected with multiple boards. |
| `--no-cache` | Bypass all query caches and re-run from scratch. |
| `--cache PATH` | Keep the query cache in this DuckDB file (created if absent). Default: a per-user file shared by every project. Also settable via `DCT_CACHE_PATH`. Mutually exclusive with `--no-cache`. |
| `--diagnostics-json` | Emit all diagnostics (errors and warnings) as JSON Lines to stderr. stdout stays the render payload on success; one compact JSON object per diagnostic is written to stderr, line-delimited so a truncated read still yields whole objects. |
| `--allow-chart-errors` | Allow per-chart errors (missing columns, query failures, data-shape problems caught while sizing the board) without exiting non-zero. Default: fail; see [Warnings & CI behavior](#warnings-ci-behavior). |
| `--fail-fast` | Stop immediately on the first render failure. Default: continue rendering remaining boards, exit 1 at the end. |
| `--max-workers INT` | Maximum parallel query workers (default: 8, from config). Also settable via `DCT_MAX_WORKERS`. Effective only for external warehouse executors; DuckDB serializes access internally regardless of this setting. |
| `--no-warnings` | Suppress warning output to stderr. Warnings still appear in `--format json` output so agents and consumers always see them. |
| `--ignore-warning CODE` | Suppress a specific render-time warning code (repeatable). Suppressed warnings move to `suppressed_warnings` in `--format json` output. An unknown code, or an `ERR-*` code, exits 1. A retired warning code prints a `WARN-RETIRED-IGNORE-CODE` notice and does not change the exit code. |
| `--print0`, `-0` | Delimit produced output paths with NUL (`\0`) instead of newline, for safe piping to `xargs -0` when paths contain spaces. |

## Warnings & CI behavior

By default, `dct render` exits `1` if **any chart has a runtime error**: a missing column, a failed query, an unresolvable reference, or a data-shape problem caught while the board is being sized (a NULL in a pie's theta column, say). This is the CI-safe contract: a broken chart fails the build instead of shipping a silently-partial dashboard.

For live previews and agent iteration, where a partial render is useful feedback rather than a failure, pass `--allow-chart-errors` to keep exit code `0` and render whatever charts succeeded.

```bash
dct render charts/sales.yml --allow-chart-errors
```

Render-time *warnings* (as opposed to chart errors) print to stderr by default and don't affect the exit code. Use `--no-warnings` to silence them, or `--ignore-warning CODE` to suppress one specific code (repeatable):

```bash
dct render charts/sales.yml --ignore-warning WARN-REDUNDANT-ENCODING
```

The text output groups repeats: each warning code prints once per board with a count, the charts or queries it applies to, and the message and fix once. `--diagnostics-json` and `--format json` keep one entry per instance.

`dct docs warnings` lists every registered warning code; `dct docs warnings <CODE>` explains one.

## Output formats

| Format | Purpose |
|---|---|
| `svg` (default) | Scalable vector graphics: embedding, presentations |
| `html` | Interactive HTML page with embedded charts |
| `png` | Raster image: screenshots, thumbnails |
| `pdf` | PDF document: reports, printing |
| `thumbnail` | Abstracted SVG preview: no readable text, same size as the board |
| `terminal` | ASCII/Unicode charts printed to stdout |
| `json` | Post-execution resolved layout + data |
| `text` | Plain text rendering |
| `yaml` | Compiled board YAML |
| `data` | Flat JSON: queries keyed by name, charts keyed by slug |

## Examples

### Static export

```bash
dct render charts/sales.yml                         # → charts/sales.svg
dct render charts/sales.yml --format html
dct render charts/sales.yml --format png
dct render charts/sales.yml --format pdf
dct render charts/sales.yml --output sales.svg
```

### Variables

```bash
dct render charts/sales.yml \
  --var region=West \
  --var category=Electronics
```

### Terminal preview

```bash
dct render charts/sales.yml --format terminal
```

```text
================================================================================
 Sales Dashboard
================================================================================

Daily Revenue Trend
      ┌────────────────────────────────────────────────────────────┐
2400.0┤    ▗                ▟                                 ▗    │
2141.7┤   ▄▀▖              ▞ ▚               ▞▖              ▄▀▖   │
...
```

Terminal format writes directly to stdout. Use shell redirection to save:

```bash
dct render charts/sales.yml --format terminal > dashboard.txt
```

### Reading YAML from stdin

```bash
dct render - --format terminal --project-dir . <<'EOF'
charts:
  revenue:
    query:
      source: ./data/sales.csv
      sql: SELECT * FROM sales
    type: bar
    x: region
    y: revenue
rows:
  - revenue
EOF
```

There's no `type: csv` / `file:` query shape; a file is referenced with `source:` pointing at the path, and the table name is the file's stem (`sales.csv` → `sales`). See [Inline File Sources](../sources/index.md#inline-file-sources).

```bash
echo 'charts: {revenue: {query: {source: ./data/sales.csv, sql: "SELECT * FROM sales"}, type: bar, x: region, y: revenue}}
rows: [revenue]' | dct render - --format terminal
```

```bash
cat generated_dashboard.yml | dct render - --output - > output.svg
```

`--project-dir` controls where relative file paths (CSVs, etc.) are resolved from when reading stdin. Defaults to cwd.

### CI artifact generation

```bash
for board in charts/*.yml; do
  dct render "$board" \
    --format html \
    --output "dist/$(basename "$board" .yml).html"
done
```

### Inspect resolved layout for debugging

```bash
dct render charts/sales.yml --format json > sales_resolved.json
```

### Get exact values in the text summary

`--format text` (the default for agent tools) is a compact per-chart summary:
field mappings and value ranges, not the rows themselves. Use `--format text-data`
to append a `## Data` section with every query's actual rows, grouped by query
name (a query shared by several charts is dumped once). Rows are capped the
same way every other row-embedding format caps them (`--max-rows-per-query`,
uncapped by default), with an explicit "showing N of M rows" note when capped.

```bash
dct render charts/sales.yml --format text-data
```

### Extract the underlying data

`--format data` drops the layout and returns two flat maps: `queries` keyed by
query name, and `charts` keyed by slug. Each query carries its SQL and exactly
one copy of its rows; charts reference their query by name rather than
embedding the rows, so charts sharing a query do not repeat the result set.

```bash
dct render charts/sales.yml --format data > sales_data.json
```

```json
{
  "id": "sales",
  "title": "Sales",
  "queries": {
    "monthly": {
      "type": "sql",
      "sql": "SELECT month, revenue FROM dundersign_serving.monthly_metrics ORDER BY month",
      "rows": [{"month": "2026-01", "revenue": 48210}]
    }
  },
  "charts": {
    "revenue_trend": {
      "type": "line",
      "query": "monthly",
      "title": "Revenue Trend",
      "x": "month",
      "y": "revenue"
    }
  }
}
```

SQL is emitted as compiled; Jinja variable references are left
uninterpolated, and the values they resolve to appear under `variables`. A row
cap declares itself on the affected query as
`rows_truncated: {head, tail, total}`; rows are never dropped silently.

## Origin-absolute links in exports

By default, links inside rendered HTML and SVG files are root-relative
(`/org/proj/d/slug/`). That works when the file is served from the same host,
but breaks when it is opened as a standalone file (`file://`) or embedded
cross-origin.

Set `public_url` in your `dbt_charts.yml` to make export links fully-qualified:

```yaml {contract=project-config}
public_url: "https://dashboards.example.com"
```

With that setting, `dct render` produces `https://dashboards.example.com/d/slug/`
instead of `/d/slug/`. Leave it unset (the default, empty string) for local use.

## Caching

Query results are **cached on disk by default**, so rendering a board again does not send its queries to the warehouse again. A result is reused until it is older than the query's [`cache:` duration](../queries.md#how-long-results-stay-cached), which is 24 hours unless you set it.

```bash
dct render charts/sales.yml
dct render charts/sales.yml   # reuses cached query results
```

When a render reuses cached results it says so on stderr, with the age of the oldest one:

```text
3 queries served from cache, oldest result 2h 14m old. Pass --no-cache to re-query.
```

A render that ran every query prints nothing. Pass `--no-cache` to skip the cache and run every query from scratch.

### Where the cache lives

With no flag, the cache is one file in your user cache directory, shared by every project and by `dct serve`:

| Platform | Path |
|----------|------|
| macOS | `~/Library/Caches/com.getdbt/charts/query-cache.duckdb` |
| Linux | `~/.cache/com.getdbt/charts/query-cache.duckdb` (or under `$XDG_CACHE_HOME`) |
| Windows | `%LOCALAPPDATA%\com.getdbt\charts\query-cache.duckdb` |

Sharing one file is safe: an entry is keyed on the source's connection identity, the SQL, and the variable values, so two projects, or two git worktrees of one project, reuse each other's results only when they would have run the same query against the same source. The file and its directory are readable only by your user. Entries older than about a week are removed from this file, so query results do not pile up on disk; that includes results of a `cache: forever` query, which a file you choose with `--cache` keeps for good. To clear it, delete the file.

To keep the cache somewhere else, pass `--cache <path>`:

```bash
dct render charts/sales.yml --cache cache.duckdb
```

The file is created automatically if it doesn't exist yet, and dbt Charts never removes entries from a file you chose. `--cache` also reads from the `DCT_CACHE_PATH` environment variable, and a project can set the location once with the `path` key under `cache:` in `dbt_charts.yml` (shown in the [`dct serve` reference](serve.md#caching)). The flag beats the environment variable, which beats the project config. `--cache` and `--no-cache` are mutually exclusive.

### Several processes at once

Any number of `dct render` and `dct serve` processes can share one cache file. Each opens the file only for the moment it reads or writes a result. If another program keeps the file open (a DuckDB shell, for example), dbt Charts retries for about ten seconds and then stops with `ERR-CACHE-FILE-UNAVAILABLE`, naming the file and giving DuckDB's reason, which says which process holds it where DuckDB knows. A cache file that is damaged or not writable stops the same way. dbt Charts never continues without the cache, because that would quietly re-run every query.

## Diagnostics JSON

For programmatic consumers (agents, CI, IDE extensions), `--diagnostics-json` emits all diagnostics (both errors and warnings) as JSON Lines to **stderr**, leaving stdout free for the render payload:

```bash
dct render charts/sales.yml --diagnostics-json --format svg > output.svg 2> diags.jsonl
```

On success, warnings stream to stderr as JSONL and the rendered output goes to stdout (or `--output`). On failure, errors stream to stderr as JSONL and the process exits non-zero. Each line is one compact JSON object; line-delimited format means a truncated read still yields whole diagnostics.

```bash
dct render charts/sales.yml --diagnostics-json 2>&1 | grep '^{' | jq .
```

## Related

- [`dct serve`](serve.md): interactive preview with auto-reload
- [`dct validate`](validate.md): fast pre-render validation
- [`dct query`](query.md): inspect one named query without rendering the whole board

# serve (https://docs.dbtcharts.com/cli/serve/)

# `dct serve`

Start the local dashboard server. Renders your dashboards in the browser; board file paths map to URLs (`charts/sales.yml` → `/sales/`). Query parameters become variables.

```bash
dct serve [OPTIONS]
```

## How it finds your project

`dct serve` auto-discovers the project root by walking up from the current directory looking for `dbt_charts.yml` or `dbt_project.yml`. When a dbt project is found, the SQL dialect is inferred from the active profile target.

## How it picks a port

Resolution order:

1. `--port` flag
2. `DCT_PORT` env var
3. `server.port` in `dbt_charts.yml`
4. Deterministic hash of the project directory

If the chosen port is occupied, the next available port is used automatically.

## Server config

Serve-only project settings live under `server:` in `dbt_charts.yml`.

```yaml {contract=project-config}
server:
  port: 3000
  nav: true
  debug: true
```

Set `server.nav: false` to hide the dbt Charts nav bar. Set `server.debug: false`
to disable Starlette's debug pages.

## Options

| Flag | Description |
|---|---|
| `--port INT` | Port number. Auto-resolved if not set. |
| `--host TEXT` | Host address. Default: `localhost`. |
| `--project-dir PATH` | Project directory for resolving board file paths. |
| `--dialect TEXT` | SQL dialect (auto-detected from dbt, or `duckdb`). |
| `--target TEXT` | dbt target name. Default: `DBT_TARGET` env, then profile default. |
| `--max-workers INT` | Maximum parallel query workers per render (default: 8, from config). Also settable via `DCT_MAX_WORKERS`. Effective only for external warehouse executors; DuckDB serializes access internally regardless of this setting. |
| `--no-cache` | Skip the query-result cache entirely (every request re-runs queries). |
| `--cache PATH` | Keep the query cache in this DuckDB file (created if absent). Default: a per-user file shared by every project. Also settable via `DCT_CACHE_PATH`. Mutually exclusive with `--no-cache`. |

## Examples

```bash
# Start with auto-detected project + port
dct serve

# Pin a port
dct serve --port 3000

# Bind on all interfaces, such as in Docker
dct serve --host 0.0.0.0

# Use the `prod` dbt target
dct serve --target prod

# Keep the query cache in a file of your choosing
dct serve --cache cache.duckdb
```

## Caching

Query results are **cached on disk by default**, in the same per-user file [`dct render`](render.md#caching) uses. Results survive a server restart, and a board already rendered from the command line opens without re-running its queries. Two `dct serve` processes can run side by side and share that cache.

To keep the cache in another file, pass `--cache <path>`:

```bash
dct serve --cache cache.duckdb
```

The file is created automatically if it doesn't exist yet. `--cache` also reads from the `DCT_CACHE_PATH` environment variable, and a project can set the same location once in `dbt_charts.yml`:

```yaml {contract=project-config}
cache:
  ttl: 24h
  path: .dct/cache.duckdb
```

The flag beats the environment variable, which beats the project config; with none of them set, the per-user file is used. Several servers and renders can share any of these files; see [Several processes at once](render.md#several-processes-at-once). Pass `--no-cache` to skip the cache entirely. `--cache` and `--no-cache` are mutually exclusive.

## URL routing

| Path | Renders |
|---|---|
| `/` | `charts/index.yml` if present, otherwise a listing of available boards |
| `/<board-name>/` | The board at `charts/<board-name>.yml` |
| `/<folder>/` | `charts/<folder>/index.yml` if present, otherwise a listing of the folder |
| `/<board-name>/?region=West` | Same board with `region` variable set |

![dct serve's auto-generated board listing at the project root; no charts/index.yml, so it falls back to a directory listing, nav bar included](../assets/screens/cli/serve/board-listing.png){: width="900" height="274" }

## When to use what

| If you want… | Use |
|---|---|
| Live, interactive previews while editing YAML | `dct serve` |
| Static export (SVG, HTML, PNG, PDF) | [`dct render`](render.md) |
| Interactive YAML editor + AI Copilot | [`dct playground`](playground.md) |

## Stopping the server

Press `CTRL+C` in the terminal.

## Related

- [`dct render`](render.md): static export
- [`dct playground`](playground.md): interactive editor

# query (https://docs.dbtcharts.com/cli/query/)

# `dct query`

Run a named board query, execute raw SQL, or validate SQL for structural issues; all in one command. The first operand is the query context: a data source name, a CSV/JSON/Parquet file path, or a board file (`.yml`, `.yaml`, `.md`, `.markdown`).

## Modes

| Mode | Invocation | Description |
|---|---|---|
| Board execute | `dct query board.yml NAME` | Run a named query from a board, print the result as CSV |
| Raw SQL execute | `dct query db 'SELECT …'` | Execute SQL directly against a data source |
| File execute | `dct query data/orders.csv 'SELECT …'` | Execute SQL against one data file; the table name is the file stem |
| SQL from file | `dct query db --file query.sql` | Execute SQL read from a file |
| Validate | `dct query db 'SELECT …' --validate` | Lint SQL for missing joins and re-aggregation |

## Usage

```bash
dct query [OPTIONS] [CONTEXT] [QUERY]
```

`CONTEXT` is a source name, a data file path (resolved like a board's inline `source:`: from the project root), or a board path (`.yml`, `.yaml`, `.md`, `.markdown`). `QUERY` is SQL for source contexts, or a named query/reference for board contexts.

## Options

| Flag | Description |
|---|---|
| `--validate` | Run static lint instead of executing. |
| `--file PATH` | Read SQL from a file instead of passing inline. Requires a source context. |
| `--dialect NAME` | SQL dialect hint for `--validate` (`duckdb`, `bigquery`, etc.). |
| `--var KEY=VALUE` | Variable override (repeatable). |
| `--show-suppressed` | Include suppressed diagnostics in `--validate` output. |
| `--json` | Output JSON instead of CSV: one object per row, up to 1,000 rows, with `truncated` set when more exist. |
| `--project-dir PATH` | Project directory for resolving relative paths. |

## Examples

```bash
# Run the `revenue` query from a board and print it as CSV
dct query charts/sales.yml revenue

# Execute raw SQL against a named source
dct query my_warehouse 'SELECT month, revenue FROM dundersign_serving.monthly_metrics ORDER BY month'

# Execute SQL against a CSV file (table name = file stem)
dct query data/orders.csv 'SELECT status, count(*) FROM orders GROUP BY 1'

# Execute SQL from a file
dct query my_warehouse --file analytics/monthly.sql

# Static lint
dct query my_warehouse 'SELECT SUM(a.x), SUM(b.y) FROM a JOIN b ON a.id = b.id GROUP BY 1' --validate

# Static lint on a named board query
dct query charts/sales.yml revenue --validate

# Machine-readable output
dct query charts/sales.yml revenue --json
dct query my_warehouse 'SELECT 1' --validate --json
```

## Output

Results print as CSV: a header line, then one line per row. The output is capped at about 37,500 bytes, the same cap the MCP `execute_query` tool applies to what a model reads. When rows are cut, a notice on stderr says how many were shown and how to narrow the query. There is no row-count flag; put `LIMIT` in the SQL, or filter, aggregate, and select fewer columns.

## Exit codes

- `0`: success (named-query execute, SQL execute, validate with no errors)
- `1`: error (file not found, compile error, validation errors, warehouse error)

## Related

- [Queries reference](../queries.md)
- [`dct render`](render.md)
- [`dct search`](search.md)

# search (https://docs.dbtcharts.com/cli/search/)

# `dct search`

Search dashboards by keyword with ranked results. Each hit includes the board's title, notes, and source path, plus its match score, why it matched, and the charts whose id or title matched. Run `dct search ""` to list every board by path. Board files in markdown are searched too. For a board's charts and queries, run [`dct describe`](describe.md) on its path.

```bash
dct search [OPTIONS] {query}
```

## Arguments

| Argument | Description |
|---|---|
| `QUERY` | Keywords to match against dashboard metadata. |

## Options

| Flag | Description |
|---|---|
| `--json` | Output as JSON. |
| `--limit INT` | Maximum results to return. Default 10, max 200 (values above 200 are clamped to 200). |
| `--project-dir DIRECTORY` | Project root for resolving board paths and finding project config.  [env var: DCT_PROJECT_DIR] |

## Examples

```bash
dct search revenue
dct search "monthly trends" --limit 5
dct search orders --json
```

## What's searched

Each board is indexed on:

- `title:` and `notes:` fields
- Chart ids and titles
- Query names and SQL bodies
- Tags and other metadata

Hits are ranked by relevance.

## Finding a chart

Each board hit lists the charts that matched, by id (`matched_charts` in `--json` output). A board path plus a chart id addresses one chart:

```bash
dct search revenue
dct describe charts/sales.yml --chart revenue_kpi
dct render charts/sales.yml --chart revenue_kpi
```

When charts on several boards match, each board's hit lists its own.

## When to use which search verb

| If you want to find… | Use |
|---|---|
| A dashboard about revenue | `dct search` |
| A column or table in the warehouse | [`dct query`](query.md) against `INFORMATION_SCHEMA` |
| A topic in the YAML reference docs | [`dct docs --search`](docs.md) |
| A packaged agent skill | [`dct skills`](skills.md) |

## Related

- [`dct query`](query.md)
- [`dct docs`](docs.md)
- [`dct skills`](skills.md)

# impact (https://docs.dbtcharts.com/cli/impact/)

# `dct impact`

Which boards break if this column changes.

```bash
dct impact COLUMN [OPTIONS]
```

A dbt author about to rename a column wants one answer before touching the model: which dashboards depend on it. `dct impact` walks every board's compiled SQL (named queries, inline chart queries, layers, cross-board imports) and reports the ones that reference the column on a base table, resolved through CTEs, aliases and correlated subqueries. dbt `ref('orders')` maps to `orders`; `source('raw', 'orders')` maps to the dotted `raw.orders`, so `--table raw.orders` narrows to the source while `--table orders` finds both spellings (narrowing with the dotted name will not match boards that reach the same relation via `ref()`). No warehouse connection: the index is built from the YAML alone. The scan covers boards under `charts/`, markdown boards included; when nothing is found there, the command says so rather than reporting a clean zero.

## Options

| Option | Description |
|---|---|
| `--table NAME` | Narrow to columns of this table/model (for common names like `id`) |
| `--json` | Typed output for agents and scripts |
| `--project-dir PATH` | Project root (default: walk up from the current directory) |

## Indeterminate boards

A board whose column use cannot be determined (a `SELECT *` over a base table, SQL that does not parse, a jinja expression standing where a column or table name would be (`WHERE {{ filter('country', country) }}`), a `ref()`/`source()` spelling the index cannot resolve (package-qualified, versioned), or a board that fails compile) is listed separately, never silently omitted. A board missing from an impact list reads as "safe to rename", which is the one wrong answer that matters; verify indeterminate boards by hand before trusting an empty hit list.

## Examples

```bash
dct impact customer_id                 # Who references this column?
dct impact id --table users            # Narrow a common name to one table
dct impact customer_id --json | jq '.hits[].board'
```

## Related

- [`dct validate --warehouse`](validate.md): checks whether each query still binds against the live warehouse
- [`dct search`](search.md): keyword search over dashboard metadata

# describe (https://docs.dbtcharts.com/cli/describe/)

# `dct describe`

Describe a dashboard's queries, charts, variables, and layout.

```bash
dct describe [OPTIONS] PATH...
```

## Arguments

| Argument | Description |
|---|---|
| `PATH...` | Path(s) to board YAML files or directories. One or more required. |

## Options

| Flag | Description |
|---|---|
| `--chart ID` | Describe one chart on the board: the chart, the queries it reads, and only the variables it depends on. Takes exactly one board file. |
| `--json` | Output as JSON. |
| `--project-dir PATH` | Project directory for resolving relative paths. |

## Examples

```bash
dct describe charts/sales.yml
dct describe charts/sales.yml --json
dct describe charts/sales.yml charts/inventory.yml --json
dct describe charts/
dct describe charts/*.yml --json | jq '.[] | select(.charts | length > 5)'
dct describe charts/sales.yml --chart revenue_kpi
```

A chart is addressed by its board path plus its chart id, the same pair `dct render BOARD --chart ID` takes. `dct search` lists the matching chart ids for each board. An id the board doesn't declare fails with `ERR-UNKNOWN-CHART`, which lists the board's charts.

When given a directory, `dct describe` globs `**/*.yml` and `**/*.yaml`, skipping any file whose name starts with `_` (partials and templates).

## JSON output shape

Single file: returns a JSON **object**. Two or more files: returns a JSON **array**. Exit code is `1` if any file has errors.

## Related

- [`dct validate`](validate.md): fast structural validation (no structure summary)
- [Error Handling Guide](../guides/error-handling.md): anatomy of a dbt Charts error

# docs (https://docs.dbtcharts.com/cli/docs/)

# `dct docs`

Browse the dbt Charts YAML reference offline. The syntax guide lives in one file (`dbt_charts/DBT_CHARTS_SYNTAX.md` in the wheel) with one H2 per topic; the generated field, error, and warning references ship beside it and appear in the topic index as `reference`, `error-reference`, and `warning-reference`. Useful when you're editing YAML without a browser, or when an AI agent needs to look something up. The topic index also links to the full web docs site.

```bash
dct docs [OPTIONS] [TOPIC]
```

## Modes

| Invocation | Behavior |
|---|---|
| `dct docs` | Topic index: one row per topic, each with a one-line description |
| `dct docs cheatsheet` | One-page essentials: the shape of a board in one screen |
| `dct docs <topic>` | One H2 section by slugified name |
| `dct docs all` | Syntax guide plus the generated field reference, unsliced |
| `dct docs reference` | Generated YAML field reference |
| `dct docs errors` | List every registered error code with a one-line summary |
| `dct docs errors <CODE>` | Full documentation for one error code |
| `dct docs warnings` | List every registered render-time warning code with a one-line summary |
| `dct docs warnings <CODE>` | Full documentation for one warning code |
| `dct docs --search "grid"` | Ranked search across every topic section and the generated references |
| `dct docs charts --search "legend"` | The same search, scoped to one topic |

Both `errors` and `warnings` are filtered views over the same diagnostic
registry; a code typed under the "wrong" verb still resolves and reports its
actual level, rather than failing with an unknown-code error.

## Arguments

| Argument | Description |
|---|---|
| `TOPIC` | Topic slug, slugified H2 heading (for example, `board`, `charts`, `queries`, `layout`). Use `all` for the syntax guide plus the field reference, `reference` for the field reference alone, `errors` to browse error codes, or `warnings` to browse render-time warning codes. Omit for the topic index. |
| `CODE` | Diagnostic code to look up in detail (for example, `ERR-NO-LAYOUT`, `WARN-REDUNDANT-ENCODING`). Only valid when `TOPIC` is `errors` or `warnings`; case-insensitive. |

## Options

| Flag | Description |
|---|---|
| `--search TEXT`, `-s TEXT` | Ranked term search (BM25) over every H2/H3 section of the reference plus the generated field, error, and warning references. Multi-word queries match on terms, not the exact phrase. Pass a `TOPIC` as well to scope the hits to that topic. Each hit prints the whole matched section and names the topic to read next with `dct docs <topic>`. |
| `--json` | Stable JSON output suitable for agent consumption. |
| `--limit INT` | Max search hits to return. Default 5, max 20. |

## Examples

```bash
dct docs                          # Topic index
dct docs cheatsheet               # One-page essentials
dct docs charts                   # Full docs for the charts topic
dct docs all                      # Syntax guide + field reference, unsliced
dct docs reference                # Generated YAML field reference
dct docs errors                   # List every registered error code
dct docs errors ERR-NO-LAYOUT     # Full doc for one error code
dct docs warnings                 # List every render-time warning code
dct docs warnings WARN-REDUNDANT-ENCODING  # Full doc for one warning code
dct docs --search "grid layout"   # Ranked search across topics
dct docs charts -s "hide legend"  # Ranked search scoped to the charts topic
dct docs charts --json            # Agent-shaped output
```

## When to use which discovery verb

| If you want… | Use |
|---|---|
| Reference docs about YAML fields, chart types, layout | `dct docs` |
| To search dashboards in your project | [`dct search`](search.md) |
| To explore the warehouse schema | [`dct query`](query.md) against `INFORMATION_SCHEMA` |
| Packaged agent skill examples | [`dct skills`](skills.md) |

## Related

- [`dct skills`](skills.md)
- [`dct search`](search.md)
- [`dct query`](query.md)

# skills (https://docs.dbtcharts.com/cli/skills/)

# `dct skills`

List packaged agent skills, or show one by name. Skills are the AI-facing knowledge packs that ship with dbt Charts, each one teaches an AI assistant a specific authoring pattern (for example, `kpi-row`, `top-n-with-detail`, `before-after-comparison`).

```bash
dct skills [OPTIONS] [NAME]
```

## Arguments

| Argument | Description |
|---|---|
| `NAME` | Skill name to show. Omit to list all skills. |

## Options

| Flag | Description |
|---|---|
| `--json` | Output as JSON. |

## Examples

```bash
dct skills                  # List every packaged skill
dct skills kpi-row          # Show the kpi-row skill body (markdown)
dct skills kpi-row --json   # Same skill, JSON-shaped
```

A skill's name differs by surface: dbtcharts.com's chat invokes it bare (`/board-build`), while a file-installed local skill reads `dct-board-build`. The registry name (what `dct skills <name>` and MCP `get_skill` take) is always bare, on every surface; the `dct-` prefix exists only in the file-installed directory name and frontmatter, produced once by `dct init skills`.

## How skills are used

- **Orientation.** `dct skills intro` is the one to read first: what dbt Charts is, the shortest path from data to a rendered board, and a table of which skill to read next. It is the skill the one-line agent hand-off on dbtcharts.com points at.
- **File install (recommended).** `dct init skills` copies CLI-rendered skills to your agent skill directories, each one namespaced under a `dct-` prefix (`dct-board-build/`, `dct-board-design/`, ...) so they never collide with a skill your project or another tool already installed. Gitignore ours with `.agents/skills/dct-*/`, or the same `dct-*/` pattern under the Claude Code skills directory, without touching anyone else's. `dct init skills` always overwrites an existing install, so after `pip install -U dbt-charts`, re-run it to pick up new or updated skills.
- **MCP server.** `dct mcp serve` exposes skills as tools that AI agents can call.
- **Zero-install fallback.** `dct skills <name>` prints a skill body without file install; useful in CI or when you only need to read the content.
- **Reading a pattern.** A pattern skill's body includes its YAML, which `dct skills <name>` prints for you to copy.

## Related

- [CLI and MCP for AI assistants](ai-cli-and-mcp.md): when to use the CLI vs MCP
- [`dct init skills`](init.md): install skill files to agent directories
- [`dct init mcp`](init.md): wire MCP config for AI clients
- [`dct mcp serve`](mcp.md): run the MCP server

# doctor (https://docs.dbtcharts.com/cli/doctor/)

# `dct doctor`

Diagnose why `dct` can't reach your data.

```bash
dct doctor [OPTIONS]
```

Reports how dbt Charts was installed, whether your project and `profiles.yml` were found, and whether each configured source has its warehouse adapter installed. Paste the output into a support ticket or hand it to an AI assistant. The default run is offline and opens no warehouse connection.

```text
$ dct doctor

 ✓ install     dbt Charts 1.8.0 (uv tool), Python 3.13.1 at /home/ana/.local/share/uv/tools/dbt-charts/bin/python
 ✓ project     dbt_charts.yml at /home/ana/shop; dbt project at /home/ana/shop
 ✓ profiles    /home/ana/.dbt/profiles.yml
 ✗ adapter     warehouse: the dbt-snowflake adapter is not installed in this Python environment
               uv tool install "dbt-charts[snowflake]"
 ✓ adapter     local: duckdb adapter installed
 – connection  connections not tested
               run `dct doctor --with-warehouse`

1 failed, 0 warnings.
```

Marks: `✓` pass, `!` warn, `✗` fail, `–` skip.

## Options

| Option | Description |
|---|---|
| `--with-warehouse` | Also connect to each warehouse source with `SELECT 1` |
| `--json` | Machine-readable report (see [JSON output](#json-output)) |
| `--project-dir PATH` | Where to start looking for the project (default: the current directory) |

## What it checks

Checks run in this order. One failing check never stops the next.

### `install`

The dbt Charts version, the install method (`uv tool`, `pip`, or `editable`), and the Python interpreter running `dct`. Always `pass`. An adapter installed into a different Python than the one shown here is the most common cause of a "not installed" error.

### `project`

Looks for `dbt_charts.yml` or `dbt_project.yml` in the starting directory and its parents. `warn` when neither is found; the `adapter` and `connection` checks are then skipped.

### `profiles`

Locates `profiles.yml` using the same search order as the rest of `dct`: `DBT_PROFILES_DIR`, the project directory, then `~/.dbt/`. `skip` when there is no dbt project, `fail` when no `profiles.yml` is found. A `dbt_profile` source that sets `profiles_dir` gets its own check (with `source` set) against that directory; the default search is reported unless every `dbt_profile` source sets its own.

### `adapter`

One check per source in `dbt_charts.yml`. It imports the warehouse adapter the source needs; a missing one fails with the extra to install. A `dbt_profile` source is checked against the adapter its profile target names, so a missing `profiles.yml` or an unknown profile fails here too. File sources (`csv`, `json`, `parquet`), `http` sources, and databases dbt Charts runs natively (such as `sqlite`) need no dbt adapter and are `skip`. If the `sources:` block itself cannot be loaded, a single `adapter` check without a `source` reports why.

### `connection`

Without `--with-warehouse`, a single `skip`. With it, one check per source: `SELECT 1` against the warehouse, failing with the connection error. Sources whose adapter check did not pass, and file sources, are `skip`.

## JSON output

`dct doctor --json` prints a `DoctorReport`:

| Field | Description |
|---|---|
| `success` | `false` when any check is `fail` |
| `checks` | Every check, in the order above |
| `checks[].code` | `install`, `project`, `profiles`, `adapter`, or `connection` |
| `checks[].source` | Source name; set on per-source `adapter`, `connection`, and `profiles` checks |
| `checks[].status` | `pass`, `warn`, `fail`, or `skip` |
| `checks[].message` | What was found |
| `checks[].hint` | The command or flag that fixes it, when there is one |

Fields that are unset are omitted. This shape is version 1: the `code` values and field names are stable, and a rename ships behind a version bump.

## Exit code

`1` when any check is `fail`, otherwise `0`. A `warn` or `skip` never fails the run.

## Examples

```bash
dct doctor                                   # Offline checks
dct doctor --with-warehouse                  # Also test each connection
dct doctor --json | jq '.checks[] | select(.status == "fail")'
```

## Related

- [Troubleshooting](../guides/troubleshooting.md): errors by symptom
- [`dct validate --warehouse`](validate.md): checks board queries against the warehouse

# AI assistants (https://docs.dbtcharts.com/cli/ai-cli-and-mcp/)

# CLI and MCP for AI assistants

dbt Charts exposes the same capabilities to AI assistants in two ways: **`dct` CLI commands** (shell) and an **MCP server** (`dct mcp serve`). Both call the same Python APIs; they are thin wrappers over one engine, not two products.

This page explains **why both exist**, **when each is the right choice**, and how they relate to **agent skills**.

## Why both?

| Surface | What it is | Best for |
|---------|------------|----------|
| **CLI** | Subcommands like `dct query`, `dct validate`, `dct render`: stdout, `--json`, exit codes | Any environment with a shell and `dct` on `PATH` |
| **MCP** | Structured tools (`execute_query`, `render_board`, …) over stdio | MCP-native clients, hosted agents, editors without shell |

Different agents read different integration layers:

- **Cursor, Codex, Claude Code**: shell + optional MCP + file-based skills
- **VS Code / GitHub Copilot agent mode**: MCP tools; no project skill directory today
- **The [dbt Charts Cloud](../cloud/ai-copilot.md) copilot**: MCP only; no shell, no local file install

One surface cannot cover all of those. Keeping both avoids forcing every user through MCP setup while still serving clients that *only* speak MCP.

## When to prefer the CLI

**Default recommendation:** if the agent can run shell commands and `dct` is installed, **use the CLI**.

Reasons:

1. **Lower setup friction**: `pip install dbt-charts` is enough. No per-client MCP config, no `dct init mcp`, no restart-the-IDE step.
2. **Works everywhere**: local dev, CI, headless agents, SSH, scripts. Same verbs in every unconstrained environment.
3. **Portable agent knowledge**: skills and docs teach `dct validate`, `dct query`, `dct docs`. That vocabulary works even when MCP is not wired up.
4. **Human parity**: what the agent runs is what you run in the terminal. Easier to debug and reproduce.
5. **Long-term baseline**: the zero-MCP path (`dct docs`, `dct skills`, `dct validate`) stays the floor; MCP is an upgrade, not a prerequisite.

Typical CLI-first setup:

```bash
uv tool install dbt-charts   # or: pip install dbt-charts
dct skills intro         # what the tool is, and which skill to read next
dct init skills          # optional: copy the skills into this repo's agent directories
dct init mcp             # optional; only if you also want MCP
```

An agent that has never seen dbt Charts needs only the first two lines, so the
sentence to hand one is short:

```text
I want to make charts of this data with dbt Charts. Run `uv tool install dbt-charts`, then `dct skills intro`, and follow what it prints.
```

Agent skills installed to `.agents/skills/` (or agent-specific skill directories) are **CLI-oriented**: they reference `dct` verbs, not MCP tool names.

## When MCP is required or better

Use MCP when the CLI is **unavailable** or **secondary**:

| Situation | Why MCP |
|-----------|---------|
| **VS Code / Copilot agent mode** | Agent invokes MCP tools; no shell, no file skill dirs (use MCP `get_skill` / resources for workflow knowledge) |
| **dbt Charts Cloud copilot** | Controlled environment: no `dct` subprocess from the agent, no writing to the user's skill dirs; MCP is the only integration |
| **Claude Desktop / some IDE chat UIs** | Chat is MCP-native; configuring `dct mcp serve` is the intended path |
| **Structured tool calls** | MCP returns typed JSON without parsing terminal output; nice when already connected, not worth the setup cost alone |

Setup:

```bash
dct init mcp             # auto-detect Cursor, VS Code, Claude Code, Codex, …
dct mcp serve            # or let the client spawn this via config
```

MCP exposes the same operations under tool names (for example, `render_board`, `execute_query`, `docs`). Skills served over MCP use that vocabulary; the registry hides CLI-only skills like `mcp-setup` from MCP clients.

## Skills: file install vs CLI lookup vs MCP

Workflow knowledge (build, review, design patterns) ships as **agent skills**: `SKILL.md` files in the wheel.

| Delivery | Surface | When |
|----------|---------|------|
| **`dct init skills`** (file copy to agent dirs) | CLI-rendered files in `.agents/skills/` | Local agents: Cursor, Codex, Claude Code, GitHub Copilot Coding Agent |
| **`dct skills <name>`** | CLI | Fallback, humans, CI, zero-MCP |
| **MCP `get_skill` / resources** | MCP | Copilot, the dbt Charts Cloud copilot, any connected MCP client |

File-installed skills assume the agent can run `dct` commands. MCP-delivered skills assume connected tools. Same content, different vocabulary, picked at serve/install time.

## Reading the docs without the CLI

An agent with only an HTTP fetch tool can read these docs as Markdown instead of HTML:

- `https://docs.dbtcharts.com/llms.txt` indexes the pages that matter most.
- `https://docs.dbtcharts.com/llms-full.txt` is every page in one file.
- Every page is also published as Markdown at its source path, for example `https://docs.dbtcharts.com/quick-guide.md` or `https://docs.dbtcharts.com/charts/index.md`.
- Any page URL returns its Markdown when the request sends `Accept: text/markdown`:

```bash
curl -H "Accept: text/markdown" https://docs.dbtcharts.com/quick-guide/
```

## Quick decision guide

```text
Can the agent run shell commands and is dct installed?
├─ YES → Prefer CLI (dct query, dct validate, dct docs, dct skills)
│         Install skills:  dct init skills
│         Optional MCP:    dct init mcp
└─ NO  → Use MCP (dct init mcp or hosted integration)
          Skills via get_skill / dct://guide/* resources
```

## Same engine, different wire format

Both surfaces delegate to `dbt_charts.agent_api`:

- `dct render` ↔ MCP `render_board`
- `dct query` ↔ MCP `execute_query`
- `dct docs` ↔ MCP `docs`
- `dct skills` ↔ MCP `list_skills` / `get_skill`

Pick one primary surface per environment. Do not configure MCP *and* teach the agent to shell out for the same operation unless you have a reason (for example, debugging). In mixed setups, **CLI for execution, MCP when CLI is impossible** is the usual split.

## Related

- [`dct init`](init.md): project bootstrap, skills install, MCP wiring
- [`dct skills`](skills.md): skill catalog and search
- [`dct mcp`](mcp.md): MCP server commands and tool list

# cloud (https://docs.dbtcharts.com/cli/cloud/)

# `dct cloud`

Operate [dbt Charts Cloud](../cloud/index.md) from the terminal: connect a
project's repository, wire up a warehouse connection, map sources, and
render — the CLI surface behind the `cloud-setup` product skill.

```bash
dct cloud [OPTIONS] COMMAND [ARGS]...
```

Every verb accepts `--json` for machine-readable output and `--host` to
target a non-default Cloud deployment (env var `DCT_CLOUD_HOST`). Most also
resolve an org, and sometimes a project, from context rather than requiring
`--org`/`--project` on every call — see [Context resolution](#context-resolution-org-and-project)
below.

## Authentication

```bash
dct cloud login
```

Signs you in with the OAuth device grant: it opens the approval page in
your browser (and prints the URL, for when it can't), you sign in (or
create an account), pick or create the organization the CLI should reach,
and approve. `dct cloud login` then
stores the resulting token in the local config file (`dct cloud use` prints
its path) — one browser approval, once per machine, and it covers every
repository you work in and every organization you approved.

Unchecking an organization at the consent screen narrows what the token can
reach; running `dct cloud login` again re-consents and replaces the stored
credential. The organizations you check apply to the CLI on every machine you
signed in from: narrowing on one laptop narrows the others too, without signing
them out. `dct cloud logout` revokes and clears it, and `dct cloud whoami`
reports the host, where the credential came from, and what it can reach.

A token may also come from the `DCT_CLOUD_TOKEN` environment variable — the
way CI and other agents authenticate without a browser. Every verb that
needs a credential reads it from `DCT_CLOUD_TOKEN` first, then the config
file. Run a read-only verb like `dct cloud orgs` to confirm it works.

The same token also reads board pages, so a script or an agent can check its
own work rather than handing a URL to a person:

```bash
curl -H "Authorization: Bearer $DCT_CLOUD_TOKEN" \
  "$(dct cloud boards --json | jq -r '.boards[0].url')"
```

That is read-only: board pages, their `.svg` / `.png` / `.pdf` exports, and
their render artifacts. It grants nothing the token's owner does not
already have. See [Access control](../cloud/access-control.md#reading-a-board-with-a-cli-token)
for the exact bounds.

## Context resolution: org and project

Resolution order for the org (and project, where a verb takes one):

1. Explicit `--org` (and `--project`) flags.
2. This repository's own `published_to:` record: a `published_to:` key in
   the nearest `dbt_charts.yml` above the current directory, written by a
   successful `dct cloud project connect`. It is the project's home URL,
   trailing slash included — `published_to:
   "https://dbtcharts.com/acme-data/analytics/"` — so pasting it into a
   browser opens the project. This only applies when neither `--org` nor
   `--project` is given.
3. This repository's git remotes, matched against the projects connected to
   your organizations. An unambiguous match wins even with no flag; two
   matches is an error naming both, so you pick.
4. The stored default from `dct cloud use`.
5. Otherwise, a loud error listing the orgs/projects you can choose from.

A `published_to:` naming a different host than the one this call is using
(`--host`, `DCT_CLOUD_HOST`, or the configured default) is an error naming
both hosts, not a silent skip to step 3: a stale or moved record is worth
fixing, not working around quietly.

**Destructive verbs are strict**: `dct cloud org delete`, `dct cloud project
delete`, `dct cloud connection delete`, `dct cloud member remove`, `dct cloud
invite revoke`, and `dct cloud grant revoke` skip steps 2 and 4. Only an
explicit flag or an unambiguous repo match can name what gets deleted, so a
stale `dct cloud use` default can never silently pick which org, project, or
connection loses its data. `published_to:` is skipped for the same reason: a
fork of a connected repository carries the record verbatim, and unlike a
git-remote match it does not correct itself in the fork, so honoring it
would let a delete run in the fork remove the upstream project.

**`dct cloud project connect` skips step 4 too**, for a reason of its own:
a repository being connected matches nothing yet (steps 2 and 3 answer
nothing either, before the connect that would create the record), so the
stored default would answer every time. A stale default would bind the repo
into whatever org it happened to point at, so connect refuses instead and
lists your orgs; pass `--org`. A successful connect then writes
`published_to:` into the local `dbt_charts.yml` (printed to the terminal,
with a reminder to commit it) so the next call in this repo resolves from
step 2 instead of falling through to git-remote matching.

The write is verified, never assumed. Because the record outranks the
git-remote match, connect writes it only when the checkout you are standing
in really is the repository it just connected — its git remotes have to
match. When they do not, when no `dbt_charts.yml` exists yet at the
connected root, or when the file is one the splice cannot edit safely,
connect prints the exact key and value to add by hand instead of writing.
The project is already connected either way: a local write that cannot
happen never takes the connect result (or its `--json` body) away from you.

Pin a default so routine verbs don't need `--org`/`--project` every time:

```bash
dct cloud use acme                  # org only
dct cloud use acme/analytics        # org and project
```

## Secrets input

[`dct cloud connection create`](#dct-cloud-connection-create) never takes a
credential on the command line: `--set` refuses any field that carries one
(`password`, `token`, `credentials_json`, `private_key`,
`private_key_passphrase`),
because a value on argv sits in shell history and the process list. Supply
the credential through exactly one of:

| Flag | Use for |
|---|---|
| `--keyfile FILE` | A key file — BigQuery's service-account JSON, Snowflake's private key |
| `--password-stdin` | A password typed or piped into stdin |
| `--password-env VAR` | A password already sitting in an environment variable |

A connection whose test fails outright is reported as a failure and is not
saved: the command exits non-zero, prints the warehouse's own error, and
leaves nothing behind, so the retry is the same command once you have fixed
whatever that error names.

A test that could not finish in time is different. The warehouse may simply
still be starting up: a suspended Snowflake warehouse resumes on the first
query, so the check disproved nothing and the connection **is** saved. The
command still exits non-zero, and the error names the connection's slug and
the `dct cloud connection test <slug>` command that re-runs the check once
the warehouse answers. Re-running `connection create` in that state fails on
the slug that already exists.

## Automating setup

The whole Cloud onboarding runs from a script or a coding agent. A person is
needed twice, to approve the login and to pick the repository on GitHub, and
the [`--start`/`--wait`](#approving-in-a-separate-call) split hands each of
those to them without the script blocking. This example publishes a
repository named `analytics` into a new `acme` organization, with its boards'
`source: warehouse` backed by BigQuery:

```bash
# 1. Sign in: a person approves the printed URL.
dct cloud login --start
dct cloud login --wait

# 2. Create the organization.
dct cloud org create Acme --slug acme

# 3. Connect this repository: a person installs the GitHub App and picks it.
dct cloud project connect --org acme --start
dct cloud project connect --wait

# 4. Add a warehouse connection; the key comes from a file, never a flag.
dct cloud connection create --org acme --type bigquery --keyfile key.json \
    --set project=acme-gcp --set dataset=analytics

# 5. Point the boards' source at it (the slug `connection create` printed).
dct cloud source map warehouse acme-gcp --org acme --project analytics

# 6. Publish: pull the repository and render its boards.
dct cloud project sync --org acme --project analytics

# 7. Invite a teammate.
dct cloud member invite alex@acme.com --org acme --role creator

# 8. Confirm the boards are live.
dct cloud boards --org acme --project analytics
```

A few things the sequence relies on:

- **Step 3 needs `--org`.** Connect never falls back to the `dct cloud use`
  default (see [Context resolution](#context-resolution-org-and-project)). A
  public repository can skip the browser entirely:
  `dct cloud project connect --org acme --git-url https://github.com/acme/analytics.git`.
- **The project slug** defaults to the repository name, `analytics` here;
  pass `--slug` to `--start` to choose another.
- **Connection fields depend on the warehouse.** BigQuery needs
  `--set project=...` and `--set dataset=...` beside `--keyfile`; the server
  names any missing field. Password warehouses take `--password-stdin` or
  `--password-env VAR` instead. See [Secrets input](#secrets-input) and
  [Data connections](../cloud/connections.md).
- **Map sources before syncing.** `dct cloud sources` lists the source names
  the project's boards declare. A board synced before its source is mapped
  renders without one.
- **Explicit `--org` and `--project`** keep a script independent of what the
  checkout or the stored default would resolve to. At any point,
  `dct cloud status --org acme` names the next step still missing.
- **Every verb takes `--json`** when a script needs to read the result.

### In CI

A CI job cannot approve a browser login. Store a token as a CI secret and
expose it as `DCT_CLOUD_TOKEN`; every verb reads that variable before the
config file, so the job skips step 1. The token is the one a
`dct cloud login` stored in the config file, and it reaches only the
organizations approved at that login. `dct cloud whoami` confirms which ones
before the job does anything else.

## Command catalog

### Setup

| Command | Purpose |
|---|---|
| [`login`](#dct-cloud-login) / [`logout`](#dct-cloud-logout) / [`whoami`](#dct-cloud-whoami) | Sign in, sign out, or check who you're signed in as |
| [`use`](#dct-cloud-use) | Set the default org (and project) for this machine |
| [`status`](#dct-cloud-status) | What's set up in an org, and what it needs next |
| [`org create`](#dct-cloud-org-create) / [`delete`](#dct-cloud-org-delete) | Create or delete an organization |
| [`project connect`](#dct-cloud-project-connect) / [`sync`](#dct-cloud-project-sync) / [`scaffold`](#dct-cloud-project-scaffold) / [`delete`](#dct-cloud-project-delete) | Connect, sync, scaffold, or delete a project |
| [`connection create`](#dct-cloud-connection-create) / [`test`](#dct-cloud-connection-test) / [`schema-refresh`](#dct-cloud-connection-schema-refresh) / [`delete`](#dct-cloud-connection-delete) | Create, test, refresh, or delete a warehouse connection |
| [`source map`](#dct-cloud-source-map) | Point a board source at a connection |
| [`render`](#dct-cloud-render) | Start renders for boards that have none yet |

### Read-only listing

| Command | Scope | Purpose |
|---|---|---|
| [`orgs`](#read-only-listing-verbs) | — | Organizations you belong to |
| [`members`](#read-only-listing-verbs) | org | The organization's members |
| [`invites`](#read-only-listing-verbs) | org | Pending invitations |
| [`grants`](#read-only-listing-verbs) | org | Live connector grants |
| [`projects`](#read-only-listing-verbs) | org | Projects connected to an organization |
| [`connections`](#read-only-listing-verbs) | org | Warehouse connections available in an organization |
| [`boards`](#read-only-listing-verbs) | project | A project's boards, render state, render time, served commit, and view URLs |
| [`sources`](#read-only-listing-verbs) | project | A project's declared sources and what backs them |

### Membership management

| Command | Purpose |
|---|---|
| [`member invite`](#dct-cloud-member) / [`remove`](#dct-cloud-member) / [`role`](#dct-cloud-member) | Invite, remove, or change the role of a member |
| [`invite revoke`](#dct-cloud-invite) / [`resend`](#dct-cloud-invite) | Revoke or re-send a pending invitation |
| [`grant revoke`](#dct-cloud-grant-revoke) | Revoke a connector grant |

### Access administration

`access`, `public`, `team`, `role`, `identity`, `connection access`, `member show`, and `audit` are documented in [Administer access from the CLI](../cloud/access-from-the-cli.md).

## `dct cloud login`

```bash
dct cloud login [--host HOST] [--no-browser] [--start | --wait]
```

Runs the OAuth device grant against `--host` (default: the configured
host). Opens the approval page in your browser and prints the same
instruction (a URL to open, with a code to enter if the URL doesn't
already carry it), then waits for you to approve. On a machine with no
display (a Linux SSH session, say) it only prints; `--no-browser` forces
that anywhere, and still waits. On success, prints the host and the
organizations the new token can reach; the token itself is never printed.
Running it again re-consents and replaces whatever credential was stored
before. `login` refuses to run while `DCT_CLOUD_TOKEN` is set, since that
token would outrank the one it stores.

| Flag | Description |
|---|---|
| `--no-browser` | Print the approval URL instead of opening it in a browser |
| `--start` | Begin the login, print the approval URL, and exit without waiting for approval |
| `--wait` | Wait for a login begun with `--start` to be approved, then store the token |
| `--host TEXT` | Cloud deployment to talk to [env var: `DCT_CLOUD_HOST`] |
| `--json` | Emit the raw API response as JSON |

```bash
dct cloud login
dct cloud login --host https://selfhosted.example.com
dct cloud login --no-browser
```

### Approving in a separate call

Bare `login` blocks until someone approves in the browser, which can take
longer than the timeout a script or coding agent runs each command under.
Split it into two calls instead:

```bash
URL=$(dct cloud login --start)
echo "Approve this login: $URL"
dct cloud login --wait
```

`--start` begins the grant, prints the approval URL on stdout with nothing
around it, and exits without opening a browser. The pending grant is saved
beside the config file, so `--wait` can pick it up from a separate process.
Hand the URL to whoever approves; `--wait` then blocks until they do, stores
the token, and prints the organizations it reaches, exactly as bare `login`
finishes. Put `--host` on `--start`: `--wait` reads the host from the
pending grant. With `--json`, `--start` emits `host`, `verification_uri`,
`verification_uri_complete`, `user_code`, and `expires_in` instead of the
bare URL.

`--wait` uses up the pending grant whether it succeeds or not. If the
approval was denied or the code expired first (`expires_in` seconds), run
`--start` again. A `--wait` with no pending grant is an error that points
back at `--start`. Pass one of the two flags, never both.

## `dct cloud logout`

```bash
dct cloud logout
```

Revokes the stored token and clears it from the config file. Refuses if
`DCT_CLOUD_TOKEN` is set — that env var is the credential actually in
effect, so unset it to log out.

## `dct cloud whoami`

```bash
dct cloud whoami
```

Prints the host in use, whether the credential came from `DCT_CLOUD_TOKEN`
or the config file, and the organizations (and your role in each) the
credential can reach; the consented-orgs list is the answer to "what can
this token do." Run inside a checkout with a `published_to:` record, it adds
a `PUBLISHED HERE` column marking which of those organizations (and which
project) this checkout is connected to, instead of leaving you to guess
among however many the credential administers. That marking is a display
detail of the human output: `--json` answers the same shape it always has,
the one the HTTP API returns.

## `dct cloud use`

```bash
dct cloud use ORG(/PROJECT)
```

Set the default org (and project) for commands run on this machine. Stored
locally and never checked against Cloud — a slug that doesn't exist fails
loudly on the next verb that uses it.

```bash
dct cloud use acme
dct cloud use acme/analytics
```

## `dct cloud status`

```bash
dct cloud status [OPTIONS]
```

Readiness: what is set up in this org, and what it needs next. This is the
verb the `cloud-setup` skill loops on — read its next-step instruction, run
the verb it names, check status again, repeat until it reports nothing left
to do. It is also the preflight: it works before you sign in and before an
org is chosen, so every prerequisite is readable from one command instead of
discovered by a separate failed command each.

### "This checkout"

Every call, human or `--json`, opens with a "This checkout" section reporting
facts about the directory it ran from. The first five lines are computed
locally, with no network access, so they print the same before, during, or
after signing in:

- `path:` the project root, or that no `dbt_charts.yml` was found and the
  exact file to create.
- `git:` whether this is a checkout at all, the current branch, the origin
  remote, and commits ahead/behind the remote-tracking branch — "as of last
  fetch": this never fetches.
- `git identity:` printed only when `user.email` or `user.name` is unset (the
  first commit would fail).
- `boards:` how many board files the project has (a folder's `meta.yml`
  defaults file is never counted), plus every skipped file and why, when any
  were skipped.
- `sources:` the project's declared sources and their types (never credential
  values) — so you know which warehouse credential setup will need.

A sixth line, `cloud:`, needs the network and so prints once an org has
resolved, right after the local lines and before the stage table: which
org/project this checkout is tied to (`published_to` first, then a
git-remote match), or that nothing ties it to the org being reported.

In human mode every one of these lines prints to stdout; under `--json` all
of them print to stderr, so stdout stays exactly Cloud's `OrgStatus`
response — `dct cloud status --json | jq` always parses.

Before you're signed in, or before an org can be resolved, `status` still
prints the five local lines first, then the usual refusal (`dct cloud
login`, or which org to pass) and exits non-zero — the `cloud:` line and
everything past it needs the network this call never reaches.

### "Human steps ahead"

Before signing in, `status` prints a short list of the human actions that
are locally certain: approving the browser login, and a push when there are
local commits to send (including a branch that has never been pushed at
all). Two more — picking the GitHub repository, and a warehouse connection
— depend on facts only the network can confirm, so before signing in they
print under a separate "Possibly (confirm after signing in)" heading instead
of being asserted alongside the certain ones.

Once signed in, for as long as an org resolves and its stage isn't `done`
(more precisely: as long as there is a `next_step`, which also covers a
`done` stage with a failed or chart-errored board left), the same list
prints as certain fact, derived from server state: picking the GitHub
repository (a fresh org with no project yet, or a checkout this org's
projects don't match — naming `--git-url` for a public repository and the
browser pick otherwise, or stating plainly when the origin isn't on GitHub
at all), a warehouse connection or a source-mapping step (the tied project's
own row says which), or a push. Named once here instead of discovered one
refusal at a time — what a reviewer-gated agent needs to collect consent for
up front. Signed in with no org resolved prints no list at all: nothing
about state exists yet to derive one from.

The stages, in order: `missing_project`, `unsynced`, `untested_connection`,
`unmapped_sources`, `missing_boards`, `unrendered_boards`, `done`. The org
reports the earliest incomplete stage across its projects. A synced project
with no boards on its branch is `missing_boards`, never `done`. Each project
also gets a `boards:` line: total, ready, unrendered, rendering, failed,
errored; `done` points at `dct cloud boards` for the URLs. The `ready` and
`errored` counts print `unknown`, not `0`, against a Cloud deployment older
than the installed `dct`.

`--project` narrows the project rows to one slug — a client-side filter of
the same response, not a different shape; an unknown slug is a clear error
naming the org's real projects.

| Flag | Description |
|---|---|
| `--org TEXT` | Organization slug (default: inferred, then `use`) |
| `--project TEXT` | Narrow the project rows to this slug |
| `--host TEXT` | Cloud deployment to talk to (default: the configured host) [env var: `DCT_CLOUD_HOST`] |
| `--json` | Emit the raw API response as JSON |

## Read-only listing verbs

`orgs`, `members`, `invites`, `grants`, `projects`, `connections`, `boards`,
`sources` all follow the same shape: no arguments, `--host` and `--json` as
above, plus `--org` (and, for the project-scoped ones, `--project`) —
resolved per [Context resolution](#context-resolution-org-and-project) when
omitted. `orgs` takes no `--org`; it lists every organization the token
belongs to.

```bash
dct cloud orgs
dct cloud members --org acme
dct cloud connections --org acme --json
dct cloud boards --org acme --project analytics
dct cloud sources --project analytics
```

`boards` carries the two facts that answer "is my change live":

```text
SLUG            STATUS  RENDERED_AT       COMMIT   URL
exec-overview   ready   2026-09-06 10:50  8a2f27c  https://dbtcharts.com/acme/analytics/d/exec-overview
new-board       not_rendered  -           -        https://dbtcharts.com/acme/analytics/d/new-board
```

`RENDERED_AT` is when the board's latest render finished, in your own
timezone. `COMMIT` is the commit that render read the board from, abbreviated
to seven characters (`--json` carries the full SHA, and `null` for both when
the board has no finished render).

A board you edited is live once *its own* two values move: read the listing
before your push and again after the sync, and each board your commit changed
gets a later `RENDERED_AT` and a different `COMMIT`. A board your commit did
not change normally keeps both, because nothing re-renders content that did
not change, so compare only the boards you touched.

Neither value moving means the re-render has not landed yet, not that the
commit was dropped: a sync queues renders that run behind live page views and
re-run each board's queries. A failed render writes no new complete render,
so the two columns cannot move for one — they only ever prove success, and
`STATUS` is what covers the rest. A `warning` that appeared since your first
reading means the re-render ran and failed, since only a newer failed attempt
puts a board there. A `warning` that was already there is inconclusive: it is
undated, so it may be the old failure or a new one of your commit. An
unchanged `errored` belongs to the render `RENDERED_AT` names, so it is the
previous one's. A board still reading `ready` or `not_rendered` is waiting on
its queued re-render; look again shortly, and run
[`dct cloud project sync`](#dct-cloud-project-sync) if you are unsure a sync
ever ran.

`COMMIT` is a commit in *Cloud's* copy of your repository. For a project only
ever edited through git that is your own commit, so it matches your
`git rev-parse HEAD`; once boards are edited in Cloud too, its work branch
carries those commits and the merge commits each sync creates, so the sha
stops matching your `HEAD` and is Cloud's coordinate rather than yours. Either
way, the sha *changing* is what tells you your content landed.

`STATUS: ready` alone means only that *a* render exists, not that it is a
render of your edit. A board rendered before Cloud began recording commits
shows `-`; those rows are never backfilled with a guess, and the column fills
in the next time the board renders.

### Board render statuses

`boards` reports each board's `render_status`, plus an `error` explaining it
where there is something to explain:

| Status | Meaning |
|---|---|
| `ready` | A render exists and every chart in it came back clean. |
| `errored` | The board rendered, but some charts came back as error cards. `error` carries the first chart diagnostic. |
| `warning` | The last render attempt failed outright. `error` carries that attempt's message. |
| `blocked` | A source this board names maps to a connection that has not passed its last test, so no render of this board can hold real data. `error` names the source and, for a connection your token may list, its slug, whether that connection failed its last test or has never been tested, and the `dct cloud connection test` command to run. It never carries the warehouse driver's own error text: run the named command to see that. A token holding only `dashboards:read` is told which source is blocked and to ask an organization admin, since a connection's slug is a connection fact. |
| `not_rendered` | No render has been started for this board yet. |

`blocked` outranks the render-derived values: a connection that never answered
means the board's contents are not trustworthy no matter what the last render
did, and re-rendering will not change that. The block is per board: a sibling
board over a passing connection, or over a csv/json/parquet file in the repo,
is not blocked and `render` starts it. A board that names no `source:` at all
resolves through the default it inherits, so it is judged against every source
its project maps. Fix the connection first:

```bash
dct cloud connection test prod-dwh
```

## `dct cloud render`

```bash
dct cloud render [OPTIONS]
```

Start renders for the project's boards that have none yet, or all of them. It
reports how many it started and how many are still unrendered. A board over a
connection that has not passed its last test is skipped, and the command prints
which connection to test, so a count of zero is never the whole answer. Boards
over passing connections and repo file sources start regardless.

| Flag | Description |
|---|---|
| `--force` | Re-render every board with fresh query results, including ones that already rendered — the lever for a board that stays errored after its source was mapped or its warehouse fixed. Needs project admin. |
| `--org TEXT` | Organization slug (default: inferred, then `use`) |
| `--project TEXT` | Project slug (default: inferred, then `use`) |
| `--host TEXT` | Cloud deployment to talk to (default: the configured host) [env var: `DCT_CLOUD_HOST`] |
| `--json` | Emit the raw API response as JSON |

## `dct cloud org create`

```bash
dct cloud org create [OPTIONS] {name}
```

Create an organization. You become its admin.

| Argument | Description |
|---|---|
| `NAME` | Display name for the organization |

| Flag | Description |
|---|---|
| `--slug TEXT` | URL slug (default: from the name) |
| `--host TEXT` | Cloud deployment to talk to [env var: `DCT_CLOUD_HOST`] |
| `--json` | Emit the raw API response as JSON |

```bash
dct cloud org create Acme
dct cloud org create Acme --slug acme
```

## `dct cloud org delete`

```bash
dct cloud org delete [OPTIONS]
```

Delete an organization and all its data. Refused while it has projects.

| Flag | Description |
|---|---|
| `--org TEXT` | Organization slug (inferred from this repo, else required; never the `use` default) |
| `--yes` | Skip the confirmation prompt (required, non-interactively) |
| `--host TEXT` | Cloud deployment to talk to [env var: `DCT_CLOUD_HOST`] |
| `--json` | Emit the raw API response as JSON |

Strict org resolution applies (see [Context resolution](#context-resolution-org-and-project));
the resolved coordinate is printed before deleting. Without `--yes`, an
interactive terminal is asked to type it back to confirm; a non-interactive
run is refused outright.

## `dct cloud project connect`

```bash
dct cloud project connect [OPTIONS]
```

Connect a GitHub repository as a project. Two paths:

- `--git-url URL`: fully headless. For a private repository, pass
  `--git-username` and `--git-password` (or set `DCT_GIT_PASSWORD` to keep the
  token out of shell history). The credential needs write access: Cloud pushes
  edits to the `dbt-charts/<project>` branch of the repository.
- Default (no `--git-url`) — prints a URL, waits for you to install the
  GitHub App and pick the repository in the browser, then finishes here.
  This browser pick isn't bypassable: Cloud authorizes it from your own
  GitHub account's list of repositories you administer.

Connect never uses the stored `dct cloud use` default: binding a repository
to an organization is not something to guess from a setting that was never
checked against Cloud. Pass `--org`; it is only optional when this
repository is already connected to exactly one organization (re-connecting,
or a second project from the same repo).

| Flag | Description |
|---|---|
| `--git-url TEXT` | Connect a repository by HTTPS URL, with no browser hop |
| `--git-username TEXT` | Username for a private `--git-url` repo (blank: anonymous) |
| `--git-password TEXT` | Password or token for `--git-username` (blank: none) [env var: `DCT_GIT_PASSWORD`] |
| `--root TEXT` | Folder holding `dbt_project.yml` inside the repo |
| `--trunk TEXT` | Branch Cloud pulls from (default: the repo's) |
| `--name TEXT` | Project name (default: the repo's) |
| `--slug TEXT` | Project slug (default: from the name) |
| `--timeout FLOAT` | Seconds to wait for the browser repo pick (default: `300.0`) |
| `--poll-interval FLOAT` | Seconds between pick checks (default: `3.0`) |
| `--start` | Print the install/pick URL and exit without waiting for the pick |
| `--wait` | Wait for a connect begun with `--start` to finish |
| `--org TEXT` | Organization slug (inferred from this repo, else required; never the `use` default) |
| `--host TEXT` | Cloud deployment to talk to [env var: `DCT_CLOUD_HOST`] |
| `--json` | Emit the raw API response as JSON |

```bash
dct cloud project connect --org acme
dct cloud project connect --git-url https://github.com/acme/analytics.git --org acme
```

### Picking the repository in a separate call

The browser path blocks for up to `--timeout` seconds while someone installs
the GitHub App and picks the repository. A script or agent that cannot wait
that long splits it the same way as [`login`](#approving-in-a-separate-call):

```bash
URL=$(dct cloud project connect --org acme --start)
echo "Install the GitHub App and pick the repository: $URL"
dct cloud project connect --wait
```

`--start` resolves the org, prints the install/pick URL on stdout with
nothing around it, and exits. It saves the pending connect together with any
`--name`, `--slug`, `--trunk`, and `--root` you passed, so give those to
`--start`: `--wait` takes the org, host, and those values from what
`--start` saved. `--wait` polls for the pick for up to `--timeout` seconds,
then creates the project and records `published_to:` just as the blocking
form does. A `--wait` that times out keeps the pending connect, so running it
again resumes the same pick. With `--json`, `--start` emits `org` and `url`.

Neither flag combines with `--git-url`, which has no browser step to split,
and you pass one of the two, never both.

## `dct cloud project sync`

```bash
dct cloud project sync [OPTIONS]
```

Pull the project's repository and refresh its branches, and re-render the
boards the new commits changed.

**A `git push` does not publish; this does.** A push puts your commit on your
git host, and Cloud serves it only after a sync. A GitHub (App or token),
GitLab or Bitbucket project syncs itself within seconds of the push (a
webhook), with a daily reconcile behind it; an Other Git host project has
nothing watching the remote, so its only automatic sync is an hourly sweep.
Running this verb publishes immediately in both cases.

A freshly queued sync hasn't landed yet: the very next `dct cloud status`
still reports `unsynced`, which reads as "this did nothing" if you don't know
to expect the lag. When this call queues a sync, it prints a line saying so —
give it a few seconds and re-run `status`.

The sync runs in the background, so this verb reports what it queued rather
than a finished result. Confirm the landing with
[`dct cloud boards`](#read-only-listing-verbs): each board your commit changed
gets a new `RENDERED_AT` and a new `COMMIT` once its re-render finishes.

| Flag | Description |
|---|---|
| `--org TEXT` | Organization slug (default: inferred, then `use`) |
| `--project TEXT` | Project slug (default: inferred, then `use`) |
| `--host TEXT` | Cloud deployment to talk to [env var: `DCT_CLOUD_HOST`] |
| `--json` | Emit the raw API response as JSON |

## `dct cloud project scaffold`

```bash
dct cloud project scaffold [OPTIONS]
```

Open the `dbt_charts.yml` scaffold PR. GitHub-connected projects only.

| Flag | Description |
|---|---|
| `--org TEXT` | Organization slug (default: inferred, then `use`) |
| `--project TEXT` | Project slug (default: inferred, then `use`) |
| `--host TEXT` | Cloud deployment to talk to [env var: `DCT_CLOUD_HOST`] |
| `--json` | Emit the raw API response as JSON |

## `dct cloud project delete`

```bash
dct cloud project delete [OPTIONS]
```

Delete a project and all its data.

| Flag | Description |
|---|---|
| `--org TEXT` | Organization slug (inferred from this repo, else required; never the `use` default) |
| `--project TEXT` | Project slug (default: inferred, then `use`) |
| `--yes` | Skip the confirmation prompt (required, non-interactively) |
| `--host TEXT` | Cloud deployment to talk to [env var: `DCT_CLOUD_HOST`] |
| `--json` | Emit the raw API response as JSON |

Strict project resolution applies (see [Context resolution](#context-resolution-org-and-project)).

## `dct cloud connection create`

```bash
dct cloud connection create [OPTIONS]
```

Create a connection and test it in one call. Non-secret fields go in
`--set`; which ones a type needs is the server's answer, and it names any
that are missing:

```bash
dct cloud connection create --type bigquery --keyfile key.json \
    --set project=acme-gcp --set dataset=analytics
```

Key material is never a flag value — see [Secrets input](#secrets-input)
above.

Every later verb addresses the connection by its slug, which is the slugified
`--name`. Leave `--name` off and the display name defaults to the field that
names the warehouse — BigQuery's `project`, otherwise the `database` — and a
successful create prints the slug it derived:

```text
Created acme-gcp — connection test passed.
Next: dct cloud source map <source> acme-gcp
```

A test that fails outright saves nothing, so a retry, after you fix whatever the
error names, is the same command; there is no slug left over to collide with, and
no `connection delete` to run first. A test that could not finish in time does
keep the connection. Re-run the check with `dct cloud connection test <slug>`
rather than re-running `connection create`, which would collide with the slug
already taken.

| Flag | Description |
|---|---|
| `--type TEXT` | Warehouse type, such as `bigquery` or `snowflake` (required) |
| `--set KEY=VALUE` | A connection field, repeatable (for example, `--set dataset=analytics`); not `name`, which is `--name`, and not a credential |
| `--keyfile FILE` | File holding the service-account key or private key |
| `--password-stdin` | Read the password from stdin |
| `--password-env VAR` | Env var holding the password |
| `--name TEXT` | Display name; its slug is the connection's id (default: BigQuery's project, otherwise the database) |
| `--org TEXT` | Organization slug (default: inferred, then `use`) |
| `--host TEXT` | Cloud deployment to talk to [env var: `DCT_CLOUD_HOST`] |
| `--json` | Emit the raw API response as JSON |

Per-warehouse field names and security notes: [Data connections](../cloud/connections.md).

## `dct cloud connection test`

```bash
dct cloud connection test [OPTIONS] {connection}
```

Ask Cloud to re-run a connection's credential check.

| Argument | Description |
|---|---|
| `CONNECTION` | Connection slug, as `dct cloud connections` lists it |

| Flag | Description |
|---|---|
| `--org TEXT` | Organization slug (default: inferred, then `use`) |
| `--host TEXT` | Cloud deployment to talk to [env var: `DCT_CLOUD_HOST`] |
| `--json` | Emit the raw API response as JSON |

## `dct cloud connection schema-refresh`

```bash
dct cloud connection schema-refresh [OPTIONS] {connection}
```

Re-run a connection's schema profile.

| Argument | Description |
|---|---|
| `CONNECTION` | Connection slug, as `dct cloud connections` lists it |

| Flag | Description |
|---|---|
| `--org TEXT` | Organization slug (default: inferred, then `use`) |
| `--host TEXT` | Cloud deployment to talk to [env var: `DCT_CLOUD_HOST`] |
| `--json` | Emit the raw API response as JSON |

## `dct cloud connection delete`

```bash
dct cloud connection delete [OPTIONS] {connection}
```

Delete a warehouse connection. Boards that query it start failing.

| Argument | Description |
|---|---|
| `CONNECTION` | Connection slug, as `dct cloud connections` lists it |

| Flag | Description |
|---|---|
| `--yes` | Skip the confirmation prompt (required, non-interactively) |
| `--org TEXT` | Organization slug (inferred from this repo, else required; never the `use` default) |
| `--host TEXT` | Cloud deployment to talk to [env var: `DCT_CLOUD_HOST`] |
| `--json` | Emit the raw API response as JSON |

Strict org resolution applies (see [Context resolution](#context-resolution-org-and-project)).

## `dct cloud source map`

```bash
dct cloud source map [OPTIONS] {source} {connection}
```

Point one declared source at a connection. Omitting `--schema` preserves
whatever override the source already has; `--schema ""` clears it
deliberately.

| Argument | Description |
|---|---|
| `SOURCE` | Source name a board's `source:` uses |
| `CONNECTION` | Connection slug to point it at |

| Flag | Description |
|---|---|
| `--schema TEXT` | Schema this source resolves against |
| `--org TEXT` | Organization slug (default: inferred, then `use`) |
| `--project TEXT` | Project slug (default: inferred, then `use`) |
| `--host TEXT` | Cloud deployment to talk to [env var: `DCT_CLOUD_HOST`] |
| `--json` | Emit the raw API response as JSON |

```bash
dct cloud source map warehouse acme-bigquery --org acme --project analytics
dct cloud source map warehouse acme-bigquery --schema staging
```

## `dct cloud member`

```bash
dct cloud member invite [OPTIONS] {email}
dct cloud member remove [OPTIONS] {email}
dct cloud member role [OPTIONS] {email} {role}
```

| Command | Arguments | Purpose |
|---|---|---|
| `invite` | `EMAIL` | Invite one address to the organization (`--role TEXT` to set the role on acceptance) |
| `remove` | `EMAIL` | Remove a member from the organization |
| `role` | `EMAIL ROLE` | Change a member's role |

Each also takes `--org`, `--host`, and `--json` as above.

```bash
dct cloud member invite alex@acme.com --role admin
dct cloud member role alex@acme.com admin
dct cloud member remove alex@acme.com
```

## `dct cloud invite`

```bash
dct cloud invite revoke [OPTIONS] {email}
dct cloud invite resend [OPTIONS] {email}
```

| Command | Arguments | Purpose |
|---|---|---|
| `revoke` | `EMAIL` | Revoke a pending invitation |
| `resend` | `EMAIL` | Re-send a pending invitation |

Each also takes `--org`, `--host`, and `--json` as above.

## `dct cloud grant revoke`

```bash
dct cloud grant revoke [OPTIONS] {grant_id}
```

Revoke a connector grant. May cut the credential making this call.

| Argument | Description |
|---|---|
| `GRANT_ID` | Grant id, as `dct cloud grants` lists it |

| Flag | Description |
|---|---|
| `--org TEXT` | Organization slug (default: inferred, then `use`) |
| `--host TEXT` | Cloud deployment to talk to [env var: `DCT_CLOUD_HOST`] |
| `--json` | Emit the raw API response as JSON |

## Related

- [Getting Started with Cloud](../cloud/getting-started.md): the guided walkthrough this CLI drives
- [Data connections](../cloud/connections.md): warehouse types, per-field connection details, and security notes
- [Access control](../cloud/access-control.md): org roles referenced by `member role`

# mcp (https://docs.dbtcharts.com/cli/mcp/)

# `dct mcp`

MCP (Model Context Protocol) server commands for AI assistant integration.

For **when to use MCP vs the CLI**, see [CLI and MCP for AI assistants](ai-cli-and-mcp.md). Prefer the CLI when the agent has shell access and `dct` is installed; use MCP when the environment is MCP-only (VS Code/Copilot agent mode, the [dbt Charts Cloud](../cloud/index.md) copilot) or when structured tool calls are already wired up.

```bash
dct mcp [OPTIONS] COMMAND [ARGS]
```

## Subcommands

| Command | Purpose |
|---|---|
| [`dct mcp serve`](#dct-mcp-serve) | Start the MCP server for AI assistant integration. |

## `dct mcp serve`

Starts an MCP server that lets AI assistants like Cursor, Claude Code, Claude Desktop, and ChatGPT interact with your dbt Charts project. The server runs in stdio mode, the standard transport for MCP-compatible tools.

```bash
dct mcp serve [OPTIONS]
```

### Options

| Flag | Description |
|---|---|
| `--project-dir PATH` | dbt Charts or dbt project directory. Default: current directory. |

### Examples

```bash
dct mcp serve
dct mcp serve --project-dir ./my-project
```

### Manual client configuration

In most cases, [`dct init mcp`](init.md) writes the right config for you. For manual setup of Claude Code (`~/.config/claude/config.json`) or Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "dbt-charts": {
      "command": "dct",
      "args": ["mcp", "serve"]
    }
  }
}
```

For a nested project directory:

```json
{
  "mcpServers": {
    "dbt-charts": {
      "command": "dct",
      "args": ["mcp", "serve", "--project-dir", "/absolute/path/to/project"]
    }
  }
}
```

## What the MCP server exposes

CLI verbs wrapped as MCP tools that agents call directly:

**Board authoring**

- `render_board`: compile, validate, and produce SVG / HTML / PNG / PDF
- `describe_board`: describe a dashboard's queries, charts, variables, and layout

**Data discovery**

- `search_boards`: keyword search across board files (an empty query lists them all)
- `docs`: read packaged YAML docs

**Query inspection**

- `execute_query`: run raw SQL (`sql`), or one named query from a board file (`board` + `query`), and return the result as CSV. There is no row-limit argument: the AI writes `LIMIT` and `OFFSET` in the SQL. Results are bounded at about 25,000 tokens; a cut result says so and how to narrow the query

**Agent skills**

- `list_skills`: enumerate packaged agent skill recipes
- `get_skill`: read a specific skill

**Diagnostic code lookup**

- `list_diagnostic_codes`: list every registered error/warning code with a one-line summary, optionally filtered by `level`
- `get_diagnostic_code`: full documentation for one error or warning code

See [`dct skills`](skills.md) for the agent-facing skill catalog that ships alongside.

## Resources

Beyond tools, the MCP server exposes read-only `dct://` resources: content an assistant can fetch by URI without a tool call:

| Resource | Content |
|---|---|
| `dct://boards` | List of all dashboards in the project with metadata |
| `dct://board/{path}` | YAML content and compiled structure of one dashboard |
| `dct://docs/all` | The complete YAML reference; same content as `dct docs all` |
| `dct://docs/reference` | Field-level YAML reference, generated from the compiler's models |
| `dct://docs/error-reference` | Generated reference of every `ERR-*` error code |
| `dct://docs/warning-reference` | Generated reference of every `WARN-*` warning code |
| `dct://docs/{topic}` | One H2 section of the reference (same slugs as `dct docs <topic>`) |
| `dct://guide/board-design` | Design principles for dashboards; chart choice, layout for at-a-glance monitoring |
| `dct://guide/report-design` | Design principles for narrative, data-driven reports |
| `dct://guide/board-build` | Recommended build-test-iterate workflow, caching, and tool usage patterns |
| `dct://guide/board-review` | Structural (YAML + validate) and visual (rendered image) review workflow |

The server runs every query fresh unless `DCT_CACHE_PATH` is set; with it set, query results are cached in that DuckDB file. Unlike `dct render` and `dct serve`, it does not use the per-user cache file by default.

## Related

- [CLI and MCP for AI assistants](ai-cli-and-mcp.md): when to use MCP vs `dct` CLI commands
- [`dct init mcp`](init.md): wire MCP into specific AI clients
- [`dct skills`](skills.md): agent skill catalog

# playground (https://docs.dbtcharts.com/cli/playground/)

# `dct playground`

Open the hosted dbt Charts playground, an interactive YAML editor with live preview, in your browser. Built for fast iteration: edit YAML, see the dashboard render, optionally drive edits with an AI Copilot.

![The playground's toolbar above the YAML editor pane beside a live SVG preview pane, rendering a small seeded example board straight from its source YAML](../assets/screens/cli/playground/playground-layout.png){: width="1400" height="1000" }

```bash
dct playground
```

Opens `https://play.dbtcharts.com` in your default browser and prints the URL, which is useful when a browser can't be opened (for example, over SSH).

The hosted playground is a generic sandbox with the bundled example gallery, not your own project. To render your own boards locally instead, install the standalone `dbt-charts-playground` editor (not yet on public PyPI; ships via the private dbt Charts registry) and run it against your project directory:

```bash
dct-playground --base-dir /path/to/your/project
```

## YAML editor completions

The Playground YAML editor suggests dbt Charts keys, chart types, variable input types, themes, and local query/chart references while you type. Use `Ctrl-Space` on Windows/Linux or `Cmd-Space` on macOS to open completions explicitly.

The editor also supports a VSCode-parity keymap (multi-cursor select-next-occurrence, toggle comment, move line, undo/redo) - see the [Editor Keybindings reference](../reference/editor-keybindings.md).

## Inline validation

The editor validates as you type: an invalid board renders an error card in the preview pane instead of a stale or blank render; one card per error, with a code badge, message, and (where relevant) a hint and a location.

![The preview pane showing the playground's error card, an unknown-field validation error with its code badge and message](../assets/screens/cli/playground/playground-invalid-yaml-error.png){: width="697" height="328" }

## When to use what

| If you want… | Use |
|---|---|
| Live YAML editor + AI Copilot in the browser | `dct playground` |
| Serve boards and inspect templates against a real warehouse | [`dct serve`](serve.md) |
| Static export | [`dct render`](render.md) |

## Related

- [`dct serve`](serve.md)
- [`dct render`](render.md)

# Overview (https://docs.dbtcharts.com/variables/)

# Variables

Variables describe the filters and inputs that live inside the dashboard shell. Each definition renders a labeled control, and the runtime keeps queries and charts in sync when values change. Variables must be explicitly referenced in query filters so behavior stays predictable.

**Variable names must be unique within a file and across all imported files.**

----

## How Variables are Defined

Every entry under `variables` needs a name and a source (column or query). The `input` widget is optional; when omitted, the compiler auto-detects it from the other fields (for example, `options` → `select`, `min`/`max` → `slider`, boolean `default` → `checkbox`). The compiler:

- derives a `title` (label) and `placeholder` from the slugified name unless you override them,
- validates that the chosen `input` matches the source type,
- keeps `default` undefined unless you explicitly set it.

Variables **do not** auto-apply themselves. Wire them in your query `filters` (plain names, Jinja expressions, helper functions) so you stay in control.

`label` is the only variable field that displays; it's the text above the input
control. `notes:` is optional and never appears in the rendered board; it's prose
for AI search, tooling, and the missing-required-variables prompt. The rule
holds everywhere in dbt Charts: if something displays, it has a display name
(`title`, `subtitle`, `label`, `text`); if it doesn't, it's `notes`.

```yaml {contract=board-root}
variables:
  priority:
    column: dundersign.tickets.priority
    input: select

  product_family:
    query: queries.product_family_list
    input: multiselect
```

### Inputs and Type Mapping

The `input` field is optional. When omitted, the compiler auto-detects the widget from the variable's other fields (options → `select`, `min`/`max`/`step` → `slider`, boolean default → `checkbox`, list default → `multiselect`, `hidden` with no other signals → `text`). You can still set `input` explicitly to override auto-detection. The table below captures the available types; `daterange` is the default for date or timestamp sources so you can work with start/end values in expressions.

For a complete reference of all input types and their options, see [UI Elements](ui-elements.md).

| Input | Description | Default Type |
|-------|-------------|--------------|
| `select` | Single-choice dropdown | `string` |
| `multiselect` | Dropdown with multiple choices | `array` / `string[]` |
| `input` / `text` | Free-form text | `string` |
| `textarea` | Multi-line text | `string` |
| `slider` | Numeric slider (`min`, `max`, `step` required) | `number` |
| `datepicker` | Single date picker | `date` (for rare single-date filters) |
| `daterange` | Date range picker | `date` / `timestamp` (preferred default) |
| `checkbox` | Boolean toggle | `boolean` |
| `radio` | Small set of explicit options | `string` |

### Column Binding (most common)

`column` binds a variable to a table column (`<tablename>.<columnname>`). The compiler reads the column’s metadata (type, enums, nullability) to populate options, determine operators, and suggest placeholder text. Column bindings still require explicit wiring inside query `filters`.

```yaml {contract=board-root}
variables:
  priority:
    column: dundersign.tickets.priority
    input: select
```

The table may be qualified when it does not live in the connection's default
schema, `column: gis.fact_sales.property_type`, or
`column: warehouse.gis.fact_sales.property_type`. Everything before the last dot
is the table reference; the last segment is the column.

Add `operator` or `default` only if you need to override the default behavior.
Variables are optional by default; add `required: true` only when the dashboard
cannot render without a value.

`required: true` is a generic render-time contract, not a chart-specific
feature. Any query or chart that depends on that variable will fail to render
until the value is supplied, typically through a URL query parameter or a
variable `default:` in the board YAML.

### Query-Powered Variables

`query` draws variable options from custom SQL. Pass either an existing query name (`query: queries.regions`) or inline SQL. The result must include at least one column for the value; additional `label` or `description` columns improve the UI.

```yaml {contract=board-root}
variables:
  brand:
    query: |
      SELECT brand_id AS value, brand_name AS label
      FROM brands
      ORDER BY brand_name
    input: select
```

### Additional Options

- `default`: initial value before user interaction
- `placeholder`: override the auto-generated hint
- `required`: block rendering until a value is supplied
- `options`: `static` list or `dynamic_query` reference for select/multiselect
- `min`/`max`/`step`: required for sliders
- `operator`: controls how the value becomes a filter expression

When a required variable is missing, dbt Charts returns the normal structured
render error. The fix is to either open the board with the needed query
parameter, or define `default:` for that variable.

## Wiring Variables to Queries

Variables must be referenced explicitly in query `filters` (plain name, Jinja expression, or helper function). The compiler turns those references into SQL filters, and the runtime refetches whenever a referenced variable changes.

When a variable is unset or null, filters should gracefully handle this by returning `1=1` (always true) so no filtering is applied. This is the default behavior when using the `filter()` helper macro.


```yaml {contract=board-fragment}
queries:
  tickets:
    sql: |
      SELECT * FROM dundersign.tickets
      WHERE {{ filter('status', status) }}
        AND {{ filter_date_range('created_at', date_range) }}
    source: my_postgres
```


Or reference a variable directly with no helper, when you don't need null-handling:


```yaml {contract=board-fragment}
queries:
  tickets:
    sql: |
      SELECT * FROM dundersign.tickets
      WHERE status = '{{ status }}'
    source: warehouse
```


For formatting, conditional logic, and helper macros, see [Expressions](expressions.md).

## Reactive Behavior

- Queries refresh when their referenced variables change.
- Charts redraw when their queries finish.
- Debouncing, optimistic loading, and errors are handled automatically.

## Example: Column-bound Filter

By default, variables are unset (null) until a user selects a value. Use the `filter()` macro in SQL queries to handle this gracefully; when the variable is null, it returns `1=1` (no filter applied).


```yaml {contract=board-root}
variables:
  status:
    column: dundersign.tickets.status
    input: select
    # No default - variable starts as null/unset

queries:
  tickets:
    sql: |
      SELECT
        status,
        COUNT(*) as ticket_count
      FROM dundersign.tickets
      WHERE {{ filter('status', status) }}
      GROUP BY status
    source: my_postgres
```


When `status` is null/unset, the filter returns `1=1` and all statuses are shown. When a user selects a status, the filter becomes `status = 'new'` or `status = 'solved'`.

For more examples and details on the `filter()` macro, see [Expressions](expressions.md).

## Interactive Variables

![A variables strip with one control of every documented input type: select, multiselect, text, textarea, number, slider, datepicker, daterange, checkbox, and radio](../assets/screens/variables/ui-elements/variables-strip.png){: width="1074" height="203" }

Every rendered dashboard states its current variable values as ordinary SVG text, and
that is all a standalone artifact carries. Changing a value re-runs the queries behind
it, so the controls themselves are served by a host that can do that: `dct serve` and
dbt Charts Cloud lay them over the dashboard's variables strip.

SVG, HTML, PNG, and PDF therefore share one rendered dashboard. A file you exported
(an `.svg`, `.png`, `.pdf`, or a `dct render` `.html`) shows the filter state it was
rendered with, and never a control that cannot filter.

### How It Works

1. Each variable is drawn into the dashboard as a labeled control showing its
   current value (a dropdown, a field, a checkbox, a slider) in a strip the
   dashboard measures and reserves exactly enough room for
2. On `dct serve` or Cloud, a small runtime binds those controls: menus open,
   values commit, the dashboard re-renders. It adds behavior, not elements;
   the controls are already in the board
3. Everywhere else (a PNG export, a PDF, a plain SVG viewer) the same controls
   render as a picture of the dashboard's filter state
4. Variable values can be used in chart titles, queries, and conditional logic via Jinja templates

### Supported Interactive Input Types

| Input | Interaction | Description |
|-------|-------------|-------------|
| `select` | Dropdown menu | Single-choice selection |
| `text` / `input` | Type in place | Free-form text entry |
| `number` | Type in place | Numeric input with min/max/step |
| `slider` / `range` | Click or arrow keys | Slider with value display |
| `checkbox` | Click or space | Boolean toggle |
| `date` / `datepicker` | Type in place | Date selection |

### Example: Interactive Dashboard


```yaml {contract=board-root}
title: Support Tickets Dashboard

variables:
  status:
    label: Status
    input: select
    options:
      static: [new, solved]
    # No default - starts unset, shows all statuses

  priority:
    label: Priority
    input: select
    options:
      static: [low, normal, high, urgent]
    # No default - starts unset, no priority filter

queries:
  tickets:
    sql: |
      SELECT status, COUNT(*) as ticket_count
      FROM dundersign.tickets
      WHERE {{ filter('status', status) }}
        AND {{ filter('priority', priority) }}
      GROUP BY status
    source: my_postgres

charts:
  tickets_chart:
    title: "Tickets{% if status %} with status {{ status }}{% endif %}"
    type: bar
    query: tickets
    x: status
    y: ticket_count

rows:
  - tickets_chart
```


### Static Options

For interactive-only variables (not bound to a data source), use `options.static`. Note: variables don't need an "All" option; when unset, they simply don't apply any filter.

```yaml {contract=board-root}
variables:
  category:
    input: select
    options:
      static: [Electronics, Accessories, Tools]
    # No default - starts unset, shows all categories

queries:
  products:
    sql: |
      SELECT * FROM products
      WHERE {{ filter('category', category) }}
    source: my_postgres
```

These variables don't need a `column`, `query`, or other source; the options are defined statically in the YAML. When the variable is unset (no selection), the `filter()` macro returns `1=1` and all categories are shown.

### Using Variables in Templates

Variables can be used anywhere Jinja templates are supported:

- **Chart titles**: `title: "Sales for {{ region }}"`
- **Query SQL**: `WHERE region = '{{ region }}'`
- **Conditional rendering**: `visible: show_details`

## Built-in Directory Variables

Four variables are automatically injected into the Jinja render context for every
dashboard, scoped to the board file's own directory. They require no `variables:`
declaration and are always available in `text:` blocks and titles.

These are **author-injected built-ins**, distinct from the declared `variables:`
block covered above. They have no UI control and are computed at render time from
the board's location on disk.

| Name | Type | Description |
|------|------|-------------|
| `this_dir` | object | The directory containing the board file |
| `parent_dir` | object or `None` | The parent directory; `None` at the project root |
| `siblings` | list | Entries in the board's own directory (one level) |
| `tree` | string | Pre-rendered markdown indented listing of the directory |

### Object shapes

**`this_dir` and `parent_dir`** are plain objects with three fields:

| Field | Value |
|-------|-------|
| `name` | Directory name (for example, `reports`) |
| `path` | Path relative to the project root (for example, `charts/reports`) |
| `url` | Serve URL with trailing slash (for example, `/charts/reports/`) |

**`siblings`** is a list; each entry has:

| Field | Value |
|-------|-------|
| `name` | File or directory name (for example, `summary.yml`) |
| `url` | Serve URL (extension stripped for files; trailing slash for directories) |
| `is_dir` | `true` for directories, `false` for files |
| `ext` | File extension (`.yml`, `.yaml`, `.md`) or empty string for directories |
| `label` | Filename stem; use this for display (for example, `summary` for `summary.yml`) |

**`tree`** is a pre-rendered markdown string of the directory tree, depth-bounded to
avoid pathological trees. Drop it directly into a text block or a code fence.

### Example: landing page that lists its siblings

A dashboard at `charts/reports/index.yml` can list its neighbors:

```yaml {contract=board-root}
title: Reports
text: |
  ## {{ this_dir.name }}

  {% for s in siblings %}
  - [{{ s.label }}]({{ s.url }})
  {% endfor %}
```

Or show the full tree:

```yaml {contract=board-root}
title: Reports
text: |
  {{ tree }}
```

Or link to the parent directory:

```yaml {contract=board-root}
text: |
  {% if parent_dir %}
  ← [Back to {{ parent_dir.name }}]({{ parent_dir.url }})
  {% endif %}
```

### Scope and limits

- Variables are scoped to the **board's own directory**; there is no way to point at a
  different directory in v1 (deferred).
- The `label` field uses the **filename stem** only. Reading each sibling's frontmatter
  `title:` is not done at this stage because compiling every sibling is expensive.
- The variable name set is **closed**: `this_dir`, `parent_dir`, `siblings`, `tree`.
  Do not declare `variables:` entries with these names; user-declared variables would
  shadow the built-ins (user wins, per Jinja merge order).

## Advanced Topics

For nested dependencies, conditional filters, and layout orchestration driven by variables, see [Advanced Variables](advanced.md).

## Related

- [UI Elements](ui-elements.md) – Complete reference for all input types and options
- [Expressions](expressions.md) – Formatting, conditional logic, and the `filter()` macro
- [Advanced Variables](advanced.md) – Dependent variables and conditional layouts
- [Queries](../queries.md) – How variables plug into query filters
- [Charts](../charts/index.md) – Interactions that set variables or add filters

# Variable References & Expressions (https://docs.dbtcharts.com/variables/expressions/)

# Variable References & Expressions

Variables are referenced inside your SQL with Jinja expressions: from simple substitution to conditionals, calculations, and the parameterized `filter()` helper.

---

## Simple Variable References

The easiest way to use a variable is directly in your SQL:


```yaml {contract=board-root}
variables:
  priority:
    input: text
queries:
  tickets:
    sql: |
      SELECT status, COUNT(*) AS ticket_count FROM dundersign.tickets
      WHERE priority = '{{ priority }}'
      GROUP BY status
    source: my_postgres
```


When you reference a variable, dbt Charts automatically:
- Uses the variable's current value, bound as a query parameter
- Re-runs the query (and updates its charts) when the variable changes

---

## Jinja Expressions

For more complex cases, the full power of Jinja is available inside the SQL (similar to dbt):


```yaml {contract=board-fragment}
queries:
  tickets:
    sql: |
      SELECT status, COUNT(*) AS ticket_count FROM dundersign.tickets
      WHERE created_at >= '{{ date_range[0] }}'                        -- date_range is a [start, end] list
        AND priority = '{{ priority or "normal" }}'                    -- default value
        AND ticket_type = '{{ "incident" if include_incidents else "task" }}'  -- conditional
      GROUP BY status
    source: my_postgres
```


---

## Filtering with Variables

You can connect dbt Charts [variables](index.md) to your SQL using Jinja's conditional logic, which should be familiar to anyone using dbt. You can utilize the full power of [Jinja2's logic](https://jinja.palletsprojects.com/en/3.1.x/templates/) giving you full control when you need it.

### Simple Variable Replacement

The simplest way to filter is direct substitution:


```yaml {contract=board-fragment}
queries:
  tickets:
    sql: |
      SELECT * FROM dundersign.tickets
      WHERE status = '{{ status }}'
    source: my_postgres
```


Above we use Jinja2 template syntax to insert the `status` variable into the query.  Whenever the variable changes, this query will change and re-run, automatically updating any charts utilizing it.

Variables are referenced directly by name; there's no `variables.` or other namespace prefix.

### Conditional Filtering

Often variables will be unset by default, in which case we don't want to apply a filter the the query.  For instance by default we may want a dashboard to show all regions and have the variable there for users who want to drill down.

To handle unset variables, we can use Jinja `if` blocks. This is the standard way to write dynamic SQL:


```yaml {contract=board-fragment}
queries:
  tickets:
    sql: |
      SELECT * FROM dundersign.tickets
      WHERE 1=1
      {% if status %}
        AND status = '{{ status }}'
      {% endif %}
    source: my_postgres
```


This works but is verbose, especially as you get into complexities of a filter allowing `null` and checking the difference between `undefined` and `null` and `none` values.


- `{% if variable is defined %}` - Check if variable exists
- `{% if variable is not none %}` - Check if variable has a value
- `{{ variable | default('val') }}` - Provide fallbacks


To make this cleaner, we've created a few helper macros that will conditionally apply the filter.

---

## Filter Macros

dbt Charts provides the `filter` macro to simplify this common pattern. It handles the conditional logic, null checking, and syntax for you.

**Security Note:** Filter macros use parameterized queries to prevent SQL injection. Variable values are passed as parameters to the database, never interpolated directly into SQL strings. See [Queries: Parameterized Queries](../queries.md#security-parameterized-queries) for details.

### The `filter` Function

`filter(column: str, value: Any, operator: str = '=', none: str = 'allow') -> str`

The `filter` function generates a parameterized SQL condition when the value is set. When the value is unset (`None`, empty string, or an empty list), it returns `1=1` (no constraint, show all rows) by default, or `1=0` (show nothing) with `none='deny'`.

**Syntax:** ``{{ "{{" }} filter('<column>', <value>, ['<operator>']) {{ "}}" }}``

**Arguments:**
1. `column`: The database column to filter on (validated as an identifier).
2. `value`: The variable or value to test; always bound as a query parameter. A list value automatically becomes an `IN (...)` clause.
3. `operator` (optional, default `=`): The SQL operator (for example, `>=`, `LIKE`). Validated against an allowlist. Can be a variable.
4. `none` (keyword-only, default `'allow'`): What an unset value means: `'allow'` emits `1=1` (unfiltered), `'deny'` emits `1=0` (no rows).

### Examples

**Basic Usage:**


```yaml {contract=board-fragment}
queries:
  tickets:
    sql: |
      SELECT * FROM dundersign.tickets
      WHERE {{ filter('status', status) }}
        AND {{ filter('priority', priority) }}
    source: my_postgres
```


**Dynamic Operator:**

Sometimes you may want to change the operator applied to the filters.  Say for example you have a dashboard with a variable `age`.  You may want to filter the dashboard by all users below that age, or equal to it, or above it.

You can do this simply by making another variable for the operator allowing users to choose between "Greater than", "Less than", or "Equal to" in the UI.


```yaml {contract=board-root}
variables:
  age_op:
    input: text
    default: ">="
  age_val:
    input: number
    default: 21

queries:
  users:
    sql: |
      SELECT * FROM users
      WHERE {{ filter('age', age_val, age_op) }}
    source: my_postgres
```


**Unset Means Nothing, or Everything:**

An unset filter is ambiguous: does no selection mean *show all rows* or *show none*? `filter()` defaults to show-all (`1=1`); pass `none='deny'` when an empty selection should return no rows (for example, permission-style filters):


```yaml {contract=board-fragment}
queries:
  tickets:
    sql: |
      SELECT * FROM dundersign.tickets
      WHERE {{ filter('status', status, none='deny') }}
    source: my_postgres
```


> For dependent inputs, conditional layouts, and other advanced behavior, see [Advanced Variables](advanced.md).

### Supported Operators

The `filter` function validates operators against an allowlist to prevent SQL injection. Supported operators include:

- Comparison: `=`, `!=`, `<>`, `>`, `<`, `>=`, `<=`
- Pattern matching: `LIKE`, `NOT LIKE`, `ILIKE`, `NOT ILIKE`
- Set operations: `IN`, `NOT IN`
- Null checks: `IS`, `IS NOT`
- Range: `BETWEEN`, `NOT BETWEEN`
- PostgreSQL regex: `~`, `~*`, `!~`, `!~*`

Using an unsupported operator will raise an error at query execution time.
The allowlist is what `filter()` accepts, not what every warehouse runs.
`ILIKE` exists on Postgres, Redshift, DuckDB, Snowflake, Databricks and Spark;
the `~` regex operators only on Postgres, Redshift and DuckDB. BigQuery, MySQL,
SQL Server, SQLite and Trino reject `ILIKE`, and every warehouse outside that
Postgres family rejects `~`. On those, write the case-folding in SQL
(`LOWER(name) LIKE LOWER({{ q }})`).

**Date values.** When the value is a calendar date (a `date` or `datepicker`
variable, or a `daterange` endpoint), `filter()` compares the column as a
`DATE` the same way `filter_date_range()` does:
`CAST(created_at AS DATE) >= DATE '2024-01-15'`. A `TIMESTAMP` column then
works on every warehouse, and a row at 13:00 on the chosen day counts as that
day. A list of dates gets the same treatment; a list that mixes dates with
other values is an error. Because the column is wrapped in a cast, a plain
index on it no longer applies, and whether a warehouse still prunes
partitions on the wrapped column is up to that warehouse; compare a `DATE`
column when that cost matters.

**Lists.** A list value takes `IN` (the default) or `NOT IN`; an ordering
operator (`>=`, `<`, ...) with a list is an error rather than a silent `IN`.

### Array Handling

If the variable is an array (for example, from a multiselect input), `filter()` emits an `IN (...)` clause automatically; no operator needed:


```yaml {contract=board-root}
variables:
  statuses:
    default: ["new", "solved"]

queries:
  tickets:
    sql: |
      SELECT * FROM dundersign.tickets
      WHERE {{ filter('status', statuses) }}
    source: my_postgres
```


### Date Range Filtering

Date ranges are another common filter that we've made simpler with the `filter_date_range` function (specialized macro):

`filter_date_range(column: str, value: DateRange) -> str`

The column is compared as a `DATE`, so a `TIMESTAMP` column works without an
author-supplied cast, and BigQuery no longer rejects comparing a `TIMESTAMP`
column against `DATE` bounds directly. The exact SQL is chosen per warehouse
(`CAST(... AS DATE)` on most, `DATE(...)` on SQLite, which has no `DATE`
type). Because the column is truncated to a date, the range is inclusive of
the whole end day: a `TIMESTAMP` at 13:00 on the end date still matches.

Either end may be left open. `["2025-10-01", null]` filters with
`>= '2025-10-01'` and its control reads "From 1 Oct 2025"; `[null, "2026-10-04"]`
filters with `<= '2026-10-04'` and reads "Until 4 Oct 2026". With both ends
open, nothing is filtered.


```yaml {contract=board-root}
variables:
  date_range:
    input: daterange

queries:
  tickets:
    sql: |
      SELECT * FROM dundersign.tickets
      WHERE {{ filter_date_range('created_at', date_range) }}
      -- Generates: WHERE CAST(created_at AS DATE) BETWEEN '2024-01-01' AND '2024-01-31'
    source: my_postgres
```


When a chart's `x` column comes from the column you filter here, the chart's
time axis spans the whole selected range, not just the dates that have rows. See
[Range-pinned axes](../charts/time-axes.md#range-pinned-axes).


### Complete SQL Query Example


```yaml {contract=board-root}
variables:
  priority:
    options:
      static: ["low", "normal", "high", "urgent"]

  date_range:
    input: daterange

queries:
  tickets:
    sql: |
      SELECT
        status,
        priority,
        COUNT(*) as ticket_count
      FROM dundersign.tickets
      WHERE {{ filter('priority', priority) }}
        AND {{ filter_date_range('created_at', date_range) }}
      GROUP BY 1, 2
      ORDER BY ticket_count DESC
      LIMIT 100
    source: my_postgres
```


### Comparison: Before and After

**Before (boilerplate):**


```yaml {contract=board-fragment}
queries:
  tickets:
    sql: |
      SELECT * FROM dundersign.tickets
      WHERE status = 'solved'
        AND (priority = {{ priority }} OR {{ priority }} IS NULL)
        AND (created_at >= {{ date_range[0] }} OR {{ date_range[0] }} IS NULL)
        AND (created_at <= {{ date_range[1] }} OR {{ date_range[1] }} IS NULL)
    source: my_postgres
```


**After (with filter functions):**


```yaml {contract=board-fragment}
queries:
  tickets:
    sql: |
      SELECT * FROM dundersign.tickets
      WHERE status = 'solved'
        AND {{ filter('priority', priority) }}
        AND {{ filter_date_range('created_at', date_range) }}
    source: my_postgres
```


Much cleaner and easier to read!

---

## Expression Patterns

### Date Range Indexing

A `daterange` variable resolves to a plain `[start, end]` list, not an object,
index into it directly (there's no `date_range.start`/`.end`, and no `date`
Jinja filter):


```yaml {contract=board-fragment}
queries:
  tickets:
    sql: |
      SELECT * FROM dundersign.tickets
      WHERE created_at >= '{{ date_range[0] }}'
        AND created_at <= '{{ date_range[1] }}'
    source: my_postgres
```


For the common `BETWEEN` case, prefer the `filter_date_range()` macro (below)
over manual indexing.

### Calculations

Perform calculations on variable values:


```yaml {contract=board-fragment}
queries:
  tickets:
    sql: |
      SELECT * FROM dundersign.tickets
      WHERE due_at >= '{{ date_range[0] }}'  -- start of window
    source: my_postgres
```


### Conditionals

Use conditionals for dynamic logic:


```yaml {contract=board-fragment}
queries:
  tickets:
    sql: |
      SELECT * FROM dundersign.tickets
      WHERE status = '{{ "new" if include_open else "solved" }}'
        AND priority = '{{ priority if priority else "normal" }}'
    source: my_postgres
```


### Null Handling

Handle null or empty values:


```yaml {contract=board-fragment}
queries:
  tickets:
    sql: |
      SELECT * FROM dundersign.tickets
      -- Using filter() (recommended; unset variables handled automatically)
      WHERE {{ filter('priority', priority) }}
      -- Manual defaults (if you need custom logic)
        AND priority = '{{ priority or "normal" }}'
    source: my_postgres
```


**Recommendation:** Use the `filter()` helper instead of manual null handling; it's cleaner and handles edge cases automatically.

---

## Using Variables in Queries

### Filter Conditions

Reference variables in WHERE clauses:


```yaml {contract=board-root}
variables:
  status:
    options:
      static: ["new", "solved"]
  date_range:
    input: daterange
    default: ["2024-01-01", "2024-12-31"]

queries:
  tickets:
    sql: |
      SELECT status, COUNT(*) AS ticket_count FROM dundersign.tickets
      WHERE {{ filter('status', status) }}
        AND {{ filter_date_range('created_at', date_range) }}
      GROUP BY status
    source: my_postgres
```


### Dynamic Values

Use expressions for dynamic values:


```yaml {contract=board-fragment}
queries:
  tickets:
    sql: |
      SELECT * FROM dundersign.tickets
      WHERE created_at >= '{{ date_range[0] }}'
        AND {{ filter('priority', priority) }}
    source: my_postgres
```


---

## Using Variables in Charts

### Interaction Targets

Setting variables from chart clicks is planned but is not part of the authored
chart schema today. Strict chart validation rejects `interactions:` blocks. For
now, use variables in query SQL, and use chart-level `link:` when a
click should navigate to another page.

---

## Variable Reference Syntax

### Simple (Recommended)

- `var_name` - Direct reference
- `"var_name"` - Quoted (if value must be string)

### Jinja (Advanced)

- `{{ var_name }}` - Jinja reference (no namespace prefix, bare name only)

---

## When to Use Jinja

Use Jinja expressions when you need:

- **Default values:** `{{ priority or 'normal' }}`
- **List indexing:** `{{ date_range[0] }}`: a `daterange` variable is a `[start, end]` list
- **Calculations:** ``{{ "{{" }} min_amount * 1.1 {{ "}}" }}``
- **Conditionals:** `{{ 'active' if flag else 'inactive' }}`

For simple cases, direct references are cleaner and easier to read.

---

## Best Practices

### Prefer the Helper Over Hand-Rolled Conditionals

`{{ filter('status', status) }}` handles unset values, lists, and parameter
binding in one call; reach for it before writing `{% if %}` blocks by hand.

### Use Jinja for Complex Logic

Use Jinja when you need:
- Conditional logic
- Calculations
- Formatting
- Default values

### Keep Expressions Simple

Complex expressions can be hard to understand and maintain:


```sql
-- Good: Clear and readable
WHERE priority = '{{ priority if priority else 'normal' }}'

-- Avoid: Too complex
WHERE priority = '{{ priority if priority and priority in ['low', 'normal', 'high', 'urgent'] else 'normal' }}'
```


### Test Expressions

Test your expressions with different variable values to ensure they work correctly.

---

## Related

- [Variables](index.md) – Defining variables
- [UI Elements](ui-elements.md) – All input types and options
- [Advanced Variables](advanced.md) – Dependent variables and conditional layouts
- [Queries](../queries.md) – Using variables in queries
- [Charts](../charts/index.md) – Using variables in charts

# Variable UI Elements (https://docs.dbtcharts.com/variables/ui-elements/)

# Variable UI Elements

Complete reference for all variable input types and their configuration options.

---

## Overview

Each variable can optionally specify an `input` property that determines what UI control is rendered. If not specified, the input type is given a smart default based on the type. You can override the default by explicitly setting `input` to match your intended use case.

![A variables strip with one control of every documented input type: select, multiselect, text, textarea, number, slider, datepicker, daterange, checkbox, and radio](../assets/screens/variables/ui-elements/variables-strip.png){: width="1074" height="203" }

One of every input type below, rendered together in a single variables strip.

---

## Input Types

### `select` - Single Choice Dropdown

Renders a dropdown menu allowing users to select one option from a list.

![The Priority select control and its open option menu, offering an italic All row above low, normal, high, and urgent](../assets/screens/variables/ui-elements/select-open.png){: width="205" height="218" }

**Value shape:** `string`

**Configuration:**

```yaml {contract=board-root}
variables:
  region:
    input: select
    options:
      static: [North, South, East, West]
    # Optional:
    default: North  # Initial selection
    placeholder: "Select a region..."
```

**Options Source:**
- `options.static`: Array of static values, all strings or all numbers
- `options.query`: Reference to a query that returns options
- `column`: Automatically populated from column values

**Value type.** The browser sends a chosen option back as text, and the value
has to reach SQL with the column's type: BigQuery and Trino refuse to compare
an integer column with a string. A numeric `options.static` list types the
value as a number by itself. When the options come from a query, say what
they are with `data_type: number` or `data_type: date` (a date-typed choice
then compares the column as a date, like a `date` input). Without it, a
query-driven option is a string.

```yaml {contract=board-root}
variables:
  year:
    input: select
    options:
      query: years
    data_type: number
```

Select controls render the options you provide. dbt Charts does not add an "All" option to that list automatically. An unset select is already no filter (`filter()` emits `1=1`), so the usual all/no-filter choice is to leave the variable unset. A non-required select's open menu shows an italic clear-selection row above a divider (see the screenshot above) — labeled **All** unless the variable sets a `placeholder:`, in which case that text is used instead. It's a clear-selection affordance, not an authored option; picking it unsets the variable rather than sending a literal "All" value to your query. If you author an explicit option for it, give it the same type as the others: a list mixing numbers and words (`[2023, 2024, All]`) is refused, because the list is what types the value the control sends back.

**Example:**

```yaml {contract=board-root}
variables:
  priority:
    column: dundersign.tickets.priority
    input: select
    # Options auto-populated from column
```

---

### `multiselect` - Multiple Choice Dropdown

Renders a dropdown menu allowing users to select multiple options.

![The Ticket type multiselect control and its open option menu, an italic All row above task, problem, question, and incident, with problem and incident checked](../assets/screens/variables/ui-elements/multiselect-open.png){: width="256" height="218" }

**Value shape:** `array` / `string[]`

**Configuration:**

```yaml {contract=board-root}
variables:
  regions:
    input: multiselect
    options:
      static: [North, South, East, West]
    # Optional:
    default: [North, South]  # Initial selections
```

**Usage in Filters:**

When using `multiselect` variables with the `filter()` macro, use the `IN` operator:


```yaml {contract=board-root}
variables:
  priorities:
    input: multiselect
    options:
      static: [low, normal, high, urgent]
queries:
  tickets:
    sql: |
      SELECT * FROM dundersign.tickets
      WHERE {{ filter('priority', priorities, 'IN') }}
    source: my_postgres
```


---

### `input` / `text` - Text Input

Renders a single-line text input field for free-form text entry.

![The Search text input, showing its placeholder text](../assets/screens/variables/ui-elements/text-widget.png){: width="296" height="75" }

**Value shape:** `string`

**Configuration:**

```yaml {contract=board-root}
variables:
  search_term:
    input: text  # or 'input'
    placeholder: "Enter search term..."
    # Optional:
    default: ""
```

**Example:**

```yaml {contract=board-root}
variables:
  product_name:
    input: text
    placeholder: "Search products..."
```

---

### `textarea` - Multi-line Text Input

Renders a multi-line text area for longer text input.

![The Triage notes control, rendered as a single-line text field showing its placeholder](../assets/screens/variables/ui-elements/textarea-widget.png){: width="406" height="75" }

**Note:** `textarea` currently renders as the same single-line field as
`text`; there is no multi-line box in the variables strip yet.

**Value shape:** `string`

**Configuration:**

```yaml {contract=board-root}
variables:
  notes:
    input: textarea
    placeholder: "Enter notes..."
    # Optional:
    default: ""
```

---

### `number` - Numeric Input

Renders a numeric input field with optional min/max/step constraints.

![The Minimum age (days) number input, showing its default value of 0](../assets/screens/variables/ui-elements/number-widget.png){: width="294" height="75" }

**Value shape:** `number`

**Configuration:**

```yaml {contract=board-root}
variables:
  min_revenue:
    input: number
    # Optional bounds, enforced when a value is committed: one past min or max
    # lands on the bound, and one off the step grid lands on the nearest step.
    min: 0
    max: 1000000
    step: 100
    # Optional hint, shown muted while the field is empty. A default fills the
    # field, so the two are not used together.
    placeholder: "Enter minimum revenue"
```

**Optional Properties:**
- `min`: Minimum allowed value
- `max`: Maximum allowed value
- `step`: Increment/decrement step size
- `placeholder`: Hint shown while the field is empty
- `default`: Value the field starts with

---

### `slider` - Numeric Slider

Renders a range slider for selecting numeric values within a range.

![The Rows to show slider, thumb positioned at its default value of 15](../assets/screens/variables/ui-elements/slider-widget.png){: width="329" height="51" }

**Value shape:** `number`

**Configuration:**

```yaml {contract=board-root}
variables:
  top_n:
    input: slider
    min: 1
    max: 100
    step: 1
    # Optional:
    default: 10
    label: "Top N Results"
```

**Required Properties:**
- `min`: Minimum slider value
- `max`: Maximum slider value
- `step`: Slider step size

**Example:**

```yaml {contract=board-root}
variables:
  limit:
    input: slider
    min: 5
    max: 50
    step: 5
    default: 15
```

---

### `datepicker` - Single Date Picker

Renders a date picker for selecting a single date.

![The Start date datepicker field, showing 1 Jan 2026](../assets/screens/variables/ui-elements/datepicker-widget.png){: width="232" height="75" }

**Value shape:** `date`

**Configuration:**

```yaml {contract=board-root}
variables:
  start_date:
    input: datepicker
    # Optional:
    default: "2024-01-01"
```

**Usage:**


```yaml {contract=board-fragment}
queries:
  sales:
    sql: |
      SELECT * FROM dundersign.tickets
      WHERE {{ filter('created_at', start_date, '>=') }}
    source: my_postgres
```


---

### `daterange` - Date Range Picker

Renders a date range picker for selecting start and end dates.

![The Date range field, showing 1 Jan to 1 Aug 2026](../assets/screens/variables/ui-elements/daterange-widget.png){: width="368" height="75" }

**Value shape:** `date` (returns object with `start` and `end` properties)

**Configuration:**

```yaml {contract=board-root}
variables:
  date_range:
    input: daterange
    # Optional:
    default: ["2024-01-01", "2024-12-31"]
```

**Usage:**

Use the `filter_date_range()` macro for date ranges:


```yaml {contract=board-fragment}
queries:
  sales:
    sql: |
      SELECT * FROM dundersign.tickets
      WHERE {{ filter_date_range('created_at', date_range) }}
    source: my_postgres
```


Or access start/end directly:


```yaml {contract=board-fragment}
queries:
  sales:
    sql: |
      SELECT * FROM dundersign.tickets
      WHERE created_at >= '{{ date_range[0] }}'
        AND created_at <= '{{ date_range[1] }}'
    source: my_postgres
```


---

### `checkbox` - Boolean Toggle

Renders a checkbox for boolean true/false values.

![The Show ticket list checkbox, checked](../assets/screens/variables/ui-elements/checkbox-widget.png){: width="172" height="54" }

**Value shape:** `boolean`

**Configuration:**

```yaml {contract=board-root}
variables:
  show_details:
    input: checkbox
    # Optional:
    default: false
    label: "Show Details"
```

**Usage:**

Commonly used for conditional rendering:

```yaml {contract=board-fragment}
rows:
  - visible: show_details
    rows:
      - detail_chart
    # Chart only shown when checkbox is checked
```

---

### `radio` - Radio Button Group

Renders a group of radio buttons for selecting one option from a small set.

![The View control, rendered as a dropdown showing Summary selected](../assets/screens/variables/ui-elements/radio-widget.png){: width="191" height="75" }

**Note:** `radio` currently renders as the same dropdown as `select`; there
is no dedicated radio-button widget in the variables strip yet.

**Value shape:** `string`

**Configuration:**

```yaml {contract=board-root}
variables:
  view_type:
    input: radio
    options:
      static: [Summary, Detailed, Compact]
    # Optional:
    default: Summary
```

**Best For:**
- Small sets of options (2-5 choices)
- When you want all options visible at once
- When the selection affects layout or display mode

---

## Common Properties

All input types support these optional properties:

### `label`

Override the auto-generated label (defaults to variable name):

```yaml {contract=board-root}
variables:
  region:
    label: "Select Region"
    input: select
```

### `placeholder`

Set placeholder text for text inputs:

```yaml {contract=board-root}
variables:
  search:
    input: text
    placeholder: "Search products..."
```

### `default`

Set the initial value before user interaction:

```yaml {contract=board-root}
variables:
  region:
    input: select
    options:
      static: [North, South, East, West]
    default: North
```

**Note:** If no `default` is set, the variable starts as `null`/`undefined`. When used with the `filter()` macro, unset returns `1=1` (no filter applied). A non-required select like this one can always get back to that unset state via its menu's clear-selection row (see [`select` - Single Choice Dropdown](#select-single-choice-dropdown)), without needing an authored option for it.

### `required`

Block rendering until the variable has a value:

```yaml {contract=board-root}
variables:
  region:
    input: select
    required: true
    options:
      static: [North, South, East, West]
```

---

## Input Type Selection Guide

| Use Case | Recommended Input |
|----------|------------------|
| Single selection from many options | `select` |
| Multiple selections | `multiselect` |
| Free-form text search | `text` / `input` |
| Long text input | `textarea` |
| Numeric value with constraints | `number` |
| Numeric value in a range | `slider` |
| Single date selection | `datepicker` |
| Date range selection | `daterange` |
| Boolean toggle | `checkbox` |
| Small set of mutually exclusive options | `radio` |

---

## Related

- [Variables](index.md) – Basic variable setup and wiring
- [Expressions](expressions.md) – Using variables in queries and filters
- [Advanced Variables](advanced.md) – Dependent variables and conditional logic

# Advanced Variables (https://docs.dbtcharts.com/variables/advanced/)

# Advanced Variables

When your dashboard needs dynamic behavior beyond simple filters, this advanced variables guide shows how to:

- wire dependent variables (country → state, metric selectors, etc.),
- conditionally emit filters using helper macros,
- show or hide charts/boards based on the current values.

----

## Dependent Variables

Dependent filters arise whenever one variable drives another (pick a country, then the state dropdown updates). To keep the UI and SQL in sync:

1. Source the dependent dropdown from a query that references the parent variable.
2. Guard the filtering logic with the `filter` macro so the dependent filter only applies when both variables have values.


```yaml {contract=board-root}
variables:
  country:
    column: locations.country
    input: select

  state:
    query: |
      SELECT DISTINCT state
      FROM locations
      WHERE {{ filter('country', country) }}
      ORDER BY state
    input: select

queries:
  customers:
    sql: |
      SELECT *
      FROM customers
      WHERE {{ filter('country_name', country) }}
        AND {{ filter('state_name', state if country else None) }}
    source: my_postgres
```


The `state` list refreshes whenever `country` changes, and its filter only runs when both `country` and `state` are defined. This keeps the dropdown options clean and the SQL lean.

## Conditional Filters

Use the `filter` macro (and `filter_date_range` for ranges) to keep your SQL compact while still handling `undefined` or `null` gracefully. You can rely on the default behavior (`value` is defined), or pass an explicit `condition` to control when the filter fires.


```yaml {contract=board-fragment}
queries:
  sales:
    sql: |
      SELECT *
      FROM revenue
      WHERE {{ filter('region', region) }}
        AND {{ filter_date_range('order_date', date_range) }}
        AND {{ filter('total_revenue', min_revenue, '>=') }}
    source: my_postgres
```


If you need customized fallback values or formatting, use Jinja inside the arguments (for example, `region or 'North'`).

## Layout Visibility (`visible`)

Variables can drive which charts or boards appear on the dashboard. Layout items and charts support a `visible` field that controls whether the item is rendered.

> **Note:** `variables.visible` is a separate, unrelated field that controls whether a variable's input control appears in the UI. `visible` on a layout item or chart controls whether that item is included in the rendered output.

The `visible` field accepts:

- A **variable name** (bare string): item is shown when the variable is truthy
- A **Jinja boolean expression**: no `{{ }}` braces required
- A **`{query, column}` probe**: executes a named query and reads a single boolean cell
- `true` / `false`: static visibility

If `visible` is omitted, the item is always shown.

### Conditionally Showing a Row

Use a checkbox variable to toggle a section:

```yaml {contract=board-fragment}
variables:
  show_details:
    input: checkbox
    default: false

rows:
  - summary_kpis

  - visible: show_details
    rows:
      - region_map
      - region_table
```

### Conditionally Showing a Chart

Use a nested-board wrapper with `visible` to show/hide a chart:

```yaml {contract=board-fragment}
variables:
  show_forecast:
    input: checkbox
    default: false

rows:
  - trend_line
  - visible: show_forecast
    rows:
      - forecast_line
```

### Swapping Content

List both items with mutually exclusive expressions:

```yaml {contract=board-root}
variables:
  mood:
    input: select
    options:
      static: [happy, sad]
    default: happy

rows:
  - visible: "mood == 'happy'"
    style:
      background: "#FFF9C4"
    text: |
      # :smile:
      Everything is awesome!

  - visible: "mood == 'sad'"
    style:
      background: "#37474F"
      font:
        color: white
    text: |
      # :cry:
      Everything is terrible.
```

### Query-Backed Visibility

Execute a named query and read a single boolean cell:

```yaml {contract=board-fragment}
queries:
  layout_flags:
    sql: "SELECT {{ has_schema }} AS show_warm"

rows:
  - visible:
      query: layout_flags
      column: show_warm
    rows:
      - column_inventory
```

The query must return **exactly one row** and the named column must hold a boolean-coercible value. Multiple rows raise a `ValueError`.

This approach keeps your layout definitions declarative and easy to read.

## See Also

- [Variables](index.md) – Basic variable setup and wiring
- [UI Elements](ui-elements.md) – All input types and options
- [Expressions](expressions.md) – How to reference variables inside SQL and filters

# Themes (https://docs.dbtcharts.com/themes/)

# Themes

A theme is the visual identity of a board: its typography, its canvas, its
palette, and how every axis, rule, and table row is painted. You pick one with
a single line at the top of the board file, and every chart on the board
inherits it.

```yaml {contract=board-fragment}
title: "Sales Dashboard"
theme: neon

rows:
  - revenue_chart
```

Five themes ship with dbt Charts. Everything below the theme line stays the
same, so switching one is a one-word edit.

---

## The five built-in themes

The same board, rendered five times. Only the `theme:` line differs.

=== "clarity"

    Serif headings on white. The default, and the one to start from.

    ```dbt-charts-example {format=render-only}
    title: "Northwind Coffee, Q3"
    theme: clarity

    queries:
      totals:
        columns: [revenue, orders]
        values:
          - [1284500, 8420]
      monthly:
        columns: [month, channel, revenue]
        values:
          - [Jul, Wholesale, 214000]
          - [Aug, Wholesale, 231500]
          - [Sep, Wholesale, 248900]
          - [Jul, Retail, 138400]
          - [Aug, Retail, 151200]
          - [Sep, Retail, 166300]
          - [Jul, Subscription, 41800]
          - [Aug, Subscription, 49600]
          - [Sep, Subscription, 58800]

    charts:
      revenue:
        query: totals
        type: kpi
        label: Revenue
        value: revenue
        style:
          value:
            format: currency_whole
      orders:
        query: totals
        type: kpi
        label: Orders
        value: orders
        style:
          value:
            format: integer
      trend:
        query: monthly
        type: line
        title: Revenue by channel
        x: month
        y: revenue
        color: channel
        style:
          axis_y:
            labels:
              format: currency_whole

    rows:
      - cols:
          - revenue
          - orders
      - trend
    ```

=== "paper"

    Clarity's typography on a warm cream canvas, with matching gridlines and rules.

    ```dbt-charts-example {format=render-only}
    title: "Northwind Coffee, Q3"
    theme: paper

    queries:
      totals:
        columns: [revenue, orders]
        values:
          - [1284500, 8420]
      monthly:
        columns: [month, channel, revenue]
        values:
          - [Jul, Wholesale, 214000]
          - [Aug, Wholesale, 231500]
          - [Sep, Wholesale, 248900]
          - [Jul, Retail, 138400]
          - [Aug, Retail, 151200]
          - [Sep, Retail, 166300]
          - [Jul, Subscription, 41800]
          - [Aug, Subscription, 49600]
          - [Sep, Subscription, 58800]

    charts:
      revenue:
        query: totals
        type: kpi
        label: Revenue
        value: revenue
        style:
          value:
            format: currency_whole
      orders:
        query: totals
        type: kpi
        label: Orders
        value: orders
        style:
          value:
            format: integer
      trend:
        query: monthly
        type: line
        title: Revenue by channel
        x: month
        y: revenue
        color: channel
        style:
          axis_y:
            labels:
              format: currency_whole

    rows:
      - cols:
          - revenue
          - orders
      - trend
    ```

=== "vivid"

    A crafted sans and a saturated palette. Loud, systematic, high contrast.

    ```dbt-charts-example {format=render-only}
    title: "Northwind Coffee, Q3"
    theme: vivid

    queries:
      totals:
        columns: [revenue, orders]
        values:
          - [1284500, 8420]
      monthly:
        columns: [month, channel, revenue]
        values:
          - [Jul, Wholesale, 214000]
          - [Aug, Wholesale, 231500]
          - [Sep, Wholesale, 248900]
          - [Jul, Retail, 138400]
          - [Aug, Retail, 151200]
          - [Sep, Retail, 166300]
          - [Jul, Subscription, 41800]
          - [Aug, Subscription, 49600]
          - [Sep, Subscription, 58800]

    charts:
      revenue:
        query: totals
        type: kpi
        label: Revenue
        value: revenue
        style:
          value:
            format: currency_whole
      orders:
        query: totals
        type: kpi
        label: Orders
        value: orders
        style:
          value:
            format: integer
      trend:
        query: monthly
        type: line
        title: Revenue by channel
        x: month
        y: revenue
        color: channel
        style:
          axis_y:
            labels:
              format: currency_whole

    rows:
      - cols:
          - revenue
          - orders
      - trend
    ```

=== "neon"

    The dark theme. Near-black canvas, bright marks, inverted scaffold.

    ```dbt-charts-example {format=render-only}
    title: "Northwind Coffee, Q3"
    theme: neon

    queries:
      totals:
        columns: [revenue, orders]
        values:
          - [1284500, 8420]
      monthly:
        columns: [month, channel, revenue]
        values:
          - [Jul, Wholesale, 214000]
          - [Aug, Wholesale, 231500]
          - [Sep, Wholesale, 248900]
          - [Jul, Retail, 138400]
          - [Aug, Retail, 151200]
          - [Sep, Retail, 166300]
          - [Jul, Subscription, 41800]
          - [Aug, Subscription, 49600]
          - [Sep, Subscription, 58800]

    charts:
      revenue:
        query: totals
        type: kpi
        label: Revenue
        value: revenue
        style:
          value:
            format: currency_whole
      orders:
        query: totals
        type: kpi
        label: Orders
        value: orders
        style:
          value:
            format: integer
      trend:
        query: monthly
        type: line
        title: Revenue by channel
        x: month
        y: revenue
        color: channel
        style:
          axis_y:
            labels:
              format: currency_whole

    rows:
      - cols:
          - revenue
          - orders
      - trend
    ```

=== "stark"

    Bare chrome: plain sans, a boxed plot frame, black rules. It is the
    structural root every other built-in theme extends, and it carries the same
    series palette as `vivid`; what it strips is the scaffold, not the color.

    ```dbt-charts-example {format=render-only}
    title: "Northwind Coffee, Q3"
    theme: stark

    queries:
      totals:
        columns: [revenue, orders]
        values:
          - [1284500, 8420]
      monthly:
        columns: [month, channel, revenue]
        values:
          - [Jul, Wholesale, 214000]
          - [Aug, Wholesale, 231500]
          - [Sep, Wholesale, 248900]
          - [Jul, Retail, 138400]
          - [Aug, Retail, 151200]
          - [Sep, Retail, 166300]
          - [Jul, Subscription, 41800]
          - [Aug, Subscription, 49600]
          - [Sep, Subscription, 58800]

    charts:
      revenue:
        query: totals
        type: kpi
        label: Revenue
        value: revenue
        style:
          value:
            format: currency_whole
      orders:
        query: totals
        type: kpi
        label: Orders
        value: orders
        style:
          value:
            format: integer
      trend:
        query: monthly
        type: line
        title: Revenue by channel
        x: month
        y: revenue
        color: channel
        style:
          axis_y:
            labels:
              format: currency_whole

    rows:
      - cols:
          - revenue
          - orders
      - trend
    ```

| Theme | Voice | Canvas |
|-------|-------|--------|
| `clarity` | Serif typography, gray scaffold. The default. | White |
| `paper` | Clarity on a warm cream background. | Cream |
| `vivid` | Crafted sans, loud and systematic. | White |
| `neon` | Crafted sans, dark. | `#161616` |
| `stark` | Bare chrome, structural. Every other theme extends it. | White |

Those five names are the entire set. A typo, or an invented combination like
`clarity-paper`, is rejected at compile time rather than quietly falling back
to the default:

```yaml {contract=board-fragment expect=error code=ERR-UNKNOWN-THEME}
title: "Quarterly Report"
theme: clarity-paper

rows:
  - revenue_chart
```

```text
ERR-UNKNOWN-THEME  Unknown theme 'clarity-paper'. Available built-in themes:
clarity, neon, paper, stark, vivid.
Hint: Did you mean 'clarity'?
```

Saved inside a project, the same board reports `ERR-EXTENDS-UNRESOLVED`
instead: there, `extends:` can also name a board at the project root, so the
compiler tried that too and offers it as a fix.

---

## What a theme owns

dbt Charts splits visual decisions two ways, and the split is what keeps
themes swappable:

- **Theme** answers *how the scaffold is painted*: named fonts, colors,
  surfaces, palette choices, stroke and fill, mark widths.
- **Chart** answers *what this chart means*: its query, its type, and the
  columns bound to each channel.

A theme sets type through the seven named fonts in `style.fonts` (see
[Typography](styling.md#typography)). The serif voice of `clarity` is set on
`fonts.heading.family` and `fonts.body.family` alone, and every slot bound to
those fonts follows.

So a theme is the default owner of properties like `style.background`,
`style.charts.color.gradient.palette`, the visual `mark.*` leaves (color, fill,
stroke, opacity, stroke width), and the spark and `spark_bar` paint surfaces.
Concretely, changing a theme restyles:

- the board background and every card surface
- chart marks: bars, lines, areas, points
- axis grid lines, labels, and titles
- table headers, borders, and row stripes
- variable inputs: backgrounds, borders, labels
- title and body text color

For the full board-level `style:` inventory, see [Styling](styling.md).

---

## Custom themes

A custom theme is not a new file format and not a fork of a built-in. It is an
ordinary board file that `extends:` a theme and overrides only the keys you
name. Everything you do not name is inherited.

### Extending is a deep merge

`extends:` deep-merges the boards you list, in order, with later entries
winning. Because the merge is deep, naming
`style.charts.color.categorical.palette` replaces exactly that leaf; the rest
of the theme's chart styling is untouched.

Here is `clarity` wearing one company's brand: a canvas, an accent, and a
palette. Everything else, the serif headings, the axis treatment, the type
scale, the spacing, is still `clarity`:

```dbt-charts-example
title: "Northwind Coffee, Q3"

extends: clarity

style:
  background: "#fbf7f0"
  accent: "#a1421f"
  charts:
    color:
      categorical:
        palette: category-6-tonal-orange
        single_series_palette: category-6-tonal-orange

queries:
  monthly:
    columns: [month, channel, revenue]
    values:
      - [Jul, Wholesale, 214000]
      - [Aug, Wholesale, 231500]
      - [Sep, Wholesale, 248900]
      - [Jul, Retail, 138400]
      - [Aug, Retail, 151200]
      - [Sep, Retail, 166300]
      - [Jul, Subscription, 41800]
      - [Aug, Subscription, 49600]
      - [Sep, Subscription, 58800]

charts:
  trend:
    query: monthly
    type: line
    title: Revenue by channel
    x: month
    y: revenue
    color: channel
    style:
      axis_y:
        labels:
          format: currency_whole

rows:
  - trend
```

One thing worth noticing: a theme's surfaces are chosen together. Move the
canvas to a warm cream and the cool-gray table stripe inherited from `clarity`
will read as a cast against it, so name that too:

```yaml {contract=board-root}
style:
  charts:
    table:
      row:
        stripe:
          color: "#f4ece0"
```

### Lifting it into a shared file

Once more than one board wants that look, move the `style:` block into its own
board file under `charts/`. Prefix the filename with an underscore to mark it
as a non-listable building block: it will not appear in board listings, but
other boards can extend it.

```yaml {contract=board-root}
# charts/_northwind-brand.yml
extends: clarity

style:
  background: "#fbf7f0"
  accent: "#a1421f"
  charts:
    color:
      categorical:
        palette: category-6-tonal-orange
        single_series_palette: category-6-tonal-orange

rows: []
```

Then point boards at it. For the whole project at once, put it in
`charts/meta.yml`, which cascades to every board beneath it:

```yaml {contract=board-root}
# charts/meta.yml
extends: ./_northwind-brand.yml
```

Or on one board:

```yaml {contract=board-root}
# charts/my-dashboard.yaml
extends: ./_northwind-brand.yml
```

The layer already names its base theme (`extends: clarity` above), so a board
never lists the theme beside it. A board's own `extends:` merges over the
project's, key by key, which is how a dark variant becomes one line on the
boards that want it. In dbt Charts Cloud, the Design panel's Theme select and Project
Settings offer these layers by title, beside the built-ins.

### Two rules that bite

**Reach for a path ref.** An entry with no `/` and no `.yaml`/`.yml` extension
is read as a built-in theme name first, and otherwise as a board at your
*project root*, not under `charts/`. So `extends: _northwind-brand` will not
find `charts/_northwind-brand.yml`; `extends: ./_northwind-brand.yml` will.

**A list composes, and later entries win.** `extends:` also takes a list, for
stacking one layer on another: a layout template under a brand layer, say.
Later entries win the style merge, and the last recognized theme name anywhere
in the chain sets the palette and paint defaults. A theme name has no place in
that list when a layer already extends it.

The Playground gallery's `composition/_report-base.yml` is a template any
board can `extends:` to inherit its theme and card spacing.

### Overriding one board, or one chart

You do not need a custom theme to change one thing once. A board's own
`style:` block cascades on top of whatever theme is active, and a chart's
`style:` cascades on top of the board's:

```yaml {contract=board-fragment}
theme: paper

style:
  background: "#ffffff"

charts:
  revenue_chart:
    query: monthly
    type: line
    x: month
    y: revenue
    style:
      color:
        static: "#a1421f"
```

Chart styles are sparse overlays: an omitted field inherits the nearest theme
or board value, and an explicit `null` clears a nullable one. This includes
partial `style.charts.<family>.marks.bar.border` and
`style.charts.pie.marks.slice.labels` blocks.

Chart titles cascade through their own tier between the board heading and a
chart's own override: `style.title` (the board heading) < `style.charts.title`
(every chart's title) < `style.charts.<family>.title` (one chart type) < a
chart's own `style.title`. See
[Styling every chart's title](styling.md#styling-every-charts-title).

---

## Where to go next

- [Styling](styling.md) for the full `style:` inventory, format aliases, text
  and border styling, and per-chart overrides.
- [Palettes](guides/palettes.md) for the shipped palette catalog with visible
  swatches, and how categorical, sequential, and diverging families differ.
- [Tonal Foundations](guides/tonal-foundations.md) for the design reasoning
  behind the neutral scaffold colors.

# Styling (https://docs.dbtcharts.com/styling/)

# Styling

Control the visual appearance of your dashboard globally or per-chart.

For the implementation-backed inventory of single-chart properties, see the [YAML Schema Reference](reference/yaml-reference.md). This page explains how that chart property surface relates to reusable themes and style presets.

For the current design-direction note behind dbt Charts's neutral frame colors, including why the product is exploring near-black ink and an off-white app canvas, see [Tonal Foundations](guides/tonal-foundations.md).

For the dbt Charts-specific chart palette direction, including the full catalog of shipped palettes with visible swatch previews, see [Palettes](guides/palettes.md).

---

## Themes

A theme paints the whole board: typography, canvas, palette, and every axis,
rule, and table row. Five ship with dbt Charts, you select one with a single
line, and you build a custom one by extending it.

```yaml {contract=board-fragment}
title: "Sales Dashboard"
theme: neon

rows:
  - revenue_chart
```

See [Themes](themes.md) for all five side by side, what a theme owns versus
what a style preset or a chart owns, and how to build a custom theme. This page
covers the `style:` surface a theme paints, and the per-board and per-chart
overrides that cascade on top of it.

---

## Title and header overflow

Title overflow is a style-owned scaffold behavior. Use `style.title.overflow`
to choose between `clip`, `truncate`, `wrap-two`, and `wrap`. The default is
`wrap-two`. `clip` hard-cuts text, `truncate` adds an ellipsis, `wrap-two`
wraps to two lines and ellipsizes the second line when needed, and `wrap`
fully wraps. The same setting applies to Vega-Lite and table chart titles.
A KPI has no title: `style.label.overflow` sets its label's mode, and defaults
to the chart title's.

For tables, header labels wrap to two lines by default (the theme's
`charts.table.header.overflow`); they do not follow the chart title's overflow
mode. Override that with `style.header_overflow` for the whole table or
`style.columns[].header_overflow` for a specific column.

### Styling every chart's title

`style.title` styles the board's own heading (and, by default, feeds every
chart title too). Use `style.charts.title` to style chart titles specifically,
apart from the board heading:

```yaml {contract=board-root}
style:
  title:
    font:
      color: "#111111"   # Board heading, and chart titles unless charts.title sets color
  charts:
    title:
      font:
        color: "#4b5563"   # Every chart's own title
```

Any field you don't set under `style.charts.title` falls back to `style.title`,
which falls back to the theme: you never need to repeat the full set of title
fields (font, sizes, position, overflow, and so on) to override just one.
Precedence, low to high: `style.title` < `style.charts.title` <
`style.charts.<family>.title` < a chart's own `style.title` (set on that one
chart).

---

## Global Styling

Set styling options for the entire dashboard using `style:` at the board root. The most commonly authored board-level style keys are:

```yaml {contract=board-root}
style:
  background: "#f5f5f5"    # Working-surface background color
  font:
    family: "Inter"        # Font family name
    emoji: monochrome      # Emoji rendering mode
  formats:
    revenue: "$,.0f"       # Custom project-specific format alias
  charts:
    axis:
      grid:
        visible: true      # Chart-level axis grid default
```

For the full inventory of board-level `style:` keys, see the [YAML Schema Reference](reference/yaml-reference.md). The top-level `style:` block is typed as `StylePatch`; all fields are optional, and they cascade on top of the selected theme. Commonly used top-level keys include `background`, `font`, `formats`, `palettes`, `roles`, `charts`, `layout`, `variables`, `frame`, `title`, `text`, `border`, `accent`, and `muted`.

Properties like `palette`, `axis`, `legend`, `backgrounds`, and `css` (which appeared in older examples) are **not** valid at the board `style:` root.

### Style Options

- `background`: Working-surface background color (hex, rgb, name, or "transparent")
- `font.family`: Font family name
- `font.emoji`: Emoji rendering mode (`monochrome`, `system-default`, `disabled`)
- `formats`: Format alias map (see [Format names and aliases](#format-names-and-aliases))
- `charts.*`: Chart-type style tree: grid, legends, palettes per chart (see [Chart-Level Styling](#chart-level-styling))

`palettes:` (role name → palette file name, for example, `category: editorial-10`) is authorable at the board level (not on chart-local `style:`, which rejects it) and still rebinds single-color role tokens (`category[2]`, `chrome.ink`) wherever one is authored: a board's `palettes:` merges into the cascade that those tokens resolve against.

That token rebinding is a separate mechanism from palette **roles** (`palette: category` instead of `palette: editorial-10`), which are a built-in-theme-authoring feature only. Substituting a role for the palette file it names happens once, while one of the shipped themes (`clarity`, `neon`, `paper`, `stark`, `vivid`) loads. A board's own `palettes:` does not extend that substitution to the board's `palette:`/`single_series_palette:`/gradient `palette:` fields; nor does a chart's, nor a [custom theme](themes.md#custom-themes) board's. Outside a built-in theme's own YAML, those fields must always name a shipped palette (see [Color Palettes](#color-palettes)), never a role.

### Data-freshness stamp

dbt Charts stamps how fresh the data is (`Data as of 09:44 UTC on 30 Jul 2026`)
in the lower-left footer by default, on the same baseline as the footer
attribution. The value is the query time for a fresh render, or the write time
of the oldest cached query when results are served from cache, so the board
never reads as fresher than it is. It is always shown in UTC, because a static
export cannot know the viewer's timezone.

Use `style.timestamp.position` to move it between the footer baseline and the
top row, `style.timestamp.align` to choose the left or right edge, and
`style.timestamp.format` to change the text, a strftime string that carries the
whole line, label included. The default is `position: footer` and `align: left`.

```yaml {contract=board-root}
style:
  timestamp:
    position: top
    align: right
```

A custom `format` that prints a clock time must show its zone; include `%Z`
(or a literal `UTC`). The value is UTC, and an unlabeled clock would be misread
as local time, so dbt Charts rejects a zone-less clock format at compile. A
date-only caption needs no zone.

When the timestamp is right-aligned on the footer baseline, dbt Charts keeps the
footer attribution on the far right and shifts the timestamp left so the two
strings do not overlap. If the footer is hidden, a footer-right timestamp uses
the right page edge.

### Markdown text styling

Markdown prose in a `text:` block (body copy, inline `` `code` `` and fenced code
blocks, and `> blockquotes`) is painted from the theme, so it tracks the active
theme and accent automatically. Body text uses `style.text.font`; headings use
`style.title.font`; links use `style.accent`. Inline code, fenced code, and
blockquotes have their own **box** style groups under `style.text`, with the same
`font` / `background` / `border` shape used by chart cards and callouts:

```yaml {contract=board-root}
style:
  text:
    code:                 # inline + fenced code
      font:
        family: "ui-monospace, SFMono-Regular, Menlo, monospace"
        color: "#222222"
      background: "#f3f4f6"   # code surface fill
      border:
        color: "#e5e7eb"      # code box border
        width: 1
        radius: 4             # rounded code chips / blocks
    blockquote:           # > blockquote
      font:
        color: "#5f6b7a"      # muted quote text
        style: italic
      background: "#f9fafb"   # blockquote surface fill
      border:
        color: "#3b82f6"      # left rule (the theme accent by default)
        width: 3
        radius: 0
    divider:              # `---` lines and markdown-table gridlines
      color: "#e0e0e0"
```

`style.text.divider` is the one knob for both horizontal rules (`---`) and the
gridlines of a markdown table written inside a `text:` block. It does not affect
`type: table` charts; those draw their lines from `style.charts.table.header.divider`
and `style.charts.table.row.divider`.

### Dividers

Every separator line is a `divider` with the same four keys: `visible`, `color`,
`width` (px) and `dasharray` (a dash pattern in px such as `"6 3"`; unset is
solid). Table dividers add
`continuous`. Each divider is complete in every theme, so writing one key changes
only that key: setting `style.text.column.divider.color` recolors the line between
prose columns and leaves it off.

| Key | Line |
|---|---|
| `style.text.column.divider` | between prose columns (off by default) |
| `style.text.divider` | markdown `---` and markdown-table gridlines |
| `style.footer.divider` | above the footer attribution |
| `style.charts.table.header.divider` | under the table header |
| `style.charts.table.row.divider` | under each body row (off by default) |
| `style.charts.table.row.roles.{summary,total}.divider` | above summary and total rows |
| `style.charts.support_table.divider` | between the plot and the support strip (off by default) |
| `style.charts.support_table.row.divider` | under each support-strip row (off by default) |

`font` accepts the full font overlay (`family`, `color`, `size`, `weight`, `style`,
`decoration`, `case`); `border` is the standard `width` / `color` / `radius` group.
Every key is optional in a board `style:`; set just the leaf you want to change (for
example `style.text.code.background` to recolor code chips for one dashboard). The
built-in `neon` theme ships darker code/blockquote surfaces; custom themes set these
in theme YAML so all dashboards inherit them.

The `font` overlay is fully honored for code and blockquote prose: `family`, `color`,
`size`, `weight`, `style` (italic), and `decoration` (underline / line-through) all
render. `case` supports `upper` and `lower`; the richer transforms (`title`, `sentence`,
`slug`, `camel`) are rejected on markdown prose rather than silently ignored.

### Border & Corner Styling

Most `border:` groups in the theme (the `text.code` / `text.blockquote` boxes
above, and callout cards) accept the full `width` / `color` / `radius` group
(plus the optional `dash_array` / `line_cap` / `dash_offset` fields). A few
interior slots render **corner rounding only**: their renderer never draws a
stroke, so `width` and `color` would validate but do nothing. Those slots
accept `radius` alone and reject `width` / `color` / `dash_array`:

- `style.variables.input.border`: the variable-strip input controls
- `style.charts.spark_bar.border`: the `spark_bar` chart's outer frame
- `style.charts.table.spark.columns.border`: inline `spark.type: columns` bars
- `style.charts.table.spark.bar.border`: inline `spark.type: bar` cells

```dbt-charts-example
title: "Top regions"

queries:
  regions:
    type: values
    columns: [region, revenue]
    values:
      - [West, 812000]
      - [East, 654000]
      - [Central, 431000]
      - [South, 298000]

charts:
  region_ranking:
    query: regions
    type: spark_bar
    x: revenue
    y: region

style:
  charts:
    spark_bar:
      border:
        radius: 8

rows:
  - region_ranking
```

A slot that does draw a stroke keeps the full group. `style.text.code.border`
paints the box around a fenced code block, so all three fields land on the
rendered rect: `width` as the stroke width, `color` as the stroke, `radius`
as the corner rounding:

```dbt-charts-example
title: "Reading a board file"

style:
  frame:
    width: 700
  text:
    code:
      border:
        width: 2
        color: "#9aa4b2"
        radius: 6

rows:
  - text: |
      Every board is a YAML file. A chart names its query, its type, and the
      columns bound to each channel:

          charts:
            region_ranking:
              query: regions
              type: spark_bar
              x: revenue
              y: region
```

### Emoji handling

Themes control how emoji codepoints render via `style.font.emoji`. This field
is **required**; the theme YAML must set it explicitly (no in-code default).
The base theme cascade sets `emoji: monochrome`; all built-in themes
inherit this via `extends:` unless they override it.

| Value | HTML surfaces | SVG / PNG via vl-convert | PDF via ReportLab |
|---|---|---|---|
| `monochrome` (default) | Bundled Noto Emoji for the curated set, monochrome; anything else falls to the OS font | Bundled Noto Emoji for the curated set; anything else is a missing glyph | Bundled Noto Emoji on single-emoji runs; mixed-text emoji still gapped |
| `system-default` | OS color emoji wins (Apple Color, Segoe UI Emoji, Noto Color Emoji) | No emoji font registered; emoji codepoints render as missing glyphs | Missing glyphs |
| `disabled` | OS color emoji wins (no dbt Charts emoji wiring) | Missing glyphs; no `@font-face` partial shipped | Missing glyphs |

```yaml {contract=board-root}
# Default: dbt Charts's calm monochrome, same glyphs everywhere
style:
  font:
    emoji: monochrome
```

```yaml {contract=board-root}
# Let the browser pick OS-native color emoji (HTML-only; SVG/PNG degrade)
style:
  font:
    emoji: system-default
```

```yaml {contract=board-root}
# No dbt Charts emoji wiring at all
style:
  font:
    emoji: disabled
```

Note: `system-default` and `disabled` intentionally degrade on SVG/PNG/PDF
surfaces; there is no OS fallback on those renderers. `monochrome` is the mode
that carries emoji across surfaces, but only for the codepoints it bundles.

**The bundled font covers a curated set of chart-relevant emoji** (status marks,
trend arrows, time, money, ops, org and geo, marks, documents, smileys, and weather),
not the full emoji repertoire. An emoji outside that set falls to the OS font in a
browser and is a missing glyph in SVG, PNG, and PDF. Two further limits worth
knowing:

- A codepoint spelled with the emoji variation selector (U+FE0F), the form most
  emoji pickers emit, is painted by the OS in a browser even when the bundled
  font carries it, because that selector requests emoji presentation and browsers
  answer it with a color font.
- Text width is measured against the bundled font, so an emoji outside the set is
  measured as a narrow placeholder and painted at full width. Expect wrapping to
  be off around it.

If an emoji you need isn't covered, prefer a word or a chart glyph over relying on
the fallback.

---

## CSS Scope & Limitations

The `style.css` file styles the **Dashboard Shell** (HTML), but has limitations regarding internal Chart elements (SVG).

### What CSS Can Style (HTML)
- **Layout**: Rows, columns, grids, margins.
- **Typography**: Section titles, markdown text, KPI cards, headers.
- **Interactive Elements**: Filter inputs, buttons, tabs.
- **Backgrounds**: Page background, section borders, shadows.

### What CSS Cannot Style (Charts)
- **Chart Internals**: Bars, lines, axes, legends inside the Vega-Lite charts.
- **PDF Exports**: Static exports use a different rendering path where external CSS may not apply fully.

**Recommendation:**
- Use **Style Options** (a chart's own `style.color`, `chart.style`) for chart colors and axes.
- Use **Custom CSS** for layout, typography, and branding of the surrounding page.

---

## Chart-Level Styling

Override theme for specific charts:

```yaml {contract=board-fragment}
charts:
  custom_chart:
    title: "Custom Styled Chart"
    query: sales
    type: bar
    x: month
    y: total_revenue
    style:
      color:
        categorical:
          palette: editorial-10   # A built-in categorical palette
      legend:
        visible: true             # Show legend (default)
      axis:
        grid:
          visible: false           # Hide grid lines
```

Chart styles are sparse overlays on the active theme. An omitted field inherits
the nearest theme or board-level value. An explicit `null` is accepted only where
it means no value: `legend.symbol_limit: null` removes an inherited entry cap,
`footer.link: null` renders no link, and `axis_y.labels.format: null` emits no
format. Any other `null` fails validation; omit the key instead.

---

## Style Options

### Color Palettes

Choose from built-in color palettes:

- `editorial-10` - Default categorical palette: blue-first ten-color set tuned for calm, editorial multi-series charts
- `vivid-10` - Higher-saturation ten-color categorical set
- `tableau` - Tableau-style 10-color set, for users who want the familiar hues
- `dbt-seq-blue` - Blue sequential palette (light → dark)
- `dbt-seq-green`, `dbt-seq-amber`, `dbt-seq-rust`, `dbt-seq-teal`, `dbt-seq-purple`, `dbt-seq-brown` - Single-hue sequential palettes
- `dbt-seq-gray` - Achromatic sequential palette (magnitude without hue)

**Choosing a palette:**
- **Categorical data**: Use `editorial-10` or another categorical palette
- **Sequential data**: Use a `dbt-seq-*` palette
- **Accessibility**: Consider colorblind-friendly palettes

The full catalog, including diverging palettes, tonal category sets, and dark-theme companions, is in the [Palettes guide](guides/palettes.md).

### dbt Charts Palette Direction

Alongside the generic built-in schemes above, dbt Charts now documents its own
chart-library palette direction:

- the default dbt Charts categorical palette is a blue-first ten-color set tuned for
  calm, editorial multi-series charts
- single-series charts (one mark, no color encoding) inherit the active
  theme's single-series ink (for example, dark blue on clarity, warm dark brown
  on paper) instead of falling back to the categorical palette's anchor
- `hero-6` is a hero-blue-versus-neutrals palette for charts where one series
  should dominate

See [Palettes](guides/palettes.md) for the full catalog with swatch previews.

### A neutral single-series mark

Every theme's single-series ink is a color (dark blue on clarity, warm dark
brown on paper) because most boards want a chart's one mark to read as
data, not chrome. When a chart genuinely encodes nothing by hue and a
neutral mark communicates that more honestly, pin
`single_series_palette` to a gray scaffold step instead.

At board scope, every single-series chart on the board goes neutral:

```yaml {contract=board-root}
style:
  charts:
    color:
      categorical:
        single_series_palette: [dbt-grays.heading]
```

At chart scope, only the one chart goes neutral; a `static` color skips the
palette-slot machinery entirely, since a single-series chart never has more
than one slot to skip:

```yaml {contract=chart-body}
style:
  color:
    static: dbt-grays.heading
```

### Legend

Control legend display per chart (within a chart's `style:` block):

```yaml {contract=board-root}
charts:
  my_chart:
    type: bar
    style:
      legend:
        visible: false  # Hide legend
```

Top-horizontal legends hide their title automatically because the color-channel
name is usually redundant. Set `title.visible: true` to opt in when the title adds
useful context:

```yaml {contract=board-root}
charts:
  my_chart:
    type: bar
    style:
      legend:
        position:
          edge: top
        title:
          visible: true   # opt in; omitted means hidden for this layout
```

For other legend layouts, `title.visible: false` hides only the title while keeping
the color swatches.

`direction` is inferred from `position.edge`: `top` and `bottom` legends are
`horizontal`, `left` and `right` are `vertical`. Author `direction` to override.
An inferred-horizontal legend too wide for one row wraps at `compact_columns`;
author `direction` or `columns` to opt out.

Automatic compact top legends and wrapped horizontal legends use `compact_columns` from the active legend style
(the base theme uses two). Set a positive integer on a chart's legend style to tune
that automatic wrapping; `columns: 0` leaves ordinary legends on the renderer
default.

`style.legend` is not supported on `kpi` or `table` charts; neither renders a color legend, so authoring it is a validation error.

`values` pins an explicit legend entry order and filter; see
[Legend](charts/color-channels.md#legend) for the full resolution rules
(matching a column name against its rendered label, and what happens when an
entry doesn't resolve):

```yaml {contract=board-root}
charts:
  my_chart:
    type: bar
    style:
      legend:
        values: ["Paid", "Organic", "Referral"]
```

### Grid Lines

Show or hide grid lines per chart (within a chart's `style:` block):

```yaml {contract=board-root}
charts:
  my_chart:
    type: bar
    style:
      axis:
        grid:
          visible: true    # Show grid lines
          # visible: false  # Hide grid lines
```

Ratio-percent bar, line, area, and scatter charts automatically emphasize the
unity baseline at `y=1` when the effective y-domain includes that value. This
is the common 100% guide for retention, conversion rate, and NRR charts
stored as ratios such as `1.08`. Style the rule with the existing
`axis_y.grid.threshold` color and width settings, or hide it on its own with
`grid.threshold.visible: false`, which leaves the axis's other gridlines in
place:

```yaml {contract=board-root}
charts:
  nrr:
    type: line
    style:
      axis_y:
        scale:
          continuous:
            domain: [0.95, 1.2]
        grid:
          threshold:
            width: 3
            # visible: false  # hide the threshold rule only
        labels:
          format: percent_whole
```

The same `grid.threshold` style block is authorable on any axis slot, not
just `axis_y`. A chart with its own quantitative x column, a scatter plotting
one ratio against another for example, earns an independent zero or unity
rule on that axis too; style or suppress it the same way, scoped to
`axis_x.grid.threshold`.

### Holding an Axis Still Across Filter Changes

A chart's measure axis is scaled to the rows its query returned, so changing a
filter variable rescales it; the same value can land at a different pixel
before and after the change. When viewers compare values across filter
selections, pin the bounds yourself with an explicit domain:

```yaml {contract=board-root}
charts:
  quarterly_revenue:
    type: bar
    x: month
    y: revenue
    style:
      axis_y:
        scale:
          continuous:
            domain: [0, 800]   # same frame of reference for every selection
```

An authored `domain` wins over every other axis-scaling behavior; headroom and
the zero-baseline heuristic both step aside for it.

### Starting a Line Chart at Zero

A line chart's y-axis fits the data: when every value sits far from zero, the
axis zooms in so the line's movement fills the plot. Bar and area charts start
at zero by default because their marks encode length. To anchor a line chart at
zero, pin `zero: true`; `zero: false` forces the zoomed axis:

```yaml {contract=chart-body}
style:
  axis_y:
    scale:
      continuous:
        zero: true
```

To make that the default for every line chart in a project, set it on the
`line` family in `charts/meta.yml` (or in a theme layer the project extends).
Bar, area, and scatter charts are untouched, and a chart's own `zero: false`
still wins:

```yaml {contract=board-root}
style:
  charts:
    line:
      axis_y:
        scale:
          continuous:
            zero: true
```

### Axis Labels

Hide axis labels with `labels.visible: false`:

```yaml {contract=chart-body}
style:
  axis_y:
    labels:
      visible: false   # hide y-axis labels entirely
```

This matches the existing convention for other axis elements (`grid.visible`, `line.visible`, `ticks.visible`).

#### Suppressing the axis title alongside `x_label`/`y_label`

`style.axis_y.title.visible` / `style.axis_x.title.visible` control whether
the axis title itself is drawn. Authoring `x_label`/`y_label` normally forces
the axis title on (it overrides the theme's default suppression so the label
has somewhere to show up), but an explicit
`title.visible: false` authored anywhere on the chart (`style.axis_y`/`style.axis_x`, the type-conditional
`style.axis_quantitative`/`style.axis_band`, or the chart's shared
`style.axis` patch) still wins and suppresses just the on-axis text. The
label keeps doing its other jobs (the tooltip and any endpoint/rail labels),
so `y_label: "% from Data Lakes"` plus `axis_y.title.visible: false` is a
legal, supported combination for a chart that wants the label without the
axis-title space it reserves.

This precedence holds for a board-level override too: a
`style.charts.axis_y.title.visible: false` set once on the board suppresses the
axis title on every chart, even those that author `y_label`. An explicit
`title.visible` you author, whether on the board or on a single chart, always
wins over the label-forcing default; a chart-level override just narrows the
effect to that one chart.

Axis settings follow one rule: the more specific path wins, whichever file set
it. `style.charts.axis_y` from a board loses to the theme's
`style.charts.axis_quantitative` and `style.charts.bar.axis_y`, so name the
chart type or the quantitative slot to override a theme's value there. The type
slot (`axis_quantitative`, `axis_band`) beats the channel slot (`axis_x`,
`axis_y`), which beats `axis`; this holds in a chart's own `style` too.

#### Label density

Three knobs control how densely labels are packed on an axis:

**`labels.overlap`**: two switches for resolving overlapping x-axis labels.
On temporal axes dbt Charts tries skip before tilt. For bucketed temporal axes,
skip shows labels at the next meaningful calendar boundary while leaving the
axis, label-format time unit, and ticks unchanged. A resolved coarser
`labels.time_unit`, whether authored or chosen automatically, also sets the
default tick cadence. Categorical axes never skip because every category label
carries domain information; they only use an authored font size and tilt. If the
automatically thinned labels still do not fit, tilt rotates them through
`tilt_increments`, shallowest first. Font size never changes.

Quantitative x-axes bypass overlap resolution because Vega-Lite places their
continuous-scale ticks.

**`labels.min_gap`**: minimum pixel gap between adjacent label bounding boxes before they count as non-overlapping (default `16`). Only active when overlap resolution is on. Raise it to add visible breathing room between retained labels.

**`labels.max_width`**: maximum pixel width before a label is truncated with `…` (Vega-Lite default `180px`). Tighten for narrow charts; loosen for charts with long category names.

```yaml {contract=chart-body}
style:
  axis_x:
    labels:
      overlap:
        skip: true
        tilt: true
      min_gap: 24
      max_width: 120
```

##### Positioning and boundary

Three knobs control where a label sits relative to its tick and whether it
survives clipping at the axis range edges.

**`bound`**: hide labels whose bounding boxes overflow the axis range.

Reach for it when a categorical x-axis has one very long label at the first or
last position that bleeds into the chart padding or off the canvas. Accepts
`true` (hide any overflow) or a pixel tolerance (hide only when overflow exceeds
that many pixels).

```yaml {contract=board-root}
charts:
  product_revenue:
    type: bar
    x: product_name     # categorical, some labels very long
    y: revenue
    style:
      axis_x:
        labels:
          bound: true   # hide labels that bleed past chart edge
```

**`flush`**: align the first and last labels flush with the scale range rather
than centered on their tick.

Reach for it when time-series edge labels ("Jan 2022" / "Dec 2024") get clipped
at chart edges. Note: Vega-Lite defaults differ by axis: `true` for x, `false`
for y. Accepts `true`/`false` or a pixel tolerance (flush only when label
exceeds by more than that many pixels).

```yaml {contract=board-root}
style:
  charts:
    axis_y:
      labels:
        flush: true     # opt y-axis into flush alignment (VL default is false)
```

```yaml {contract=board-root}
charts:
  monthly_revenue:
    type: line
    x: month
    y: revenue
    style:
      axis_x:
        labels:
          flush: 4      # flush only if label exceeds scale edge by more than 4px
```

**`offset`**: pixel offset of the label from its tick anchor.

Reach for it when fine-grained nudging is needed, for example when
`axis_x.ticks.offset` shifts the ticks themselves or when bar-band tick
positioning leaves labels misaligned with bar centers. Negative values move
labels toward the chart interior; positive toward the chart edge.

```yaml {contract=board-root}
charts:
  weekly_signups:
    type: bar
    x: week
    y: signups
    style:
      axis_x:
        labels:
          offset: -3    # nudge labels 3px toward chart interior
```

---

## Format names and aliases

All named format identifiers in dbt Charts fall into one of two categories:
**engine-predefined** names (owned by the engine, resolved with house rules) and
**custom project aliases** (defined in `style.formats`: a d3 spec, a predefined
name, or a format block).

### Engine-predefined names

The following names are built into the engine. Authors write them in any
`format:` field. A board may redefine one in `style.formats`, as long as the
redefinition is the same kind (number or date).

`format:` slots take either kind: the column decides whether a date or a number
is being painted. A redefined engine name must keep its kind
(`ERR-FORMAT-KIND-MISMATCH`): a date spec under `currency` would paint a number
axis with garbage rather than failing.

**Numeric formats:**

| Name | Example output |
|------|----------------|
| `currency` | $1.23M |
| `currency_whole` | $1,235 |
| `currency_full` | $1,234.57 |
| `currency_compact` | $1.2M |
| `percent` | 12.3% |
| `percent_whole` | 12% |
| `percent_delta` | +12.3% |
| `integer` | 1,235 |
| `delta` | +31 |
| `number` | 1.23M |
| `number_full` | 1,234.57 |
| `compact` | 1.2M |
| `year` | 2025 |
| `id` | 1204331 |
| `duration` | 1h 23m |
| `bytes` | 1.53 MB |
| `latitude` | 37.7749° |
| `longitude` | −122.4194° |
| `rating` | 4.5 |

**The bare name compacts; the `_full` suffix spells the number out.**
`currency` and `number` are the names to reach for on a dashboard, where a
label has to be read at a glance. `currency_full` and `number_full` are for the
surfaces that must show every digit: a reconciliation view, a billing
breakdown, anything that has to tie out against a source system.
`currency_whole` and `integer` drop the minor unit at every magnitude.
`compact` and `currency_compact` compact like `number` and `currency` but keep
two significant digits (`1.2M`, `45K`, `1.2B`) for a headline where the third
digit is noise. They are analytic in every slot (K, M, B, never `k`, `mn`,
`bn`), KPIs included.

`currency` and `number` apply SI notation for large values, rounded
to three significant digits with trailing zeros trimmed: `50752.9` renders as
`$50.8K`. A raw d3 `~s` spec is not the same thing: d3's own default is six
significant digits, so `format: "$~s"` gives `$50.7529K`. (Both shown in the
same analytic register here; a literal `$~s` authored inline also renders in
d3's native register, `$50.7529k`, as described under Format aliases.)

`percent`, `percent_whole`, and `percent_delta` expect a **0–1 ratio**; the
engine multiplies by 100 before formatting, so `0.182` renders `"18.2%"`.
`percent` and `percent_whole` refuse a 0–100-shaped value outright rather than
paint `"1820%"` (`ERR-PERCENT-RANGE`); divide by 100 before it reaches the
chart. `percent_delta` is exempt, because a delta legitimately runs past 100%.

**`year` is an identifier, not a quantity.** Every other numeric name groups
digits or scales by magnitude; a year should have neither (`2,025` and
`2.025K` are both wrong for a year). `year` renders plain integer digits with
no grouping.

**Ids, durations, file sizes, coordinates and ratings.** A name for each kind of
number that `number` would otherwise abbreviate (an order id `1204331` is not
`1.2 M`). Each takes the plainest unit the data carries:

- `id` prints the digits with no separator and never compacts. A text id
  (`A-1204331`) passes through unchanged.
- `duration` reads a span in **seconds** and prints its two largest units:
  `5025` is `1h 23m`, `45` is `45s`, `273600` is `3d 4h`. A zero lower unit is
  dropped (`3600` is `1h`), and a fraction of a second rounds half up.
- `bytes` reads a size in **bytes** and prints decimal SI (1 kB is 1000 B) to
  three significant digits with the unit spaced from the number at every
  magnitude: `950 B`, `1 kB`, `1.53 MB`.
- `latitude` and `longitude` read signed **degrees** and print up to four
  decimals with a degree sign: `37.7749°`, `−122.4194°`. A whole degree prints
  `−122°`, so axis ticks stay short.
- `rating` prints one decimal: `4.5`, `4.0`.

`duration` and `bytes` paint on chart axes, value labels and tooltips, and in a
`kpi` or a `table`. A unit the engine has no name for (`km`, `mi`) is a custom
format; see [A unit of your own](#a-unit-of-your-own).

```dbt-charts-example
title: "One column per kind of number"

queries:
  files:
    type: values
    columns: [order_id, latitude, longitude, rating]
    values:
      - [1204331, 37.7749, -122.41942, 4.5]
      - [1204332, 51.5074, -0.1278, 3.0]
      - [1204333, -33.8688, 151.2093, 4.8]

charts:
  kinds:
    query: files
    type: table
    style:
      columns:
        order_id:
          format: id
        latitude:
          format: latitude
        longitude:
          format: longitude
        rating:
          format: rating

rows:
  - kinds
```

```dbt-charts-example
title: "Time to first response"

queries:
  handle_time:
    type: values
    columns: [team, seconds]
    values:
      - [Billing, 95]
      - [Support, 62]
      - [Sales, 118]

charts:
  handle:
    query: handle_time
    type: bar
    x: team
    y: seconds
    style:
      marks:
        bar:
          labels:
            visible: true
            format: duration

rows:
  - handle
```

**Engine-only formats** (handled directly by the engine, not through a format spec; valid on KPI and table format slots only, not on Vega-rendered slots such as axis labels, mark value labels, or support_table). `duration` and `bytes` are not in this group: they have a Vega form and paint on charts as well.

| Name | Behavior |
|------|----------|
| `percent_number` | Formats `27.6` as `27.6%` (value is already a percentage) |
| `percent_number_delta` | Formats `+3.2` as `+3.2%` with sign (value is already whole percent) |
| `percentage_points_delta` | Formats `+1.5` as `+1.5 pts` with sign. Input is whole points, not a fraction: a delta of `0.575 - 0.47` renders `+0.1 pts`; multiply by 100 in the query |

**Time formats**: the names a date format takes, beside a raw strftime spec
like `%b %Y`:

| Name | Example output |
|------|----------------|
| `date_short` | 7 Mar 2024 |
| `time_short` | 14:05 |
| `date_year` | 2024 |
| `date_quarter` | Q1 |
| `date_month` | Jan |
| `date_week` | W10 |

A date axis labels by the grain it detects (a monthly series reads `Jan`, with
the year on the first label and on every January), and `date_year`,
`date_quarter`, `date_month` and `date_week` name those labels. The engine's own
`date_month` is that vocabulary, not a spec, so a slot that names one the board
has not redefined raises `ERR-FORMAT-GRAIN-NAME-NOT-REDEFINED`. Redefine the name
in `style.formats` with a strftime spec to relabel that grain on every axis and
tooltip header of the board:

```dbt-charts-example
title: "Monthly revenue"

style:
  formats:
    date_month: "%b '%y"

queries:
  monthly:
    type: values
    columns: [month, revenue]
    values:
      - ["2026-01-01", 120]
      - ["2026-02-01", 150]
      - ["2026-03-01", 135]
      - ["2026-04-01", 180]

charts:
  revenue:
    query: monthly
    type: bar
    x: month
    y: revenue
    style:
      orientation: vertical

rows:
  - revenue
```

The axis reads `Jan '26`, `Feb '26`, and the tooltip header the same. An axis's own
`labels.format` still wins, and a number spec under a grain name raises
`ERR-FORMAT-KIND-MISMATCH`. Days keep `date_short`.

**Clickable text formats**: an `email` column is a `mailto:` link in tables and
KPIs; other charts print the text. `url` does the same for a web address.

| Name | A table cell or KPI value links to |
|------|---------------|
| `email` | `mailto:ann@example.com` |
| `url` | the value itself, which must be an absolute `http(s)` URL |

The value prints unchanged. An authored `link:`, a foreign-key drill and a
filter link each win over the format's link, and an empty value stays plain
text. The names take no spec, so `style.formats` cannot redefine them
(`ERR-FORMAT-TEXT-REDEFINED`) and a Vega-rendered slot such as an axis label
rejects them (`ERR-FORMAT-TEXT-IN-VEGA-SLOT`). A number under either raises
`ERR-TABLE-FORMAT-KIND-MISMATCH`, and a `url` value without an `http://` or
`https://` scheme raises `ERR-URL-VALUE-NOT-ABSOLUTE`.

**Name a column's format once, on its query.** A query's
[`formats:`](queries.md#column-formats) gives a column one of these names (or a
`style.formats` name) and every chart that shows the column uses it, with no
`format:` repeated per chart. A chart sets its own slot only for an exception:

```yaml {contract=board-root}
queries:
  revenue_by_month:
    columns: [month, revenue, orders]
    values:
      - [2026-01-01, 1234567, 4210]
    formats:
      revenue: currency
      orders: integer
```

### Using predefined names in charts

```yaml {contract=board-root}
charts:
  revenue:
    type: bar
    x: month
    y: revenue
    style:
      axis_y:
        labels:
          format: currency

  conversion:
    type: bar
    x: date
    y: rate
    style:
      axis_y:
        labels:
          format: percent

  raw_d3:
    type: bar
    x: month
    y: amount
    style:
      axis_y:
        labels:
          format: "$,.0f"
```

### Custom project aliases (`style.formats`)

Add `style.formats` at the theme or board level to define project-specific short
names. Board keys override theme keys; theme keys not redefined by a board
propagate through unchanged.

**Restyle every chart at once by redefining an engine name.** `number`,
`currency`, `percent`, `date_short` and the other engine names are keys like
any other. Every axis, tooltip, mark label, table cell, KPI value and
data-table strip with no format of its own reads the board's definition:

```yaml {contract=board-root}
style:
  formats:
    currency: "$,.0f"
    number: ",.0f"
    date_short: "%b %Y"
```

A query's `formats:` and a slot's own `format:` (an axis's `labels.format`, a
KPI's `value.format`) still win. A redefined name prints exactly the spec you wrote, at every
magnitude: the engine's rules for that name (compaction, trimmed zeros, and
the switch to `currency_full` / `number_full` below 1) no longer apply, so a
redefined `currency` of `$.3~s` prints `$670m` for 0.67. Redefine
`currency_full` or `number_full` too and the engine's own `currency` and
`number` use yours below 1. A redefinition must stay the same kind as the
name: a date spec under `currency` raises `ERR-FORMAT-KIND-MISMATCH`.

#### A unit of your own

The engine names no distance, weight or currency unit beyond the ones above. A
unit is a custom format: an object with a `spec` and a `suffix`, defined once in
`style.formats` and used by name:

```dbt-charts-example
title: "Distance"

style:
  formats:
    km:
      spec: ",.0f"
      suffix: " km"

queries:
  trips:
    type: values
    columns: [route, distance]
    values:
      - [Lisbon to Madrid, 625]
      - [Madrid to Paris, 1054]
      - [Paris to Berlin, 1054]

charts:
  routes:
    query: trips
    type: table
    style:
      columns:
        distance:
          format: km

rows:
  - routes
```

**In a theme YAML:**

```yaml {contract=board-root}
style:
  formats:
    revenue: "$~s"       # project-specific alias
    arr: "$,.0f"
    cost: ",.2f"
```

**In a board YAML (adds or overrides for this board only):**

```yaml {contract=board-root}
style:
  formats:
    arr: "$,.2f"    # override theme's arr alias for this board
```

An alias to a literal d3 spec resolves with no house post-processing. An alias to
a predefined name keeps that name's house rules, so a block can name a house
format with an affix, such as a second currency beside the board's own:

```yaml {contract=board-root}
style:
  formats:
    usd:
      spec: number
      prefix: "US$"
```

An alias target that is none of these raises `ERR-FORMAT-INVALID` at compile
time.

**Any string that isn't a known name or alias is tried as a raw d3 format spec.**
`format: "$,.0f"` on an axis slot is a supported escape hatch for cases where none of
the named presets fit; it passes through unchanged and is validated as a legal
d3 string at compile time.

### A format with its own prefix or suffix: the `FormatConfig` object form

A board has one currency, set by [`regional:`](#regional-settings): every
money format and every `$` spec prints it. Use the object form below only for
what that cannot express: a second currency on the board (define it once as a
[`style.formats` alias](#a-format-with-its-own-prefix-or-suffix-the-formatconfig-object-form)),
a long-form name (`50 US dollars`), or a combination like `50 $ US`.

Every `format:` field above -- an axis's
`labels.format`, `axis_y.mirror.format`, a mark's `labels.format`/
`total_label.format`, a layer's own `axis_y.labels.format`, a
`support_table` entry's `format`, and each value in `style.formats` -- also
accepts an object instead of a string:

```yaml {contract=chart-body}
style:
  axis_y:
    labels:
      format:
        spec: ",.0f"      # a raw d3 spec, or an engine-predefined name
        suffix: " US dollars"
```

A `$` in `spec`, the money names' included, prints the board's currency, so a
second currency goes in `prefix`/`suffix` over a spec without `$`. An affix on
a money name composes around the board's currency instead:
`{spec: currency, prefix: "US "}` prints `US $12.4K` on an `en-US` board.

**Sign placement.** `sign_placement: before_prefix` puts a negative sign ahead
of the prefix (`−€500`); `after_prefix` puts it between prefix and digits
(`EUR −500`). Unset, a prefix ending in a space (a word or code) takes
`after_prefix`, any other prefix `before_prefix`. Where the prefix paints on one
value only (see `repeat`), the sign always follows it, so the anchor's digits
line up with the bare values beside it (`€−50` above `−40`); `before_prefix`
there raises `ERR-FORMAT-SIGN-BEFORE-ANCHORED-PREFIX`. A `suffix` always trails
the digits (`−500 EUR`). A table column keeps the sign against the digits
(`€  −500`) because its prefix lane is shared down the column, so
`sign_placement` on a table column raises
`ERR-FORMAT-SIGN-PLACEMENT-TABLE-UNSUPPORTED`.

**Repeat.** `repeat: anchor` paints the prefix and suffix on one value per axis,
table column or support_table row; the engine picks which. `repeat: every`
paints them on every value. Unset keeps each surface's default: a vertical axis
and a `symbol_mode: anchors` table anchor, a horizontal bar's value axis
repeats, and a support_table row anchors a predefined format's affix where its
cells have an order. Value labels, totals, tooltips and KPIs show one value, so
they ignore `repeat`.

```yaml {contract=chart-body}
style:
  axis_y:
    labels:
      format:
        spec: ",.0f"
        prefix: "EUR "
        repeat: anchor
```

A `prefix`/`suffix` combines freely with an SI spec, compacting axis and all --
a `number` spec with `prefix: "US$"` paints `US$12.4M` on an axis exactly the
way the engine's own `currency` preset paints `$12.4M`; the affix composes
around the shared-magnitude ladder rather than colliding with it. A raw `.3~s`
literal keeps d3's own register (`US$12.4M`) unless `notation` says otherwise.

A `prefix`/`suffix` also composes cleanly with a literal spec that carries d3's
own `$` symbol -- the authored prefix comes first, then the symbol's own body: a
`$,.0f` spec with `prefix: "US "` paints `US $154,500` (`US −$154,500` for a
negative), never `$US 154,500` or a dropped prefix.

**Restrictions.** None of these targets has an expression slot to compose a
prefix/suffix/notation into:

- A temporal axis's format (`ERR-FORMAT-AFFIX-TIME-UNSUPPORTED`,
  caught at compile) -- a strftime spec paints through Vega's native time
  formatter, not d3-format's number grammar.
- A categorical (nominal/ordinal) axis (`ERR-FORMAT-AFFIX-NOMINAL-AXIS-UNSUPPORTED`),
  which fires at resolve, once the actual channel type is known.

A table column or KPI paints a date spec's affix around the date instead:
a `%b %Y` spec with `prefix: "FY "` on a table column paints `FY Jan 2026`.

**`notation`** overrides the analytic (`1.2M`, suffix stated once) vs.
narrative (`1.2mn`, repeated per value) register that `currency`/`number`
otherwise pick automatically. It only affects an SI-shaped spec -- useful on
a raw `~s` literal with `notation: narrative`, which otherwise
renders in d3's own native register instead of either house register. It does
nothing to a date or any other non-SI spec.

**An authored `labels.expr` overrides the axis's format entirely.** When an
axis carries a custom label expression, it renders exactly as written -- no
prefix, suffix, or notation from the format is composed into it:

```yaml {contract=chart-body}
style:
  axis_y:
    labels:
      format:
        spec: ",.0f"
        prefix: "EUR "
      expr: "datum.label + ' /mo'"
```

Inside the expression, `datum.label` is Vega's own text formatted from the
plain d3 spec, so a native `$`/`#` in the spec appears in it, but a
`FormatConfig` prefix, suffix, or notation does not. Write the symbol into
the expression yourself:

```yaml {contract=chart-body}
style:
  axis_y:
    labels:
      expr: "'EUR ' + datum.label + ' /mo'"
```

A surface the expression doesn't govern, like the tooltip, still paints the
full format.

The object form works as a `style.formats` alias value too, referenced by
name everywhere a string alias is. That is how a board mixes currencies: the
board's own currency comes from `regional:`, each other one is an alias.

```yaml {contract=board-root}
regional:
  currency: EUR
style:
  formats:
    usd:
      spec: ",.0f"
      prefix: "US$"
charts:
  revenue:
    type: bar
    x: month
    y: revenue_usd
    style:
      axis_y:
        labels:
          format: usd
```

### Suppressing format with `null`

Use `format: null` (or omit `format:`) to suppress format emission and let
VL/D3 pick its own default based on the axis scale type. This is the
canonical way to override an inherited theme-level `format: number` per
chart; no `format: auto` string sentinel.

## Regional settings

`regional:` sets how a board writes numbers and dates: `locale.number` picks the
separators and the currency template, `locale.time` the month, weekday and
AM/PM names, `currency` the symbol that template prints.

```yaml {contract=board-root}
regional:
  locale:
    number: de-DE   # default en-US
    time: de-DE     # default en-US
  currency: USD     # default: the number locale's own
```

Set it in `charts/meta.yml` and every board beneath it follows; a board's own
`regional:` overrides it field by field. A nested board takes its root board's
`regional:`; a different one is an error (`ERR-REGIONAL-NESTED-MISMATCH`).
Themes don't carry it.

### Number locale

`locale.number` is a d3-format locale name (`fr-FR`, `de-CH`, `en-IN`, ...). It sets the
thousands separator, the decimal mark, the percent and minus signs, and where
the currency goes: `1 234 567,5` in `fr-FR`, `12,34,567.5` in `en-IN`,
`1.234,50 €` in `de-DE`. It also names the magnitude abbreviations, in
`de-DE` `1,5 M` where a magnitude is declared once (an axis) and `1,5 Mio.` on
every value (a label).

For a locale d3 doesn't ship, write the definition yourself, mirroring d3's
`formatLocale`:

```yaml {contract=board-root}
regional:
  locale:
    number:
      decimal: ","
      thousands: "."
      grouping: [3]
      currency: ["", " EUR"]
      percent: " %"   # optional, default %
      minus: "-"      # optional, default −
      analytic: [" k", " M", " Mrd", " Bio"]           # optional, default en-US
      narrative: [" Tsd.", " Mio.", " Mrd.", " Bio."]  # optional, default en-US
```

`analytic` and `narrative` are the thousand, million, billion and trillion
suffixes: `analytic` is the extra-short form, where a magnitude is declared
once (`1.5M` on an axis); `narrative` is the abbreviated form, on every value
(`1.5mn`). Each is printed as written, so a leading space is part of the
suffix.

### Time locale

`locale.time` is a d3-time-format locale name. It names the months, weekdays and
AM/PM on every painted date: axis ticks, tooltips, table cells, and the `%c`,
`%x` and `%X` composite formats. It also sets the day a date picker's calendar
week starts on, from the locale's region (CLDR): Monday in `de-DE`, Sunday in
`en-US`, Saturday in `fa-IR`. `de-DE` prints `Mrz` and `Okt` where `en-US`
prints `Mar` and `Oct`. The number and time locales are independent: set both
for a German board.

d3 ships time locales for `ar-EG`, `ar-SY`, `ca-ES`, `cs-CZ`, `da-DK`, `de-CH`,
`de-DE`, `en-CA`, `en-GB`, `en-US`, `es-ES`, `es-MX`, `fa-IR`, `fi-FI`, `fr-CA`,
`fr-FR`, `he-IL`, `hr-HR`, `hu-HU`, `it-IT`, `ja-JP`, `ko-KR`, `mk-MK`, `nb-NO`,
`nl-BE`, `nl-NL`, `pl-PL`, `pt-BR`, `ru-RU`, `sv-SE`, `tr-TR`, `uk-UA`, `vi-VN`,
`zh-CN` and `zh-TW`. For any other language or region, such as `pt-PT`, write the definition, mirroring
d3's `timeFormatLocale`:

```yaml {contract=board-root}
regional:
  locale:
    time:
      date_time: "%A, %e %B %Y %X"
      date: "%d/%m/%Y"
      time: "%H:%M:%S"
      periods: [AM, PM]
      days: [Domingo, Segunda-feira, Terça-feira, Quarta-feira, Quinta-feira, Sexta-feira, Sábado]
      short_days: [dom, seg, ter, qua, qui, sex, sáb]
      months: [janeiro, fevereiro, março, abril, maio, junho, julho, agosto, setembro, outubro, novembro, dezembro]
      short_months: [jan, fev, mar, abr, mai, jun, jul, ago, set, out, nov, dez]
      week_start: sunday
```

`date_time`, `date` and `time` are the patterns `%c`, `%x` and `%X` expand to;
`date_time` may not contain `%c`, and `date` and `time` may not use `%c`, `%x` or
`%X`. `days` starts on Sunday; `week_start` is `sunday` through `saturday`.

### Currency

The engine money names -- `currency`, `currency_whole` and `currency_full` --
are d3 specs with a `$` (`$,.2f`), and d3 prints the locale's currency for a
`$`: its symbol, at its side, with its gap. A `$` in a spec you write does the
same. `currency` swaps the symbol for an ISO 4217 code's and keeps the
locale's placement:

| `locale.number` | `currency` | `currency_full` of 1234.5 |
|---|---|---|
| `en-US` | | $1,234.50 |
| `de-DE` | | 1.234,50 € |
| `en-US` | `EUR` | €1,234.50 |
| `de-DE` | `USD` | 1.234,50 $ |
| `en-US` | `CHF` | CHF 1,234.50 |

A word symbol gets a space where the locale's own symbol had none (`CHF 1`,
not `CHF1`). `currency` accepts USD, EUR, GBP, JPY, CAD, AUD, CHF, SEK, NOK,
DKK, INR, CNY, BRL and MXN; `JPY` has no minor unit, so `currency_full` prints
whole yen. A custom locale whose `currency` template is empty has no place for
a symbol, so setting `currency` beside it is an error.

```dbt-charts-example
title: "EMEA results"

regional:
  locale:
    number: de-DE
    time: de-DE

queries:
  region_results:
    type: values
    columns: [region, revenue, target, price]
    values:
      - [Nordics, 1234567, 1500000, 0.67]
      - [Benelux, 987654, 1100000, 0.82]
  total:
    type: values
    columns: [revenue]
    values:
      - [2222221]

charts:
  revenue_kpi:
    query: total
    type: kpi
    value: revenue
    style:
      value:
        format: currency
  revenue_bar:
    query: region_results
    type: bar
    x: region
    y: [revenue, target]
    style:
      axis_y:
        labels:
          format: currency
  results_table:
    query: region_results
    type: table
    style:
      columns:
        revenue:
          format: currency_whole
        target:
          format: currency_whole
        price:
          format: currency

rows:
  - revenue_kpi
  - revenue_bar
  - results_table
```

**Placement.** Where the currency repeats on every value -- a KPI, a label, a
tooltip, a `repeat: every` column, an axis that repeats its unit -- it takes
the locale's side (`1,23 M €`). Where it is declared once -- a table column
in `symbol_mode: anchors`, an anchored support_table row, an axis that labels
one tick -- it leads the digits (`€1,23 M`, then bare values).

**One currency per board.** `regional:` sets the currency for the whole board,
including every `$` spec you write. To show a second currency, or one
`regional.currency` lacks, define a `style.formats` alias in
[the object form](#a-format-with-its-own-prefix-or-suffix-the-formatconfig-object-form)
with `prefix:` or `suffix:` over a spec without `$`.

---

## Typography

Every piece of text on a board reads one of seven **named fonts** declared
under `style.fonts`. Change a named font once and every title, label, or
caption bound to it follows:

```yaml {contract=board-root}
style:
  fonts:
    heading:
      family: "'Source Serif 4', Georgia, serif"
    body:
      family: "Inter"
```

| Font | Used by |
|------|---------|
| `heading` | Board titles, chart titles, markdown `#` to `######` |
| `subtitle` | Title subtitles |
| `body` | Markdown prose |
| `label` | Axis and legend labels and titles, tooltips, KPI labels, table cells and headers, variable controls, tabs, details |
| `caption` | Footers, timestamps, callout messages |
| `numeral` | KPI values, quantitative axis labels, support tables, pie totals |
| `code` | Inline and fenced code in markdown |

A named font takes the same fields as any `font:` block (`family`, `color`,
`size`, `weight`, `style`, `decoration`, `case`, `line_height`) and sets only
the fields it names. A board's `fonts:` merge with the theme's key by key, so
redefining `heading` keeps the theme's `body`. KPI fonts paint one line and
take no `line_height`; a named font's is dropped there.

### Heading sizes

Heading levels H1 to H6 share the `heading` font and differ only in size. The
sizes live on the `heading` font as a six-step list, `sizes`; `heading` takes
no `size`:

```yaml {contract=board-root}
style:
  fonts:
    heading:
      sizes: [30, 20, 16, 14, 11, 11]
```

A board title reads its level's step, markdown `#` reads the first step, and
chart titles pick a step by card width.

### Applying a named font to a slot

Any `font:` slot except the root `style.font` and `details.arrow.font` takes a named font in one of three forms:

```yaml {contract=board-root}
style:
  title:
    font: heading
  charts:
    kpi:
      value:
        font:
          extends: numeral
          size: 40
```

- **By name:** `font: heading` uses the named font as-is.
- **By name with overrides:** `extends:` plus the fields that differ.
- **Inline:** a plain `font:` block with no name.

An unknown name raises `ERR-FONT-UNKNOWN` and lists the fonts in scope. When a
slot names a font, it replaces whatever a theme bound to that slot. The root
`style.font` is the base every other font inherits from, so it rejects a name;
set `style.fonts.body` to restyle base text.

### Fonts that extend fonts

A `style.fonts` entry takes the same forms as a slot, so a font can start from
another font. Define a per-role font once and bind slots to it:

```yaml {contract=board-root}
style:
  fonts:
    tag:
      extends: label
      weight: 600
      case: upper
  charts:
    kpi:
      label:
        font: tag
```

A bare name makes an alias: `small: caption` is a second name for `caption`.

An entry is its parent's fields plus its own, and its own fields win. Chains of
any length work; a cycle raises `ERR-FONT-REGISTRY` and names the path. `sizes`
is the heading ramp and is never inherited. `extends: null` gives an entry no
parent. When a board's entry sets `extends`, it replaces the theme's entry of
the same name instead of tweaking it.

### Families

Common font choices:
- `Inter` - Modern, readable sans-serif
- `Roboto` - Google's Material Design font
- `Open Sans` - Friendly, readable sans-serif
- `Lato` - Humanist sans-serif

### Case

Every font slot supports a `case` field that applies a letter-case transform to
the text before it reaches SVG or Vega-Lite output. The default is `none`
(no transform).

| Value | Behavior |
|-------|----------|
| `none` | No transform (default). Text is rendered exactly as authored or returned from the database. |
| `title` | Chicago/Gruber-style title case. Lowercases stopwords (a, an, and, at, but, by, for, in, of, on, or, the, to, via, vs.). Always capitalizes the first and last word. **Preserves any token containing internal capitals**: `ARR`, `MRR`, `iPhone`, `GitHub`, `SQL` are untouched. |
| `sentence` | Uppercases the first letter; preserves all other characters as authored. Acronyms already capitalized by the author are preserved. |
| `upper` | All characters uppercased. |
| `lower` | All characters lowercased. |
| `slug` | Machine identifier form: spaces/hyphens → underscore, lowercased. `Order Status` → `order_status`. |
| `camel` | camelCase: first word lowercase, subsequent words capitalized. `order status` → `orderStatus`. |

#### Why smart title case matters

The `case: title` value uses the Gruber algorithm, not the naive "capitalize
every word" approach shipped by CSS `text-transform: capitalize`, Microsoft
Word, and most BI tools. The key rule: **any token that already contains
internal capitals is left alone**. This means metric initialisms common in
dashboards are safe:

```text
ARR Growth by Segment         →  ARR Growth by Segment  (correct)
Revenue by Customer Segment   →  Revenue by Customer Segment
from the top                  →  From the Top
```

A naive every-word capitalizer would produce `Arr Growth By Segment`; editorial
garbage that damages brand credibility on published dashboards.

#### Setting case in a theme

Theme authors can enforce a casing convention across all text slots by adding
`case:` to the font block at whichever level they want it to take effect:

```yaml {contract=unverified}
# In a theme YAML; title-case all chart titles, board titles, and KPI labels
title:
  font:
    case: title

charts:
  font:
    case: title
```

```yaml {contract=board-root}
# In a board YAML; upper-case axis tick labels for this chart only
charts:
  pipeline_stages:
    type: bar
    x: stage
    y: count
    style:
      axis_x:
        labels:
          font:
            case: upper
```

#### Scope and limitations

`case` applies to **static authored text and data-derived static values**:

- Board title and subtitle
- Chart title (as emitted in the Vega-Lite spec)
- KPI label text
- Table header display names
- Legend titles (as emitted in the Vega-Lite spec)
- Error and placeholder overlay text

Axis titles are not in that list. A derived axis title is the bound column's
name split into words: an all-lowercase or all-uppercase word is lowercased
(`REVENUE` renders `revenue`), and a mixed-case word such as `MTok` keeps its
spelling. An authored `x_label`/`y_label` or `field_labels` entry renders as
written.


For **data-bound tick labels and legend item labels** (rendered by Vega at
runtime from query results), only `upper` and `lower` are applied; they map
directly to Vega expression language (`upper(datum.label)`,
`lower(datum.label)`). The `title` and `sentence` values have no equivalent in
Vega expression language, so they cannot be applied to data-bound labels at
render time.

Board markdown body text (`text:` blocks) is intentionally excluded; applying
case to Markdown would corrupt code spans, links, and emphasis markup.

---

## Board-Level Styling

Apply CSS-like styles to any board or nested layout section:

```yaml {contract=board-root}
rows:
  - title: "Styled Section"
    style:
      background: "#f0f4f8"
      border:
        width: 2
        color: "#667eea"
        radius: 8
      padding: "16px"
      font:
        color: "#333"
    cols:
      - text: Content
```

### Supported Style Properties

| Property | Example | SVG | HTML | Description |
|----------|---------|:---:|:----:|-------------|
| `background` | `"#f5f5f5"` | ✅ | ✅ | Background color (hex, rgb, named) |
| `border` | `"2px solid #ddd"` or `{width: 2, color: "#ddd", radius: 8}` | ✅ | ✅ | Border: CSS shorthand string, or a `width` / `color` / `radius` group |
| `font.color` | `"#333"` | ✅ | ✅ | Text color. Titles and headings use it unless `title.font.color` is set. |
| `padding` | `"16px"` | ✅ | ✅ | Inner spacing (affects content layout) |
| `margin` | `"8px 16px"` | ❌ | ✅ | Outer spacing |
| `gap` | `"12px"` | ✅ | ✅ | Override gap between child items |

### Padding & Sizing

Padding is accounted for in layout calculations. When you add padding to a board:

1. The board's children have less available space
2. Content is properly inset from the border
3. Height calculations include the padding

```yaml {contract=board-root}
# Padding formats (CSS-style)
rows:
  - style:
      padding: "16px"           # All sides equal
    cols:
      - text: Content
  - style:
      padding: "8px 16px"       # Vertical, horizontal
    cols:
      - text: Content
  - style:
      padding: "8px 16px 12px"  # Top, horizontal, bottom
    cols:
      - text: Content
  - style:
      padding: "8px 16px 12px 4px"  # Top, right, bottom, left
    cols:
      - text: Content
```

### Border Styling

`border` takes the CSS shorthand string or a group; `radius` rounds the corners
and exists only in the group form:

```yaml {contract=board-root}
rows:
  - title: "Shorthand"
    style:
      border: "2px solid #667eea"  # width style color
    cols:
      - text: Content
  - title: "Group"
    style:
      border:
        width: 2
        color: "#667eea"
        radius: 8
    cols:
      - text: Content
```

### Example: Styled Cards

Create card-style sections with backgrounds and borders:

```yaml {contract=board-root}
cols:
  - text: "### Success Card"
    style:
      background: "#c8e6c9"
      border:
        width: 2
        color: "#4caf50"
        radius: 12
      font:
        color: "#1b5e20"

  - text: "### Warning Card"
    style:
      background: "#fff3e0"
      border:
        width: 2
        color: "#ff9800"
        radius: 12
```

---

## Layout Sizing

### Automatic Sizing

dbt Charts automatically calculates sizes based on content:

- **Charts**: 300px default height (KPIs: 100px, Tables: 250px)
- **Titles**: Height based on font size and text length
- **Markdown content**: Height based on rendered text with word-wrapping

### User-Specified Widths

In `cols` layouts, specify widths for individual items:

```yaml {contract=board-fragment}
cols:
  - width: "30%"    # 30% of available width
    rows:
      - sidebar_chart
  - width: "70%"    # 70% of available width
    rows:
      - main_chart
```

Supported formats:
- Percentages: `"30%"`, `"70%"`
- Pixels: `"200px"`, `"400px"`
- Auto (default): Remaining space divided equally

### Gap Control

Control spacing between items:

```yaml {contract=board-fragment}
# Per-section gap override
rows:
  - title: "Compact Section"
    style:
      gap: "8px"  # Smaller gap between children
    cols:
      - a
      - b
```

### Content-Aware Heights

Heights are calculated based on content type:

| Content Type | Default Height |
|--------------|----------------|
| Standard chart | 300px |
| KPI card | 100px |
| Table | 250px |
| Title | Based on text |
| Markdown | Based on rendered content |

In `cols` layouts, all items get the same height (maximum of their content heights) for proper alignment.

---

## Number Formatting

dbt Charts uses [d3-format](https://d3js.org/d3-format) spec strings everywhere numbers appear: chart axis labels, KPI tiles, and table cells all share the same format spec language.

### Format spec syntax

The d3-format spec grammar is:

```text
[[fill]align][sign][symbol][0][width][,][.precision][~][type]
```

| Token | Meaning | Example |
|-------|---------|---------|
| `fill` | Padding character (default space) | `0>10.2f` |
| `align` | `>` right · `<` left · `^` center · `=` sign-then-pad | `<10.2f` |
| `sign` | `-` minus-only · `+` always · `(` parens negatives · ` ` space | `+,.2f` |
| `symbol` | `$` currency prefix · `#` alternate form | `$,.2f` |
| `0` | Zero-pad to width | `06.2f` |
| `width` | Minimum output width | `10.2f` |
| `,` | Thousands separator | `,.2f` |
| `.precision` | Decimal digits (or significant figures for `s`, `g`, `r`) | `.2f` |
| `~` | Trim trailing zeros and decimal point | `.1~%` |
| `type` | Format type; see table below | `f` |

**Types:**

| Type | Description | Spec | Result |
|------|-------------|------|--------|
| `f` | Fixed-point | `,.2f` on 1234.56 | `1,234.56` |
| `%` | Percentage (×100 + %) | `.1~%` on 0.05 | `5%` |
| `p` | Percentage to significant digits | `.1p` on 0.1234 | `10%` |
| `e` | Exponential | `.2e` on 1234.56 | `1.23e+3` |
| `s` | SI prefix | `~s` on 1500000 | `1.5M` |
| `g` | General (shorter of `e`/`f`) | `.3g` on 0.001234 | `0.00123` |
| `r` | Rounded significant digits | `.2r` on 12.56 | `13` |
| `d` | Integer | `d` on 12.9 | `13` |
| `n` | Locale number (same as `,g`) | `n` on 1234 | `1,234` |
| `b` | Binary | `#b` on 255 | `0b11111111` |
| `o` | Octal | `#o` on 255 | `0o377` |
| `x` / `X` | Hex, lower / upper | `#x` on 255 | `0xff` |
| `c` | Character data (verbatim) | `c` on 1234.5678 | `1234.5678` |

Every d3-format type works in every format slot: axis labels, KPI tiles and table cells all resolve the same grammar, so a spec that renders on an axis renders identically in a KPI.

**Bad specs fail at compile.** A format string that is not a predefined engine name, a `style.formats` alias, or a valid d3-format spec fails `dct validate` and `dct render` with `ERR-FORMAT-INVALID`, pointing at the line and offering a "did you mean" hint, so a typo like `percent_1` is caught before anything renders, not dropped silently.

**`B`-for-billion divergence.** dbt Charts's Python formatter (KPI tiles and table cells) maps the SI giga prefix `G` to `B` so that `1.5G` displays as `1.5B`. Chart axes use real d3.js in the browser, which emits `G`. This is a deliberate dbt Charts extension. The `number` format rounds to 3 significant figures and uses `K/M/B/T` with no space (analytic; narrative `k/mn/bn/trn`) in dbt Charts (vs `k/M/G/T` in d3).

For the full d3-format reference see <https://d3js.org/d3-format>.

### Numeric display conventions

dbt Charts's defaults for numeric display on dashboard surfaces. The d3 spec language above is the mechanism; the conventions below are the house style that governs which spec to reach for.

**Prefer predefined names over raw d3 specs.** Use `currency`, `currency_whole`, `currency_full`, `percent`, `percent_delta`, `integer`, `delta`, `number` from the engine-predefined set ([Format names and aliases](#format-names-and-aliases) above). Raw d3 specs only when no predefined name fits, for example, sub-1% percent precision needs `".2%"`. Raw specs work, but a board full of them is harder to read and won't benefit from future engine improvements to the house formatters.

**KPI support deltas without a glyph: use `style.support.format: delta`, not `integer`.** `format: integer` (`,.0f`) drops the sign on positive values; a support value of `+31` renders as bare `31`, direction-blind. `format: delta` (`+,d`) forces the leading sign on positive values (d3 emits the minus sign on negatives either way). Reserve `integer` for values that are not deltas (counts, totals). When the support row already carries a directional glyph (`▲`/`▼` via `support.glyph`), the icon communicates direction and either format reads fine.

**Currency: reach for the bare name.** `format: currency` (`$.3~s`) is the dashboard default (`$1.2M`, `$47`) because the digits below the top three add precision a reader doesn't use at a glance and crowd KPI rails and table columns. `format: currency_whole` (`$,.0f`) writes the number out without cents. Reserve `format: currency_full` (`$,.2f`) for surfaces that demand reconciliation accuracy: billing breakdowns, financial statements, reports where exact match-to-source matters. Negative currency uses a minus prefix (`-$1,234`), not accounting parens.

**Two notation families ship with the theme.**

| Family | Form | Use for |
|---|---|---|
| Analytic | `$2.5M`, no space before the suffix, uppercase `K`/`M`/`B`/`T` | Dashboard chrome: axes, KPIs, dense tables, tooltips |
| Narrative | `$2.5mn`, no space, lowercase `k`/`mn`/`bn`/`trn` | Prose surfaces: text cards, annotations, page/section/chart titles |

Theme choice (`clarity`, `neon`, etc.) is visual identity. Notation family is independent; a narrative-feeling theme can still use analytic notation in its axes.

**Precision is a group decision.** The reader's context (a single headline KPI vs. a long table column) determines how much precision is tolerable as much as the value's magnitude does. Magnitude sets the default; surface modulates.

**Default by magnitude:**

| Range | Format | Examples |
|---|---|---|
| ≥ 20% | whole percent | `23%`, `47%`, `89%` |
| 1–20% | one decimal (`percent`) | `1.2%`, `8.7%`, `12.5%` |
| < 1% | two decimals (raw d3 `".2%"`) | `0.12%`, `0.045%` |

**Modulate by surface.** A single headline KPI or short rail (1–4 values) can afford one more decimal than the band default; there's nothing to scan against. A long table column or axis (>10 similar-magnitude values) is a real tradeoff: whole-percent aids scan-uniformity and distribution reading; the band default's precision aids close comparison across rows. The right call depends on the column's actual use: distribution scan favors the simpler form, close comparison favors keeping the decimal. Adjacent surfaces showing the same metric may format differently: a reconciliation table at `.0%` while its headline KPI shows `.1%`.

**Meaningful-precision override.** Some metrics carry signal in tenths of a percent regardless of magnitude or surface: A/B test conversion rates (4.27% vs 4.31% is a 1% relative lift), MoM churn at basis-point resolution, conversion rates in a tight range. For these, use `".2%"` regardless of band. Precision is fundamentally a data-layer call; if the data carries signal in tenths or hundredths, the chart should show it.

**Zero values strip trailing decimals, even when siblings have them.** Render `0`, `$0`, `0%`; never `0.00`, `$0.00`, `0.0%`. A `$0` KPI picks `format: currency_whole` even if its partner KPI uses `format: currency` for sub-dollar precision. The value is exactly zero; sibling-matching decimals fake precision the data doesn't have.

**NULL renders as `—` (em-dash), never as `0`.** They are different claims about the data.

**A KPI whose query returns zero rows raises an error.** A silent `0` or `—` hides a real problem (broken query, empty filter, wrong source).

**Tables anchor the currency symbol.** Default `symbol_mode: anchors` puts `$` on the first row of a column; rows below omit it. The first row anchors the column for the rows below.

**Compaction is a column-level decision, not per-value.** Compact when ≥4 similar-magnitude values exceed 10,000, or when surface density demands it. With 2–3 values the longer form usually reads fine. Adjacent surfaces showing the same metric may compact differently: a reconciliation table can show full precision while the headline KPI compacts.

---

## Best Practices

### Consistent Styling

- Use the same color palette throughout a dashboard
- Keep font choices consistent
- Use grid lines consistently (all on or all off)

### Accessibility Considerations

- Choose colorblind-friendly palettes
- Ensure sufficient contrast
- Use labels and legends for clarity

### Color Values

A color field accepts:

- hex: `#fff`, `#1d4ed8`, `#1d4ed880`
- a CSS color name: `steelblue`, `transparent`, `none`
- a palette token: `dbt-grays.surface-subtle`, `category[2]`
- a color function: `rgb()`, `hsl()`, `oklch()`, `var(--brand)`

Anything else (`url(...)`, gradients, `{{ ... }}`, characters such as `;` `{` `}` `"`) fails validation at the field. A bare name that is not a CSS color name or palette token fails when the style resolves. Table column colors may also name a query column.

A font `family` is a CSS stack. Names that are not valid CSS identifiers, such as `Source Serif 4`, are quoted for you. A family name may not contain a comma.

### Color Choices

- **Categorical data**: Use distinct colors (`editorial-10`)
- **Sequential data**: Use gradient palettes (`dbt-seq-blue`, `dbt-seq-green`)
- **Avoid**: Too many colors (5-7 max for clarity)

### Performance

- Styling has minimal performance impact
- Use global style when possible (more efficient)
- Override only when necessary

---

## Related

- [Charts](charts/index.md) - Chart styling options
- [Boards](boards/index.md) - Layout and organization

# VS Code & Cursor Extension (https://docs.dbtcharts.com/editor-extension/)

# VS Code & Cursor Extension

The dbt Charts extension turns any editor built on VS Code (VS Code itself, Cursor,
and other forks) into a dashboard authoring environment: syntax highlighting for
board YAML (including the SQL and Jinja inside it), snippets for every chart and
layout type, and a live split-pane preview of the rendered dashboard next to the
file you are editing.

![A dbt project open in VS Code: studio-scorecard.yml in the editor beside the live preview of the rendered board](editor-extension-assets/vscode-light.webp#only-light){: width="2000" height="1087" }
![A dbt project open in VS Code: studio-scorecard.yml in the editor beside the live preview of the rendered board](editor-extension-assets/vscode-dark.webp#only-dark){: width="2000" height="1087" }

---

## Install

**VS Code:** [Install from the VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=dbtLabsInc.dbtcharts),
or [open it directly in VS Code](vscode:extension/dbtLabsInc.dbtcharts).

**Cursor and other VS Code forks:** install from
[Open VSX](https://open-vsx.org/extension/dbtLabsInc/dbtcharts), the registry
they resolve extensions from.

Or search for **dbt Charts** in the editor's **Extensions** panel. The
extension ID is `dbtLabsInc.dbtcharts` in every editor, so it also installs
from a terminal:

```bash
code --install-extension dbtLabsInc.dbtcharts
cursor --install-extension dbtLabsInc.dbtcharts
```

The editor keeps the extension updated, the same as any other marketplace
install. To pin a specific version instead, VS Code accepts a version suffix
(Cursor does not document a CLI version-pin flag):

```bash
code --install-extension dbtLabsInc.dbtcharts@<version>
```

The [`dct init`](cli/init.md) setup wizard also offers to install the
extension for any editor it finds on your `PATH`, and `dct init code` or
`dct init cursor` does it directly.

### Requirements

- VS Code 1.91 or later (or a fork of an equivalent version, such as Cursor)
- The [`dct` CLI](guides/installation.md) for preview, export, and validation;
  highlighting, snippets, and completion work without it

---

## Which files it recognizes

The extension switches a file into dbt Charts mode (highlighting, snippets, and
completion) when any of these hold:

| Rule | Examples |
|------|----------|
| File is named `dbt_charts.yml` | your project config |
| Filename ends in `.board.yml` | `sales.board.yml` |
| Any `.yml`, `.yaml`, or `.md` file under a `charts/` directory **inside a project** (a folder with a `dbt_charts.yml` or `dbt_project.yml` ancestor) | `charts/sales.yml`, `charts/partials/_header.yml` |
| Any other `.yml` / `.yaml` file whose content has a `queries:` or `charts:` block **and** a `rows:`, `cols:`, `grid:`, or `tabs:` layout | a dashboard file kept outside `charts/` |

The `charts/` rule matches on an exact path segment inside a recognized project
root, so a directory named `my_charts_backup/` (or a `charts/` folder in a repo
with no project marker) is left alone. The content rule is a fallback for files
kept outside `charts/`; it applies once the extension is active in the
workspace, which any of the other rules (or opening the preview) takes
care of.

---

## Live preview

Press **Cmd+Shift+V** (macOS) or **Ctrl+Shift+V** (Windows/Linux) to open the
rendered dashboard beside your file, or run **dbt Charts: Open Preview to the
Side** from the Command Palette. The preview:

- **Re-renders as you type**, debounced, and again on every save
- **Renders real data.** It shells out to `dct render` in your project, so
  queries hit the same sources your dashboards use in production
- **Is a static render, and says so.** The preview shows `dct render` output, an
  artifact. Its variable pills are a picture of the controls, not the controls,
  and its board links point at a server the panel does not have. Clicking either
  one opens the board in your browser behind [`dct serve`](cli/serve.md), where
  they are live
- **Navigates back to source.** Click a chart in the preview to jump to its
  definition in the YAML

Preview requires the `dct` CLI. The extension looks for it in a `venv/`,
`.venv/`, or `env/` beside your workspace before falling back to `PATH`; point
[`dbt-charts.cli.path`](#settings) at it directly if it lives elsewhere. When a
render fails,
the preview pane shows the same structured error you would get from
[`dct validate`](cli/validate.md), so you can fix the YAML without leaving the
editor.

---

## Syntax highlighting

Board YAML is highlighted as a language in its own right, not as generic YAML:

- YAML structure, with dbt Charts's own keywords (chart types, input types, and
  top-level keys) called out distinctly
- **SQL inside `sql:` blocks**, highlighted as SQL
- **Jinja templating** (`{{ ... }}`, `{% ... %}`) inside those SQL blocks

The highlighting rules are generated from the same schema the engine compiles
against, so new chart types and keys light up as soon as you upgrade.

---

## Completion

Value completion for the fields whose options are a fixed set (`theme:`, chart
`type:`, and variable `input:`) works out of the box, with no Python and no
other extensions installed. The values come from the schema shipped inside the
extension, so you get the real list rather than whatever words happen to be
elsewhere in the buffer.

Completion for keys, query references, and chart references is part of the
optional [language server](#optional-language-server).

---

## Snippets

Type a prefix and press <kbd>Tab</kbd> to expand a working scaffold.

| Prefix | Expands to |
|--------|------------|
| `dbt-charts:board` | Complete board skeleton |
| `query` | SQL query definition |
| `query-filter` | Query with a Jinja `filter()` call |
| `query-dbt` | Query using dbt `ref()` |
| `chart` | Generic chart definition |
| `chart:kpi` | KPI / metric card |
| `chart:table` | Data table |
| `chart:map` | Geographic map |
| `variable:select` | Select dropdown variable |
| `variable:select-query` | Select variable with options from a query |
| `variable:daterange` | Date range picker variable |
| `variable:slider` | Number slider variable |
| `layout:rows` | Vertical row layout |
| `layout:cols` | Horizontal column layout |
| `layout:grid` | Grid layout |
| `layout:tabs` | Tabbed layout |
| `source:duckdb` | DuckDB source block |
| `source:postgres` | PostgreSQL source block |
| `jinja:filter` | Jinja `filter()` call for a `WHERE` clause |
| `jinja:ref` | dbt `ref()` call |
| `jinja:if` | Jinja `if` block |

Most prefixes have plain-language aliases too (`dashboard`, `query`, `kpi`,
`grid`, and so on) so the snippet surfaces even if you don't remember the
exact prefix.

---

## Export and validation

Run these from the Command Palette (**Cmd/Ctrl+Shift+P**) with a board file open:

- **dbt Charts: Export as HTML**: render to a standalone HTML file
- **dbt Charts: Export as PNG**: render to an image
- **dbt Charts: Validate Dashboard**: run a full [`dct validate`](cli/validate.md)
  pass and report the result

All three call the `dct` CLI, so the output is identical to running
[`dct render`](cli/render.md) yourself.

---

## Validation in other editors

Any editor with a YAML language server (Neovim, JetBrains, Zed, vscode.dev) can
complete and validate a board against its published JSON Schema. Put this line
first in the file:

```text
# yaml-language-server: $schema=https://docs.dbtcharts.com/schema/board.json
```

`dct init` writes it into the starter board, and `dct migrate` keeps it first
and stamps `_schema_version` below it. The URL serves the latest dbt Charts
release's schema and becomes available with the first release that publishes
one. After upgrading, run `dct migrate` to clear any warnings about older
syntax. To pin a release, use
`https://docs.dbtcharts.com/schema/<version>/board.json`. The file is large and meant for validators, not for AI
agents to read: they should use [`dct validate`](cli/validate.md) instead.

---

## AI integration

The extension pairs with the dbt Charts MCP server, which gives Cursor's and VS
Code's AI assistants tools to inspect your schema, run queries, and render
dashboards. Run **dbt Charts: Setup AI Integration (MCP)** from the Command
Palette and it wires up the workspace for the editor you're in, writing
`.cursor/mcp.json` in Cursor or `.vscode/mcp.json` in VS Code. In Cursor, the
extension offers this once per workspace when no dbt Charts entry is configured
yet.

The equivalent from a terminal:

```bash
dct init mcp           # auto-detect installed AI clients
dct init mcp cursor    # or target one
dct init mcp vscode
```

See [`dct mcp`](cli/mcp.md) for the server and the tools it exposes.

---

## Optional language server

A Python language server ships inside the extension and adds deeper editing
features, checked against the real compiler rather than a static schema:

- **Diagnostics as you type**: every error and warning the compiler produces
  (invalid chart and input types, undefined query references, missing required
  fields), each with a clickable code that opens its documentation page.
  Warnings about redundant authored elements (unused charts, redundant labels)
  appear faded via VS Code's `Unnecessary` tag rather than as a squiggle.
- **Diagnostics on preview render**: the 15 render-time warnings (narrow bar
  bands, dominant pie segments, zero-row queries, and others that require query
  results to evaluate) appear in a dedicated **dbt-charts-render** group in the
  Problems panel each time you trigger a preview. They are cleared automatically
  when you edit the file, so stale warnings never overlap with live compiler
  output.
- Completion for top-level keys, query references, and chart references
- Hover documentation for chart types, input types, and Jinja functions
- **Go to Definition**: Ctrl/Cmd+Click a query or chart reference to jump to
  where it's defined
- Document outline for the variables, queries, and charts sections

It is **on by default** and starts the first time you open a board file, so a
workspace with no board YAML never launches it; the interpreter discovery that
makes some systems prompt for filesystem access waits until you are actually
editing a dashboard.

It needs a Python interpreter with dbt Charts installed. If the server can't
start, a **dbt Charts: no diagnostics** indicator appears in the status bar;
click it for the reason. Syntax highlighting keeps working either way. Point it
at a specific interpreter with:

```json
{
  "dbt-charts.languageServer.pythonPath": "/path/to/your/venv/bin/python"
}
```

To turn it off entirely:

```json
{
  "dbt-charts.languageServer.enabled": false
}
```

The interpreter you point at needs dbt Charts installed:

```bash
pip install "dbt-charts"
```

The language server's own protocol dependencies ship inside the extension, so
this is the only environment requirement. Everything else in this page works
without it.

---

## Commands

| Command | Default shortcut |
|---------|------------------|
| dbt Charts: Open Preview | none |
| dbt Charts: Open Preview to the Side | `Cmd/Ctrl+Shift+V` |
| dbt Charts: Refresh Preview | none |
| dbt Charts: Export as HTML | none |
| dbt Charts: Export as PNG | none |
| dbt Charts: Validate Dashboard | none |
| dbt Charts: Setup AI Integration (MCP) | none |

---

## Settings

| Setting | Default | What it does |
|---------|---------|--------------|
| `dbt-charts.cli.path` | `dct` | Path to the dbt Charts CLI executable |
| `dbt-charts.preview.autoRefresh` | `true` | Re-render the preview as the file changes |
| `dbt-charts.preview.refreshDelay` | `500` | Milliseconds to wait after a change before re-rendering |
| `dbt-charts.languageServer.enabled` | `true` | Run the Python language server (starts when you open your first board file) |
| `dbt-charts.languageServer.pythonPath` | `python` | Interpreter used to run the language server |
| `dbt-charts.trace.server` | `off` | Log LSP traffic to the dbt Charts output channel |

Point `dbt-charts.cli.path` at your project's virtualenv (for example
`.venv/bin/dct`) when dbt Charts is installed per-project rather than globally.

---

## Troubleshooting

**Preview says the render command failed, or `dct` was not found.**
The extension could not run the CLI. Check that `dct --version` works in a
terminal, and if dbt Charts lives in a virtualenv, set `dbt-charts.cli.path` to that
environment's `dct`.

**A dashboard file isn't highlighted.**
Its path probably doesn't match any of the rules under
[Which files it recognizes](#which-files-it-recognizes). Move it under `charts/`,
rename it to `*.board.yml`, or set the language mode manually from the status
bar.

**The language server won't start.**
Confirm that the interpreter in `dbt-charts.languageServer.pythonPath` has
dbt Charts installed, then set `dbt-charts.trace.server` to `verbose` and check
the dbt Charts output channel.

**The preview renders but charts are empty.**
That's a data problem, not an editor problem; run
[`dct query`](cli/query.md) against the same source to check what the query
returns.

---

## Related

- [Installation & Setup](guides/installation.md): installing the `dct` CLI
- [`dct init`](cli/init.md): project setup, including the extension
- [`dct mcp`](cli/mcp.md): the MCP server the AI integration command configures
- [Getting Started](guides/getting-started.md): building your first dashboard

# Overview (https://docs.dbtcharts.com/integrations/)

# Integrations

dbt Charts provides integrations for embedding rendered boards and charts
directly in external documentation and publishing tools.

## Available Integrations

| Integration | Status | Description |
|-------------|--------|-------------|
| [MkDocs](mkdocs.md) | Supported | Embed boards in MkDocs sites via fenced `dbt-charts` and `dbt-charts-example` blocks |
| [Streamlit](streamlit.md) | Supported | Embed a board in a Streamlit app. Streamlit in Snowflake is not yet verified |
| Sphinx | Planned | Directive for reStructuredText / Sphinx projects |
| Hugo | Planned | Shortcode for Hugo static sites |

## Architecture

Integrations render through the same **project session API**
(`dbt_charts.agent_api.ProjectSession`).  `ProjectSession.render_board()`
handles the full compile-execute-render pipeline and returns a typed
envelope carrying embeddable output (SVG, HTML, PNG, or PDF).  Each
integration is a thin adapter that:

1. Detects embed blocks or directives in the host tool's source format
2. Resolves the board file (or its raw YAML) relative to the project
3. Opens a `ProjectSession` and calls `render_board()` to get rendered output
4. Injects the output into the host tool's build pipeline

This keeps the core dbt Charts architecture undistorted by any single
platform's conventions. See [MkDocs](mkdocs.md) for a worked example.

# MkDocs Integration (https://docs.dbtcharts.com/integrations/mkdocs/)

# MkDocs Integration

Embed live dbt Charts boards and examples in your MkDocs site with fenced code
blocks handled by `pymdownx.superfences`.

## Installation

Install MkDocs, `pymdown-extensions`, and dbt Charts in the same environment:

```bash
pip install mkdocs pymdown-extensions dbt-charts
```

If you prefer the packaged convenience extra, `dbt-charts[mkdocs-plugin]` still
installs the base MkDocs dependency set, but the supported embed path is the
fenced markdown handler documented below rather than a separate MkDocs plugin.

## Configuration

Register the custom fences in your `mkdocs.yml`:

```yaml {contract=unverified}
markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: dbt-charts
          class: dbt-charts
          format: !!python/name:dbt_charts.integrations.markdown.fence_dbt_charts
        - name: dbt-charts-example
          class: dbt-charts-example
          format: !!python/name:dbt_charts.integrations.markdown.fence_dbt_charts_example
```

The handlers resolve `file=` paths against your project root. Inline YAML and
`file=` inputs are both supported. In dbt Charts' published docs, full runnable
examples are kept inline so the markdown stays self-contained.

## Usage

Use `dbt-charts` when you want a render-only embed:

````markdown
## Revenue Overview

    ```dbt-charts {file=charts/revenue.yml}
    ```
````

Inline YAML also works:

````markdown
```dbt-charts
charts:
  revenue:
    query: sales
    type: bar
    x: product
    y: revenue
rows:
  - revenue
```
````

## Example Layouts

Use `dbt-charts-example` when you want the YAML and render together:

````markdown
    ```dbt-charts-example {file=charts/revenue.yml}
    ```
````

Supported `format=` options:

- `side-by-side` (default)
- `stacked`
- `render-only`
- `yaml-only`

Example:

````markdown
    ```dbt-charts-example {file=charts/revenue.yml format=render-only}
    ```
````

## Playground Links

`dbt-charts-example` blocks include playground links automatically. Inline YAML is
compressed into the playground URL; file-backed examples use the resolved YAML
source.

## How It Works

1. MkDocs parses fenced blocks through `pymdownx.superfences`.
2. The dbt Charts fence handlers resolve either inline YAML or `file=` input.
3. dbt Charts compiles and renders the board during the docs build.
4. The rendered output is injected into the generated HTML.
5. Render failures become visible error `<div>` blocks instead of crashing the
   entire build.

## Board Rendering API

If you are building another integration, open a project session and render
directly:

```python
from dbt_charts.agent_api import ProjectSession
from dbt_charts.core.board import raise_on_dashboard_failure

session = ProjectSession.open("path/to/your/project")
try:
    board = session.project.path("charts/overview.yml").read_board()
    rendered = session.render_board(board=board, format="svg")
    raise_on_dashboard_failure(rendered)
    svg = rendered.data  # str for svg/html, bytes for png/pdf
finally:
    session.close()
```

See the [Integrations overview](index.md) for the broader architecture.

# Streamlit Integration (https://docs.dbtcharts.com/integrations/streamlit/)

# Streamlit Integration

Render a dbt Charts board inside a Streamlit app with `st_board()`, from the
`dbt-charts[streamlit]` extra.

## Installation

```bash
pip install "dbt-charts[streamlit]"
```

Requires Streamlit 1.51 or later.

## Usage

```python
import streamlit as st
from dbt_charts.integrations.streamlit import st_board

st.title("Revenue")
st_board("charts/revenue.yml", project_dir="path/to/your/project")
```

`st_board()` compiles and renders the board (inline SVG, no external requests)
and mounts it at the width of its Streamlit column, keeping the board's
proportions. A board that fails as a whole raises, rather than drawing an
empty frame. A single chart that fails still draws, as an error card in its
place.

## Variable controls

The board's own variable controls work the way they do under `dct serve`: a
viewer opens a control, picks a value, and the board renders again with it.
Tabs work the same way. The app needs no widgets of its own for this.

What the viewer picked is kept in Streamlit's session state, one entry per
board path. Pass `key=` to mount the same board twice on one page.

## Setting a variable from the app

`variables=` sets a board's `variables:` from the app, for example from a
Streamlit widget. A value the app passes wins over what the viewer picks in
the board, so pass only the variables the app owns. The board still draws a
control for such a variable, and a pick there is overridden on the next
render:

```python
import streamlit as st
from dbt_charts.integrations.streamlit import st_board

year = st.selectbox("Year", [2023, 2024, 2025])
st_board(
    "charts/revenue.yml",
    project_dir="path/to/your/project",
    variables={"year": year},
)
```

## Streamlit in Snowflake

Streamlit in Snowflake (SiS) apps run with a live Snowpark session and no dbt
profile to connect with. Pass that session in, and SQL queries against a
`snowflake` source run through it instead:

```python
import streamlit as st
from snowflake.snowpark.context import get_active_session
from dbt_charts.integrations.streamlit import st_board

session = get_active_session()
st_board(
    "charts/revenue.yml",
    project_dir="path/to/your/project",
    session=session,
)
```

Without `session=`, `st_board()` renders like any other local dbt Charts
project (DuckDB or a local dbt profile).

These limits apply to queries that run through the session:

- A query with `setup_sql:` is refused, because a Snowpark session runs one
  statement per call.
- The session must be using the database and schema the source declares.
  Unqualified table names resolve in the session's current database and
  schema, so a mismatch is refused with an error naming both. Call
  `session.use_database(...)` and `session.use_schema(...)` before
  `st_board()`.
- The source's `account`, `role`, and `warehouse` are not applied. Queries
  run in the session's account, with its role's privileges, on its warehouse.
- A refused or failed query shows as an error card on its chart.
- A source's `attribution:` labels are not sent. They travel in the dbt query
  header, which this path does not use.
- A source's `max_query_duration_seconds` is not applied. The session belongs
  to the app, so statement timeouts are whatever the app set on it.

### Reruns re-query

Streamlit re-runs the whole script on every interaction, including a pick in
a board control, and each `st_board()` call compiles the board and runs its
queries again. Against a
warehouse that is billed work on every click. Snowflake's own result cache
serves a repeated identical query at no compute cost; beyond that, caching is
the app's job.

### Container runtime notes

SiS apps that need `dbt-charts[streamlit]` from PyPI run in **container
runtime**, not the default warehouse runtime, which has no outbound package
access. Container runtime reaches PyPI through either an artifact repository
you configure, or an external access integration your account admin grants.

### Whose privileges the queries run with

By default a Streamlit in Snowflake app runs with
[owner's rights](https://docs.snowflake.com/en/developer-guide/streamlit/object-management/owners-rights):
queries run as the app owner's role, so a row access policy evaluates against
the owner and every viewer sees the same rows. Snowflake documents a
restricted caller's rights option for container-runtime apps. Read their page
before relying on per-viewer row policies inside an app.

### Not yet verified

These have not been verified against a real Streamlit in Snowflake (SiS)
environment:

- Queries through a live Snowpark session.
- Whether SiS's content-security policy allows the inline `<script>` a
  rendered board carries. That script drives hover states and the variable
  controls. If it is blocked, the charts and layout still render, without
  tooltips and with controls that do not respond.
- Whether the full `dbt-charts[streamlit]` dependency set installs cleanly in
  SiS's container runtime.

# Overview (https://docs.dbtcharts.com/examples/)

# Examples

Working examples for common dbt Charts patterns. Except for the inline-data
quick start, the complete boards query **Dundersign**, the demo dataset
bundled with the playground; paste them there and they render as-is.

Start here:

- [Quick Start Example](quickstart.md)
- [KPI Board Example](kpi-dashboard.md)
- [Interactive Board Example](interactive.md)
- [Nested Layouts Example](nested-layouts.md)
- [Drill-Down Example](drill-down.md)

# Quick Start Example (https://docs.dbtcharts.com/examples/quickstart/)

# Quick Start Example

`dct init` creates a `charts/guide.yml` starter board in your project.
It works without a database: its sample data is inline.
You can open it in your browser immediately with `dct serve`.

This page walks through a minimal example to explain the key concepts.

---

## Complete Board

```yaml {contract=unverified}
title: "Hello World Board"

source: db

queries:
  sales:
    sql: |
      SELECT month, revenue
      FROM dundersign_serving.monthly_metrics

rows:
  - title: "Monthly Revenue"
    charts:
      revenue_chart:
        title: "Revenue by Month"
        query: queries.sales
        type: bar
        x: month
        y: revenue
    cols:
      - revenue_chart
```

---

## Step-by-Step Explanation

### 1. Board Definition

```yaml {contract=board-root}
title: "Hello World Board"
```

- `title`: Display title (optional but recommended)

### 2. Query Definition

```yaml {contract=unverified}
queries:
  sales:
    sql: |
      SELECT month, revenue
      FROM dundersign_serving.monthly_metrics
```

- `sales`: Query name (use descriptive names)
- `sql`: A plain SQL query, run against the `source:` declared on the board
- `dundersign_serving.monthly_metrics`: A pre-aggregated rollup from the Dundersign demo dataset

### 3. Section and Chart

```yaml {contract=unverified}
rows:
  - title: "Monthly Revenue"
    charts:
      revenue_chart:
        title: "Revenue by Month"
        query: queries.sales
        type: bar
        x: month
        y: revenue
    cols:
      - revenue_chart
```

- `rows`: Top-level layout (vertical stack)
- `title`: Section title
- `charts`: Chart definitions
- `cols`: Nested horizontal layout containing the chart reference
- `revenue_chart`: Chart identifier
- `query: queries.sales`: References the query defined above (use `queries.` prefix for clarity)
- `type: bar`: Bar chart type
- `x: month`: X-axis uses the `month` column
- `y: revenue`: Y-axis uses the `revenue` column

---

## How to Run It

1. Save this YAML to a file (for example, `hello_world.yml`)
2. Validate it:
   ```bash
   dct validate hello_world.yml
   ```
3. Preview it:
   ```bash
   dct serve
   ```
4. Open your browser to the URL printed by `dct serve` on startup

---

## What You'll See

- A bar chart showing revenue by month
- Data fetched via a plain SQL query against your warehouse
- A responsive layout that works on any device

---

## Next Steps

- **[KPI Board](kpi-dashboard.md)** - Add multiple KPIs
- **[Interactive Board](interactive.md)** - Add variables and filters
- **[Read the Queries Guide](../queries.md)** - Learn more about queries
- **[Read the Charts Guide](../charts/index.md)** - Learn more about charts
- **[CLI Reference](../cli/index.md)** - Complete CLI command reference
- **[Getting Started Guide](../guides/getting-started.md)** - Step-by-step tutorial

# KPI Board Example (https://docs.dbtcharts.com/examples/kpi-dashboard/)

# KPI Board Example

A simple board showing multiple key performance indicators (KPIs), built on
the Dundersign demo dataset; paste it into the playground and it renders
as-is.

---

## Complete Board

```dbt-charts-example
title: "Executive KPIs"

source: db

queries:
  totals:
    sql: |
      SELECT
        SUM(revenue) AS total_revenue,
        SUM(new_users) AS new_users,
        SUM(documents_completed) AS documents_completed,
        SUM(tickets_resolved) AS tickets_resolved
      FROM dundersign_serving.monthly_metrics

rows:
  - grid:
      columns: 24
      items:
        - item: revenue_kpi
          width: 6
        - item: users_kpi
          width: 6
        - item: documents_kpi
          width: 6
        - item: tickets_kpi
          width: 6

    charts:
      revenue_kpi:
        label: "Total Revenue"
        query: queries.totals
        type: kpi
        value: total_revenue

      users_kpi:
        label: "New Users"
        query: queries.totals
        type: kpi
        value: new_users

      documents_kpi:
        label: "Documents Completed"
        query: queries.totals
        type: kpi
        value: documents_completed

      tickets_kpi:
        label: "Tickets Resolved"
        query: queries.totals
        type: kpi
        value: tickets_resolved
```

The query reads `dundersign_serving.monthly_metrics`, a pre-aggregated rollup
maintained by Dundersign's dbt project, so the SQL is a plain `SELECT` with
no date functions, portable across warehouses.

---

## Key Concepts Demonstrated

### KPI Chart Type

The `kpi` chart type displays a single metric as a large number:

```yaml {contract=unverified}
revenue_kpi:
  label: "Total Revenue"
  query: queries.totals
  type: kpi
  value: total_revenue
```

- `type: kpi`: KPI chart type (dbt Charts-specific)
- `value: total_revenue`: KPI value; column reference (string column name, required for KPI type)

### Grid Layout

Using a grid layout to arrange multiple KPIs:

```yaml {contract=board-fragment}
grid:
  columns: 24
  items:
    - item: revenue_kpi
      width: 6
    - item: users_kpi
      width: 6
    - item: documents_kpi
      width: 6
    - item: tickets_kpi
      width: 6
```

- `columns: 24`: 24-column grid system
- `items`: List of items to place
- `width: 6`: Each chart takes 6 columns (4 charts × 6 columns = 24 columns total)

### Multiple Values in One Query

A single query can return every KPI's value as its own column:

```yaml {contract=unverified}
queries:
  totals:
    sql: |
      SELECT
        SUM(revenue) AS total_revenue,
        SUM(new_users) AS new_users,
        SUM(documents_completed) AS documents_completed,
        SUM(tickets_resolved) AS tickets_resolved
      FROM dundersign_serving.monthly_metrics
```

Each KPI chart references the same query but displays a different column.

---

## Layout Variants

KPI charts ship in three layouts, selected via `style.variant:`:

- `stacked` (default): value, label, and support on three lines. The fixed slot widths keep multi-KPI rows aligned.
- `inline`: value, label, and support all on one row, baseline-aligned. Good for tight summary strips.
- `compact`: 2-column. Big value on the left; up to two stacked lines on the right, with the bottom right line sharing baseline with the value.

```yaml {contract=unverified}
revenue_kpi:
  label: "Total Revenue"
  query: queries.totals
  type: kpi
  value: total_revenue
  support:
    value: revenue_delta_pct
    label: vs last month
    glyph: ▲
  style:
    variant: inline
    support:
      format: percent_delta
      tone: positive
```

Content sits at the chart root: the `value`, `label`, an optional headline `glyph`, and the `support` line's `value`, `label`, and `glyph`. How it looks sits under `style:`: `variant`, the support row's `format` and `tone`, and a `font` for each slot (`style.value.font`, `style.value.affix.font`, `style.value.glyph.font`, `style.label.font`, `style.support.font`, `style.support.glyph.font`). `style.label.overflow` sets how a long label fits (`clip`, `truncate`, `wrap-two`, `wrap`).

`label:` and `support:` are each independently optional in all three variants. In compact, a `support:` block authored without a `label:` splits across both right-column lines automatically (`glyph + value` on top, support label on the baseline).

`compact` assumes the card is wide enough to fit the value alongside its label and support. Long labels or narrow grid widths can push text past the card's right edge. The `stacked` default wraps its label automatically; if you're authoring compact KPIs at narrow widths, prefer `stacked`.

`inline` handles this itself: when the assembled value + label + support run does not fit the card at its available width, it falls back to the `stacked` arrangement for that card automatically; you don't need to switch variants by hand. A `WARN-KPI-INLINE-VARIANT-FALLBACK-TO-STACKED` warning tells you when this happened, since the card no longer matches the `style.variant: inline` you authored.

---

## Variations and Extensions

### Add Markdown Content

Add context above the KPIs:

```yaml {contract=unverified}
rows:
  - title: "Executive Summary"
    text: |
      # Key Performance Indicators

      Real-time view of business performance.
    grid: ...
    # ... charts
```

### Add Trend Charts

Combine KPIs with trend charts:

This adds a line chart of the raw series next to the KPIs. For a fitted trend
line (a straight regression line overlaid on the data), see
[Trend Lines](../charts/layered-charts.md#trend-lines) in the layered charts
guide.

```yaml {contract=unverified}
queries:
  monthly:
    sql: |
      SELECT month, revenue
      FROM dundersign_serving.monthly_metrics
      WHERE month > (SELECT MIN(month) FROM dundersign_serving.monthly_metrics)
        AND month < (SELECT MAX(month) FROM dundersign_serving.monthly_metrics)
      ORDER BY month

rows:
  - title: "Overview"
    grid:
      columns: 24
      items:
        - item: revenue_kpi
          width: 6
        # ... other KPIs
        - item: revenue_trend
          width: 24

    charts:
      revenue_kpi:
        # ... KPI definition
      revenue_trend:
        query: queries.monthly
        type: line
        x: month
        y: revenue
```

### Add Filters

Add variables to filter the KPIs:

```yaml {contract=board-root}
variables:
  date_range:
    input: daterange
    # No default: starts on the full history

queries:
  totals:
    sql: |
      SELECT
        SUM(revenue) AS total_revenue,
        SUM(new_users) AS new_users
      FROM dundersign_serving.monthly_metrics
      WHERE {{ filter_date_range('month', date_range) }}
```

---

## Related

- [Charts Guide](../charts/index.md) - Learn about KPI charts
- [Boards Guide](../boards/index.md) - Learn about grid layouts
- [Interactive Board Example](interactive.md) - Add variables and filters

# Interactive Board Example (https://docs.dbtcharts.com/examples/interactive/)

# Interactive Board Example

A board with variables and filters that update charts dynamically, built on
the Dundersign demo dataset; paste it into the playground and it renders
as-is.

---

## Complete Board

```dbt-charts-example
title: "Document Activity with Filters"

source: db

variables:
  status:
    input: select
    options:
      static: ["sent", "completed"]
    # No default: starts on All statuses

  date_range:
    input: daterange
    # No default: starts on the full history

  min_pages:
    input: slider
    min: 1
    max: 20
    step: 1
    default: 1

queries:
  filtered_documents:
    sql: |
      SELECT
        status,
        COUNT(*) AS documents,
        ROUND(AVG(page_count), 1) AS avg_pages,
        ROUND(AVG(days_to_complete), 1) AS avg_days_to_complete
      FROM dundersign.documents
      WHERE {{ filter('status', status) }}
        AND {{ filter_date_range('created_at', date_range) }}
        AND {{ filter('page_count', min_pages, '>=') }}
      GROUP BY status
      ORDER BY documents DESC

  monthly:
    sql: |
      SELECT month, revenue, active_users
      FROM dundersign_serving.monthly_metrics
      WHERE {{ filter_date_range('month', date_range) }}
        AND month > (SELECT MIN(month) FROM dundersign_serving.monthly_metrics)
        AND month < (SELECT MAX(month) FROM dundersign_serving.monthly_metrics)
      ORDER BY month

rows:
  - title: "Filtered Document View"
    grid:
      columns: 24
      items:
        - item: documents_chart
          width: 12
        - item: revenue_chart
          width: 12
        - item: documents_table
          width: 24

    charts:
      documents_chart:
        title: "Documents by Status"
        query: queries.filtered_documents
        type: bar
        x: status
        y: documents

      revenue_chart:
        title: "Revenue by Month"
        query: queries.monthly
        type: line
        x: month
        y: revenue

      documents_table:
        title: "Status Details"
        query: queries.filtered_documents
        type: table
```

Note how `date_range` is wired into **both** queries: one variable can drive
any number of charts.

---

## How Variables Work

### Variable Definition

Variables are defined at the board level:

```yaml {contract=board-root}
variables:
  status:
    input: select
    options:
      static: ["sent", "completed"]
    # No default: starts on All statuses
```

- `input`: The UI component (select, slider, daterange, etc.)
- `options`: Available options (static list or dynamic query)
- `default`: Initial value; omit it to start unfiltered

### Wiring Variables to Queries

Variables are referenced in the query SQL: the `filter()` helper skips the
condition entirely when its variable is unset:

```yaml {contract=board-fragment}
queries:
  filtered_documents:
    sql: |
      SELECT status, COUNT(*) AS documents
      FROM dundersign.documents
      WHERE {{ filter('status', status) }}
        AND {{ filter_date_range('created_at', date_range) }}
        AND {{ filter('page_count', min_pages, '>=') }}
      GROUP BY status
```

When a variable changes, the query automatically re-executes with the new values.

---

## User Interaction Flow

1. **User selects status** from dropdown → `status` variable updates
2. **User adjusts date range** → `date_range` variable updates
3. **User moves slider** → `min_pages` variable updates
4. **Query re-executes** with new filter values
5. **Charts update** automatically with new data

---

## Key Concepts

### Handling "All" Values

When a variable can be "All", `filter()` already does the right thing for an
unset value, and a non-required select or multiselect already offers a
clear-selection row back to that unset state, so most boards need nothing
further. If you want "All" to instead appear as one of the visible, selectable
options in the list, use a Jinja conditional in the SQL:


```sql
WHERE {{ filter('status', status if status != 'All' else None) }}
```


This shows all statuses when "All" is selected, otherwise filters to the selected status.

### Multiple Variable Types

This example shows three common variable types:
- **Select**: Single choice dropdown
- **Date range**: Date range picker
- **Slider**: Numeric range input

### Grid Layout with Multiple Charts

Using grid layout to show multiple charts:

```yaml {contract=board-fragment}
grid:
  columns: 24
  items:
    - item: documents_chart
      width: 12
    - item: revenue_chart
      width: 12
    - item: documents_table
      width: 24
```

---

## Extensions

### Add More Variables

Add additional filters:

```yaml {contract=board-root}
variables:
  priority:
    input: multiselect
    options:
      static: ["low", "normal", "high", "urgent"]
    default: ["high", "urgent"]
```

### Dynamic Options

Load options from a query:

```yaml {contract=board-root}
variables:
  template:
    input: select
    options:
      query: queries.template_list
```

---

## Related

- [Variables Guide](../variables/index.md) - Learn about variables
- [Expressions Guide](../variables/expressions.md) - Learn about variable references
- [Drill-Down Example](drill-down.md) - Planned click filtering

# Nested Layouts Example (https://docs.dbtcharts.com/examples/nested-layouts/)

# Nested Layouts Example

A board demonstrating complex layouts using nested sections.

---

## Complete Board

```dbt-charts-example
title: "Dashboard with Nested Layouts"

source: db

queries:
  totals:
    sql: |
      SELECT SUM(revenue) AS total_revenue, SUM(documents_created) AS documents
      FROM dundersign_serving.monthly_metrics

  monthly:
    sql: |
      SELECT month, revenue, active_users, documents_created
      FROM dundersign_serving.monthly_metrics
      WHERE month > (SELECT MIN(month) FROM dundersign_serving.monthly_metrics)
        AND month < (SELECT MAX(month) FROM dundersign_serving.monthly_metrics)
      ORDER BY month

rows:
  # Level 1: Main Container
  - cols:
      # Left sidebar (auto width if not specified)
      - width: "25%"
        rows:
          - title: "KPIs"
            charts:
              revenue_kpi:
                label: "Revenue"
                query: queries.totals
                type: kpi
                value: total_revenue
              documents_kpi:
                label: "Documents"
                query: queries.totals
                type: kpi
                value: documents

            # Sidebar content - stacked KPIs
            rows:
              - revenue_kpi
              - documents_kpi

      # Main content (75% width)
      - width: "75%"
        rows:
          - title: "Trends"
            # Top charts row
            cols:
              - revenue_trend:
                  title: "Revenue"
                  query: queries.monthly
                  type: line
                  x: month
                  y: revenue
              - users_trend:
                  title: "Active Users"
                  query: queries.monthly
                  type: line
                  x: month
                  y: active_users

          # Bottom chart (full width)
          - details_table:
              title: "Monthly Details"
              query: queries.monthly
              type: table
```

---

## Layout Explanation

### Visual Structure

```text
┌─────────────┬──────────────────────────────────┐
│   KPIs      │         Trends                   │
│             │                                  │
│ Revenue KPI │ ┌────────────┬────────────┐      │
│             │ │ Revenue    │ Active     │      │
│ Docs KPI    │ │ Trend      │ Users      │      │
│             │ └────────────┴────────────┘      │
│             │                                  │
│             │ ┌─────────────────────────┐      │
│             │ │ Monthly Details Table   │      │
│             │ └─────────────────────────┘      │
└─────────────┴──────────────────────────────────┘
```

### Nesting Levels

1.  **Root Board**: Has a `rows` layout (default).
2.  **Row 1**: Has a `cols` layout to split Sidebar (25%) vs Main (75%).
3.  **Sidebar**: Has a `rows` layout to stack KPIs vertically.
4.  **Main**: Has a `rows` layout to stack Trends on top of Details.
5.  **Trends**: Has a `cols` layout to put the Revenue and Active Users charts side-by-side.

---

## Key Concepts

### Alternating Row/Column Splits

The pattern for nested layouts:
- **Rows:** Stack vertical
- **Cols:** Stack horizontal
- **Grid:** 2D arrangement

This creates flexible, responsive layouts.

### Board Nesting

Any item in a layout list can be another full board definition:

```yaml {contract=board-fragment}
rows:
  - cols:  # Nested board
      - item_1
      - item_2
```

### Layout Types in Nested Sections

Each nested board can have its own layout:
- `rows`: Vertical arrangement
- `cols`: Horizontal arrangement
- `grid`: Grid layout
- `tabs`: Tabbed organization

---

## When to Use Nested Layouts

### Sidebar + Main Content

Use `cols` for the main split:

```yaml {contract=unverified}
cols:
  - width: "250px"
    rows: [...] # Sidebar content
  - rows: [...] # Main content
```

### Multi-Column Layouts

Create multi-column boards:

```yaml {contract=unverified}
cols:
  - rows: [...] # Column 1
  - rows: [...] # Column 2
  - rows: [...] # Column 3
```

### Complex Grids

Combine nested sections with grid layouts:

```yaml {contract=board-fragment}
rows:
  - grid:
      columns: 24
      items:
        - item: chart1
          width: 12
        - item: chart2
          width: 12
```

---

## Best Practices

### Limit Nesting Depth

Avoid too many nesting levels (3-4 max):
- Harder to understand
- More complex to maintain
- Can impact performance

### Use Descriptive Titles

Add titles to nested sections for clarity:

```yaml {contract=unverified}
rows:
  - title: "KPIs"
    cols: [...]
```

### Narrow Screens

A board is a fixed-width frame that the page scales; nested layouts never reflow or stack. `cols` keeps every item side by side, so a row with many items gives each one little width. For a narrow target, set `style.frame.width` and size the rows for it (see [Sizing](../boards/sizing.md)).

---

## Related

- [Boards Guide](../boards/index.md) - Learn about boards and layouts
- [Layout Types Reference](../reference/layout-types.md) - Detailed layout reference

# Drill-Down Boards (https://docs.dbtcharts.com/examples/drill-down/)

# Drill-Down Boards

Drill down is the BI pattern of clicking a summary element (a bar, a table
cell, a KPI) to navigate to a detail board with context pre-filled. dbt Charts
supports drill-down with the `link:` field on charts and tables.

The examples query the Dundersign demo dataset's support tickets, and the
link targets follow its `customer-support/` board tree.

---

## Bar chart drill-down

Set `link:` on a chart to make every data element clickable. Channel
placeholders (`{{ x }}`, `{{ y }}`, `{{ color }}`, `{{ theta }}`) expand to
the clicked row's value for that channel.

```dbt-charts-example
source: db

queries:
  tickets_by_status:
    sql: |
      SELECT status, COUNT(*) AS tickets
      FROM dundersign.tickets
      GROUP BY status
      ORDER BY tickets DESC, status

charts:
  by_status:
    type: bar
    query: tickets_by_status
    x: status
    y: tickets
    title: Tickets by Status — click to drill
    link: "/customer-support/tickets/list?status={{ x }}"

rows:
  - by_status
```

Clicking the **new** bar navigates to
`/customer-support/tickets/list?status=new`, the target board the
[last section](#target-board) of this page defines. Board-root paths resolve
automatically in `dct serve` and Cloud.

---

## In-page variable update

A `link:` starting with `?` updates a dashboard variable without leaving the
board. This is how cross-chart filtering works inside a single board:

```yaml {contract=board-fragment}
variables:
  selected_stage:
    label: Stage
    default: ""

charts:
  by_stage:
    type: bar
    query: opportunities_by_stage
    x: stage_name
    y: amount
    link: "?selected_stage={{ x }}"   # updates variable, no navigation

  by_owner:
    type: bar
    query: opportunities_by_owner     # queries filtered by selected_stage
    x: owner_name
    y: amount
    title: Reps (filtered by stage above)
```

---

## Table drill-down

A chart-root `link:` makes the whole row clickable (a row-wide band that
highlights on hover), while a per-column `link:` makes that column's cells
their own links. A cell link always wins the click over the row band:

```yaml {contract=board-fragment}
charts:
  tickets_table:
    type: table
    query: open_tickets
    link: "/customer-support/tickets/detail?id={{ id }}"   # whole-row drill-down
    style:
      columns:
        id:
          label: Ticket
          # no column link → clicking the row navigates to detail
        subject:
          label: Subject
          # no column link → part of the clickable row
        status:
          label: Status
          link: "/customer-support/tickets/categories?status={{ status }}"   # this column links elsewhere
```

The chart-root `link` is the row destination; a column `link` overrides it for
clicks on that column's cells. Columns without their own `link` are not inked
as links; they are simply part of the clickable row.

---

## Target board

The detail board receives the clicked value as a URL query parameter. Use a
`variables:` entry with `input: text` to read it:

```yaml {contract=board-root}
# charts/customer-support/tickets/list.yml
variables:
  status:
    input: text         # populated from ?status= query param
    default: "new"      # shown when opened without a parameter

queries:
  filtered_tickets:
    sql: SELECT * FROM dundersign.tickets WHERE {{ filter('status', status) }}
```

---

## Related

- [Chart Interactions](../charts/interactions.md): `link:` field reference and full template syntax
- [Linking Between Boards](../boards/linking.md): board path resolution rules
- [Variables](../variables/index.md): reading URL parameters with `input: text`

# Overview (https://docs.dbtcharts.com/cloud/)

# dbt Charts Cloud

This section covers **[dbt Charts Cloud, the hosted
product](https://dbtcharts.com/accounts/signup/)**, not the open source `dct`
engine documented everywhere else on this site. Cloud is the optional hosted
layer on top of open source dbt Charts: it connects to the git repository
holding your dashboards, and adds the things a team needs beyond a single local
`dct serve` process: who can see and edit which dashboards, and when their data
re-runs.

Everything else (the YAML language, boards, charts, queries, and variables)
is unchanged. A dashboard authored for Cloud is the same board YAML you'd write
and preview locally.

## What Cloud adds

- **[Getting started](getting-started.md)**: connect your git repository
  and warehouse, and create your first project.
- **[Data connections](connections.md)**: org-level warehouse credentials
  mapped onto the source names your YAML uses.
- **[Access control](access-control.md)**: who can view, edit, or refresh a
  dashboard, decided by where it lives in your project.
- **[Refresh](refresh.md)**: when a dashboard's queries re-run versus when a
  viewer sees a cached result.
- **[Git workflow](git-workflow.md)**: how edits become commits, change
  branches and merging, review mode, and the Git settings screen.
- **[AI Copilot](ai-copilot.md)**: what the in-app chat panel knows about
  your project, and how to extend it with your own instructions and skills.

## Everything here from the terminal

Every setup step in this section also has a CLI verb:
[`dct cloud`](../cli/cloud.md) signs you in, creates organizations, connects
repositories and warehouses, maps sources, syncs, and invites teammates. It
is how a coding agent or a CI job sets Cloud up; see
[Automating setup](../cli/cloud.md#automating-setup) for the whole sequence.

## Related

- [dbt Charts Overview](../index.md): the open source engine and the YAML
  language it compiles
- [Boards](../boards/index.md): the dashboards Cloud governs

# Getting Started (https://docs.dbtcharts.com/cloud/getting-started/)

# Getting Started

!!! info "dbt Charts Cloud"
    This page describes [dbt Charts Cloud](index.md), the hosted
    product — these features are not part of the open source `dct`
    engine.


Setting up dbt Charts Cloud takes three steps: connect the git repository that
holds your dbt Charts project, create a project pointing at it, and connect
your warehouse. At the end, every dashboard in your repo is live, shared, and
updating on every push.

## The easy way: hand this to your coding agent

The fastest path to a live board is to paste this into the coding agent
you're already using in this repository and let it drive the setup end to
end. The `cloud-setup` skill it reads carries every step; the prompt names it
and grants the two permissions the setup needs, so the agent doesn't stop
to ask for them halfway.

```text
Publish this repository's boards to dbtcharts.com with dbt Charts. You may
push dbt Charts files to this repository's default branch and create a
read-only warehouse credential for dbt Charts Cloud.
Start with: uv tool install dbt-charts && dct skills cloud-setup
(the install takes a few minutes: give it a long timeout rather than retrying)
```

The agent needs you in the browser once. It runs `dct cloud login`, which
prints a code and a URL: sign in (or create an account), pick or create the
organization the CLI should reach, and approve. Right after, unless the
repository is public, it hands you a link to install the GitHub App and
pick the repository; the page after the pick tells you to go back to the
terminal, and there is nothing else to press. Everything else — connecting
the project, wiring up the warehouse, mapping sources, rendering — the agent
does itself, serving the boards locally so you can watch as it goes.

Prefer doing it by hand? The manual steps below are the same flow, walked
through in the UI.

**Everything here from the terminal.** Each step below is also a
[`dct cloud`](../cli/cloud.md) verb. To script the setup yourself, or to see
exactly what the agent runs, follow
[Automating setup](../cli/cloud.md#automating-setup).

Before you start you need:

- A git repository containing a dbt Charts project: a `dbt_charts.yml` and a
  `charts/` directory of dashboards. If you don't have one yet, build it
  locally first with the open source engine: see
  [Installation](../guides/installation.md) and the
  [Quick Guide](../quick-guide.md).
- A warehouse that Cloud can reach over the internet (see
  [Data connections](connections.md)), unless your boards only read file
  sources.

## Sign in and create an organization

Sign up with an email address and password, or with Google or GitHub sign-in
where offered (social sign-in is used only to authenticate you; it does not
grant Cloud access to your repositories).

Everything in Cloud belongs to an **organization**: members, projects, and
warehouse connections are all org-scoped. Create one with a name and a URL
slug, and you become its admin. Invite teammates by email; each invitation
is a single-use link that expires after seven days. Members hold one of three
org roles:

- **Admin**: manages members, the git connection, and warehouse connections.
  An org always keeps at least one.
- **Creator**: uses and builds projects and dashboards, subject to
  [access control](access-control.md). This is the default for a new invitation.
- **Viewer**: read-only. Access control still decides *which* dashboards they
  see, but a Viewer's grants are capped to view-only capabilities, so no grant
  can give them edit rights.

## Connect your git repository

Cloud reads dashboards straight from git; the repository stays the source of
truth. A repository can be on GitHub, on gitlab.com, on bitbucket.org, or on any
other host that serves plain HTTPS git. There are five ways to connect one:

**GitHub App (recommended).** Connecting starts in Cloud and finishes on GitHub.
You authorize the dbt Charts GitHub App, and Cloud then asks GitHub (as you,
right then) which repositories you can reach. It offers **only the ones GitHub
says you administer**, and connects the one you pick. Nothing about that answer
is stored: every connection re-asks. Once connected, every push syncs
automatically via webhook.

![Connecting a repository: Cloud hands off to GitHub, which decides which repositories you administer](../assets/screens/cloud/getting-started/repo-connect.png){: width="501" height="402" }

Two things follow from letting GitHub decide:

- **Admin on the repo is the requirement.** Write access is not enough. If a
  repository you expected isn't offered, you don't administer it on GitHub;
  ask a GitHub admin for that repo, not a Cloud admin.
- **Cloud can't widen an installation.** Which repositories an installation
  covers is chosen on GitHub, by someone who administers the account. If the
  App isn't installed yet, or covers the wrong repositories, Cloud sends you to
  GitHub's own install/configure page and picks the flow back up when you
  return. If you can't install it yourself, GitHub turns your install into a
  request for an account owner to approve; come back and connect once they do.

**GitHub personal access token.** For organizations that don't allow GitHub App
installs. Pick the **GitHub** tile, expand **Use a fine-grained personal access
token instead**, and paste the repository URL and a token; see [Personal access
token](#personal-access-token) below.

**GitLab.** Pick the **GitLab** tile on the New project page and paste the
repository URL and an access token; see [GitLab](#gitlab) below for which token
to create.

**Bitbucket.** Pick the **Bitbucket** tile on the New project page and paste the
repository URL and a repository access token; see [Bitbucket](#bitbucket) below.

**Other Git host.** A repository can also be connected by its plain HTTPS URL,
with no App install. Pick the **Other Git host** tile on the New project page. For a private
repository, enter a username and a password or token (from the CLI,
`--git-username` and `--git-password`). The credential needs
write access: Cloud pushes your edits to the `dbt-charts/<project>` branch of
the repository. Credentials in the URL itself and non-HTTP schemes are
rejected, and syncing is by periodic poll or an on-demand sync rather than push
webhooks.

One GitHub installation can serve several dbt Charts organizations without
sharing anything between them: an org only ever sees the repositories its own
members connected. A repository can back more than one project in the same
org; each project pins its own work branch, so distinct projects on the same
repo are distinguished by branch, never by repository alone.

### Personal access token

Some GitHub organizations don't allow third-party App installs. For those, the
**GitHub** tile also offers a fine-grained personal access token. Cloud opens
pull requests with it, as with the App, and registers a push webhook on the
repository with it, so a push syncs within seconds. A daily reconcile picks up
any delivery GitHub drops.

Create the token under **Settings › Developer settings › Fine-grained tokens**
on GitHub:

- **Resource owner**: the account or organization that owns the repository. An
  organization that requires approval for tokens must approve it first.
- **Repository access**: **Only select repositories**, and pick the one
  repository. Metadata read-only is added automatically.
- **Repository permissions**: **Contents: Read and write**, **Pull requests: Read
  and write** and **Webhooks: Read and write**.

Cloud uses the webhook permission to register that push webhook, and removes it
when you delete the project or point it at another repository.

Paste the repository URL (the HTTPS one from **Code**) and the token into Cloud;
Cloud signs in as `x-access-token`, so there is no username to enter. Cloud checks
at connect time that the token can push, read pull requests and list the
repository's webhooks. GitHub doesn't report a token's permissions, so a token
without **Pull requests: Read and write** only fails when the first pull request
opens, with a message naming the missing permission.

Fine-grained tokens expire, after at most 366 days, and belong to the account that
created them; see [Replacing a token](#replacing-a-token).

### GitLab

The **GitLab** tile connects a repository on gitlab.com with an access token.
Self-managed GitLab is not covered by this tile; use **Other Git host**.

Whatever token you use needs the `api` scope and the **Maintainer** role on the
project. Cloud checks at connect time that the token can push, has the `api`
scope, and can manage the project's webhooks, and rejects one that can't.
Maintainer is what lets Cloud register a push webhook on the project, so a push
to the repository reaches Cloud within seconds.

Cloud opens merge requests for the work branch like pull requests on GitHub: a
merge request opens as a draft while a board fails to compile, and goes ready
once every board compiles.

| Token | Works | gitlab.com plan | Owned by | Expiry |
|---|---|---|---|---|
| [Service account](https://docs.gitlab.com/user/profile/service_accounts/) (project or group) | Yes, recommended | Free and up | Not a person | Can be none |
| [Project access token](https://docs.gitlab.com/user/project/settings/project_access_tokens/) | Yes | Premium and up | The project's bot | Up to 365 days |
| [Group access token](https://docs.gitlab.com/user/group/settings/group_access_tokens/) | Yes | Premium and up | The group's bot, for the whole group | Up to 365 days |
| [Personal access token](https://docs.gitlab.com/user/profile/personal_access_tokens/) | Yes | All | A person | Up to 365 days |
| Deploy token | No | All | | Read-only, no API |

A service account is the recommended choice: it is not tied to a person, so the
connection keeps working when people leave, and it is free on every GitLab plan.
A project service account is created by a project Maintainer under **Settings
› Service accounts**; a group service account needs an Owner of the top-level
group. Add it to the project with the Maintainer role, create a personal access
token for it with the `api` scope, and paste that token into Cloud.

### Bitbucket

The **Bitbucket** tile connects a repository on bitbucket.org with a repository
access token. Bitbucket Data Center is not covered by this tile; use **Other Git
host**.

Create the token under **Repository settings › Security › Access tokens** in the
repository, and give it these permissions:

- **Repositories: Write**
- **Pull requests: Write**
- **Webhooks: Read and write**

Bitbucket shows the token only once, so copy it before leaving the page. Paste
the repository URL (the HTTPS one from **Clone**) and the token into Cloud; Cloud
signs in as `x-token-auth`, the username Bitbucket requires for these tokens, so
there is no username to enter. Cloud checks the token when you connect, and
rejects one that can't manage webhooks. Webhooks: Read and write is what lets
Cloud register a push webhook on the repository, so a push to it reaches Cloud
within seconds.

A repository access token belongs to the repository, not a person, so the
connection keeps working when people leave, and it is available on every
Bitbucket Cloud plan. It only works for the repository it was created in.
Bitbucket app passwords no longer work.

Cloud opens a pull request for your edits as on GitHub: it opens as a draft while
any board fails to compile and is marked ready once every board compiles.

### Replacing a token

When a token expires or loses access, syncing stops and the project's
**Settings → Git** page says so. Create a new token with the same permissions
and paste it under **Settings → Git → Edit**; leaving the field blank keeps the
saved token.

### Disconnecting GitHub

Disconnecting GitHub (via **Settings → General → Overview → Disconnect all
repositories**, beside the org's project list) unbinds every project in the org from its repository; the
projects themselves are not deleted. Their git data, branches, and dashboard history are preserved, and so
is the repository URL on each project.

The GitHub App stays installed: it belongs to the GitHub account, and other
dbt Charts organizations may be using the same installation. Uninstalling it is
done on GitHub, and that disconnects every org at once.

After disconnecting you can:

- **Reconnect**: connect each project again from its **Settings → Git** page.
  There is no automatic re-link: reconnecting re-asks GitHub whether you still
  administer that repository, which is the point.
- **Delete a project** from the bottom of its **Project settings** page. This
  removes its dashboards and Cloud's git data, and cannot be undone. Cloud
  also removes the push webhook it registered. The work branch and any open
  pull or merge request stay in your repository for you to close.

## Create a project

A project binds one repository (or one subdirectory of it) to a set of
dashboards. Org admins create them; a project binds a repository to the whole
org, so the tier matches what the action does.

**GitHub App (two-step).** Step one hands you to GitHub, which reports back the
repositories you administer; pick one. Cloud then reads that repo's default
branch and tree to pre-fill the form: the project name and slug derive from the
repository name, and the folder path is inferred from the location of your
`dbt_charts.yml` (or `charts/` directory) in the tree. You can edit the
pre-filled values before saving.

**GitLab, Bitbucket, GitHub personal access token, and Other Git host (one
step).** Paste the repository URL and the credential on the tile's form and
fill in the fields below yourself; nothing is pre-filled.

The fields are:

- **Name and slug**: the slug becomes part of the project's URLs.
- **Repository**: the GitHub repo you picked, or the URL you pasted.
- **Folder path** (optional): where the dbt Charts project lives inside the
  repo, for example, `data/dashboards`. This is what makes monorepos work: several
  projects can share one repo with different folder paths.
- **Upstream branch**: the branch your team merges to (your repo's default
  branch if left blank on GitHub). It must exist. Cloud treats it as
  pull-only: Cloud never commits to it directly.
- **Work branch** (optional): the Cloud-owned branch where edits made in
  Cloud land. Left blank, it is `dbt-charts/<slug>`, or `dbt-charts/<slug>-2`,
  `-3` and so on if that name is taken. A name you choose must not already
  exist on the remote. Cloud creates it. Changes reach your upstream branch
  the same way any change does: through a pull request, which Cloud opens
  and keeps updated for you.

On creation Cloud runs a first sync: it fetches the default branch, registers
every dashboard in `charts/`, and discovers the source names your YAML
references. If the sync fails (bad branch, unreachable remote), nothing is
half-created; fix the issue and try again.

The project's **Settings → Git** screen tracks the connection from here on:
when it last synced and pushed, the repository and branches, and a file
browser over exactly what Cloud sees.

![The Git settings screen: sync status, connection details, and the file browser](../assets/screens/cloud/git-workflow/settings-git.png){: width="960" height="797" }

## Connect your warehouse

Dashboards name their sources in YAML (`source: warehouse`); Cloud maps each
name to an org-level warehouse connection. After the first sync, an admin is
prompted to map any unmapped sources; create a connection (PostgreSQL,
Snowflake, BigQuery, Redshift, Databricks, or Trino), test it, and pick the sources
it serves.
The full flow, per-warehouse fields, and security notes are on
[Data connections](connections.md).

## What you'll see

Once a project has a synced repo and mapped sources, its dashboards are live:

![A project's dashboard list, nav included: exactly the board files synced from its repository](../assets/screens/cloud/getting-started/dashboard-list.png){: width="1280" height="1085" }

- **Dashboards track git.** The dashboard list is exactly the board files in
  `charts/` on the synced branch.
- **A push is not a publish.** Your commit goes live on the next sync, which
  a GitHub, GitLab, or Bitbucket project starts within seconds of the push
  and an Other Git host project only picks up on an hourly sweep. `dct cloud
  project sync` (or **Sync now** on the Git settings screen) publishes right away, and
  `dct cloud boards` proves it landed: a board you edited gets a later
  `RENDERED_AT` and a different `COMMIT` once its re-render finishes. See the
  [git workflow](git-workflow.md).
- **Edits made in Cloud land on the work branch**, visible immediately to
  the team and mergeable into the default branch via the rolling pull
  request. Dashboards under `_drafts/` stay in a private working area until
  promoted; see [access control](access-control.md).
- **Branch previews**: board URLs gain a branch scope (`/b/<branch>/…`) to
  view any branch's version; see the [git workflow](git-workflow.md).
- **Freshness** is governed by refresh policy; see [Refresh](refresh.md).

## Related

- [`dct cloud`](../cli/cloud.md): every step on this page from the terminal
- [Data connections](connections.md): warehouse types, testing, and source
  mapping
- [Access control](access-control.md): who can see and edit what
- [Refresh](refresh.md): keeping dashboard data current
- [AI Copilot](ai-copilot.md): tuning what the project's chat panel knows

# Warehouse privileges (https://docs.dbtcharts.com/cloud/warehouse-privileges/)

# Warehouse privileges

!!! info "dbt Charts Cloud"
    This page describes [dbt Charts Cloud](index.md), the hosted
    product — these features are not part of the open source `dct`
    engine.


dbt Charts only ever reads from your warehouse. It runs `SELECT` queries to draw
boards and never writes to your tables. The credential you give a
[connection](connections.md) should be able to do exactly that much and no more.

One exception is worth knowing before you scope the role: a board may declare
`setup_sql`, which is allowed to create *temporary* functions, tables, and views
for the length of its own query session. Nothing it creates outlives the session
or touches your data. If your boards use it, the role needs whatever temporary-
object privilege your warehouse requires; on PostgreSQL that is `TEMPORARY` on
the database.

This page covers creating a read-only role and granting it access to the tables
your boards read.

## Don't reuse your dbt credential

The most convenient credential is usually the one already in your project's
`profiles.yml`, and it is the wrong one. That credential builds your models: it
holds `CREATE`, and usually `DROP`, on the schemas dbt writes to. Handing it to
a reporting tool gives that tool the ability to destroy the warehouse it is
supposed to be reading.

Cloud pre-fills a new connection's host, database, and other non-secret settings
from your committed `profiles.yml`, because that saves you looking them up.
**Secrets are never read from your repository.** Enter a separate read-only
credential in the password field.

## 1. Create the role

dbt does not create roles or users, so this part is a one-time piece of SQL you
run yourself. Substitute your own names, schemas, and a strong password.

### PostgreSQL

```sql
CREATE ROLE dbt_charts_ro LOGIN PASSWORD 'replace-me';
GRANT CONNECT ON DATABASE analytics TO dbt_charts_ro;
GRANT USAGE ON SCHEMA analytics TO dbt_charts_ro;
```

### Redshift

```sql
CREATE USER dbt_charts_ro PASSWORD 'replace-me';
GRANT USAGE ON SCHEMA analytics TO dbt_charts_ro;
```

### Snowflake

```sql
CREATE ROLE dbt_charts_ro;
CREATE USER dbt_charts_svc TYPE = SERVICE DEFAULT_ROLE = dbt_charts_ro;
GRANT ROLE dbt_charts_ro TO USER dbt_charts_svc;

GRANT USAGE ON WAREHOUSE reporting_wh TO ROLE dbt_charts_ro;
GRANT USAGE ON DATABASE analytics TO ROLE dbt_charts_ro;
GRANT USAGE ON SCHEMA analytics.marts TO ROLE dbt_charts_ro;
```

A Snowflake connection needs `USAGE` on a warehouse as well as on the data;
without it the role cannot run a query at all. Snowflake blocks passwords for
service users, so add a key-pair or an access token to `dbt_charts_svc` when
you connect.

### BigQuery

BigQuery uses IAM rather than SQL. Create a service account, then give it two
roles: `roles/bigquery.jobUser` on the project so it can run queries, and
`roles/bigquery.dataViewer` on each dataset it should read.

```bash
gcloud iam service-accounts create dbt-charts-ro --project my-project

gcloud projects add-iam-policy-binding my-project \
  --member "serviceAccount:dbt-charts-ro@my-project.iam.gserviceaccount.com" \
  --role roles/bigquery.jobUser \
  --condition=None
```

`--condition=None` states the binding is deliberately unconditional. Without
it, gcloud refuses to add a binding on any project whose IAM policy already
contains conditional bindings and prompts interactively instead.

Grant `roles/bigquery.dataViewer` per dataset rather than project-wide, so the
service account sees only what it needs.

## 2. Grant read access: with dbt

**This is the recommended path for anything dbt builds.** dbt has a
[`grants` config](https://docs.getdbt.com/reference/resource-configs/grants)
that is declarative, lives in git alongside the models it describes, and is
re-applied on every run. Add one block to `dbt_project.yml`:

```yaml {contract=unverified}
models:
  my_project:
    +grants:
      select:
        - dbt_charts_ro
```

On your next `dbt run`, dbt grants `SELECT` on every model it builds to
`dbt_charts_ro`. New models are covered automatically as they are added, which is
the part that hand-written SQL cannot do.

Start at this level: one grant covering everything your project builds. It is
the right amount of access to begin with, and dbt Charts can help you narrow it
later once you have boards to narrow against.

Snowflake and BigQuery normalize identifiers differently, so write the grantee
name the way your warehouse expects it. On BigQuery the grantee is an IAM
principal, for example `serviceAccount:dbt-charts-ro@my-project.iam.gserviceaccount.com`.

### Narrowing to part of your project

The same config works at any level of the `models:` tree, so a folder can grant
differently from the project default:

```yaml {contract=unverified}
models:
  my_project:
    +grants:
      select:
        - dbt_charts_ro
    finance:
      +grants:
        +select:
          - finance_team
```

Note the `+` on `+select:`. Inside a `grants` block, a privilege written as
`select:` **replaces** whatever was inherited, while `+select:` **adds to** it.
Written without the `+` above, models under `finance/` would be readable by
`finance_team` and no longer by `dbt_charts_ro`.

This is easy to get wrong and fails quietly: one model out of hundreds stops
being readable. If you take one thing from this page, take the `+`.

## 3. Grant read access: by hand

Raw SQL is the right tool in two cases: sources dbt does not build (a landing
schema loaded by something else), and one-off situations where you would rather
apply the privilege yourself.

### PostgreSQL and Redshift

```sql
GRANT SELECT ON ALL TABLES IN SCHEMA raw TO dbt_charts_ro;
ALTER DEFAULT PRIVILEGES IN SCHEMA raw GRANT SELECT ON TABLES TO dbt_charts_ro;
```

`ALTER DEFAULT PRIVILEGES` only covers objects created by the role that runs it,
so run it as the role that loads that schema, otherwise new tables will not be
covered.

### Snowflake

```sql
GRANT SELECT ON ALL TABLES IN SCHEMA analytics.raw TO ROLE dbt_charts_ro;
GRANT SELECT ON FUTURE TABLES IN SCHEMA analytics.raw TO ROLE dbt_charts_ro;
GRANT SELECT ON ALL VIEWS IN SCHEMA analytics.raw TO ROLE dbt_charts_ro;
GRANT SELECT ON FUTURE VIEWS IN SCHEMA analytics.raw TO ROLE dbt_charts_ro;
```

`ALL TABLES` does not include views, and `FUTURE` grants are what cover objects
created later; all four statements matter.

## Hand-written grants and dbt do not mix

If you grant by hand on a relation **dbt builds**, expect to lose it. There are
two separate ways that happens, and both are worth knowing.

**Once a model has any `grants:` config, dbt owns its whole grant set.** On the
next run dbt lists the relation's current grants, compares them to what your
config declares, and revokes anything it finds that you did not configure. A
privilege you granted by hand is not merely forgotten; it is explicitly
revoked. On Redshift and BigQuery this is the behavior you will hit.

**On PostgreSQL and Snowflake, a full refresh drops grants outright.** Both
treat a replaced relation as a new object that does not inherit the old one's
privileges, so `dbt run --full-refresh` loses hand-issued grants regardless of
config. (Snowflake can be told otherwise per model with
[`copy_grants`](https://docs.getdbt.com/reference/resource-configs/snowflake-configs),
which defaults to off.)

There is one case where a hand-issued grant does survive: a project with **no**
`grants:` config anywhere. dbt skips grant handling entirely, so nothing is
revoked, until the relation is next replaced, on the warehouses above.

The practical rule is simple. If dbt builds it, grant it in `+grants:`. If dbt
does not build it, grant it by hand.

## Verifying it worked

A connection test tells you the credential can reach the warehouse and log in.
Being able to log in is not the same as being able to read your tables; a role
with no `SELECT` anywhere still authenticates successfully.

After granting, run `dbt run` so the grants are applied, then open a board. If a
query fails on permissions, the message names the relation the role cannot read,
which is the one to add.

## Related

- [Data connections](connections.md): creating and testing a connection
- [Network access](connections.md#network-access): the address to allow
  through your warehouse's firewall
- [Access control](access-control.md): which people can see which boards, a
  separate concern from what the warehouse credential can read

# Administer access from the CLI (https://docs.dbtcharts.com/cloud/access-from-the-cli/)

# Administer access from the CLI

!!! info "dbt Charts Cloud"
    This page describes [dbt Charts Cloud](index.md), the hosted
    product — these features are not part of the open source `dct`
    engine.


Everything the Access settings pages do is also a `dct cloud` verb, so a
script, a CI job, or an agent can answer "can Sam open finance?", onboard a
team to a folder, or export the audit log without a browser. Each verb calls
the same Cloud API the pages use and gives the same answer; see
[Access control](access-control.md) for how grants, inheritance, and public
access work.

Every verb takes `--json` (the raw API response), `--org`, and `--host`.
Verbs that act on a project also take `--project`. `audit export` always
prints JSON or CSV, so it takes `--format` instead of `--json`.

## Who can run what

A token's scope is a ceiling: the person who signed in must also be an org
admin. `dct cloud login` asks for all of these.

| Scope | Verbs |
|---|---|
| `orgs:admin` | `access list`, `check`, `grant`, `revoke`, `remove-here`, `restore`, `inherit`, `stop-inheriting`, `general`; `public`; `member show`; `audit list` and `export`; `team`; `role`; `identity groups` |
| `connections:admin` | `connection access list`, `grant`, `revoke` |

Who may open a board is an organization matter, so every access verb needs
`orgs:admin`; the `projects:admin` scope covers project settings only.

A verb the token's scope does not cover fails with a 403 naming the scope.

## Check who can open what

```bash
dct cloud access list --project analytics --who sam@acme.com
dct cloud access check --project analytics --who sam@acme.com --path finance/revenue
```

`--who` is an email, a team slug, or `group:<id>` for an identity group,
exactly what the Check access page accepts. `access check` prints the verdict
and the grants behind it, and its exit status says the answer:

| Exit | Meaning |
|---|---|
| 0 | allowed |
| 1 | denied |
| 2 | the check could not run (bad project, unknown person, no credential) |

`access list` narrows like the Grants page: `--project`, `--who` (an email, a
team slug, or `group:<id>`), `--role`, and `--public`. `member show <email>`
prints a member's teams, identity groups, grants, and every board they can
open.

## Change access

| Verb | Effect |
|---|---|
| `access grant --who W --path P --role R` | Give W a role at P |
| `access revoke --who W --path P` | Take back the grant W holds directly at P |
| `access remove-here --who W --path P` | Remove W's access at P, inherited access included |
| `access restore --who W --path P` | Undo `remove-here` |
| `access stop-inheriting --path P` | P keeps who can open it now; later changes to its parent folders stop reaching it |
| `access inherit --path P` | P inherits its parent folders' grants again |
| `access general restricted\|org\|public --path P` | Pick who beyond the named grants can open P |

A blank `--path` is the project root; a folder ends in `/`. `general org`
lets everyone in the organization view P; `general public` lets anyone with
the link view it and needs both public gates on:

```bash
dct cloud public list
dct cloud public allow                      # the organization's gate
dct cloud public allow --project analytics  # one project's gate
```

## Teams, roles, identity groups, connections

```bash
dct cloud team create "Revenue Ops"
dct cloud team add revenue-ops --member sam@acme.com
dct cloud role create analyst --name Analyst \
  --entitlement dashboards.view --entitlement dashboards.edit
dct cloud identity groups --provider acme.okta.com   # read-only
dct cloud connection access grant warehouse --who revenue-ops --role editor
```

`role edit` replaces the name and the whole entitlement list. Identity
groups are read-only because the identity provider owns their membership.
The "everyone in the org" default on a connection is set on the connection's
page, not here.

## Audit log

```bash
dct cloud audit list --actor admin@acme.com --project analytics
dct cloud audit export --format csv --since 2026-10-01T00:00:00Z > audit.csv
```

`audit list` filters by `--since` (ISO 8601), `--actor`, `--action`, and
`--project`, and pages with `--page` and `--limit`. `audit export` follows
every page and writes one JSON array or one CSV with the columns `id`,
`created_at`, `actor`, `action`, `project`, and `summary`. Adding someone to
a team or removing them is in the trail too, since it changes who holds every
grant the team holds.

## Scripting examples

Onboard a team to a folder:

```bash
dct cloud team create "Revenue Ops"
for email in sam@acme.com riley@acme.com; do
  dct cloud team add revenue-ops --member "$email"
done
dct cloud access grant --project analytics --path finance/ \
  --who revenue-ops --role viewer
dct cloud access check --project analytics --who sam@acme.com \
  --path finance/revenue && echo "Sam can open finance/revenue"
```

Fail a CI job when a public board appears:

```bash
test "$(dct cloud public list --json | jq '.grants | length')" -eq 0
```

Export last week's audit log:

```bash
dct cloud audit export --format json \
  --since "$(date -u -d '7 days ago' +%Y-%m-%dT%H:%M:%SZ)" > last-week.json
```

On macOS, use `date -u -v-7d +%Y-%m-%dT%H:%M:%SZ`.

# Data Connections (https://docs.dbtcharts.com/cloud/connections/)

# Data Connections

!!! info "dbt Charts Cloud"
    This page describes [dbt Charts Cloud](index.md), the hosted
    product — these features are not part of the open source `dct`
    engine.


Dashboards never embed credentials; YAML names a source (`source:
warehouse`) and Cloud resolves the name to a **connection**: warehouse
credentials stored once at the organization level and shared across the
org's projects. Only org admins manage connections.

## Supported warehouses

dbt Charts only reads, so the credential you provide should be a **read-only**
one, not the credential your dbt project builds with. See
[warehouse privileges](warehouse-privileges.md) for how to create one and grant
it access.

| Type | You provide |
|---|---|
| **PostgreSQL** | Host, database, username, password. Optional: port (5432 when blank), schema (`public` when blank). SSL is required by default. |
| **Redshift** | Host, database, username, password. Optional: port (5439 when blank), schema (`public` when blank). |
| **Snowflake** | Account, warehouse, database, username, and one credential: a key-pair (recommended), a programmatic access token, or a password (deprecated; Snowflake is retiring password sign-in). Optional: schema (`PUBLIC` when blank). Snowflake only accepts an access token from a user with a network policy, which must allow Cloud's egress IPs. |
| **BigQuery** | The service-account JSON key file: drop it on the form and the project fills itself in. **List datasets** shows the datasets that key can read, then pick one. The dataset's location is read from BigQuery, never typed. |
| **Databricks** | Host, the SQL warehouse's HTTP path, catalog, and either a service principal (client ID and client secret, recommended) or a personal access token. Optional: schema. The principal needs `CAN USE` on the SQL warehouse; use a service principal when your admins have turned tokens off. The catalog is the Unity Catalog catalog your tables live in: **List catalogs** shows the ones the credentials can see, or browse Catalog Explorer in your workspace. The credential needs `USE CATALOG` on the catalog; the connection test checks it. |
| **Trino** | Coordinator host, catalog, schema, and username. Optional: port (443 with SSL, 8080 without) and a password (LDAP) or a JWT. Works with Starburst too. A password or token is only sent over HTTPS, so **Require SSL** must stay on when one is set. |

## Network access

Cloud queries your warehouse over the public internet, from one fixed
address. The warehouse has to be reachable from there: a host on a
private or internal network address is rejected when you save, and a
warehouse reachable only through a VPN, a private endpoint, or an SSH
tunnel cannot be reached at all.

If your warehouse restricts inbound traffic by address, allow:

```text
34.85.252.27/32
```

Every query dbt Charts runs leaves from that address, so one rule covers
every connection in your organization.

Where the rule goes depends on the warehouse:

| Warehouse | Where to add it |
|---|---|
| **PostgreSQL** | Your provider's allowlist (Cloud SQL authorized networks, an RDS inbound security-group rule, an Azure firewall rule), and a `pg_hba.conf` entry as well if the server restricts by client address. |
| **Redshift** | The cluster's security group, inbound on the port you connect to. The cluster also has to be publicly accessible. |
| **Snowflake** | A network policy: add the address to its `ALLOWED_IP_LIST`. |
| **BigQuery** | Nothing. BigQuery grants access through IAM rather than by address, so there is no inbound allowlist to edit. The one exception is a VPC Service Controls perimeter around the dataset, where the address belongs in an access level. |
| **Databricks** | The workspace's IP access list, not a cluster security group. This applies to serverless SQL warehouses too, since the connection targets the workspace URL rather than the warehouse's own compute. |
| **Trino** | Whatever fronts the coordinator: its load balancer's or security group's inbound rules for the coordinator port. |

Allowing the address lets our traffic reach your warehouse; it does not
authenticate it. The credential does that, so keep it scoped; see
[warehouse privileges](warehouse-privileges.md).

## Testing and saving

There is no separate test step. **Save** is the only action on the form, and
saving starts a test of the credentials against the warehouse in the
background. The page returns at once with the connection saved; the status
block beneath the form reads "Testing…" and updates in place when the result
lands, with no reload. The block always shows the connection's most recent
test: "Not tested yet" before the first one, "Testing…" while one runs, and
otherwise when it finished and whether it passed. A failure also shows the
warehouse's own error beneath the form.

One case is neither pass nor fail. If the check cannot finish in time, the
warehouse may still be starting up, so nothing was proved either way: the
connection saves without recording a failure that never happened, and the block
says the test did not finish. Re-check it once the warehouse is up.

The form keeps a failed connection because editing it here is one field and one
click. [`dct cloud connection create`](../cli/cloud.md#dct-cloud-connection-create)
has no edit verb, so it does the opposite: a test that fails outright saves
nothing, and the retry is the same command once you have fixed whatever the
printed error names. A test
that could not finish in time is the exception. The warehouse may still be
starting up, so nothing was disproved and the connection is kept. Re-run the
check with `dct cloud connection test <slug>` rather than the create command,
which would collide with the slug already taken.

To re-run the check on a saved connection, save it again (leaving a secret
field blank keeps the stored value), or use **Re-check readability** on the
connection's page, which re-runs the same authentication check.

![A connection's edit form, showing when it was last tested and whether it passed](../assets/screens/cloud/connections/connection-edit-form.png){: width="601" height="170" }

## Who can query a connection

A new connection is queryable by every member whose organization role allows querying. This is the organization default, and it starts as Editor. Viewers never query a connection directly.

An admin can change the default's role or set it to No access. With No access, only organization admins and principals with their own grant can query the connection.

Grants to individual people or teams work independently of the default. Manage them in the **Permissions** card on the connection's page, or see every connection's grants in one place under **Settings → Access → Who has access**, in its Connections section. Filter that table by person, team, identity group, or role to answer "who can query the warehouse?" or to review what someone can reach before they leave. The same table, filtered to one person, is the Connections section of their page under **Settings → Members**.

Organization admins can manage every connection whatever the grants say. A grant to an organization Viewer reads "No access" with an "Org Viewer · cannot query connections" badge, because Viewers cannot query connections. A grant to someone who has since left the organization is marked "Not a member": it still applies, and you can remove it but not change its role.

## Mapping sources

Cloud reads the source names your project's `dbt_charts.yml` declares on your
project's working branch, the branch Cloud edits and renders from. That file
is the declaration, and it is the only place Cloud looks. A name a board
writes as `source: warehouse` is a reference to a declaration, not one itself:
if `dbt_charts.yml` never declares it, it appears nowhere on this page and
every chart that uses it fails to compile, with the error pointing back here.

Each declared name that names a warehouse starts **unmapped**; queries against
it can't run until an admin maps it to a connection. `csv`, `json` and
`parquet` sources are never unmapped — they read files already in your repo,
so there is nothing to connect them to. When you create a connection you can
map pending sources to it in the same step, and a mapping can override the
schema per source when one project needs a different schema than the
connection's default.

Declarations live in git and mappings live in Cloud, so the two move on
different clocks: a source appears here as soon as it lands on the working
branch, and the connection you pick for it belongs to the project, not to the
branch: it stays picked once that branch merges.

A warehouse source's credential fields in `dbt_charts.yml` (`password:`,
`keyfile:`, or an `env_var()` standing in for one) are for rendering locally.
Cloud ignores them; the connection you map here is what a render uses.

The project's default source is also the one `ref()` and `source()` resolve
against: Cloud lists its tables to link each dbt model to its production relation
([how it resolves](../sources/index.md#on-dbtcharts-com)). Its credentials must be
able to list tables in the schemas your production dbt run builds into; a source
that cannot is recorded as a failed index build and `ref()` charts keep failing
until it can.

Mapping, re-mapping or unmapping a source re-renders the project's boards: a
render resolves its sources when it runs, so every render made before the
change is stale. A project's first render happens at sync, before anything is
mapped, and its boards show `ERR-SOURCE-NOT-FOUND` until the mapping lands
and that re-render completes. To re-render on demand, a project admin
runs `dct cloud render --force`.

![A project's source-mapping table, with one source mapped to a connection and one still unmapped](../assets/screens/cloud/connections/source-mapping-rows.png){: width="588" height="253" }

Because connections are org-level and mappings are per-project, two projects
can point the same source name at different warehouses, or share one
connection.

## Pre-filling from dbt profiles

If the repo has a committed dbt `profiles.yml`, Cloud uses it to pre-fill
the non-secret fields of a new connection: host, database, project,
dataset, and so on. Credentials are never read from the repository; secrets
are always entered directly in Cloud.

## How credentials are handled

- Credentials are encrypted at rest.
- Secrets are write-only: passwords and keys are never displayed back, and
  leaving a secret field blank when editing keeps the stored value.
- Connection management requires the org Admin role; which
  dashboards a member can query is governed separately by
  [access control](access-control.md).
- How much the credential can reach is up to you:
  [warehouse privileges](warehouse-privileges.md) covers granting it read
  access to the tables your boards need, and nothing else.

## Related

- [Warehouse privileges](warehouse-privileges.md): creating a read-only role
  and granting it access
- [Getting started](getting-started.md): the full setup flow
- [Sources](../sources/index.md): how the open source engine defines and
  uses sources in YAML

# Git workflow (https://docs.dbtcharts.com/cloud/git-workflow/)

# Git workflow

!!! info "dbt Charts Cloud"
    This page describes [dbt Charts Cloud](index.md), the hosted
    product — these features are not part of the open source `dct`
    engine.


Cloud reads and writes your boards through git; the repository stays the
source of truth, and every edit made in Cloud is a real git commit you can
see, review, and merge. This page walks the whole lifecycle: the two branches
every project has, how edits become commits, change branches and merging,
review mode, and what the Git settings screen tells you.

Connecting a repository in the first place is covered in
[Getting started](getting-started.md); this page assumes a project is already
bound to one.

## Two branches: upstream and work

Every project tracks two branches:

- **The upstream branch** (usually `main`) is your repository's default
  branch, the one your team merges to. Cloud never commits to it
  directly.
- **The work branch** (named `dbt-charts/<project>` by default) is where
  Cloud's edits land. Every board save in Cloud becomes a commit on this
  branch, authored by the person who saved. Cloud pushes it back to your
  remote, so the work branch is visible in your repository like any other
  branch, and changes flow into the upstream branch through your normal
  process. On GitHub, GitLab (as a merge request) and Bitbucket, Cloud
  maintains a rolling pull request from the work
  branch automatically; it opens with the first pushed edit and keeps
  updating as more land, and a **Create PR** button on the Git settings
  screen brings it back if it was closed.

**Syncing** keeps both sides current: Cloud pulls the upstream branch, then
carries the new upstream commits forward into the work branch so boards in
Cloud reflect what your team merged. Cloud's own commits flow the other way
with each push of the work branch.

## Pushing is not publishing

A `git push` puts your commit on your git host. Cloud publishes it on the
next **sync**, which is also what re-renders the boards the commit changed.
Those are two separate events, and how soon the second one follows the first
depends on how the project is connected:

| Connection | What syncs it automatically |
|---|---|
| GitHub (App or token), GitLab or Bitbucket | The push itself. The host sends a webhook and the sync starts within seconds. A daily reconcile picks up a delivery that never arrived. |
| Other Git host | Nothing watches the remote, so an hourly sweep is the only automatic sync. A push can wait up to an hour. |

Either way you can publish immediately, from the Git settings screen's
**Sync now** button or from the CLI:

```bash
dct cloud project sync
```

**How to know your change is live.** `dct cloud boards` prints, per board,
when its served render ran and the commit that render read the board from:

```text
SLUG            STATUS  RENDERED_AT       COMMIT   URL
exec-overview   ready   2026-09-06 10:50  8a2f27c  https://dbtcharts.com/acme/analytics/d/exec-overview
```

Read it before your push and again after the sync. A board you edited is
serving your work once *its own* two values move: a later `RENDERED_AT`, and a
different `COMMIT`.

If neither has moved, the change is not confirmed yet rather than not
published. A sync queues the re-renders and they run behind live page views,
each re-running the board's queries, so this can take a few minutes on a slow
warehouse. `STATUS` needs its own reading, because a render that fails writes
no new complete render, so the two columns cannot move for it: they only ever
prove success. A `warning` that appeared since your first reading is your
answer, because the only way a board reaches it is a newer failed attempt: the
re-render ran and failed. A `warning` that was already there is inconclusive,
since it carries no date and may be the old failure or a new one of your own
commit, so open the board rather than dismissing it. An unchanged `errored` is
the previous render's chart diagnostic, because it describes the very render
`RENDERED_AT` names. A board still reading `ready` or `not_rendered` with
nothing moved is simply waiting on its queued re-render; look again shortly,
and run `dct cloud project sync` only if you are not sure the sync ever ran.

Compare only the boards your commit changed. A board it did not touch normally
keeps both values, because nothing re-renders content that did not change;
that is a board already serving the right bytes, not one waiting to catch up.

`COMMIT` names a commit in Cloud's copy of the repository, which is not always
one of yours. Cloud commits its own board edits to the work branch and merges
your upstream branch into it on every sync, so on a project that has been
edited in Cloud the served commit is a work-branch commit and will not equal
your `git rev-parse HEAD`. On a project only ever edited through git the two
are the same sha. The sha *changing* is the signal in both cases.

`STATUS: ready` on its own only means *a* render exists, not that it is a
render of your edit. A board that has never finished a render shows `-` in
both columns, as does one last rendered before Cloud began recording commits;
neither is backfilled with a guess, and the column fills in on the board's
next render.

## The Git settings screen

**Settings → Git** is the home for all of this. The **Status** card shows
when the project last synced and pushed and how far the work branch is ahead
of upstream; the **Connection** card shows the repository, the upstream and
work branch names, and the folder inside the repository the project reads
(for repositories that hold more than one project). The **Files** panel
browses exactly what Cloud sees at the work branch tip: the same files,
at the same commit, that your boards render from.

![The Git settings screen: sync status, connection details, and the file browser](../assets/screens/cloud/git-workflow/settings-git.png){: width="960" height="797" }

When a sync cannot complete (the histories have diverged after a force
push, or Cloud's copy of the repository is missing something it needs) the
status is reported here too, with the reason, instead of silently serving
stale boards.

## Change branches

Edits don't have to land on the work branch directly. The **Branches**
screen (linked from the Git settings) lists every branch Cloud knows about
and lets you create a **change branch**: a branch off the work branch where
a set of edits can be developed together and merged as one unit.

![The Branches screen: the default branch, the work branch, and change branches with their actions](../assets/screens/cloud/git-workflow/branches.png){: width="960" height="420" }

While a change branch is open you can browse and edit any board on it:
board URLs gain a branch scope (`/b/<branch>/…`), so a link to the
in-progress version is shareable like any other board. When the work is
ready, **Merge** shows you the changed files and folds the branch back
into the work branch, and if the two branches changed the same lines,
Cloud walks you through a three-version resolution screen instead of
merging blindly. **Delete** discards the branch. On GitHub, GitLab and
Bitbucket, an org admin can also use **Open PR** to send a change branch straight to the upstream
branch as a pull request, skipping the work branch, for changes that
should go through your repository's own review instead of Cloud's.

## Review mode

By default a project is in **direct mode**: saves commit straight to the
work branch, and change branches merge without a review step. Projects that
want an approval step can turn on **branch mode**, in **Settings → Git →
Edit**:

![The Work Branch and Branch Mode fields in the git connection editor, with branch mode turned on](../assets/screens/cloud/git-workflow/branch-mode-setting.png){: width="588" height="286" }

In branch mode the work branch advances *only* through reviewed merges:
every edit happens on a change branch (the Merge button becomes
**Propose**), and merging one starts with a proposal. The Branches screen
says which mode the project is in, so you can confirm the switch took.

![Proposing a change branch for review: the changed files and a title and description for the reviewer](../assets/screens/cloud/git-workflow/branch-propose.png){: width="844" height="346" }

A proposal opens a **review**: a page showing every changed board with
the current and proposed versions rendered side by side, a visual
comparison that can highlight exactly the pixels that changed, and the
exact YAML diff. A reviewer can **Approve & merge**, **Request changes**,
or close the review; approving merges the branch into the work branch.

![A review awaiting approval: both versions rendered side by side, with the visual comparison modes](../assets/screens/cloud/git-workflow/review-compare.png){: width="1152" height="1306" }

## Commit history

The **Commits** screen (also linked from the Git settings) lists recent
commits on the work branch: who saved what, when, and the files each
commit touched, with expandable diffs. Because every Cloud edit is a real
commit, this is the full audit trail of how your boards got to their
current state, and it reads the same in Cloud and in `git log`.

![The Commits screen: every Cloud edit is a git commit with an author and a diff](../assets/screens/cloud/git-workflow/commits.png){: width="960" height="340" }

## Related

- [Getting started](getting-started.md): connecting the repository and
  creating the project.
- [Access control](access-control.md): who can edit which boards; edits
  always commit as the person who made them.
- [Refresh](refresh.md): keeping board data current between edits.

# Access Control (https://docs.dbtcharts.com/cloud/access-control/)

# Access Control

!!! info "dbt Charts Cloud"
    This page describes [dbt Charts Cloud](index.md), the hosted
    product — these features are not part of the open source `dct`
    engine.


dbt Charts Cloud governs who can see and edit dashboards the same way you
already think about shared folders: **where a dashboard lives decides who can
see it**, unless a more specific rule says otherwise. Sharing a folder shares
everything in it; sharing one dashboard inside that folder narrows or widens
access for that dashboard alone.

All access changes happen in Cloud, never in git. A dashboard's YAML never
carries a permission field, and no `_cloud.yaml` or similar file records who
can see it. Cloud is the single source of truth for access, and its admin
surface and audit trail are where you go to read or change it.

## The filesystem mental model

Think of your project like a shared drive:

```text
charts/
  finance/
    revenue_exec.yaml
    forecast.yaml
  public-reports/
    quarterly_summary.yaml
```

Grant the finance team access to the `finance/` folder, and every dashboard
inside it (present and future) is visible to them. Move
`quarterly_summary.yaml` into `public-reports/`, and it picks up that folder's
access, the same way moving a file into a different Drive folder changes who
can open it.

The key Cloud binds access to is a dashboard's **path**: its file location
relative to the project root, with the file suffix stripped
(`finance/revenue_exec`, not `finance/revenue_exec.yaml`). Folders are keyed
with a trailing slash (`finance/`). The branch a dashboard happens to live on
is never part of that key; access to a path is the same whether you're
looking at the trunk branch or a preview of a feature branch.

## Longest-prefix resolution

A dashboard's effective access is resolved by walking from the broadest scope
to the most specific:

1. The project's default access: the broadest scope, what everything in the
   project inherits absent a more specific rule
2. Each directory the dashboard's path passes through, outermost to innermost
3. The dashboard's own exact path, if it has a specific grant

Each more specific scope either **replaces** the access inherited from above
it, or **adds to it**; that's a choice you make when you grant access at a
given path, not a fixed rule. "Share this folder with Alice in addition to
whoever can already see it" and "restrict this one dashboard to Alice only"
are both ordinary grants; they just differ in whether they inherit from the
parent.

Because resolution is purely path-based, a new dashboard needs no setup to
have sensible access: drop it in `finance/` and it inherits `finance/`'s
access immediately. Nothing needs reconciling.

**Settings → Access → Grants** shows exactly this, path by path. The
picker at the top starts at **Everything**. Open it and drill from a project to
a folder to a board; you can pick any of them, and the page lists everyone who
can open that place: the grants made there first, then the ones inherited from
the folders above. An inherited row carries a quiet "from folder" tag that
links to the folder, because you edit it there. Remove it here and the path
stops inheriting that grant: the row stays in the list, marked "Removed here",
with "No access" beside it and an **Undo** button.

A folder or board also has an **Inheritance** line. **Stop inheriting** keeps
everyone who can open the place today and cuts it off from later changes to its
parent folders; **Restore inheritance** lets it follow them again.

A board's own settings panel shows the same list for that board under **Who
has access**, with the same role, Remove, and Undo controls, and a link in its
header to the board in Grants. It has no inheritance control; that
lives on the Grants page.

Under the list, **General access** is one line with three choices:

- **Restricted**: only the people listed can open it.
- **Everyone in the organization**: every member can view it.
- **Anyone with the link**: anyone can view it, signed in or not, and a
  **Copy link** button appears. This follows the
  [public access switches](#public-access-org-and-project-opt-in): while the
  organization's or the project's switch is off, the choice is unavailable and
  the line says which switch to change, with a link to it.

The **Add people or teams** field at the top lists your teams and identity
groups when you focus it and searches people as you type; pick one, choose a
role, and select **Add**.

## Seeing every grant

With **Everything** picked, **Settings → Access → Grants** is one full-height
table of every path grant in your organization, with a sticky header. Each row
shows who holds the grant, the place it applies to, and the role. A folder reads
as its full path ending in `/*`, a board as its full path with the folders
muted, and the project root as "Entire project"; the project name sits beneath.
A folder or project grant shows how many boards it covers, and the count links
to the folder. A place that stops inheriting carries a "Doesn't inherit" badge.
The role carries an icon: an eye for Can view, a pencil for Can edit, a shield
for Full access.

The header holds the **Public links** switch, which turns the organization's
public access on or off; turning it off asks first and says how many boards
stop being reachable by anyone with the link.

![Grants with Everything picked: the path grants table, each grant showing who holds it, where, how many boards it covers, and its role](../assets/screens/cloud/access-control/who-has-access.png){: width="368" height="259" }

The toolbar filters by role or to public grants only (the globe, "Show public
only"). Filters are part of the
page's address, so a filtered view is a link you can share with another admin.
Typing a person or team in the search offers their member or team page; an
identity group filters this page.

A grant that does not take full effect stays in the list with its limit spelled
out: an Editor grant held by an organization Viewer reads "Can view" with an
"Org Viewer · view only" badge beside it, and a public grant reads "No access"
with a "Public access is off for this organization" badge while public access
is off. An organization Viewer is never offered a role above Viewer.

Change a role in place from its dropdown, remove a grant from its row, or use
**Add access** to grant a person, team, or identity group a role on a project,
folder, or board. Only organization admins can open Grants.

Connections are not on this page: the Connections list in settings has a **Who
can query** column for each warehouse connection. See
[Who can query a connection](connections.md#who-can-query-a-connection).

## Check who can open a board

The **Check access** page answers "can Sam open `finance/q3-close`, and why?"
without working it out by hand. Open it from the button on Grants, a
member's page, or a team's page; the person or place you were looking at is
already filled in. Choose who (an email, a team, or an identity group) and a
board or folder, or paste a board's address, then select **Check**. The values
are part of the page's address, so a result is a link you can share with
another admin. The page only reports; it changes nothing.

The answer is one sentence, such as "Vic Viewer can view `revenue-ops/*`". When
an organization role limits a grant, a line says so: "They have Can edit there,
but their org role is Viewer, so it counts as view." **Access comes from** lists
each grant that reaches the person: its role, where it is bound, and how it
arrives (directly, via Everyone in the organization, via a team, or via an
identity group), with a link to open it. If a folder on the way down stopped
inheriting, one more sentence says which, because grants on its parent folders
do not reach it.

A denial offers **Give access**, which opens the place in Grants. A path
inside a draft is private to the person who owns the draft. Organization admins
do not bypass board grants, so checking an admin is a real question.

Checking a team or identity group answers for the group as a whole and counts
its members by outcome, such as "7 of 9 members can edit; 2 are org Viewers and
can only view".

## Roles as entitlement atoms

Access grants pair a **principal** (who) with a **role** (what) at a path:

- **Principals**: an individual, a group, a group synced in from your
  identity provider, everyone authenticated in your organization, or
  "everyone" (anyone outside your organization, signed in or not; see [Public access](#public-access-org-and-project-opt-in) below).
- **Roles** are built from a small set of underlying capabilities: viewing a
  dashboard, editing it (which covers creating, saving, promoting, moving,
  and deleting), triggering a refresh, managing who else has access at a
  path, managing data source connections, and browsing raw data directly.
  The built-in roles are **Viewer** (view only), **Editor** (view, edit,
  refresh), and **Admin** (view, edit, refresh, and manage access), and
  custom roles can be composed from the same underlying capabilities for
  finer-grained needs.

Being able to create dashboards in a folder is just holding an Editor-level
grant there; there's no separate "creator" concept. Whoever can edit a path
can also create new dashboards under it.

Membership in your organization is a separate axis from dashboard access:
being a member doesn't automatically grant view or edit rights to any
dashboard. Organization-wide visibility is an explicit grant ("every member
can view this project"), not an implicit consequence of joining. The
Members page manages that first axis: who belongs to the organization, and
at what organization role, which is a different list from any one path's
access grants:

![An organization's Members table: two Admins and several Creators; organization roles, distinct from any dashboard's access grants](../assets/screens/cloud/access-control/members-table.png){: width="458" height="235" }

Org admins can click any name to open that person's **member page**, one
scrolling profile. The header shows their photo or initials, name, email,
organization role, join date, and when they were last active. The role is a menu
that changes it in one request, with one line on what each role allows (not on
your own page), and the menu beside it removes them from the organization. A row of counts shows the
boards they can open, their grants, their teams, and the connections they can
query. An organization Viewer's page carries one banner saying what the role
limits. Sections follow:

- **Teams** shows their teams as chips you can remove, an **Add to team** menu,
  and any identity groups synced from your identity provider, read-only with
  the provider and when it last synced.
- **Grants** has **Check access** with the person filled in and **Add access**.
  It lists every path and connection grant that reaches them in one table,
  including grants made to a team, an identity group, or all members; those are
  read-only and link to the team or group that holds them. A connection grant
  shows the database icon and the connection's name. Below it, the boards they
  can open appear as a count per folder that links to the folder, never as a
  list of boards. When their grants reach more boards than they can open, the
  page says why, such as two boards under a folder that does not inherit.
- **Activity** shows the audit trail for changes to their access, including
  through teams and groups, and for changes they made.

A team's page puts a compact members list beside the team's Grants on wide
screens, with its activity below. Non-admins keep the members list and never
see the Grants or activity.

The Members page is one scroll. An add row at the top takes emails, a role, and
teams; below it the table lists a person's name and email together, their role
as a menu that changes it in one request, their teams, and when they were last
active, with a button at the end of each row to remove them. Your own row is
tagged "You" and has no remove button. Pending invitations follow the table,
and appear only when there are any.

## Public access: org and project opt-in

Public access has no per-dashboard flag. It's the same mechanism as any other
grant: the "everyone" principal gets a Viewer role at a path, and anyone
outside the organization (logged out, or signed in to another organization)
resolves as that principal. Signed-in visitors from other organizations can
only ever view, whatever role the grant carries. A public grant is view-only
for logged-out visitors too, and Cloud rejects any role beyond view for the
"everyone" principal.

Because any path is one grant away from being reachable by anyone, public
access is additionally gated by two independent switches, both **off by
default**:

- An **organization-level** switch: the outer gate. Off means no project in
  the organization can serve anything publicly, no matter what any project or
  dashboard is configured to do.
- A **project-level** switch: the inner gate. Off means that project serves
  nothing publicly, even when the organization allows it.

Both must be on, in addition to an everyone-principal grant on the path, for
a dashboard to actually be reachable without logging in. This makes a strict,
nothing-is-public posture the default, and turning on public access a
deliberate act at each level rather than something that happens by accident.
Cloud also won't let you *add* a new public grant on a path while either switch
is off; you can't opt a dashboard into public access the gates don't yet allow.
Either switch is an instant kill switch: turn one off and every path under it
stops being served publicly, no matter what grants exist. Those grants aren't
deleted; they're held inert while the switch is off, and flip the switch back
on and they apply again with nothing to re-create.

A repository can also switch public access off for its own project with
`cloud.allow_public: false` in `dbt_charts.yml` (see
[Cloud settings](../guides/installation.md#cloud-settings)). That behaves like a
third switch that can only be turned off from the file: the settings page says
when it is the one holding public links off.

The admin surface makes this auditable. The **Public links** switch in the
Grants header is the organization switch, and the globe filter ("Show public
only") lists every public grant across the organization's projects in the same
table. Remove a row to make that board or folder private. A public grant that
is switched off by a gate stays in the list, reading "No access", with the
reason.

A project's General settings hold its own switch and separately list, read-only,
which dashboards its grants would expose publicly, regardless of whether that project's own gate
happens to be open or closed at the moment, so a grant made while the gate is
closed is never a blind spot once someone flips it back on:

![A project's own settings listing the one dashboard path its grants currently expose publicly](../assets/screens/cloud/access-control/public-access-project-listing.png){: width="588" height="104" }

Flipping either switch is itself recorded in the audit trail, at whichever
level was toggled.

Public boards run queries against the organization's connection when a visitor
picks a filter value nobody has asked for yet. Opening a board that already has a
saved render, or choosing a value that has one, costs nothing. To bound the rest,
heavy filter traffic from one anonymous address on one board is paused briefly.
While paused, the visitor sees the saved render for the same filter values if one
exists, otherwise just a notice that live filters are paused, until the pause
passes. Signed-in visitors are never paused, and refreshing a board is not
available to signed-out visitors at all.

## Reading the audit trail

**Settings → Access → Audit** lists every access change, newest first under a
heading for each day. Each row shows the time, the **Actor**, where the change
came from (UI, Git, or System), and a sentence about what changed, with boards
and folders named and linked to who has access there:

- Made finance public (Viewer)
- Restricted finance/q3 to Sam, Data team (stopped inheriting from finance)

Changes made in one request are one row you can expand. A "Git" row is a board
moved outside dbt Charts, where Cloud found its grants no longer applied.
Bookkeeping rows for newly created access records are not shown.

The toolbar searches (`actor:` and `where:` narrow the search), and filters by
date, actor, kind of change, source, and project, or to public changes only.
**Export** downloads the filtered trail as CSV or JSON; an export over 10,000
events asks you to narrow the filters. On a member's page, Activity shows the
same trail filtered to that person. The `cloud_access audit` command prints the
same sentences, with `--all` for the bookkeeping rows.

## Reading a board with a CLI token

The token `dct cloud login` stores is not only an API credential: it reads
board pages too, so the tool that publishes a board (or a CI job, or an agent)
can fetch the board it just published instead of handing a URL to a person.
Send it as an ordinary bearer header:

```bash
curl -H "Authorization: Bearer $DCT_CLOUD_TOKEN" \
  https://dbtcharts.com/<org>/<project>/d/<board>
```

The token authenticates; it grants nothing. The board's own access rules
decide exactly as they do for that person in a browser, so a token cannot
reach a board its owner cannot reach. Three further limits apply:

- **Read only.** `GET` and `HEAD` on board-viewing URLs. This covers the board
  page, its snapshot pages, its `.svg` / `.png` / `.pdf` exports, and the
  render artifacts the page embeds. Every editing, renaming, refreshing, or
  variable-setting URL refuses a token, whatever its scope.
- **The `dashboards:read` scope.** A token issued without it reads nothing,
  even for a user who has full access. A token's scope can narrow what its
  owner can do and can never widen it.
- **The organizations it was approved for.** Approving `dct cloud login` or a
  connector checks one or more organizations; the token reads boards in those
  organizations only, even if its owner belongs to others.

One endpoint is deliberately outside this: the poll a board page uses while a
render is still in flight answers to signed-in browser sessions only. Wait
until `dct cloud boards` reports that board `ready`, and the completed board
and its artifacts are readable.

A token that is expired, revoked, unrecognized, or not approved for that
organization is not reported as a bad token. The response is exactly what an
anonymous request to that URL gets, because telling the two apart would let
anyone map which boards exist.

## Drafts

A draft dashboard lives in a private working area, visible only to the person
who created it; no grant or public setting on the rest of the project reaches
into it. Promoting it to a destination path re-checks access at that moment:
the person promoting must be allowed to edit the destination, or it stays a
draft. Once promoted, it takes on that path's access like any other dashboard
living there.

## Related

- [Administer access from the CLI](access-from-the-cli.md): the same
  grants, checks, and audit log as `dct cloud` verbs
- [Refresh](refresh.md): who can trigger a refresh follows the same
  path-based access model
- [Boards](../boards/index.md): the dashboards this access model governs

# AI Copilot (https://docs.dbtcharts.com/cloud/ai-copilot/)

# AI Copilot

!!! info "dbt Charts Cloud"
    This page describes [dbt Charts Cloud](index.md), the hosted
    product — these features are not part of the open source `dct`
    engine.


Every dbt Charts Cloud project has a chat panel: an AI copilot that can find
and describe your boards, run the queries behind them, and build new ones.
**Project Settings → Agent** is where an admin tunes what that copilot knows
about this particular project, beyond its built-in dbt Charts knowledge.

If you're reaching your projects from Claude or ChatGPT instead of the
in-app chat panel, that's a separate integration: see the
[Claude & ChatGPT connector](claude-chatgpt-connector.md).

## Project Instructions

If your repository already has an `AGENTS.md` or `CLAUDE.md` file, or a
`skills/` folder (also checked at a couple of dot-prefixed locations other
coding agents use, such as `.agents/skills/`), the **"Honor this project's
AGENTS.md / CLAUDE.md and skills/ folders"** checkbox decides whether the
Cloud copilot reads them.

It's off by default. A repository that's also used with a local coding agent
may ship these files written for that other tool, not for the Cloud copilot,
so Cloud never assumes they apply until an admin turns the checkbox on after
reviewing the content.

A repository can also keep these files ignored for good with
`cloud.honor_agent_instructions: false` in `dbt_charts.yml` (see
[Cloud settings](../guides/installation.md#cloud-settings)); the checkbox then
has no effect, and the settings page says so.

When it's on:

- Cloud looks for `AGENTS.md` first, then `CLAUDE.md`, and uses the first
  one it finds that isn't empty. If `AGENTS.md` exists and has content,
  `CLAUDE.md` is never read, and the two are never merged.
- Very long instructions are truncated, with a note telling the copilot it
  can read the rest of the file on request.
- A `SKILL.md` file with valid frontmatter, in its own subfolder of
  `skills/`, becomes a skill the copilot can look up the same way it looks
  up its built-in ones. A plain `.md` file dropped directly in `skills/`,
  or one with missing or invalid frontmatter, is skipped.

Project instructions and skills are treated as context the project's
authors wrote, not as rules the copilot must obey. They can't override the
copilot's own safety and tool-use policies, and they can't grant the person
chatting any capability they don't already have.

## Extra skill files

**Extra skill files** points the copilot at specific files in your
repository, one repo-relative path per line, for example:

```text
docs/style-guide.md
glossary/metrics.md
```

Each path becomes a skill the copilot can look up on demand. Unlike a real
skill folder, no special file format is required: point it at an existing
style guide or glossary and the copilot reads it as-is. A path that doesn't
exist in your repository, or points at an empty file, is skipped. This
applies regardless of the checkbox above.

## Custom instructions

**Custom instructions** is free text appended to the copilot's instructions
for every conversation in this project, independent of the checkbox above.
Use it for guidance that doesn't belong in the repository itself, such as
how your team prefers results summarized.

## Related

- [CLI and MCP for AI assistants](../cli/ai-cli-and-mcp.md): the equivalent
  skills and tools for a local coding agent working on the project's
  repository directly

# Claude & ChatGPT connector (https://docs.dbtcharts.com/cloud/claude-chatgpt-connector/)

# Claude & ChatGPT connector

!!! info "dbt Charts Cloud"
    This page describes [dbt Charts Cloud](index.md), the hosted
    product — these features are not part of the open source `dct`
    engine.


dbt Charts Cloud is a remote MCP server: paste one URL into Claude or ChatGPT
and chat with your boards and your warehouse from there — find a board, read
what it shows, run the queries behind it — signed in as you, with your own
permissions. This page walks the whole flow: connecting, what the consent
screen grants, and how to see and revoke access later.

The connector serves your whole organization through that one URL. You add it
once, not once per project: search spans every project you can reach, and
each call is still checked against your access to the specific project and
data source it touches.

If you're looking for the *local* MCP server for editing a project on your
own machine (Cursor, Claude Desktop against a checkout), that's
[`dct mcp serve`](../cli/mcp.md) — a different thing. This page is about
reaching your hosted projects from Claude.

## What the connector can do

The connector exposes eight tools. Hosts decide when to call them; this is
what each one does and what it's allowed to touch:

| Tool | What it does | Checked against |
|---|---|---|
| `search_boards` | Finds boards by name, title, or notes across every project you can reach, or lists all of them when the query is empty | Your board access |
| `describe_board` | Lists a board's charts, queries, and variables | Your board access |
| `render_board` | Renders a stored board, or a whole board of YAML the host authors on the fly | Your board access, or your query permission on any connection the YAML touches |
| `execute_query` | Runs a board's named query, or direct SQL, against a connected source | Your query permission on that source |
| `list_skills` | Lists dbt Charts' authoring guides (board-building workflows, chart-layout patterns) | Nothing when no project is named. Naming a project also lists that project's own skills, and needs your access to that project |
| `get_skill` | Reads one skill's full guide by name | Same as `list_skills` |
| `list_diagnostic_codes` | Lists the error and warning codes a render can report, optionally by level | Nothing; the registry is the same for everyone |
| `get_diagnostic_code` | Explains one diagnostic code and how to fix it | Nothing |

`execute_query` returns its rows to the AI as CSV bounded at about 25,000 tokens.
The widget you see shows at most the first 50 of those rows, and a very wide
result can still be too large to preview. The tool has no row-limit
argument: the AI writes `LIMIT` and `OFFSET` in the SQL, and a result that was
cut says so.

Every tool call is read-only: queries are statement-guarded, row-capped, and
time-limited, and nothing the connector does writes to your project. A
rendered board's widget links to the dbt Charts Cloud editor, where saving a
board (including one `render_board` authored inline) happens under your
own browser session, never through the connector. A board built entirely from
inline rows (a `type: values` query, the shape another AI tool's results
arrive in) touches no data connection at all, so it renders even for a user
whose organization has no warehouse connection configured yet.

Boards over uploaded files cannot be authored from Claude or ChatGPT yet: an
inline `render_board` YAML that queries a project's file source (a
csv/json/parquet source declared in your project's `dbt_charts.yml`, with no
warehouse connection behind it) is refused. That data is still visible
through `search_boards`/`describe_board`/`render_board` on any
stored board that already queries it — only an on-the-fly board over it,
authored live in the chat, is not yet supported. Build that board in the
Cloud editor or in chat inside dbt Charts Cloud itself instead.

The tool list is the same for every user. If you call a tool your
permissions don't cover, you get an error naming what was denied rather than
a hidden tool.

## Connect from Claude

1. In Claude, open **Settings → Connectors** and choose **Add custom
   connector**.
2. Paste your server URL: your Cloud origin plus `/mcp` — for
   example `https://dbtcharts.com/mcp`.
3. Claude discovers the sign-in flow on its own — there is no client ID or
   secret to fill in. You'll be sent to dbt Charts Cloud to sign in (if you
   aren't already) and to the consent screen described below.
4. Back in Claude, open the connector's **Tool permissions** and switch both
   groups from **Needs approval** to **Always allow**. Claude starts every
   tool of a new custom connector on **Needs approval**, which asks you to
   confirm each call. Every tool here is read-only, so allowing them is safe.

On a Claude Team or Enterprise plan, only an organization owner can add a
custom connector. If **Add custom connector** is disabled for you, ask an
owner to add `https://dbtcharts.com/mcp` for the organization. It then
appears in your connector list with a **Connect** button, and you sign in to
dbt Charts Cloud as yourself from there.

Claude connects from Anthropic's cloud, not from your device, so the server
URL must be reachable from the public internet. Details and plan
availability are in Anthropic's own guide:
[Get started with custom connectors using remote MCP](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).

## Install for your whole Claude organization

The `dbt-charts` Claude plugin bundles this connector with the board
authoring skills (building, designing, reviewing, and troubleshooting
boards), so Claude follows them without being asked. It lives in the
public `dbt-labs/dbt-charts` repository, which is a plugin marketplace.

In Claude Code, add the marketplace and install the plugin by typing these
two commands in a session:

```text
/plugin marketplace add dbt-labs/dbt-charts
/plugin install dbt-charts@dbt-charts-plugins
```

For claude.ai and Cowork, an organization owner distributes it from
**Organization settings → Plugins & skills**. Organization sync reads only
private or internal marketplace repositories, so list the public plugin
from a private marketplace repository of your own. Its
`.claude-plugin/marketplace.json`:

```json
{
  "name": "your-org-plugins",
  "owner": {
    "name": "Your IT team"
  },
  "plugins": [
    {
      "name": "dbt-charts",
      "source": {
        "source": "git-subdir",
        "url": "dbt-labs/dbt-charts",
        "path": "plugins/dbt-charts"
      }
    }
  ]
}
```

1. Choose **Add → Sync from GitHub** and pick that repository.
2. On the **Inventory** tab, set `dbt-charts` to **Installed by default**
   (members can turn it off) or **Required**.
3. In **Organization settings → Connectors**, add `https://dbtcharts.com/mcp`.
   A plugin's availability doesn't add its connector; each member then
   connects it and signs in to dbt Charts Cloud as themselves.

Anthropic's guide covers the rest:
[Manage plugins for your organization](https://claude.com/docs/plugins/admin).

## Connect from ChatGPT

1. In ChatGPT, open **Settings → Connectors** and turn on **Developer mode**
   if you haven't already.
2. Choose **Create connector** (or **Add connector**) and paste your server
   URL: your Cloud origin plus `/mcp`, for example
   `https://dbtcharts.com/mcp`.
3. ChatGPT registers itself as a client automatically (no client ID or
   secret to fill in) and sends you to dbt Charts Cloud to sign in (if you
   aren't already) and to the consent screen described below.

ChatGPT registers through anonymous dynamic client registration (DCR) rather
than Claude's client ID metadata documents. With that mechanism the app names
itself, so the consent screen marks the name **Unverified name** beside the
site your browser returns to after you approve. Continue only if that is the
site you came from (for ChatGPT, `chatgpt.com`).

## The consent screen

Connecting sends you to dbt Charts Cloud to approve the client. The consent
screen shows which account you're signed in as, asks **which organizations**
the connector may reach, and lists what it will be able to do. The first time,
every organization starts checked; when you reconnect, the organizations it can
already reach are checked. Keep at least one.

- View your boards and the data they show.
- Run SQL directly against your connected warehouse, marked **Sensitive**.

Running SQL reaches your data directly, even though nothing it returns is
written anywhere. Approve a connector the way you'd approve any tool that can
see your data. **Approve and connect** grants both; **Cancel** grants nothing.

![The consent screen: the requesting client, a checkbox per organization, and each scope on its own line](../assets/screens/cloud/claude-chatgpt-connector/consent-screen.png){: width="472" height="1095" }

## What the connector may access

The scopes you grant are a **ceiling, never a widening**. A connector acting
for you can reach at most what you can already reach in dbt Charts Cloud —
each call re-checks your own [access grants](access-control.md) against the
specific project and source it resolves to. Granting the warehouse-query
scope to a user who doesn't hold query permission on a source grants
nothing on that source.

Queries the connector runs are attributed in your warehouse's job history
with opaque per-user and per-request labels, so an administrator can answer
"who ran that query" without any personal data appearing in warehouse
metadata.

## See and revoke access

**Settings → Connectors** (`/settings/connectors`) lists every client with
active access to your account — Claude, ChatGPT, or anything else you've
authorized — with the organization it reaches, the scopes it holds, and when
its token was issued.

![The connector list: each authorized client with its organization, scopes, and token age](../assets/screens/cloud/claude-chatgpt-connector/connector-list.png){: width="601" height="270" }

**Revoke** disconnects a client immediately: its tokens are invalidated at
that moment, and its next call fails. Revoking a client disconnects it for
your account across organizations — reconnecting is the same paste-and-consent
flow from scratch.

![After revoking: the list is empty and the client's next call is refused](../assets/screens/cloud/claude-chatgpt-connector/after-revoke.png){: width="601" height="420" }

## Related

- [Access control](access-control.md) — the grants every connector call is
  checked against
- [CLI and MCP for AI assistants](../cli/ai-cli-and-mcp.md) — when to use
  the local CLI/MCP instead
- [Data connections](connections.md) — connecting the warehouse sources
  queries run against

# Refresh (https://docs.dbtcharts.com/cloud/refresh/)

# Refresh

!!! info "dbt Charts Cloud"
    This page describes [dbt Charts Cloud](index.md), the hosted
    product — these features are not part of the open source `dct`
    engine.


A dashboard's charts run queries against your database. Refresh policy
decides when those queries actually re-run, versus when a viewer sees a
cached result.

## What's Cloud-owned

Refresh in Cloud is **manual**: a dashboard re-runs its queries when someone
asks it to. There is no scheduled refresh — no cadence, timezone, event
trigger, retry or notification settings — and none of that is configurable
anywhere in the product today.

Who can trigger a refresh follows the same path-based access model as viewing
and editing: refreshing is one of the capabilities a role can carry, so
whoever holds an Editor-level (or custom) grant with that capability at a
path can refresh it. Anyone holding it sees a manual refresh control in the
dashboard's own toolbar. Like [access](access-control.md), that binding is
Cloud state keyed to a dashboard's path, not something in your project's YAML
or git history.

![The manual refresh button among the dashboard's other toolbar actions](../assets/screens/cloud/refresh/dashboard-refresh-control.png){: width="125" height="40" }

## What core gives you

Running dbt Charts on its own (`dct serve` or `dct render`), you control
freshness directly through the query-result cache. By default the cache is a
file in your user cache directory, so results outlive the server process and a
restart does not refresh anything; a result is reused until it is older than
its query's `cache:` duration. Pass `--no-cache` to re-run every query on every
request, or point `--cache <path>` (or `DCT_CACHE_PATH`) at a file of your own.
See the [`dct serve` reference](../cli/serve.md) for the full set of caching
flags.

Cloud builds on these same primitives; a manual refresh is what decides
*when* to invalidate and re-run, not a different query or storage mechanism
underneath.

## Related

- [Access control](access-control.md): the path-based model refresh
  permissions follow
- [`dct serve` reference](../cli/serve.md): cache flags for local development

# Overview (https://docs.dbtcharts.com/guides/)

# Guides

Task-oriented guides for installing, learning, and operating dbt Charts.

Read in this order:

- [Installation & Setup](installation.md)
- [Getting Started Tutorial](getting-started.md)
- [Using dbt Charts with dbt v2](dbt-fusion.md)
- [CLI Reference](../cli/index.md)
- [Validating Boards in CI](ci.md)
- [Statistical Table Design Handbook](statistical-table-design-handbook.md)
- [Palettes](palettes.md)
- [Palette resolver](palette-resolver.md)

# Forecasting with SQL (https://docs.dbtcharts.com/guides/forecasting-with-sql/)

# Forecasting with SQL

dbt Charts can visualize forecasts computed by SQL, a dbt model, or a warehouse
ML feature. The board does not need a special forecasting chart type. Your query
returns an ordered time column plus one or more measures, and a line or area
chart plots the result.

This supports forecasting workflows, including actual-versus-forecast views. It
is different from a native FP&A planning system: dbt Charts does not author a
budget, scenario, or write-back workflow. The forecast logic and any future
periods belong in SQL or in the model that SQL reads.

## The forecast is a query result

A forecast query can return a shape like this:

```sql
SELECT
  month,
  actual_revenue,
  forecast_revenue
FROM monthly_revenue_forecast
ORDER BY month
```

Historical rows can contain both measures. Future rows normally contain a null
`actual_revenue` and a value for `forecast_revenue`. The board treats both
columns as ordinary series. This makes the same chart work with a forecast
calculated by a dbt model, warehouse SQL, or a warehouse-native ML function.

## Fit a SQL trend and plot it

The following runnable example fits a straight-line trend to the sample monthly
metrics and plots the fitted series beside the observed revenue. The same shape
can be extended to future periods by adding future rows in the SQL or dbt model.

```dbt-charts-example
source: db

queries:
  monthly_revenue_forecast:
    sql: |
      WITH indexed AS (
        SELECT
          month,
          revenue AS actual_revenue,
          ROW_NUMBER() OVER (ORDER BY month) AS month_index
        FROM dundersign_serving.monthly_metrics
      ),
      fit AS (
        SELECT
          REGR_INTERCEPT(actual_revenue, month_index) AS intercept,
          REGR_SLOPE(actual_revenue, month_index) AS slope
        FROM indexed
      )
      SELECT
        indexed.month,
        indexed.actual_revenue,
        fit.intercept + fit.slope * indexed.month_index AS forecast_revenue
      FROM indexed
      CROSS JOIN fit
      ORDER BY indexed.month

charts:
  revenue_forecast:
    query: monthly_revenue_forecast
    type: line
    title: Actual Revenue and Forecast
    x: month
    y: [actual_revenue, forecast_revenue]
    style:
      number_format: currency_whole

rows:
  - revenue_forecast
```

`REGR_SLOPE` and `REGR_INTERCEPT` are convenient when the warehouse supports
them. For warehouses without those aggregates, calculate the slope and
intercept from `AVG`, `SUM`, or the warehouse's covariance functions. A rolling
average, seasonal model, or warehouse ML prediction can use the same output
shape. The important contract is that the SQL returns the time grain and the
measures the chart should display.

For a more detailed regression example, including dialect notes and layering a
fitted series over a base chart, see [Trend Lines in Layered Charts](../charts/layered-charts.md#trend-lines).

## Forecasting is not planning

Forecasting means estimating future values from historical or other input data.
Planning and budgeting usually add scenario authoring, approvals, allocations,
and write-back to an operational system. dbt Charts can display the results of
those workflows when they are modeled in the warehouse, but it does not provide
the planning workflow itself.

Waterfall and Gantt are also supported chart recipes for presenting planning and
forecast context. See [Waterfall and Gantt Recipes](../charts/types.md#waterfall-and-gantt-recipes)
for their encodings.

## Related documentation

- [Queries](../queries.md): SQL, dbt models, and query composition.
- [Line Graphs](../charts/line-graphs.md): multiple measures and time-series lines.
- [Area Charts](../charts/area-charts.md): actual-versus-forecast bands.
- [Waterfall and Gantt Recipes](../charts/types.md#waterfall-and-gantt-recipes): composed bar charts for ranges and running totals.

# Palettes (https://docs.dbtcharts.com/guides/palettes/)

# Palettes

This page is the catalog. For how to call the resolver (`palette()`,
`color()`, YAML shorthand, errors, smart defaults, scoring, anti-patterns)
see [Palette resolver](./palette-resolver.md).

## Families

Every palette belongs to one of five families. The family determines how the
resolver treats the palette and what kind of data it's for.

| Family | Purpose | Used for |
|---|---|---|
| `sequential` | Ordered magnitude (light → dark) | Continuous numeric data without a midpoint |
| `diverging` | Signed values around a midpoint | Continuous numeric data with a meaningful zero or center |
| `categorical` | Unordered categories | Discrete enums where each value is its own identity |
| `scaffold` | UI structural framing | Canvas, borders, dividers, axis text; *not* data encoding |
| `tone` | Role tokens | Negative / positive / warning semantics |

Scaffolds and tones use named slots (`canvas`, `solid`, `text`, …), not
numbered stops. The other three families use ordered stops.

---

## Sequential

Use for ordered magnitude: light at the low end, dark at the high end.
All sequential palettes ship 11 stops and downsample evenly: pass `steps=N`
to get N evenly-spaced stops from the spine.

**WCAG note.** Dark-end stops will fail WCAG AA (4.5:1) against
`#222` body text. For table cell backgrounds, use
`palette(name, surface="table")`; see
[Palette resolver](./palette-resolver.md#surfacetable-wcag-aa-safe-table-fills),
which carves the spine at the contrast boundary and returns
AA-safe stops. Or set an explicit `text_color` override on dark cells.

### `dbt-seq-blue`: default sequential

Single-hue blue. Default for continuous numeric data without a midpoint.

<div class="dbt-palette">
  <div class="dbt-palette__swatches">
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#e4f0fc;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">step 1</span><span class="dbt-palette__hex">#e4f0fc</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#c1dbf5;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">step 2</span><span class="dbt-palette__hex">#c1dbf5</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#9fc5eb;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">step 3</span><span class="dbt-palette__hex">#9fc5eb</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#80b0de;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">step 4</span><span class="dbt-palette__hex">#80b0de</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#649acf;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">step 5</span><span class="dbt-palette__hex">#649acf</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#4a85bc;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">step 6</span><span class="dbt-palette__hex">#4a85bc</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#3270a8;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">step 7</span><span class="dbt-palette__hex">#3270a8</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#1b5b92;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">step 8</span><span class="dbt-palette__hex">#1b5b92</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#04477a;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">step 9</span><span class="dbt-palette__hex">#04477a</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#00345d;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">step 10</span><span class="dbt-palette__hex">#00345d</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#002341;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">step 11</span><span class="dbt-palette__hex">#002341</span></div></div>
  </div>
</div>

### Other sequential hues

Same 11-stop architecture, different hue anchor. Pick by editorial fit;
all share the WCAG dark-end caveat above.

| Palette | Reads as | Light end | Mid (step 6) | Dark end |
|---|---|---|---|---|
| `dbt-seq-amber` | Honey → deep amber | `#f6edde` | `#a2781a` | `#2e1f00` |
| `dbt-seq-brown` | Cream → warm brown (pairs with paper theme) | `#f3eee6` | `#9b785e` | `#341911` |
| `dbt-seq-gray` | Pure achromatic (magnitude without hue) | `#eeeeee` | `#808080` | `#222222` |
| `dbt-seq-green` | Single-hue green | `#e4f3ea` | `#44926e` | `#002a19` |
| `dbt-seq-purple` | Single-hue purple | `#f5eaf8` | `#9b6ba8` | `#32113a` |
| `dbt-seq-rust` | Cream-peach → terracotta → deep rust | `#fdeae3` | `#b96648` | `#3e1000` |
| `dbt-seq-teal` | Teal / turquoise | `#dff3f5` | `#00919d` | `#00272b` |

---

## Diverging

Use for signed values around a midpoint: temperature anomalies, profit/loss,
deviations from a baseline. All diverging palettes ship 11 stops with a
neutral midpoint at step 6. Even-N downsamples auto-skip the midpoint
(no gray middle); odd-N include it.

### When to use which

| Situation | Palette |
|---|---|
| Default CVD-safe diverging | `dbt-div-blue-red` |
| Political-sensitivity (avoid red/blue) | `dbt-div-orange-teal` |
| Financial loss/gain (red negative, green positive) | `dbt-div-crimson-green`; must pair with icon + label |
| Climate / atmospheric data (conventional sunset ramp) | `dbt-div-sunset` |
| Scientific visualization (Moreland 2009) | `dbt-div-coolwarm` |

### `dbt-div-blue-red`: default

Symmetric blue-to-red about a light midpoint. CVD-safe at common subset counts.

<div class="dbt-palette">
  <div class="dbt-palette__swatches">
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#002f55;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">low extreme</span><span class="dbt-palette__hex">#002f55</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#00508a;"></div><div class="dbt-palette__meta"><span class="dbt-palette__hex">#00508a</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#2575b9;"></div><div class="dbt-palette__meta"><span class="dbt-palette__hex">#2575b9</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#689bcc;"></div><div class="dbt-palette__meta"><span class="dbt-palette__hex">#689bcc</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#a3c0dd;"></div><div class="dbt-palette__meta"><span class="dbt-palette__hex">#a3c0dd</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#e4e4e4;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">midpoint</span><span class="dbt-palette__hex">#e4e4e4</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#dcb1a9;"></div><div class="dbt-palette__meta"><span class="dbt-palette__hex">#dcb1a9</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#c88074;"></div><div class="dbt-palette__meta"><span class="dbt-palette__hex">#c88074</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#b04f41;"></div><div class="dbt-palette__meta"><span class="dbt-palette__hex">#b04f41</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#852c21;"></div><div class="dbt-palette__meta"><span class="dbt-palette__hex">#852c21</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#590b05;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">high extreme</span><span class="dbt-palette__hex">#590b05</span></div></div>
  </div>
</div>

### Other diverging palettes

| Palette | Low extreme | Mid | High extreme | Notes |
|---|---|---|---|---|
| `dbt-div-orange-teal` | `#4c1f00` | `#e4e4e4` | `#003634` | Symmetric, fully CVD-safe; non-politically-loaded |
| `dbt-div-crimson-green` | `#540a31` | `#e4e4e4` | `#00481d` | Engineered red↔green CVD pass via lightness asymmetry; **icon + label required** |
| `dbt-div-sunset` | `#125a56` | `#eceada` | `#a01813` | Paul Tol multi-hue ramp; CVD-safe; conventional in climate work |
| `dbt-div-coolwarm` | `#3b4cc0` | `#dddddd` | `#8b0000` | Moreland 2009; canonical in ParaView/VTK and scientific viz |

---

## Categorical

Use for unordered categories: series in a multi-line chart, slices in a
stacked bar, items in a legend. Categorical palettes ship a fixed number of
slots; `steps=N` returns the first N. There is no interpolation: stops are
what you get.

### One value, one color, across the whole board

A palette says which colors are available. It does not, on its own, say which
category gets which one, and if each chart decides that for itself, the same
category drifts between charts. `Electronics` ends up blue on the bar chart
and green on the line chart, and the reader has to re-read every legend
instead of trusting the color.

dbt Charts settles the question once per board. Before any chart renders, the
engine reads the executed rows, collects the distinct values of every
categorical field, and assigns each value a palette **slot**. Every chart that
draws that field then paints it from that slot, so a value keeps its color
everywhere, including on charts whose data is missing some of the values.

What is shared is the slot, not the hex. Everything a chart derives from its
palette is indexed the same way (the fill, the darker ink its direct labels
use, the swatch in an attached table), so those stay in step with each other
automatically.

Three consequences worth knowing:

- **One chart's data never disturbs another's colors.** A chart filtered down
  to two of five categories draws those two in the colors they have everywhere
  else, rather than sliding them up into the first two slots.
- **A nested board keeps its own theme.** If part of a board sets a different
  theme, a shared value takes the same *slot* in each theme's palette rather
  than being repainted in the outer theme's colors. The two halves agree on
  which position a value owns; each still looks like the theme it asked for.
  A chart whose own palette is too short to reach the slot a value owns is the
  one exception: it declines the binding and keeps the coloring it would have
  had, rather than wrapping around and giving two categories one color.
- **It only ever re-colors a `color:` channel a chart already has.** A chart
  that identifies a category some other way (a single-metric bar with
  `x: category` and no `color:`) keeps the ink it has today (see
  [`single_series_palette`](#single_series_palette-ink-for-single-series-charts)).
  Giving it a color channel it never asked for would override authored
  static colors, so the binding leaves it alone.

#### The threshold

A field is bound when **two or more charts** on the board use it as their
`color:` channel. A field only one chart colors by has no
cross-chart consistency to preserve, so it keeps the chart-local coloring it
would have had. This keeps small boards from
acquiring bindings they gain nothing from.

A chart with authored `layers:` counts like any other: its base `color:`
field binds, and each layer keeps its own series color, taken from a palette
slot no category uses.

#### Pinning a category

To fix a specific value to a specific color, author it under
`style.charts.category_colors`, keyed by data field. The keys under `values:`
are the literal data values the field takes in your query results: write
them exactly as the query returns them, not a display label.

```yaml {contract=board-root}
style:
  charts:
    category_colors:
      category:
        values:
          Electronics: category[1]
          Accessories: category[2]
          Tools: dbt-grays.muted
```

Values accept a palette token (resolved against the board's theme, so a theme
swap re-skins the board) or a literal hex. Anything else is rejected at
compile time rather than silently ignored.

A few rules follow from the block being intent rather than a cache:

- **Authoring a field binds it**, even on a single chart: the threshold only
  gates automatic binding.
- **Authored entries take the first slots.** Values found in the data but
  absent from the block are assigned after them, in first-seen order.
- **A pinned color is never reused** for a discovered value, so no two
  categories of a bound field share a swatch. Pinning two *drawn* values to
  the same color is an error rather than a silent collision.
- **A pin naming a palette color pins the slot, not the ink.** `category[2]`
  and the hex that `category[2]` resolves to mean the same thing: this value
  owns slot 2. A color the palette does not contain is taken literally.
- **A pin naming a value the render does not draw is skipped**, and warns.
  It claims no swatch, so nothing else shifts. dbt Charts cannot tell a
  misspelled pin from a category a variable filter excluded today, so it
  declines to blank the board over the difference and raises
  `WARN-CATEGORY-COLOR-PIN-UNSEEN` naming the value instead.

Pinning is also what makes an assignment survive *new* data. Slots are handed
out in the order values are first seen, so a category that shows up for the
first time partway through a chart's rows takes the slot at that position and
pushes the values after it down one. Within a single render everything stays
consistent either way; pinning is what holds a color still from one week to
the next.

If a field has more distinct values than the palette has swatches, what happens
depends on who asked for the binding:

- **You authored the field.** dbt Charts raises. You named it, so quietly not
  honoring the pins would be the wrong kind of silence. Only unpinned values
  and pins naming a palette color need a swatch, so pin the extra values to a
  color outside the palette (a variant like `category[3].light`, or a hex),
  widen the palette, or reduce the distinct count in the query.
- **The engine bound it on its own.** It declines instead: the field keeps the
  per-chart coloring it had before, which is also the only place two categories
  can still land on the same swatch, because each chart cycles the palette
  independently. Binding is something the engine volunteers; it would rather
  hand the board back unchanged than seat two categories on one color.

Either way the swatch count is the ceiling: nothing cycles inside a bound
field.

### `editorial-10`: default for clarity themes

Quieter ten-color set designed for *cycling*: the engine fills slots in
order without a human picker. It is the categorical family for the shipped
`clarity` and `paper` themes.

<div class="dbt-palette">
  <div class="dbt-palette__swatches">
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#40639c;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">blue</span><span class="dbt-palette__hex">#40639c</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#779bc9;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">sky</span><span class="dbt-palette__hex">#779bc9</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#608470;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">green</span><span class="dbt-palette__hex">#608470</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#775770;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">purple</span><span class="dbt-palette__hex">#775770</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#d49656;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">gold</span><span class="dbt-palette__hex">#d49656</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#ae6349;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">rust</span><span class="dbt-palette__hex">#ae6349</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#a0b6b7;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">teal</span><span class="dbt-palette__hex">#a0b6b7</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#ad9c7f;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">brown</span><span class="dbt-palette__hex">#ad9c7f</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#7a8895;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">gray</span><span class="dbt-palette__hex">#7a8895</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#5c6668;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">graphite</span><span class="dbt-palette__hex">#5c6668</span></div></div>
  </div>
</div>

The order is blue, sky, green, purple, gold, rust, teal, brown, gray,
graphite. Every companion uses the same positions. Public roles provide stable
semantic access, including `orange` for rust, `sage` for teal, and `charcoal`
for graphite. `cyan` and `moss` are also accepted as names for the `sky` and
`sage` slots. Prefer roles such as `category.green` when hue meaning matters;
numeric slots preserve position, not semantic intent, across palette retunes.

**Reach for `editorial-10` (over `vivid-10`) when:**

- The dashboard is meant to read as editorial: calmer, lower-chroma, fewer competing hues.
- Charts should accompany a dark single-series mark without competing with it.
- Cross-chart palette consistency matters and you'd rather not hand-pin per chart.

**Stay on `vivid-10` when:**

- A chart needs up to ten categories and editorial restraint isn't a goal. `vivid-10` keeps all ten hues apart for typical vision. For color-vision-deficient readers, the first five series clear the Leonardo gate (ΔE 11) and all ten keep a floor of ΔE 9; past five series, add direct labels or group the tail.
- The product surface is brand-default rather than editorial.

### Variants: dark, light, pale, deep

Categorical only. Every categorical palette -- shipped or inline
(`palette: ["#4e79a7", "#f28e2b", ...]`) -- derives four literal tiers
live, computed from its own stops (`variant()`, no companion file to
author or keep in sync). Address one with a trailing token segment, on
any addressing form:

| Form | Example |
|---|---|
| Role + alias | `category.blue.dark` |
| Role + slot | `category[2].light` |
| Palette name + slot | `vivid-10.3.pale` |
| Whole list | `category.deep`, `vivid-10.pale` |

The four words are literal, not a contrast direction: `dark` is never
lighter than its base and `light` never darker, on every theme. Which
variant a board or theme reaches for on a dark canvas -- so a mark stays
legible, or a mark stays deliberately recessive -- is an authoring
decision; the tier itself does not flip.

A continuous (sequential/diverging) palette's own `-dark` fork
(`dbt-seq-blue-dark`, ...) is a different, older naming convention: a
real, separately-shipped palette name, not this grammar's `.dark`
segment. A continuous palette's own stops already encode a monotonic
lightness order, so the variant grammar does not apply to it -- writing
`dbt-seq-blue.dark` raises rather than silently resolving.

| Tier | Reads as | Typical use |
|---|---|---|
| `dark` | A notch darker than the base, chroma held | Direct-label ink, contrast on light canvases |
| `light` | Moderately lighter, chroma reduced | A recessive twin that still carries its hue |
| `pale` | Very light, low chroma, one uniform band -- every stop converges to the same target lightness, regardless of the base | Dim-the-chorus / de-emphasis highlighting |
| `deep` | Very dark, chroma held, converges toward a dark pole (not a fixed band -- a darker base still ends up darker than a lighter one) | Single-series ink |

Direct-label ink (endpoint labels, stacked-bar segment names, pie slice
labels, support-table header swatches) is not sourced from the `dark`
variant -- the engine derives it live from each mark color against the
chart's own canvas (`label_ink()`), which is what keeps labels legible on
dark themes like `neon` with no theme-level rebind.

A few `editorial-10` slots, tiers computed rather than hand-tuned:

| Slot | `editorial-10` | `.dark` | `.light` | `.pale` | `.deep` |
|---|---|---|---|---|---|
| 1 | `#40639c` blue | `#284980` | `#7a90b4` | `#c5d2e7` | `#0e2e63` |
| 5 | `#d49656` gold | `#a16723` | `#ddb793` | `#e2cdb9` | `#543000` |
| 10 | `#5c6668` graphite | `#434d4f` | `#8b9192` | `#ced2d2` | `#2a3335` |

### `single_series_palette`: ink for single-series charts

`palette` (categorical, above) is the color source for charts with a `color:` channel; dbt Charts indexes into it once per distinct series value. `single_series_palette` is the separate ink source for charts that have **no** `color:` channel at all: a plain single-metric bar, line, or area. There's no series to pick a slot by value, so dbt Charts assigns each single-series chart a slot by its **position in the board**: the compiler walks the board tree in reading order and hands out `single_series_palette[0]`, `single_series_palette[1]`, and so on, wrapping back to the start once the list is exhausted. Two single-series bar charts on the same board get two different inks; the same chart re-rendered always gets the same ink, because the slot comes from tree position, not from data.

Set it at the theme or board level under `style.charts`, as a list of color
tokens or a palette name (expanded to that palette's stops at validation time).
Theme-relative role tokens resolve against the active theme, so
`category.sky.deep` selects editorial sky ink under Clarity and vivid sky ink
under Vivid.

```yaml {contract=unverified}
style:
  charts:
    single_series_palette: editorial-10.deep
    # or a role-token list:
    # single_series_palette: [category.sky.deep, category.sage.deep, category.green.deep]
```

A chart-local `style.color.static` or `style.color.categorical` override always wins over the rhythm slot; use it when one specific chart needs to break from the cycle (for example, to match an established brand color for that metric).

The rhythm slot is unaffected by the board-wide category binding: that binding only re-colors a `color:` channel a chart already has, and a single-series chart has none. See [One value, one color, across the whole board](#one-value-one-color-across-the-whole-board).

### `vivid-10`: general-purpose ten-color

Blue-led and green-third: the five most chromatic hues run first, then purple,
moss, brown, and the two neutrals. Purple and moss are tuned against
color-vision deficiency rather than for chroma, which is why they follow the
lead five. Brown and charcoal sit at slots 8 and 10 because they are the only
two stops that fall under 3:1 against a near-black canvas, so a chart needs
eight series before it draws one. The default categorical palette for the
`vivid` and `neon` themes; `editorial-10` (above) is the categorical family
for `clarity` and `paper`.

<div class="dbt-palette">
  <div class="dbt-palette__swatches">
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#0073c2;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">blue</span><span class="dbt-palette__hex">#0073c2</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#00c8ee;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">cyan</span><span class="dbt-palette__hex">#00c8ee</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#00ad75;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">green</span><span class="dbt-palette__hex">#00ad75</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#e1a500;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">gold</span><span class="dbt-palette__hex">#e1a500</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#da5a23;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">orange</span><span class="dbt-palette__hex">#da5a23</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#a86c9d;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">purple</span><span class="dbt-palette__hex">#a86c9d</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#6a8f47;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">moss</span><span class="dbt-palette__hex">#6a8f47</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#7a5531;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">brown</span><span class="dbt-palette__hex">#7a5531</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#949daa;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">gray</span><span class="dbt-palette__hex">#949daa</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#505b6b;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">charcoal</span><span class="dbt-palette__hex">#505b6b</span></div></div>
  </div>
</div>

Every slot has all four [variants](#variants-dark-light-pale-deep): `vivid-10.1.dark`,
`vivid-10.1.light`, `vivid-10.1.pale`, `vivid-10.1.deep`. Direct-label ink is
not sourced from the dark variant -- the engine derives it live from each
mark color against the chart's own canvas.

### `hero-6`: single dominant series

A six-color hero-blue-versus-neutrals palette for charts where one series
should dominate. Slot 1 is the only saturated color; slots 2–6 are
gray/brown neutrals that step into warmth.

<div class="dbt-palette">
  <div class="dbt-palette__swatches">
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#2768a3;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">hero blue</span><span class="dbt-palette__hex">#2768a3</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#acb7c2;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">light gray</span><span class="dbt-palette__hex">#acb7c2</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#929aa6;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">gray</span><span class="dbt-palette__hex">#929aa6</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#a68d72;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">brown</span><span class="dbt-palette__hex">#a68d72</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#b8a593;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">beige</span><span class="dbt-palette__hex">#b8a593</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#c7a987;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">sand</span><span class="dbt-palette__hex">#c7a987</span></div></div>
  </div>
</div>

**Contract.** The hero blue is both the most saturated *and* the darkest
color in the palette; that's the perceptual rule that makes slot 1 win.
Don't reorder; the support neutrals are designed to lie behind it.

### Tonal monochrome: `category-6-tonal-*`

Single-hue categorical palettes for editorial / brand-restrained
dashboards. Five hues ship: blue, green, purple, orange, brown, each
anchored near a `vivid-10` hue so they coordinate with the default
categorical system -- except purple, which keeps its own hue, about 14°
from `vivid-10`'s purple.

| Palette | Anchor color | Reads as |
|---|---|---|
| `category-6-tonal-blue` | `#0375c4` | All-blue |
| `category-6-tonal-green` | `#00875a` | All-green |
| `category-6-tonal-purple` | `#9650a8` | All-purple |
| `category-6-tonal-orange` | `#b74c1f` | All-orange |
| `category-6-tonal-brown` | `#9a642b` | All-brown (paper-theme companion) |

**Contract: 4 strict-safe + 2 extended.** Every tonal palette ships
6 stops with a layered contract:

| Slots | Role | CVD safety |
|---|---|---|
| 1–4 (core) | strict-safe | Color alone sufficient; pairwise CVD ΔE ≥ 11 |
| 5–6 (extended) | form-redundant only | Below the strict gate. **Require dash, marker, or pattern redundancy when used in a chart** |

The 6-stop cap is structural: at fixed hue, English's color vocabulary
saturates around 4–5 stops ("two blues that are 'just blue'"), and CVD
simulation collapses adjacent stops. If a chart needs 7+ categories, use
`vivid-10` instead.

**When to use.** Editorial / branded dashboards where chromatic restraint
matters more than category count. Small-multiples and KPI tiles where the
color budget is tight. Charts with direct labels or stable category order
; the legend reads via labels, not by glance. Avoid for many-slice pies,
dense scatters, or stacked bars with more than four segments.

**Brown ↔ cream bridge.** `category-6-tonal-brown`'s extended slots (5–6)
are deliberately hue-shifted to overlap the `dbt-creams` scaffold region.
On the paper theme, slot 6 visually merges with the surrounding chrome;
that's the design intent. Use slot 6 only with form redundancy on paper
backgrounds.

### Compatibility palettes

| Palette | Use |
|---|---|
| `tableau` | Tableau-style 10-color set. Retained for users who want the familiar Tableau hues instead of `vivid-10`. |

---

## Scaffold

Scaffolds are UI structural framing: canvas, borders, dividers, axis
labels, table stripes, secondary text. **Not data encoding.** Address
them through named aliases (`chrome.canvas`, `chrome.ink`, etc.) rather
than by integer slot.

### `dbt-grays`: neutral chrome

Twelve steps from near-white to near-black. The darkest step, `void`, is
the near-black canvas for dark themes; `clarity`, `vivid`, and other light
themes use the lighter steps for chrome.

<div class="dbt-palette">
  <div class="dbt-palette__swatches">
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#FAFAFA;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">canvas</span><span class="dbt-palette__hex">#FAFAFA</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#F7F8FA;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">surface</span><span class="dbt-palette__hex">#F7F8FA</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#EDEFF2;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">grid</span><span class="dbt-palette__hex">#EDEFF2</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#DFE1E5;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">border</span><span class="dbt-palette__hex">#DFE1E5</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#8A8C8F;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">subtitle</span><span class="dbt-palette__hex">#8A8C8F</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#626366;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">muted</span><span class="dbt-palette__hex">#626366</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#313233;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">heading</span><span class="dbt-palette__hex">#313233</span></div></div>
  </div>
</div>

### `dbt-creams`: warm chrome

Same twelve-step shape as `dbt-grays`, in warm cream tones. Default
chrome for the `paper` theme.

<div class="dbt-palette">
  <div class="dbt-palette__swatches">
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#FAF7F0;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">canvas</span><span class="dbt-palette__hex">#FAF7F0</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#F5F2EB;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">surface</span><span class="dbt-palette__hex">#F5F2EB</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#E9E1D2;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">grid</span><span class="dbt-palette__hex">#E9E1D2</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#DDD3C0;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">border</span><span class="dbt-palette__hex">#DDD3C0</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#918878;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">subtitle</span><span class="dbt-palette__hex">#918878</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#6F685D;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">muted</span><span class="dbt-palette__hex">#6F685D</span></div></div>
    <div class="dbt-palette__swatch"><div class="dbt-palette__color" style="background:#403B37;"></div><div class="dbt-palette__meta"><span class="dbt-palette__name">heading</span><span class="dbt-palette__hex">#403B37</span></div></div>
  </div>
</div>

---

## Tone

Tone palettes encode role semantics: info, negative, positive, warning. Six
named slots per palette: `bg`, `subtle`, `border`, `solid`, `solid-hover`,
`text`. Address them through `color()`, not `palette()`.

**Contract.** All tone slots are designed so canonical pairs (text-on-bg,
solid-on-white) pass WCAG AA. Tone color alone is insufficient
communication; always pair with icon + label per the standard
accessibility discipline.

### `info`: blue / information / neutral status

Informational notes, neutral status messages, non-error callouts.

| Alias | Hex | Role |
|---|---|---|
| `bg` | `#e7f4ff` | Very light blue background |
| `subtle` | `#d6ecff` | Secondary fill or hover-on-bg |
| `border` | `#6bb9f8` | Mid-tone divider / outline |
| `solid` | `#008cdd` | Canonical "information" fill |
| `solid-hover` | `#0070b3` | Darker variant for button hover state |
| `text` | `#003659` | AA-contrast text color on `.bg` and on white |

### `negative`: red / stop / bad

Critical errors, destructive actions, losses. Western convention: red = stop/bad.

| Alias | Hex | Role |
|---|---|---|
| `bg` | `#ffedec` | Very light peach tint for surface backgrounds |
| `subtle` | `#ffdbd8` | Hover-on-bg or secondary fill |
| `border` | `#e79491` | Mid-tone divider / outline |
| `solid` | `#94001e` | Canonical "this is negative" fill |
| `solid-hover` | `#6e0014` | Darker variant for button hover state |
| `text` | `#4b000a` | AA-contrast text color on `.bg` and on white |

### `positive`: green / go / good

Successful actions, gains, completions. Western convention: green = go/good.

| Alias | Hex | Role |
|---|---|---|
| `bg` | `#e3f8e9` | Very light green background |
| `subtle` | `#cff2da` | Secondary fill / hover-on-bg |
| `border` | `#82cb9b` | Mid-tone divider / outline |
| `solid` | `#00884d` | Canonical "all good" fill |
| `solid-hover` | `#006d3c` | Darker variant for button hover state |
| `text` | `#003e20` | AA-contrast text color on `.bg` and on white |

### `warning`: amber / caution

Pay attention; something needs input, nothing's broken. Western convention: amber = caution.

| Alias | Hex | Role |
|---|---|---|
| `bg` | `#fff3e5` | Very light cream-amber background |
| `subtle` | `#ffe7ca` | Secondary fill / hover-on-bg |
| `border` | `#f0b871` | Mid-tone divider / outline |
| `solid` | `#e69812` | Canonical "pay attention" fill |
| `solid-hover` | `#c68100` | Darker variant for button hover state |
| `text` | `#643f00` | AA-contrast text color on `.bg` and on white |

---

## Further reading

- [Palette resolver](./palette-resolver.md): how to call `palette()` /
  `color()` from Python or YAML, plus error semantics and the anti-pattern
  list.
- [Tonal foundations](./tonal-foundations.md): the neutral-frame thinking
  that pairs with the chrome scaffolds.

# Palette resolver (https://docs.dbtcharts.com/guides/palette-resolver/)

# Palette resolver

For *which* palettes ship and what each looks like, see
[Palettes](./palettes.md). This page covers *how to use them*.

## Resolver API

```python
from dbt_charts.core.compile.resolve.style.palette import palette, color

# Sequential / diverging: returns a list of hex stops.
palette("dbt-seq-blue")                     # 11 default stops
palette("dbt-seq-blue", steps=5)            # 5 evenly spaced stops
palette("dbt-seq-blue", reverse=True)       # reversed

# Diverging auto-skips the midpoint on even N.
palette("dbt-div-blue-red", steps=6)        # flanks, no gray middle

# Categorical and scaffold: fixed slots.
palette("vivid-10")                         # all 10 slots
palette("vivid-10", steps=4)                # first 4 slots

# Named tokens: tone roles and scaffold stops.
color("negative.solid")                     # "#94001e"
color("dbt-grays.ink")                      # "#222222"
```

### YAML shorthand

Dashboard YAML supports a compact shorthand:

```yaml {contract=unverified}
style:
  palette: "dbt-seq-blue"        # 11 stops
  palette: "dbt-seq-blue:5"      # 5 stops
  palette: "dbt-seq-blue_r"      # reversed
  palette: "dbt-seq-blue:5_r"    # 5 stops reversed
  palette: "dbt-div-blue-red:6"  # 6 stops, midpoint auto-skipped
  fill: "negative.solid"
  text: "dbt-grays.ink"
```

The shorthand is parsed by `_parse_palette_reference()`; programmatic callers
should pass kwargs (`steps=`, `reverse=`) instead.

## Theme-portable references vs. absolute pins

Color tokens in board YAML come in two grammars with different contracts:

```yaml {contract=board-root}
# Board-root style block
style:
  charts:
    marks:
      bar:
        # Theme role: resolves through the active theme's
        # `style.palettes` bindings. Switching themes re-resolves the
        # color: on vivid, `category[2]` is vivid-10's cyan; on
        # clarity, editorial-10's sky. A trailing variant segment
        # (`.dark`/`.light`/`.pale`/`.deep`) addresses a literal tier
        # of that same slot, and named aliases like `chrome.ink`
        # resolve through the chrome role.
        border:
          color: "category[2].dark"
      rule:
        stroke:
          # Absolute pin: names a physical palette and slot.
          # Theme-agnostic: the same hex on every theme, by design.
          color: "vivid-10.1"
```

Role tokens resolve everywhere colors are authored: theme YAML, the
board-root `style:` block, and chart-level `style:` blocks (the theme's
role bindings travel to the resolved boundary, so per-chart overrides
like `style.color.categorical: ["category[3].dark"]` follow a theme switch too).

**Default to theme roles when authoring boards.** A board written with role
references restyles itself completely on a theme switch. Reach for an
absolute pin only when the color is a deliberate pick that should survive
theme changes (a brand color, a semantic association like "gold means
contract revenue"); pinning is a feature there, not a bug.

Indexing is **1-indexed everywhere**: role brackets, absolute dot
references, and the integer slot aliases inside scaffold/tone palettes all
count from 1. Every stop-list family answers the positional form:
`color("vivid-10.3")`, `color("dbt-seq-blue.3")`, and
`color("dbt-div-blue-red.3")` all resolve the third stop. Tone and scaffold
palettes carry named aliases instead, so they take a slot name
(`color("positive.solid")`), not a position. The same physical stop carries
the same slot number in every variant of a family too; on the clarity
theme, `category.gold.light` and `editorial-10.5.light` are the same
gold-light color. Prefer the named role when the hue meaning should
survive a later slot reorder.

The shipped role bindings: `_base` binds `category` to the vivid-10 family
(inherited by `vivid` and `neon`); `clarity` and `paper` (which extends
clarity) rebind it to the editorial-10 family. Themes may rebind any role
via `style.palettes`, and boards can too (`style.palettes` is patchable at
the board root).

**Every categorical palette derives every tier live** (`variant()`,
compile/resolve/style/palette.py) -- there is no companion file to bind or
keep in sync. A third token segment addresses one: `category[2].dark`,
`category.blue.pale`, `vivid-10.3.deep`. `dark` is never lighter than its
base and `light` never darker, on every theme -- the tier names are
literal, not a contrast direction. Which variant a board or theme reaches
for on a dark canvas (so a mark stays legible, or a mark stays
deliberately recessive) is an authoring decision, covered in the theme
guide, not a rule this resolver enforces.

### `surface="table"`: WCAG-AA-safe table fills

For sequential and diverging spines, `palette(name, surface="table")`
returns a WCAG-AA-safe sub-palette intended for table cell backgrounds
behind `#222` body text:

```python
palette("dbt-seq-blue", surface="table")              # 11 AA-safe stops
palette("dbt-div-blue-red", surface="table", steps=5) # 5 AA-safe stops
```

The algorithm binary-searches the OKLCH-interpolated spine for the
lightness boundary where contrast against `#222222` crosses 4.5:1, then
generates `steps` stops evenly from the light end of the spine to that
boundary. The boundary is found on the continuous curve, not snapped to a
spine index, so the result is dense enough for any `steps` value without
falling off the readable edge.

`surface=` is **not** valid for categorical / scaffold / tone palettes;
their slots are fixed and there is no spine to carve. Passing
`surface="table"` on those families raises `SurfaceUnsupportedError`, as
does any unrecognized `surface=` string. `surface=None` and
`surface="default"` both return the standard downsample.

## Default palettes

When a board doesn't name a palette, colors come from the theme's
`style.palettes` roles:

| Role | Used for | `clarity` default |
|---|---|---|
| `category` | Categorical marks | `editorial-10` |
| `sequence` | Continuous scales | `dbt-seq-blue` |
| `diverge` | Signed or midpoint scales | `dbt-div-blue-red` |

Themes rebind roles: `paper` sets `sequence` to `dbt-seq-brown` and `neon` sets
it to `dbt-seq-blue-dark`. A board rebinds a role the same way under its own
`style.palettes`.

## Errors

| Exception | When |
|---|---|
| `UnknownPaletteError` | Name doesn't match; message suggests the nearest hit |
| `UnknownColorError` | `color(token)` slot unresolved |
| `CategoricalOverrequestError` | `steps=N > len(stops)` on categorical/scaffold |
| `SurfaceUnsupportedError` | `surface=` passed for a family that doesn't carve |
| `ToneAsPaletteError` | Tone name passed to `palette()` instead of `color()` |

## Anti-Patterns

A handful of famous palettes routinely produce misleading charts. The
resolver treats them two ways:

- **Hard fail**: the name is not shipped. `palette("jet")` raises
  `UnknownPaletteError`.
- **Warn + alias**: the name resolves to the nearest dbt Charts equivalent
  silently at compile time; a render-stage `WARN-PALETTE-UNSUPPORTED`
  diagnostic surfaces the nudge (`dct docs warnings --code WARN-PALETTE-UNSUPPORTED`).
  Migration paths still work either way.

### Hard-fail list

| Name | Why rejected |
|---|---|
| `jet` | Non-monotonic luminance creates illusory discontinuities and reverses ordering perception. Broadly criticized in the data-vis corpus (Cleveland, Cairo, Kosara). No defensible use remains. |
| `rainbow` | Same problem: hue steps masquerade as ordered magnitude. Luminance wobbles. |
| `hsv` | Not perceptually uniform; conflates hue and saturation. Produces banding. |

There is no dbt Charts substitute for these because their structure (rainbow,
maximal hue excursion) is the anti-pattern itself. If a chart really needs
distinct hues, use `vivid-10` (unordered) or `dbt-seq-blue` (ordered).

### Warn-and-alias list

| Name | Aliased to | Reason |
|---|---|---|
| `RdYlGn` | `dbt-div-crimson-green` | The classic red-yellow-green diverging pair is CVD-hostile; deuteranopes can't reliably distinguish the red and green ends. `dbt-div-crimson-green` is the only dbt Charts palette engineered to pass CVD ΔE ≥ 11 on R/G endpoints. |
| `parula` | `dbt-seq-blue` | MATLAB's default; not CVD-safe and superseded by the viridis family in most scientific tooling. `dbt-seq-blue` is dbt Charts's default sequential. |

The diagnostic message names the substitution explicitly so dashboards
rendered from third-party tooling don't crash, but the suggestion points at
the dbt Charts alternative for new work.

### References

- Borland & Taylor, *Rainbow Color Map (Still) Considered Harmful* (IEEE CG&A, 2007)
- Kenneth Moreland, *Diverging Color Maps for Scientific Visualization* (2009)
- Cindy Brewer et al., ColorBrewer 2.0: comparative palette library

## Palette scoring

The Colorgorical scoring helper scores any palette on four axes, a
re-implementation of the Colorgorical methodology ([Gramazio, Laidlaw,
Schloss, IEEE TVCG 2017](http://vrl.cs.brown.edu/color)) against the
public [XKCD color-name survey](https://xkcd.com/color/rgb.txt) (CC0) and
the [Schloss-Palmer 2011](https://colorcognitionlab.berkeley.edu/papers/schlosspalmer2011.pdf)
pair-preference regression.

| Score | What it measures |
|---|---|
| **Perceptual Distance** | CIEDE2000 ΔE between color pairs. Same metric as the Leonardo CVD gate. |
| **Name Difference** | Whether two colors land under different XKCD names: "can someone say 'the blue one' vs 'the green one'?" |
| **Name Uniqueness** | Whether a color unambiguously falls under one name, or sits on a boundary (cyan/teal, slate/charcoal). Higher = clearer. |
| **Pair Preference** | Schloss-Palmer regression (lightness contrast + hue-angle difference). Which pairs look good side-by-side in a legend. |

The primary gate remains **Leonardo ΔE ≥ 11** for CVD safety. Colorgorical
scoring is a **secondary quality signal**: a palette that passes Leonardo
is CVD-safe; passing the scoring functions says it is also *preferable*
and *legend-readable*.

**Known simplifications** vs the Colorgorical paper (deliberate; per the
Colorgorical paper):

- Name Difference / Uniqueness use the aggregated XKCD 949-centroid list,
  not the full 2.8M-response probability distributions from Heer-Stone
  2012. Colors near naming boundaries score worse than they would under
  the paper's full model.
- Pair Preference omits Schloss-Palmer's coolness term (requires a 5MB
  precomputed LAB→coolness lookup derived from their raw data). We keep
  the hue + lightness regression with the published coefficients
  (wh=-46.4222, wl=47.6133).

Scores are therefore mutually comparable across dbt Charts palettes, but not a
bit-exact reproduction of Colorgorical's paper numbers.

## Versioning

Once a palette spine is committed, its hex values are **immutable**.
Re-tunes ship under a new name (`dbt-seq-blue-v2`, say) so existing
dashboards don't silently shift. Bug fixes (for example, out-of-gamut typos) are
the one exception, documented in `PALETTE_CHANGELOG.md` when that
happens.

# Installation & Setup (https://docs.dbtcharts.com/guides/installation/)

# Installation & Setup

Get dbt Charts installed and configured in your environment.

---

## Prerequisites

Before installing dbt Charts, ensure you have:

- **Python 3.11+** installed
- **A database** dbt Charts can query: DuckDB, SQLite, Postgres, Snowflake, BigQuery, Redshift, Databricks, Spark, Trino, Athena, ClickHouse, or a local CSV/Parquet file. See [Warehouse adapters](#warehouse-adapters)

dbt Charts works with plain SQL, so **dbt is optional**. If you already run dbt,
dbt Charts can read your `profiles.yml` connection and query dbt-modeled tables
directly. But you don't need dbt to build dashboards.

---

## Installation

### Install dbt Charts

Install with [uv](https://docs.astral.sh/uv/getting-started/installation/)
(recommended) or [pip](https://pip.pypa.io/en/stable/installation/). If you have
neither yet, both of those pages cover Windows, macOS, and Linux.

```bash
# with uv (recommended); installs dct as a standalone CLI tool
uv tool install dbt-charts

# with pip
pip install dbt-charts
```

`uv tool install` is not the same as `uv pip install dbt-charts`. `uv tool install`
creates an isolated environment for the `dct` CLI and puts a shim on your `PATH`
(via `~/.local/bin`), independent of any project virtualenv: the closest uv
equivalent to a global `pip install`. `uv pip install dbt-charts` instead installs
dbt Charts into the *currently active* virtualenv, the way `pip install` does;
reach for that only when you want to `import dbt_charts` from your own project code,
not when you just want the `dct` command available everywhere.

If you build with dbt v2, use `uv tool install` (or `pipx`) and never install
dbt Charts into the environment that holds dbt v2. dbt v2 and dbt Core 1.x share
the `dbt-core` package name, and the warehouse adapters dbt Charts uses depend
on 1.x, so a shared environment ends with dbt v2 silently replaced. See
[Using dbt Charts with dbt v2](dbt-fusion.md#setup).

To use `dct mcp serve` (the MCP server for external AI agents), dbt Charts needs the optional `mcp` extras. If you run it without them installed, dbt Charts will detect the missing packages and offer to install them interactively. For non-interactive setups (CI, scripts), set `DCT_NO_AUTO_INSTALL=1` to suppress the prompt and get a clear error with the exact install command instead.

`dct playground` opens the hosted playground at [play.dbtcharts.com](https://play.dbtcharts.com) in your browser; no extra install required.

### Warehouse adapters

dbt Charts opens its own connection to your database, through a Python adapter
package. DuckDB and SQLite work out of the box. For every other warehouse,
install the matching extra:

| Warehouse | Extra |
|---|---|
| DuckDB, SQLite | included, nothing to install |
| Snowflake | `dbt-charts[snowflake]` |
| BigQuery | `dbt-charts[bigquery]` |
| Postgres | `dbt-charts[postgresql]` |
| Redshift | `dbt-charts[redshift]` |
| Databricks | `dbt-charts[databricks]` |
| Spark | `dbt-charts[spark]` |
| Trino | `dbt-charts[trino]` |
| Athena | `dbt-charts[athena]` |
| ClickHouse | `dbt-charts[clickhouse]` |
| Lake compute | `dbt-charts[lakecompute]` |
| SQL Server | `dbt-charts[sqlserver]`, plus Microsoft ODBC Driver 17 or 18 on the host |
| Microsoft Fabric | `dbt-charts[fabric]`, plus Microsoft ODBC Driver 17 or 18 on the host |

**Use the same installer you installed dbt Charts with.** `uv tool install`
creates an isolated environment for the `dct` CLI, and a later `pip install`
cannot add anything to it:

```bash
# if you installed the dct CLI with uv tool install
uv tool install "dbt-charts[snowflake]"

# if you installed dbt Charts into a virtualenv
pip install "dbt-charts[snowflake]"
```

Quote the argument either way: unquoted, the square brackets are shell glob
characters.

dbt Charts uses the adapter as a library for its own queries and never invokes
the `dbt` command. Each adapter depends on dbt Core 1.x, which is invisible in
an isolated `dct` environment but replaces dbt v2 when both share one
environment. If you build with dbt v2, see
[Using dbt Charts with dbt v2](dbt-fusion.md#setup).

### Verify Installation

```bash
dct --version
```

You should see the dbt Charts version number.

### Install the Editor Extension

If you author dashboards in VS Code or Cursor, install the dbt Charts extension:
it adds board YAML highlighting, snippets, and a live preview of the rendered
dashboard beside your file:

```bash
dct init code      # VS Code
dct init cursor    # Cursor
```

See the [VS Code & Cursor Extension](../editor-extension.md) page for everything
it provides and how to install it without the CLI.

---

## Upgrading

dbt Charts separates **package upgrade** (the Python wheel) from **project refresh** (workflow skill files copied into your repo). This matches how dbt, `gh`, and `npx skills` handle upgrades: pip bumps the tool; a separate command refreshes project-local artifacts.

### 1. Upgrade the package

```bash
pip install -U dbt-charts
# or, with uv:
uv pip install -U dbt-charts
```

Confirm which install is active:

```bash
dct --version
```

### 2. Refresh project artifacts

After upgrading the package:

```bash
dct init skills
```

Re-syncs skill directories (installed under a `dct-` prefix, for example, `dct-board-build/`). Retired skills are removed; current skills are always overwritten in place, no flag needed.

Targeted installs:

```bash
dct init skills agents          # .agents/skills/ (Cursor, Codex, Copilot)
dct init skills claude          # Claude Code skills directory
dct init skills --dir PATH      # custom path
```

Re-run after `pip install -U dbt-charts` to pull in skills added by the new release.

---

## Configuration

### Connect a Data Source

Name the database dbt Charts reads from in `dbt_charts.yml`. A local DuckDB file
needs no credentials, so it's the quickest way to start:

```yaml {contract=project-config}
# dbt_charts.yml
sources:
  analytics:
    type: duckdb
    path: ./data/analytics.duckdb
```

Direct source types (`postgres`, `snowflake`, `bigquery`, `redshift`,
`sqlite`) use the same credential fields as dbt profiles. See
[Sources](../sources/index.md) for every type and its connection settings.

**Using dbt?** Inside a dbt project you can skip this step: with no `sources:`
declared, dbt Charts reuses the connection of the `profile:` named in
`dbt_project.yml`, and SQL queries need no `source:`. To declare it yourself, set
`type: dbt_profile` (this also turns the automatic source off):

```yaml {contract=project-config}
# dbt_charts.yml
sources:
  analytics:
    type: dbt_profile
    profile: my_dbt_project
    target: dev
```

### Create Charts Directory

Create a directory for your dashboards (called "charts" in dbt Charts):

```bash
mkdir charts
```

Place your dashboard YAML files in this directory. The `charts/` directory is the canonical location for all dbt Charts dashboard files. The CLI defaults to this directory for `validate`, `serve`, and `render` commands.

### Project Configuration (Optional)

dbt Charts supports project-wide configuration via a `dbt_charts.yml` file in your project root.

**What belongs in `dbt_charts.yml`:** engine knobs: data sources, server port, execution settings.  The model rejects unknown keys, so presentation keys (`theme:`, `frame:`, `style:`) raise a clear error here; they belong in `charts/meta.yml`.

```yaml {contract=project-config}
# dbt_charts.yml: engine knobs only
server:
  port: 8080

sources:
  my_db:
    type: duckdb
    path: data.duckdb
```

### Execution settings

The `execution:` block controls query parallelism and timeouts:

```yaml {contract=project-config}
# dbt_charts.yml
execution:
  max_workers: 8
  max_query_duration_seconds: 300
```

- `max_workers`: maximum parallel query workers per render. Effective only for external warehouse executors (BigQuery, Snowflake, Postgres, etc.); DuckDB and SQLite serialize access internally regardless of this setting. Also settable per-run via `--max-workers` on [`dct render`](../cli/render.md) / [`dct serve`](../cli/serve.md), or the `DCT_MAX_WORKERS` env var.
- `max_query_duration_seconds`: the safety ceiling on how long a single query may run, enforced as a server-side statement timeout on network warehouses. DuckDB and SQLite are local file databases with no server to enforce a timeout, so this has no effect on them. Override per source with `sources.<name>.max_query_duration_seconds`:

```yaml {contract=project-config}
# dbt_charts.yml
sources:
  analytics:
    type: snowflake
    max_query_duration_seconds: 60
```

### Server settings

`server.markdown_metadata_table` renders non-board frontmatter keys in `.md` files as a metadata table at the top of the page. Off by default, so `AGENTS.md`, `README`, and other prose files served through dbt Charts don't suddenly acquire header tables:

```yaml {contract=project-config}
# dbt_charts.yml
server:
  markdown_metadata_table: true
```

### Cloud settings

The `cloud:` block holds rules that [dbt Charts Cloud](../cloud/index.md) applies to the project. It can only tighten: `false` turns a capability off for the project, and leaving a key out or setting it to `true` defers to the switches on the Cloud project settings page.

```yaml {contract=project-config}
# dbt_charts.yml
cloud:
  allow_public: false
  honor_agent_instructions: false
```

- `allow_public: false`: nothing in the project is served to people outside the organization, even when the organization and project public-access switches are on. See [Public access](../cloud/access-control.md#public-access-org-and-project-opt-in).
- `honor_agent_instructions: false`: the [AI copilot](../cloud/ai-copilot.md) ignores the repository's `AGENTS.md`, `CLAUDE.md`, and `skills/` folders, even when the Agent settings checkbox is on.

Cloud reads this block from the project's work branch, not the branch you are viewing, so a change branch cannot loosen it. Cloud checks the whole file: an unknown or repeated key, or a value that is not `true` or `false`, is an error rather than a switch left on, and the settings page notes when the file is overriding a switch.

**What belongs in `charts/meta.yml`:** board layout and other presentation defaults. `meta.yml` is a partial board that applies as a cascade base to every board in its directory.

```yaml {contract=board-root}
# charts/meta.yml: presentation defaults
style:
  frame:
    max_width: 1440.0     # Widest boards may auto-size to (default: 1200.0)
    card_padding: 20.0
```

**Configuration Discovery:**
- dbt Charts searches for `dbt_charts.yml` starting from the current working directory and walks up to the filesystem root.
- If you're working in a dbt project, dbt Charts also detects `dbt_project.yml` as a project root indicator.
- If no `dbt_charts.yml` is found, built-in defaults are used.

These settings apply to all dashboards in your project unless overridden in individual dashboard YAML files.

---

## Adding dbt Charts to an Existing dbt Project

If you already have a dbt project, adding dbt Charts takes three steps:

```bash
cd my-dbt-project

# 1. Install dbt Charts (see the Installation section above)

# 2. Bootstrap the project; creates charts/, dbt_charts.yml, and workflow skills
dct init

# 3. Preview the starter dashboard
dct serve
```

`dct init` creates a `charts/guide.yml` guide dashboard that works without
a database connection. It also installs workflow skills for local AI assistants
unless you pass `--no-skills`. Open the URL it prints to see the guide live.

Your dbt project should now look like this:

```text
my-dbt-project/
├── dbt_project.yml          # dbt config (existing)
├── models/                  # dbt models (existing)
├── profiles.yml             # dbt profiles (existing)
├── dbt_charts.yml           # Optional: engine knobs (sources, server port, etc.)
├── .agents/skills/          # Workflow skills for Cursor, Codex, and Copilot
├── charts/                  # dbt Charts dashboards
│   ├── guide.yml            # Starter guide: queries, charts, layout, KPIs
│   ├── sales_dashboard.yml
│   └── partials/            # Reusable dashboard fragments (prefixed with _)
│       └── _header.yml
└── assets/                  # Optional: images, CSV data files
    ├── images/
    └── data/
```

**Key conventions:**
- **`charts/`** is the canonical directory for all dashboard YAML files. The `dct` CLI defaults to this directory.
- **Partials** live in `charts/partials/` and are prefixed with `_` (for example, `_header.yml`). They're reusable fragments imported by other dashboards.
- **Subdirectories** are fine: `charts/sales/overview.yml` maps to the URL `/charts/sales/overview/` when served.
- **`dbt_charts.yml`** is optional; it sets engine knobs (sources, server port, execution config). Place it next to `dbt_project.yml`. Board layout and other presentation defaults belong in `charts/meta.yml` instead.

**dbt Charts reads your dbt project automatically.** When you run `dct serve` or `dct validate` inside a dbt project directory, dbt Charts discovers `dbt_project.yml` and connects to your database via `profiles.yml`. Your queries hit models with plain SQL.

---

## Verification

### Test Installation

1. Create a simple dashboard file `charts/test.yml`:
   ```yaml {contract=board-root}
   title: "Test Dashboard"

   queries:
     test:
       rows:
         - month: "2024-01"
           revenue: 12000
         - month: "2024-02"
           revenue: 15400
         - month: "2024-03"
           revenue: 11800

   charts:
     test_chart:
       title: "Revenue by Month"
       query: test
       type: bar
       x: month
       y: revenue

   rows:
     - test_chart
   ```

2. Validate the dashboard:
   ```bash
   dct validate charts/test.yml
   ```

3. Preview the dashboard:
   ```bash
   dct serve
   ```

4. Open your browser to the URL printed by `dct serve` on startup

If you see the dashboard, installation is successful!

---

## Troubleshooting Common Issues

### Warehouse Adapter Not Installed

**Error:** `ERR-ADAPTER-NOT-INSTALLED`, from a `type: dbt_profile` source or
a direct source alike. `dct init` prints the same text as a `Tip:` when it
detects a dbt project whose profile needs a missing adapter:

```text
ERR-ADAPTER-NOT-INSTALLED  dbt Charts needs the dbt-snowflake adapter to query
'snowflake' sources, and it is not installed in this Python environment.
Install it with: uv tool install "dbt-charts[snowflake]"
```

**Solution:** Run the command the error names. It matches how dbt Charts was
installed:

```bash
uv tool install "dbt-charts[snowflake]"   # or: pip install "dbt-charts[snowflake]"
```

See [Warehouse adapters](#warehouse-adapters) for every warehouse and its
extra. This is about dbt Charts' own database connection, not your dbt
installation; it appears whether you build with dbt v1 or
[dbt v2](dbt-fusion.md).

### dbt Downgraded to 1.x After Installing dbt Charts

**Error:** `dbt --version` reports Core 1.x and dbt v2 is gone.

**Cause:** dbt Charts was installed into the environment that holds dbt v2. Its
warehouse adapter depends on `dbt-core` 1.x, and `pip` replaced v2 to satisfy
it.

**Solution:** Remove dbt Charts from that environment, reinstall dbt v2, and
install dbt Charts as a tool instead. Steps in
[Using dbt Charts with dbt v2](dbt-fusion.md#dbt-is-suddenly-version-1x).

### Database Connection Issues

**Error:** Cannot connect to database

**Solution:**
- Check your `profiles.yml` configuration
- Verify database credentials
- Test dbt connection: `dbt debug`

### YAML Syntax Errors

**Error:** YAML parsing errors

**Solution:**
- Check YAML indentation (use spaces, not tabs)
- Validate YAML syntax with a YAML validator
- Use `dct validate` to check for errors

---

## AI / MCP Setup for IDEs

dbt Charts includes an MCP (Model Context Protocol) server that gives AI coding assistants access to your data schema, queries, and dashboard tools. To configure your IDE:

```bash
# Auto-detect installed AI clients and configure all of them
dct init mcp

# Or configure a specific client
dct init mcp cursor     # Cursor
dct init mcp vscode     # VS Code / GitHub Copilot
dct init mcp claude     # Claude Desktop
dct init mcp codex      # OpenAI Codex CLI
dct init mcp claude-code # Claude Code (.mcp.json)
```

This writes the appropriate MCP config file for each client (for example, `.cursor/mcp.json`, `.vscode/mcp.json`). After running this, your AI assistant can:
- Execute queries against your database (`execute_query` tool), including `INFORMATION_SCHEMA` queries to browse tables and columns
- Render dashboards from YAML (`render_board` tool)
- Search existing dashboards (`search_boards` tool)

**Tip:** Run `dct init mcp` after cloning any repo that uses dbt Charts; it auto-detects which AI clients you have installed.

### Manual Setup

If you prefer to configure manually, add the dbt Charts MCP server to your client's config.

For JSON-based clients (Cursor, VS Code, Claude Desktop, Claude Code, Copilot):

```json
{
  "mcpServers": {
    "dbt-charts": {
      "command": "dct",
      "args": ["mcp", "serve"]
    }
  }
}
```

For Codex (TOML: `.codex/config.toml`):

```toml
[mcp_servers.dbt-charts]
command = "dct"
args = ["mcp", "serve"]
```

If your dbt Charts or dbt project lives in a subdirectory of the workspace your AI client opens, append `"--project-dir", "/abs/path/to/your/project"` to `args` so the server starts in the right place. `dct init mcp` adds this for you when you pass `--project-dir <path>` or when it detects that the workspace and project roots diverge.

Config file locations:
- **Cursor:** `.cursor/mcp.json`
- **VS Code / Copilot:** `.vscode/mcp.json` (use `"servers"` instead of `"mcpServers"`)
- **Claude Desktop:** `~/.config/claude/config.json`
- **Claude Code:** `.mcp.json` (project root)
- **Codex CLI:** `.codex/config.toml` (TOML; project must be trusted by Codex). For global setup, write to `~/.codex/config.toml` instead.

### Starting the MCP Server Manually

```bash
dct mcp serve
```

This starts the MCP server in stdio mode (for IDE integration). It also starts an embedded HTTP server on port 8765 for dashboard preview rendering.

---

## Next Steps

- **[Getting Started Guide](getting-started.md)** - Create your first dashboard
- **[CLI Reference](../cli/index.md)** - Complete CLI command reference (validate, render, serve, schema, and more)
- **[Queries Guide](../queries.md)** - Learn about queries
- **[Examples](../examples/quickstart.md)** - See example dashboards

## Related Documentation

- [Using dbt Charts with dbt v2](dbt-fusion.md) - dbt v2 compatibility and setup
- [Troubleshooting Guide](troubleshooting.md) - Common installation and setup issues
- [Best Practices Guide](best-practices.md) - Dashboard design best practices

---

## Getting Help

If you encounter issues:

1. Check the [Troubleshooting Guide](troubleshooting.md)
2. Check your dashboard: `dct validate`
3. Check dbt configuration: `dbt debug`
4. Review the [YAML Schema Reference](../reference/yaml-reference.md)

# Getting Started Tutorial (https://docs.dbtcharts.com/guides/getting-started/)

# Getting Started Tutorial

Step-by-step tutorial for building your first dbt Charts dashboard from SQL.

---

## Prerequisites Check

Before starting, ensure you have:

- ✅ dbt Charts installed (`dct --version`; see [Installation](installation.md))
- ✅ A database dbt Charts can query: Postgres, Snowflake, BigQuery, DuckDB, SQLite, or a local CSV/Parquet file

You do **not** need dbt to build dashboards. Most projects start with plain
SQL, and dbt Charts queries dbt-modeled tables the same way.

Every example in this tutorial queries **Dundersign**, the fictional
document-signing company whose dataset ships with dbt Charts. To run them
against real data, download
[`examples.duckdb`](https://github.com/dbt-labs/dbt-charts/blob/main/examples/playground/examples.duckdb)
(12 MB) from the dbt Charts repository and save it as `data/examples.duckdb` in
the project you set up in Step 1. Every complete board below (steps 4 and 7,
and the final example) then runs as-is; the in-between steps are the fragments
that build up to them. Swap in your own tables whenever you're ready.

---

## Step 1: Set Up Project Structure

dbt Charts dashboards ("boards") live in a `charts/` directory. A minimal project
is just that directory plus a `dbt_charts.yml` that names your data source:

```text
my-project/
├── dbt_charts.yml            # Names your data source(s)
├── charts/                  # Your dashboards here
│   └── my_first_dashboard.yml
├── data/                     # Local databases
│   └── examples.duckdb       # Dundersign data, downloaded above
└── assets/                 # Optional: images, CSV data files
    ├── images/
    └── data/
```

Point `dbt_charts.yml` at a database. A local DuckDB file needs no credentials,
which makes it the quickest way to start, so this tutorial points at the
`examples.duckdb` you downloaded. `path:` takes any DuckDB file, so swap in your
own when you're ready:

```yaml {contract=project-config}
# dbt_charts.yml
sources:
  db:
    type: duckdb
    path: ./data/examples.duckdb
```

The source name `db` is the convention this tutorial sticks to; it's also
what the bundled playground project names its demo warehouse source, which
is why the boards below run unchanged there.

See [Sources](../sources/index.md) for Postgres, Snowflake, BigQuery, and dbt
profile connections.

---

## Step 2: Create a Dashboard File

Create `charts/my_first_dashboard.yml` with a title and the source it reads from:

```yaml {contract=board-root}
title: "Dundersign Overview"

source: db
```

The board-level `source:` applies to every query in the dashboard, so you don't
repeat it on each one.

---

## Step 3: Define a Query

Add a SQL query that returns the columns you want to chart:

```yaml {contract=board-root}
title: "Dundersign Overview"

source: db

queries:
  documents_by_status:
    sql: |
      SELECT
        status,
        COUNT(*) AS documents,
        ROUND(AVG(page_count), 1) AS avg_pages
      FROM dundersign.documents
      GROUP BY status
      ORDER BY documents DESC
```

The query owns the data: its grain, aggregation, and ordering. Each query has
a name (`documents_by_status`) and returns named columns (`status`,
`documents`, `avg_pages`) that charts bind to.

---

## Step 4: Create a Chart

Add a chart that maps query columns to visual channels:

```dbt-charts-example
title: "Dundersign Overview"

source: db

queries:
  documents_by_status:
    sql: |
      SELECT
        status,
        COUNT(*) AS documents,
        ROUND(AVG(page_count), 1) AS avg_pages
      FROM dundersign.documents
      GROUP BY status
      ORDER BY documents DESC

charts:
  documents_chart:
    title: "Documents by Status"
    query: documents_by_status
    type: bar
    x: status
    y: documents
```

The chart doesn't aggregate or infer anything; the query already did that.
The chart only decides that `status` goes on the x-axis and `documents` on the
y-axis.

---

## Step 5: Organize with Layouts

Layouts arrange your charts. Use `rows` to stack, `cols` to place side by side,
or `grid` for precise columns:

```yaml {contract=board-fragment}
rows:
  - title: "Document Activity"
    cols:
      - documents_chart
      - revenue_chart
```

---

## Step 6: Validate and Preview

Validate the dashboard:

```bash
dct validate charts/my_first_dashboard.yml
```

Fix any errors it reports, then start a live preview:

```bash
dct serve
```

Open the URL `dct serve` prints on startup to see your dashboard. It re-renders
as you edit the YAML.

![A served board's full chrome: nav bar, variables strip, and charts, for the Interactive Sales Board with its region and product controls](../assets/screens/guides/getting-started/served-board.png){: width="900" height="1172" }

---

## Step 7: Add Variables

Variables are the controls readers use to filter a dashboard. Wire one into the
query with the `filter()` helper; it writes the SQL predicate for the selected
value, or a no-op when nothing is selected:

```dbt-charts-example
title: "Dundersign Overview"

source: db

variables:
  status:
    input: select
    options:
      static: ["sent", "completed"]
    # No default: starts on All statuses

queries:
  documents_by_status:
    sql: |
      SELECT
        status,
        COUNT(*) AS documents,
        ROUND(AVG(page_count), 1) AS avg_pages
      FROM dundersign.documents
      WHERE {{ filter('status', status) }}
      GROUP BY status
      ORDER BY documents DESC

charts:
  documents_chart:
    title: "Documents by Status"
    query: documents_by_status
    type: bar
    x: status
    y: documents

rows:
  - title: "Document Activity"
    cols:
      - documents_chart
```

Now the status selector filters the chart. A variable never filters data on
its own; you always wire it into a query explicitly.

---

## Step 8: Add More Charts

Time-series charts want month grain, and that grain belongs to the data
layer, not the chart: Dundersign's dbt project pre-aggregates a
`dundersign_serving.monthly_metrics` rollup (one row per month), so the query
stays a plain `SELECT`; no date functions, and the same SQL runs on any
warehouse. The demo window opens and closes mid-month, so the query trims the
partial first and last months, the everyday trick for dropping in-progress
periods, again without any date math. Add the query, a second chart, and
place both in a grid:

```yaml {contract=board-fragment}
queries:
  monthly:
    sql: |
      SELECT month, revenue, new_users
      FROM dundersign_serving.monthly_metrics
      WHERE month > (SELECT MIN(month) FROM dundersign_serving.monthly_metrics)
        AND month < (SELECT MAX(month) FROM dundersign_serving.monthly_metrics)
      ORDER BY month

charts:
  documents_chart:
    title: "Documents by Status"
    query: documents_by_status
    type: bar
    x: status
    y: documents

  revenue_chart:
    title: "Revenue by Month"
    query: monthly
    type: line
    x: month
    y: revenue

rows:
  - title: "Document Activity"
    grid:
      columns: 24
      items:
        - item: documents_chart
          width: 12
        - item: revenue_chart
          width: 12
```

---

## Complete Example

Here's the full dashboard: the status filter, the status breakdown, and the
monthly trend:

```dbt-charts-example
title: "Dundersign Overview"

source: db

variables:
  status:
    input: select
    options:
      static: ["sent", "completed"]
    # No default: starts on All statuses

queries:
  documents_by_status:
    sql: |
      SELECT
        status,
        COUNT(*) AS documents,
        ROUND(AVG(page_count), 1) AS avg_pages
      FROM dundersign.documents
      WHERE {{ filter('status', status) }}
      GROUP BY status
      ORDER BY documents DESC

  monthly:
    sql: |
      SELECT month, revenue, new_users
      FROM dundersign_serving.monthly_metrics
      WHERE month > (SELECT MIN(month) FROM dundersign_serving.monthly_metrics)
        AND month < (SELECT MAX(month) FROM dundersign_serving.monthly_metrics)
      ORDER BY month

charts:
  documents_chart:
    title: "Documents by Status"
    query: documents_by_status
    type: bar
    x: status
    y: documents

  revenue_chart:
    title: "Revenue by Month"
    query: monthly
    type: line
    x: month
    y: revenue

rows:
  - title: "Document Activity"
    grid:
      columns: 24
      items:
        - item: documents_chart
          width: 12
        - item: revenue_chart
          width: 12
```

---

## Next Steps

Now that you've built your first dashboard:

1. **[Read the Queries Guide](../queries.md)**: SQL, values, files, HTTP, and dbt models
2. **[Read the Charts Guide](../charts/index.md)**: explore chart types and options
3. **[Read the Variables Guide](../variables/index.md)**: add more interactive filters
4. **[See Examples](../examples/quickstart.md)**: explore complete dashboards
5. **[Best Practices](best-practices.md)**: dashboard design best practices

---

## Common Questions

### How do I know which tables and columns are available?

Use `dct query` against `INFORMATION_SCHEMA` to browse your source's tables
and columns without leaving the terminal:

```bash
dct query db "SELECT table_schema, table_name FROM INFORMATION_SCHEMA.TABLES"
```

### Can I use multiple queries?

Yes; define multiple queries and reference them from different charts.

### How do I add more rows?

Add more items to the `rows` array. Each row can have its own `cols` or `grid`.

### Can I customize colors and styling?

Yes. See [Themes](../themes.md) for the built-in themes and custom ones, and
[Styling](../styling.md) for everything else.

---

## Related

- [Installation Guide](installation.md): installation and setup
- [CLI Reference](../cli/index.md): complete CLI command reference
- [Troubleshooting Guide](troubleshooting.md): common issues and solutions
- [Best Practices Guide](best-practices.md): dashboard design best practices
- [Queries Guide](../queries.md): query reference
- [Charts Guide](../charts/index.md): chart reference
- [Variables Guide](../variables/index.md): variables reference

# dbt v2 (https://docs.dbtcharts.com/guides/dbt-fusion/)

# dbt v2

dbt Charts runs on a dbt v2 project. It reads the artifacts your build
produces rather than driving dbt itself, so the engine you build with is not
something dbt Charts needs to know about.

One piece of setup is specific to dbt v2: dbt Charts queries your warehouse
through a Python adapter package, and that package depends on dbt Core 1.x.
Install dbt Charts in its own environment, never in the one that holds dbt v2.
[Setup](#setup) explains why.

---

## How dbt Charts uses your dbt project

dbt Charts and dbt v2 do separate jobs against the same project.

dbt v2 builds your models. `dbt build`, `dbt compile`, and the rest are
untouched: dbt Charts never invokes them, wraps them, or replaces them.

dbt Charts queries the result. `dct serve` opens its own connection to your
warehouse and runs the SQL in your boards.

That second connection is why the adapter matters. dbt Charts is a Python
program and connects through a Python adapter package such as `dbt-snowflake`.
dbt v2's adapters are compiled into its binary and cannot be imported from
Python, so dbt Charts brings its own.

Everything else already works, because dbt Charts reads your dbt files directly
instead of asking dbt to interpret them.

| What dbt Charts uses | How it reads it |
|---|---|
| `ref()` and `source()` in board queries | Reads `target/manifest.json` as plain JSON |
| `profiles.yml` connection details | Parses the YAML directly |
| `dbt_project.yml` | Parses the YAML directly |
| `{{ env_var(...) }}` in profiles | Resolved using the same rules dbt applies |
| Board YAML, charts, layout, `dct serve` | Independent of dbt entirely |
| Connecting to your warehouse | Imports a Python `dbt-<adapter>` package |

The manifest reader is version-agnostic by design. It reads a small set of node
fields that have been stable across every manifest version, so a dbt v2-written
manifest needs no compatibility shim.

---

## Setup

Install dbt Charts as a standalone tool, with the extra for your warehouse:

```bash
uv tool install "dbt-charts[snowflake]"
```

`uv tool install` gives `dct` its own private environment and puts only the
`dct` command on your `PATH`. `pipx install "dbt-charts[snowflake]"` does the
same. See [Warehouse adapters](installation.md#warehouse-adapters) for every
warehouse and its extra.

**Do not `pip install dbt-charts` into the environment that holds dbt v2.** dbt
v2 is published on PyPI as `dbt-core` 2.x, the same package name as dbt Core
1.x. The warehouse adapter dbt Charts uses depends on `dbt-core` 1.x, and one
environment can hold only one version of a package. `pip` resolves that quietly:
it removes dbt v2 and installs Core 1.x in its place. Nothing reports an error,
but your next `dbt run` executes on the old engine.

The isolated install avoids this entirely. dbt Charts reads `manifest.json` and
`profiles.yml` from disk, so it never needs to share an environment with dbt.

Point dbt Charts at your existing dbt profile:

```yaml {contract=project-config}
# dbt_charts.yml
sources:
  analytics:
    type: dbt_profile
    profile: my_dbt_project
    target: prod
```

Build, then serve:

```bash
dbt build      # dbt v2; writes target/manifest.json
dct serve
```

Boards can now `ref()` any model dbt v2 built.

---

## Troubleshooting

### Missing warehouse adapter

dbt Charts reports this the same way whether the source is a `type: dbt_profile`
source or a direct one (`type: snowflake` in `dbt_charts.yml`):

```text
ERR-ADAPTER-NOT-INSTALLED  dbt Charts needs the dbt-snowflake adapter to query
'snowflake' sources, and it is not installed in this Python environment.
Install it with: uv tool install "dbt-charts[snowflake]"
```

It means dbt Charts has no Python adapter for its own connection. It is not a
signal that dbt v1 is required, or that a dbt v2 install is broken or
undetected.

Run the command the message names. It installs the extra into the environment
`dct` runs from.

An error that survives an install reporting success means the package landed in
a different environment than the one `dct` runs from. Confirm with
`dct --version` and reinstall with `uv tool install`.

### dbt is suddenly version 1.x

`dbt --version` reports Core 1.x after installing dbt Charts, and dbt v2 is
gone. dbt Charts was installed into the same environment as dbt v2, and `pip`
replaced v2 with the Core 1.x that the warehouse adapter depends on. See
[Setup](#setup).

Recover by removing dbt Charts from that environment and installing it as a
tool:

```bash
pip uninstall dbt-charts dbt-core dbt-snowflake
pip install "dbt-core>=2"           # or however you installed dbt v2
uv tool install "dbt-charts[snowflake]"
```

### Unknown refs

`ref()` resolves from `target/manifest.json`. A missing or stale manifest leaves
refs unresolved. Build first:

```bash
dbt build
```

`dbt parse` and `dbt compile` also write the manifest, for a project you do not
want to run in full.

### dbt v1

`dbt-core` 1.x is a dependency of the `dbt-charts` package and arrives with it.
dbt Charts uses it as a library for connection handling and never runs it. In
an isolated install it lives inside `dct`'s private environment, exposes no
`dbt` command, and says nothing about which engine builds your project. It only
interferes with dbt v2 when both are installed into one environment, which is
the case [Setup](#setup) tells you to avoid.

---

## Related Documentation

- [Installation & Setup](installation.md) - warehouse adapter extras and full setup
- [Sources](../sources/index.md) - every source type and its connection settings
- [Troubleshooting Guide](troubleshooting.md) - general setup issues

# Validating Boards in CI (https://docs.dbtcharts.com/guides/ci/)

# Validating Boards in CI

Every board is YAML in git, which means every change to a board, and every change to the dbt models underneath it, can be checked on the pull request that makes it. This guide takes you from zero to a CI gate in three tiers, each catching a class of breakage the previous one cannot:

| Tier | Setup | Catches | Needs |
|---|---|---|---|
| **1. Structural** | `dct init ci` | Malformed YAML, unknown fields, broken references between charts, queries, and variables | Nothing: no credentials, no dbt |
| **2. dbt manifest** | add `dbt parse` | A `ref()` to a renamed or deleted model; a query reading a **column the model's SQL no longer produces** | `profiles.yml` for `dbt parse` (no warehouse queries run) |
| **3. Warehouse** | add `--warehouse` | Queries that no longer bind against the live warehouse: tables, columns, SQL validity | Warehouse credentials on the runner |

Most teams stop at tier 2: it catches the dominant failure (a dbt change breaking boards) without putting warehouse credentials in CI.

## Tier 1: scaffold the workflow

From anywhere inside your project:

```bash
pip install dbt-charts
dct init ci
```

This writes a GitHub Actions workflow at the repository root (`.github/workflows/dbt-charts.yml`, or `dbt-charts-<project-path>.yml` for a project nested in a monorepo) that runs [`dct validate`](../cli/validate.md) on every pull request touching your boards. Abridged (the real file also triggers on merge to main and manual dispatch, and watches its own path):

```yaml {contract=unverified}
on:
  pull_request:
    paths:
      - 'charts/**'
      - 'dbt_charts.yml'

jobs:
  validate:
    name: Validate boards
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-python@v6
        with:
          python-version: '3.13'
      - name: Install dbt Charts
        run: pip install dbt-charts
      - name: Validate boards
        run: dct validate charts
```

If your dbt project lives in a subdirectory, the scaffolded `paths:` filters and `working-directory` are qualified with the project's repo-relative path automatically: GitHub resolves `paths:` against the repository root, so a hand-written `charts/**` filter on a nested project silently never fires. See [`dct init ci`](../cli/init.md#dct-init-ci) for the details and options.

Commit the workflow, open a pull request that breaks a board on purpose (point a chart at a query that doesn't exist) and confirm the check goes red. A gate you have never seen fail is a gate you can't trust.

One operational gotcha: because of the `paths:` filters, the job doesn't start at all on a pull request that touches no boards. If you make it a *required* status check, such a PR pins at "Expected, waiting for status"; either leave it optional or drop the `paths:` filters so the job always runs (it is fast).

## Tier 2: check against your dbt models

Structural validation cannot know that `{{ ref('orders') }}` points at a model you renamed last week. That knowledge lives in dbt's `target/manifest.json`, which a bare `dbt parse` writes without building anything or querying your warehouse. Add a parse step before the validate step:

```yaml {contract=unverified}
      - name: Parse the dbt project
        run: |
          dbt deps
          dbt parse

      - name: Validate boards
        run: dct validate charts
```

With a manifest present, `dct validate` additionally checks:

- **`ref()` / `source()` targets exist.** A board referencing a renamed or deleted model fails with a did-you-mean hint. Without a manifest this is reported as a `WARN-DBT-MANIFEST-MISSING` warning rather than checked.
- **Model column drift.** Each model's output columns are derived statically from its SQL in the manifest, and every board query reaching that model through `ref()` is checked against them. Rename `customer_id` to `user_id` in `models/orders.sql`, and a board selecting `customer_id` from `{{ ref('orders') }}` fails validation with [`ERR-DBT-MODEL-COLUMN-MISSING`](../reference/errors.md#err-dbt-model-column-missing) on the same pull request, *before* `dbt run` has rebuilt the warehouse, which is exactly the window where warehouse-level validation still passes against the old table.

The drift check is honest about its limits rather than guessing: a model whose columns cannot be derived (a `SELECT *`, a macro in projection position, a seed or snapshot) warns [`WARN-DBT-MODEL-COLUMNS-UNRESOLVED`](../reference/warnings.md#warn-dbt-model-columns-unresolved), and a board query it cannot analyze (a `SELECT *` over a `ref()`) warns [`WARN-DBT-QUERY-COLUMNS-INDETERMINATE`](../reference/warnings.md#warn-dbt-query-columns-indeterminate) instead of passing in silence. Those warnings don't fail the build by default; `dct validate --strict` exits 1 on any warning if you want them to, knowing that a project which deliberately ships `SELECT *` queries will then need to make those columns explicit to get green.

`dbt parse` needs a `profiles.yml` to run, but it never queries the warehouse; a profile with placeholder credentials is enough for this tier.

## Tier 3: warehouse validation

For the failures only a live warehouse can reveal (a table dropped outside dbt, a column that exists in the model but not yet in the warehouse, dialect-specific SQL errors) add `--warehouse`:

```bash
dct validate charts --warehouse
```

This uses the cheapest per-adapter mechanism available (DuckDB `DESCRIBE`, BigQuery dry-run, `EXPLAIN` on Postgres/Redshift/Snowflake) and never runs your queries at full cost; adapters with no safe primitive are reported as *unchecked*, not as passing. It requires resolvable warehouse credentials on the CI runner, so most teams run it on a schedule or on merge to main rather than on every pull request. The mechanism table and its guarantees are in [`dct validate`](../cli/validate.md#warehouse-validation).

## Before the rename: `dct impact`

CI tells you a change broke boards after you push it. To get the answer before touching a model, ask the reverse index:

```bash
dct impact customer_id --table orders
```

[`dct impact`](../cli/impact.md) lists every board whose compiled SQL reads that column, resolved through CTEs, aliases, and `ref()` calls, no warehouse connection needed. The renaming workflow becomes: `dct impact` to see the blast radius, update the boards and the model in one pull request, and let the tier-2 gate confirm nothing was missed.

## Validating locally

The same command CI runs works at your desk and in a pre-commit hook: it is sub-second without `--warehouse`:

```bash
dbt parse && dct validate
```

Run it after editing models, before pushing, and you'll rarely see the CI gate fire at all.

## Related

- [`dct init ci`](../cli/init.md#dct-init-ci): scaffold options, nested dbt roots, monorepos
- [`dct validate`](../cli/validate.md): everything each validation tier checks
- [`dct impact`](../cli/impact.md): which boards break if this column changes
- [Error reference](../reference/errors.md) and [warning reference](../reference/warnings.md)

# dbt Charts YAML Style Guide (https://docs.dbtcharts.com/guides/yaml-style-guide/)

# dbt Charts YAML Style Guide

A comprehensive guide for writing clean, maintainable, and consistent dbt Charts board YAML files.

---

## Table of Contents

1. [Naming Conventions](#naming-conventions)
2. [Structure & Organization](#structure-organization)
3. [Type-Based Field Encapsulation](#type-based-field-encapsulation)
4. [Chart Syntax](#chart-syntax)
5. [Referencing & Modularity](#referencing-modularity)
6. [Templating & Expressions](#templating-expressions)
7. [Formatting & Syntax](#formatting-syntax)
8. [Best Practices](#best-practices)

---

## Naming Conventions

### Auto-Interpreted Titles from IDs/Slugs

**Principle**: Titles and names should be automatically interpreted from IDs/slugs when not explicitly provided.

**Rule**: If an object has an `id` or `name` field (or is a file-based board) but no `title`, the title should be auto-generated by converting the identifier to a human-readable format.

- For **file-based boards**, the filename (without extension) is the identifier.
- For **nested boards**, the explicit `id` or `name` (if provided) is the identifier.

**Examples**:

```yaml {contract=board-root}
# ✅ Good: Title auto-generated from filename 'sales_overview.yml'
# File: sales_overview.yml
# Implicit Title: "Sales Overview"
rows:
  - title: "Q1 Details"
    # ...

# ✅ Good: Explicit title overrides auto-generation
# File: sales_overview.yml
title: "Sales Dashboard - Q4 2024"
```

**Auto-Generation Rules**:
- Convert `snake_case` to `Title Case`: `revenue_by_month` → `Revenue By Month`
- Convert `camelCase` to `Title Case`: `revenueByMonth` → `Revenue By Month`
- Preserve acronyms: `kpi_revenue` → `KPI Revenue`

### Identifier Naming

**Board File Names**:
```yaml {contract=unverified}
# ✅ Good: lowercase with underscores
sales_overview.yml
monthly_sales_board.yml

# ⚠️ Discouraged (but supported): spaces, special characters, camelCase
Sales Overview.yml
monthlySalesBoard.yml
sales-board.yml
# These will still be correctly converted to titles (for example, "Sales Overview", "Monthly Sales Board")
# but standardizing on snake_case is recommended for consistency.
```

**Query Names**:
```yaml {contract=unverified}
# ✅ Preferred: Descriptive names without prefixes
queries:
  sales: ...
  sales_by_region: ...
  product_categories: ...

# ✅ Preferred: Use explicit namespacing when referencing queries
query: queries.sales  # Explicit - clearly a query
query: queries.totals  # Explicit - unambiguous

# ✅ Also acceptable: Simple reference when context is clear
query: sales  # Works when unambiguous, but explicit is preferred

# ❌ Avoid: the queries namespace already says this is a query
queries:
  q_sales: ...
query: queries.q_sales
```

**Chart IDs**:
```yaml {contract=unverified}
# ✅ Good: descriptive, indicates purpose
charts:
  revenue_by_month: ...
  sales_trend: ...
  kpi_total_revenue: ...

# ❌ Bad: generic, unclear purpose
charts:
  chart1: ...
  chart: ...
  c1: ...
```

**Variable Names**:
```yaml {contract=unverified}
# ✅ Good: clear, descriptive
variables:
  region: ...
  date_range: ...
  min_revenue: ...

# ❌ Bad: abbreviations, unclear
variables:
  reg: ...
  dr: ...
  min_rev: ...
```

---

## Structure & Organization

### Top-Level Organization

**Recommended Order**:
1. Board metadata (`title`, `notes`; the latter never appears in the rendered board itself, though Cloud surfaces it in the dashboard-card hover overlay; name is file-based)
2. Variables (user inputs/filters)
3. Queries (data definitions)
4. Charts (reusable chart definitions - optional)
5. Boards (nested boards/sections)

**Example**:
```yaml {contract=unverified}
# File: sales_dashboard.yml
title: "Sales Dashboard"
notes: "Monthly sales metrics and trends"

variables:
  # User inputs
  region: ...
  date_range: ...

queries:
  # Data queries
  sales: ...
  regional: ...

charts:
  # Optional: reusable chart definitions
  revenue_chart: ...

rows:
  # Nested boards (previously sections)
  - title: "Overview"
    cols: ...
```

### Grouping Related Elements

**Group by Domain**:
```yaml {contract=board-root}
queries:
  # Sales queries
  sales: ...
  sales_by_region: ...
  sales_trends: ...

  # Product queries
  products: ...
  product_categories: ...

  # Customer queries
  customers: ...
  customer_segments: ...
```

**Use Comments for Organization**:
```yaml {contract=unverified}
rows:
  # Overview board - high-level KPIs
  - title: "Overview"
    cols: ...

  # Trends board - time series analysis
  - title: "Trends"
    rows: ...

  # Details board - detailed tables
  - title: "Details"
    rows: ...
```

---

## Type-Based Field Encapsulation

**Principle**: When an object has different fields per "type", use the type as the encapsulating key for those fields.

**Rule**: Type-specific fields should be nested under a key matching the type name. **The presence of a type-specific key is sufficient to determine the type** - no explicit `layout:`, `type:`, `input:`, or `data_type:` fields are needed.

### Board Layout Types

**Row Layout** (presence of `rows:` key determines layout - stacks vertically):
```yaml {contract=unverified}
rows:
  - title: "Row 1"
    cols: ...
  - title: "Row 2"
    cols: ...
```

**Column Layout** (presence of `cols:` key determines layout - stacks horizontally):
```yaml {contract=unverified}
cols:
  - title: "Sidebar"
    width: "300px"
    rows: ...
  - title: "Main Content"
    rows: ...
```

**Grid Layout** (presence of `grid:` key determines layout):
```yaml {contract=unverified}
grid:
  columns: 24        # 24-column grid
  items:
    - item: kpi_revenue  # Flowing item: spans 1x1, placed automatically

    - item: chart2       # Pinned and sized
      col: 0
      row: 1
      width: 24
      height: 6

    - item: chart3       # Pinned item: explicit position
      col: 0
      row: 10
      width: 8
      height: 4

    - item: chart4_overlay  # Overlapping item: can share space with others
      col: 2
      row: 10
      width: 4
```

**Tab Layout** (presence of `tabs:` key determines layout):
```yaml {contract=unverified}
tabs:
  default: "overview"
  position: top
  boards:
    - title: "Overview" # Tab 1 (Nested Board)
      rows: ...
    - title: "Details"  # Tab 2 (Nested Board)
      cols: ...
```

**Default Layout**: If no layout-specific key is present, charts render as a row layout in the order they appear under `charts:`.

```yaml {contract=board-root}
queries:
  q_revenue:
    type: values
    columns: [month, revenue]
    values:
      - [Jan, 142000]
      - [Feb, 151000]
      - [Mar, 164000]

charts:
  revenue_by_month:
    query: q_revenue
    type: bar
    title: Revenue by month
    x: month
    y: revenue
```

This is equivalent to adding:

```yaml {contract=board-fragment}
rows:
  - revenue_by_month
```

Use `rows:`, `cols:`, `grid:`, or `tabs:` when you need explicit placement or when only some named charts should be visible.

### Query Types

**Values Query** (presence of `rows:`, `values:`, or `columns:` determines type):
```yaml {contract=unverified}
queries:
  sales:
    columns: [month, total_revenue]
    values:
      - [Jan, 142000]
      - [Feb, 151000]
```

**Raw SQL Query** (presence of `sql:` key determines type):

```yaml {contract=unverified}
queries:
  custom:
    sql: |
      SELECT * FROM dundersign.tickets
      WHERE created_at >= {{ date_range[0] }}
      LIMIT 100
    profile: my_postgres  # Required: dbt profile name
```


**Type Inference Rules** (checked in order):
1. If `rows:`, `values:`, or `columns:` are present → Values Query
2. If `url:` is present → HTTP Query
3. Otherwise → Raw SQL Query (default)

**Note**: SQL is the default query type, making it the most concise option for raw SQL queries. This covers the majority of use cases where you just need to write SQL directly.

### Variable Input Types

A flat `input:` field names the input type. Fields that belong to one type
(`options`, `min`, `max`, `step`) sit beside it on the variable.

**Select Input** (`input: select`):
```yaml {contract=board-root}
variables:
  region:
    input: select
    options:
      static: [North, South, East, West]
    placeholder: "Choose a region"
    default: North
```

**Slider Input** (`input: slider`):
```yaml {contract=board-root}
variables:
  min_revenue:
    input: slider
    min: 0
    max: 1000000
    step: 1000
    default: 10000
```

**Date Range Input** (`input: daterange`):
```yaml {contract=board-root}
variables:
  date_range:
    input: daterange
    default: ["2024-01-01", "2024-12-31"]
```

**Type Inference Rules**:
- `input:` accepts `auto`, `select`, `multiselect`, `input`, `text`, `number`, `textarea`, `slider`, `range`, `date`, `datepicker`, `daterange`, `checkbox`, and `radio`
- Omit `input:` (or write `auto`) and the type is detected from the variable's other fields: checked in order, a list `default` gives `multiselect`, `min`/`max`/`step` give `slider`, a boolean `default` gives `checkbox`, and `options` or a `column` give `select`; anything else is `text`
- Fields outside the variable's grammar are rejected, so a nested `select:` or `slider:` block fails to compile

**Key Principle**: One flat discriminator beats a nested block per type. `input:` is the single place a reader looks to learn what control a variable draws, and every type shares the same field names (`default`, `label`, `options`).

---

## Chart Syntax

**Principle**: For Vega-Lite-native charts, dbt Charts uses a thin ergonomic chart grammar. `type` chooses the chart or layer primitive, top-level channels like `x` and `y` cover the common case, and `encoding` is not an authored dbt Charts field at all.

### Single-Mark Charts

Use chart-level `type` for the primitive and top-level channels for the common authored form.

```yaml {contract=board-fragment}
charts:
  revenue_trend:
    query: sales
    type: line
    x: month
    y: revenue
    color: region
```

Spelling the Vega-Lite structure directly is not an option. `mark:` and
`encoding:` are rejected even alongside a valid `type:`, and without a
`type:` the document fails earlier still, since the chart family is chosen
by that key:

```yaml {contract=board-root expect=error code=ERR-EXTRA-FIELD}
# Rejected: mark: and encoding: are not authored fields, even with a valid type:
charts:
  revenue_trend:
    type: line
    x: month
    y: revenue
    query: sales
    mark: line
    encoding:
      x: { field: month }
      y: { field: revenue }
      color: { field: region }
```

### Use Typed Chart Style Before Vega-Lite Escape Hatches

Top-level channel shorthands should cover the 80% case. For advanced axis, scale, and legend behavior, prefer typed dbt Charts surfaces such as `style.axis_x`, `style.axis_y`, and `style.legend`.

```yaml {contract=board-fragment}
charts:
  revenue_trend:
    query: sales
    type: line
    x: month
    y: revenue
    color: region
    style:
      axis_y:
        labels:
          format: currency_whole
      legend:
        visible: false
```

If you need behavior beyond the typed authored surface, use the remaining top-level Vega-Lite escape hatches: `config`, `transform`, `params`, `resolve`, `hconcat`, `vconcat`, `concat`, or `repeat`.

### Mixed-Mark Charts Use `layers:`

Charts with multiple visual primitives use the `layers:` field on a cartesian base chart
(`bar`, `line`, `area`, or `scatter`). The base chart is a real chart type; it owns the
x-axis, frame, title, legend, and sort. `layers:` is a list of additional marks, each
discriminated by `type`.

```yaml {contract=board-fragment}
charts:
  revenue_vs_target:
    type: bar
    x: month
    y: revenue
    query: monthly
    layers:
      - type: line
        y: target
        label: Target
      - type: line
        y: prior_year
        label: Prior year
```

This keeps responsibilities clean:

- The base `type` is a real chart family, not a container or meta-type
- Each layer's `type` chooses the mark for that overlay
- The base chart owns shared chrome; layers own their mark style and y-axis side

`type: layered` does not exist; use `layers:` on a cartesian chart (`bar`, `line`, `area`, or `scatter`) instead.

### Polar Charts Still Use Chart Type Plus Channels

Pie and donut charts should follow the same model rather than introducing a separate grammar.

```yaml {contract=board-fragment}
charts:
  revenue_share:
    query: sales
    type: pie
    theta: revenue
    color: segment
```

An implementation may normalize `pie` or `donut` to Vega-Lite's `arc` mark internally, but authored YAML should still use chart `type` plus channels.

---

## Referencing & Modularity

**Principle**: Allow referencing from higher-level structures or external files for flexible organization, while also permitting definitions at lower levels for convenience.

### Hierarchical References

**Charts at Board Level**:
```yaml {contract=board-fragment}
# File: sales_overview.yml
charts:
  revenue_chart:
    title: "Revenue"
    query: sales
    type: bar

rows:
  - revenue_chart
```

**Charts at Nested Board Level**:
```yaml {contract=unverified}
# File: sales_overview.yml
rows:
  - charts:
      # Define charts locally in this nested board
      revenue_chart:
        title: "Revenue"
        query: sales
        type: bar
      orders_chart:
        title: "Orders"
        query: sales
        type: line

    cols:
      # Reference the locally defined charts
      - revenue_chart
      - orders_chart
```

**Queries at Board Level**:
```yaml {contract=unverified}
# File: sales_overview.yml
queries:
  sales:
    sql: SELECT month, SUM(revenue) AS total_revenue FROM dundersign.orders GROUP BY 1

rows:
  - title: "Revenue"
    # Reference query from board level
    query: sales
    type: bar
```

**Queries at Chart Level**:
```yaml {contract=unverified}
# File: sales_overview.yml
rows:
  - title: "Revenue"
    # Define query inline at chart level
    query:
      sql: SELECT month, SUM(revenue) AS total_revenue FROM dundersign.orders GROUP BY 1
    type: bar
```

**Note on Uniqueness**: Resource IDs must be unique per type within a file and
across the files it imports. Each type has its own namespace, so a query and a
chart may share a name; two queries may not. A chart's `query:` also accepts a
redundant `queries.` prefix (`query: queries.sales`) which reads more
explicitly but resolves identically, and within the current file only.

### External File References

**Principle**: Cross-file references are **declared, not ambient**. There is no
project-wide namespace you can reach into from anywhere; you name what you want
in your own `queries:` / `charts:` / `variables:` section, which binds it to a
local alias. Everywhere else on the board you use that alias, exactly like a
locally defined resource.

**Syntax**: `<file>.<type>.<name>`: the file path without its extension, then
the section it lives in, then the resource ID. The type segment is required; there
is no `<file>.<name>` shorthand.

```yaml {contract=board-root}
# File: charts/sales_overview.yml
queries:
  base_sales: general/simple-example.queries.revenue_by_week
charts:
  trend: general/simple-example.charts.revenue_trend
variables:
  region: general/simple-example.variables.region

rows:
  - trend                    # the alias, not the dotted path
  - title: "Revenue"
    query: base_sales
    type: bar
    x: week
    y: revenue
```

Paths are relative to the importing file's directory, and `../` climbs to a
sibling directory. See [Importing Queries](../queries.md#importing-queries-from-other-files)
for worked examples.

One form skips the alias: a chart's `query:` accepts `<file>.yml#<name>` (note
the extension and the `#`) to reach a query in another file directly. Prefer the
alias when the same query is used more than once.

!!! warning "The alias is the only place the dotted form works"

    A dotted reference is resolved where a resource is *declared*, not where it
    is *used*. It does not resolve in a layout item, and Jinja expressions see
    only local names. Declare the alias, then use the alias.

    ```yaml {contract=board-root expect=error code=ERR-UNRESOLVED-REFERENCE}
    # File: charts/sales_overview.yml
    rows:
      - _shared_charts.charts.revenue_trend   # dotted path in a layout item
    ```

    ```text
    ERR-UNRESOLVED-REFERENCE  Reference '_shared_charts.charts.revenue_trend' not found in layout item.
    ```

    **Always write the type segment.** Under `charts:` or `variables:`, omitting
    it fails loudly: `Expected '<file>.charts.<name>'`. Under `queries:` it
    fails *quietly*: `base_sales: _shared_queries.base_sales` misses the
    reference grammar, so it is read as an inline SQL string. On a board with no
    source resolved that surfaces as `ERR-SOURCE-REQUIRED`; on a board that has
    one, it compiles clean and breaks at execute time instead.

**Reusing Nested Boards**:
To share a whole section rather than a single resource, import the file itself as
a layout item, path with the extension included, relative to the importing file's
directory. Prefix a file with `_` to mark it a partial. There is no way to pull one
section out of a board file; give it its own file and import that from both places.

See [Board Imports](../boards/imports.md) for the full grammar.


### When to Use Each Approach

**Use Top-Level Definitions When**:
- Charts/queries are reused across multiple nested boards
- You want centralized organization
- Building complex boards with many components

**Use Nested Definitions When**:
- Charts are specific to one nested board
- You want to keep related code together
- Building simple boards

**Use External Partial References When**:
- Sharing components across multiple board files
- Organizing large boards into modules
- Building a library of reusable components

**Example: Hybrid Approach**:
```yaml {contract=unverified}
# File: sales_overview.yml

# Shared queries used across nested boards
queries:
  sales: ...
  products: ...

# Shared charts used in multiple nested boards
charts:
  revenue_chart: ...

rows:
  - title: "Overview"
    cols:
      # Mix of references and inline definitions
      - revenue_chart  # Reference from top level
      - orders_chart:  # Inline definition
          query: sales
          type: bar

  - title: "Details"
    rows:
      # Inline query definition for specific chart
      - detail_chart:
          query:
            sql: SELECT day, product, SUM(revenue) AS total_revenue FROM dundersign.orders GROUP BY 1, 2
          type: table
```

---

## Templating & Expressions

**Principle**: Use Jinja2 templating for dynamic values, logic, and variable substitution. Templating is allowed in SQL strings, text content, labels, and filter values.

### Basic Syntax

- **Output**: `{{ variable }}` - Renders the value of a variable or expression.
- **Logic**: `{% if condition %} ... {% endif %}` - Control flow (if/else, loops).
- **Comments**: `{# ... #}` - Comments that won't be rendered.

### Referencing Variables


```yaml {contract=unverified}
# ✅ Good: Direct variable reference in SQL
queries:
  sales:
    sql: |
      SELECT * FROM dundersign.tickets
      WHERE status = '{{ status }}'
    profile: my_postgres

# ✅ Good: Using variables in markdown content
rows:
  - title: "Overview for {{ region }}"
    text: |
      Showing sales data for **{{ region }}** from {{ date_range[0] }} to {{ date_range[1] }}.
```


### Logic and Control Flow

Use logic to make queries or content dynamic based on inputs.


```yaml {contract=unverified}
# ✅ Good: Conditional SQL generation
queries:
  dynamic:
    sql: |
      SELECT * FROM sales
      {% if region != 'All' %}
        WHERE region = '{{ region }}'
      {% endif %}
    profile: my_postgres
```


### Best Practices

1.  **Keep Logic Simple**: Avoid complex business logic in templates. Move complex logic to dbt models or database views if possible.
2.  **Quote Strings**: Remember to quote string variables in SQL: `'{{ region }}'`.
3.  **Use Filters**: Use Jinja filters for formatting: ``{{ "{{" }} revenue | format("currency") {{ "}}" }}``.

---

## Formatting & Syntax

### Indentation

**Use 2 spaces** (not tabs) for indentation:
```yaml {contract=unverified}
# ✅ Good: 2 spaces
title: "Sales Dashboard"
queries:
  sales: ...

# ❌ Bad: tabs or 4 spaces
title: "Sales Dashboard"
    queries: ...
```


### Lists vs Maps

**Use Lists for Ordered Collections**:
```yaml {contract=unverified}
# ✅ Good: list for ordered sections
rows:
  - title: "First Section"
    cols: ...
  - title: "Second Section"
    cols: ...
```

**Use Maps for Named Collections**:
```yaml {contract=unverified}
# ✅ Good: map for named queries
queries:
  sales: ...
  products: ...

# ✅ Good: map for named charts
charts:
  revenue_chart: ...
  orders_chart: ...
```

### String Formatting

**Use Quotes When Needed**:
```yaml {contract=unverified}
# ✅ Good: quotes for strings with special characters
title: "Sales Dashboard - Q4 2024"
notes: "Dashboard showing sales metrics"

# ✅ Good: no quotes for simple strings
name: sales_dashboard
type: bar

# ✅ Good: quotes for strings starting with numbers
id: "2024_sales"
```

**Multi-line Strings**:
```yaml {contract=board-root}
# ✅ Good: use | for literal block scalar
text: |
  # Sales Performance

  This quarter showed strong growth.

  Key highlights:
  - Revenue up 15%
  - Orders increased 20%

# ✅ Good: use > for folded block scalar (single line)
notes: >
  This dashboard shows monthly sales metrics
  and trends by region.
```

### SQL Queries

For SQL that spans more than one line, always use a block scalar (`sql: |`). Never use single-quoted or double-quoted strings with literal `\n` escape sequences; they look correct in an editor but make diffs unreadable and confuse agents learning from examples.

```yaml {contract=unverified}
# BAD: escaped newlines in a double-quoted string; unreadable diffs
queries:
  sales:
    sql: "SELECT\n  status\nFROM dundersign.tickets"

# BAD: single-quoted string; literal \n, DuckDB sees "SELECT\n  status\nFROM dundersign.tickets" as one line
queries:
  sales:
    sql: 'SELECT\n  status\nFROM dundersign.tickets'

# GOOD: block scalar; real newlines, readable, diffable
queries:
  sales:
    sql: |
      SELECT
        status
      FROM dundersign.tickets
```

Single-line SQL in double quotes is fine:

```yaml {contract=board-root}
queries:
  count:
    sql: "SELECT COUNT(*) AS n FROM dundersign.tickets"
```

Only convert to `sql: |` when the SQL spans multiple lines.

### Arrays

**Inline Arrays**:
```yaml {contract=unverified}
# ✅ Good: inline for short arrays
columns: [month, region, revenue]
presets: [last_7_days, last_30_days]

# ✅ Good: multi-line for longer arrays
presets:
  - last_7_days
  - last_30_days
  - last_quarter
  - last_year
```

### Comments

**Use Comments Liberally**:
```yaml {contract=unverified}
# File: sales_dashboard.yml
title: "Sales Dashboard"

# User input filters
variables:
  region: ...

# Data queries - grouped by domain
queries:
  # Sales queries
  sales: ...

  # Product queries
  products: ...

# Board layout
rows:
  # Overview board
  - title: "Overview"
    charts: ...
```

---

## Best Practices

### 1. Start Simple, Add Complexity Gradually

```yaml {contract=unverified}
# ✅ Good: Start with minimal required fields
# File: sales_dashboard.yml
queries:
  sales:
    sql: SELECT month, SUM(revenue) AS total_revenue FROM dundersign.orders GROUP BY 1

charts:
  revenue_chart:
    query: sales
    type: bar

rows:
  - revenue_chart
```

Then add features as needed:
- Add titles when auto-generated ones aren't sufficient
- Add variables when interactivity is needed
- Add styling when default appearance needs customization

### 2. Keep Layouts Clean with References

**Principle**: Strictly separate **Definition** from **Layout**.
- **Definitions**: Define charts and queries in `charts:` and `queries:` sections.
- **Layout**: Use `rows`, `cols`, and `grid` only to arrange **references** or **nested boards**.

Avoid defining charts inline within layout arrays. This keeps the visual structure clean and readable.

```yaml {contract=unverified}
# ✅ Good: Layout contains only references and structural boards
charts:
  revenue_chart: ...
  orders_chart: ...

rows:
  - cols:
      - revenue_chart
      - orders_chart
  - title: "Trends"  # Nested Board
    rows: ...

# ⚠️ Discouraged: Inline chart definitions clutter the layout
rows:
  - type: bar        # Inline chart
    query: sales
```

### 3. Use Explicit Tags for Clarity

**Principle**: If a complex inline structure feels ambiguous or confusing, use YAML Tags (`!Chart`, `!Board`, `!Query`) to make the type explicit.

```yaml {contract=unverified}
rows:
  - !Board
    title: "Complex Nested Section"
    charts:
      local_chart: !Chart
        type: bar
        query: sales
    cols:
      - local_chart
```

### 4. Use Descriptive Names

```yaml {contract=unverified}
# ✅ Good: Clear, descriptive names
queries:
  sales_by_region_and_month: ...
charts:
  revenue_trend_by_region: ...

# ❌ Bad: Unclear abbreviations
queries:
  sbr: ...
charts:
  rtbr: ...
```

### 5. Group Related Elements

```yaml {contract=unverified}
# ✅ Good: Grouped by domain
queries:
  # Sales domain
  sales: ...
  sales_by_region: ...
  sales_trends: ...

  # Product domain
  products: ...
  product_categories: ...

# ❌ Bad: Mixed organization
queries:
  sales: ...
  products: ...
  sales_by_region: ...
  product_categories: ...
```

### 6. Use Type Encapsulation Consistently

```yaml {contract=unverified}
# ✅ Good: Type-specific fields under type key
rows:
  - grid:
      columns: 24
      items:
        - item: chart1
          width: 12

# ❌ Bad: Type-specific fields at wrong level
rows:
  - grid:
      columns: 24
    items:         # Should be under 'grid'
      - item: chart1
```

### 7. Document Complex Logic


```yaml {contract=board-fragment}
# ✅ Good: Comments explain complex logic
queries:
  filtered_tickets:
    sql: |
      SELECT status, COUNT(*) AS ticket_count FROM dundersign.tickets
      -- 'All' shows every status; anything else filters to the selection
      WHERE {{ filter('status', status if status != 'All' else None) }}
        AND {{ filter_date_range('created_at', date_range) }}
      GROUP BY status
```


### 8. Validate Early and Often

```yaml {contract=unverified}
# ✅ Good: Validate YAML syntax and structure
# Use: dct validate sales_dashboard.yml

# ✅ Good: Test incrementally
# Start with minimal board, add features one at a time
```

---

## Summary

This style guide establishes conventions for writing clean, maintainable dbt Charts dashboard YAML files. Key takeaways:

1. **Auto-generate titles** from IDs/slugs when not explicitly provided
2. **Use type encapsulation** for type-specific fields (for example, `grid:`, `rows:`, `cols:`, `tabs:`)
3. **Keep layouts clean** by using references instead of inline definitions
4. **Support flexible referencing** - allow definitions at multiple levels and external files
5. **Follow consistent naming** conventions (`snake_case` for identifiers)
6. **Organize logically** - group related elements, use comments
7. **Format consistently** - 2-space indentation, clear structure
8. **Start simple** - add complexity only when needed

By following these conventions, your dbt Charts dashboards will be:
- **Readable**: Easy to understand at a glance
- **Maintainable**: Easy to modify and extend
- **Reusable**: Components can be shared across dashboards
- **Consistent**: Predictable structure across projects

---

## Validating Your YAML

After writing your dashboard YAML, validate it to catch syntax and structure errors:

```bash
dct validate charts/sales.yml
```

For strict validation that fails on warnings:

```bash
dct validate charts/sales.yml --strict
```

See the [CLI Reference](../cli/validate.md) for more validation options.

## Related Documentation

- [CLI Reference](../cli/index.md) - Validate and compile commands
- [Best Practices Guide](best-practices.md) - General dashboard development best practices
- [Troubleshooting Guide](troubleshooting.md) - Common YAML syntax issues
- [YAML Schema Reference](../reference/yaml-reference.md) - Complete field reference
- [Quick Reference](../reference/quick-reference.md) - Quick reference cheat sheet

# Best Practices (https://docs.dbtcharts.com/guides/best-practices/)

# Best Practices

Dashboard design and development best practices for dbt Charts.

---

## Naming Conventions

### Dashboard Names

- Use lowercase with underscores: `sales_overview`, not `Sales Overview`
- Be descriptive: `monthly_sales_dashboard` is better than `dashboard1`
- Avoid spaces and special characters

### Query Names

- Use descriptive names that indicate what data the query fetches: `sales`, `products`, `customers`
- Keep names concise but clear
- Use explicit namespacing (`queries.sales`) when needed to avoid collisions

### Chart IDs

- Use descriptive names: `revenue_by_month`, not `chart1`
- Indicate chart purpose: `sales_trend`, `kpi_revenue`
- Be consistent with naming patterns

### Variable Names

- Use clear, descriptive names: `region`, `date_range`, `min_revenue`
- Avoid abbreviations unless widely understood
- Use snake_case consistently

---

## Organization Strategies

### Group Related Queries

Keep queries for the same domain together:

```yaml {contract=board-root}
queries:
  # Sales queries
  sales: ...
  sales_by_region: ...

  # Product queries
  products: ...
  product_categories: ...
```

### Use Tabs for Logical Grouping

Break dashboards into logical groups with [tabs](../boards/layouts.md#tab-layout) (or [details](../boards/layouts.md#details-collapsible-sections) for collapsible groups):

```yaml {contract=board-fragment}
tabs:
  items:
    - title: "Overview"
      rows: [kpi_row]        # High-level KPIs
    - title: "Trends"
      rows: [trend_chart]    # Time series charts
    - title: "Details"
      rows: [detail_table]   # Detailed tables
```

### Add Notes

`notes:` is available on every object, boards, charts, queries, variables, and
layout items, and it's metadata for AI search and maintainer context, not
end-user copy. It never appears in the rendered board, except at the board
level, where Cloud surfaces it in the dashboard-card hover overlay on the
project/home listing. The rule: if something displays, it has a display name
(`title`, `subtitle`, `label`, `text`); if it doesn't display, it's `notes`.

```yaml {contract=board-root}
title: "Sales Dashboard"
notes: "Monthly sales metrics and trends by region"
```

---

## Performance Optimization

### Limit Query Results

Add a `LIMIT` clause when you don't need all rows:

```yaml {contract=unverified}
queries:
  sales:
    sql: |
      SELECT month, SUM(revenue) AS total_revenue
      FROM dundersign.orders
      GROUP BY month
      LIMIT 100  -- Only fetch 100 rows
```

### Reuse Queries

Multiple charts can reference the same query (more efficient):

```yaml {contract=unverified}
queries:
  sales:
    sql: |
      SELECT month, region, SUM(revenue) AS total_revenue
      FROM dundersign.orders
      GROUP BY month, region

charts:
  chart1:
    type: bar
    x: month
    y: total_revenue
    query: sales  # Same query
  chart2:
    type: line
    x: month
    y: total_revenue
    query: sales  # Same query

rows: [chart1, chart2]
```

### Use Time Grain

Bucket timestamps to the grain you need directly in SQL:

```yaml {contract=unverified}
queries:
  monthly:
    sql: |
      SELECT DATE_TRUNC('month', order_date) AS month, SUM(revenue) AS total_revenue
      FROM dundersign.orders
      GROUP BY 1
```

### Filter Early

Filter in the query, not the chart:


```yaml {contract=board-fragment}
queries:
  filtered:
    sql: |
      SELECT status, COUNT(*) AS ticket_count FROM dundersign.tickets
      WHERE {{ filter('status', status) }}
        AND {{ filter_date_range('created_at', date_range) }}
      GROUP BY status
    source: warehouse
```


---

## User Experience

### Provide Defaults

Set sensible default values for variables:

```yaml {contract=board-root}
variables:
  region:
    default: "North"  # Show useful data by default

  date_range:
    input: daterange
    default: ["2024-01-01", "2024-01-31"]  # a daterange default is a [start, end] list
```

### Use Appropriate Input Types

Match input types to use cases:

- **Select**: Single choice from predefined list
- **Slider**: Numeric ranges
- **Date range**: Time period selection
- **Checkbox**: Simple on/off flags

### Add Notes

A chart-level `notes:` documents intent for AI search and tooling; it never renders:

```yaml {contract=board-fragment}
charts:
  revenue_chart:
    title: "Revenue by Month"
    notes: "Monthly revenue trends over the past 12 months"
    query: sales
    type: bar
```

### Test Interactions

Verify click actions and filters work as expected:

- Test all variable combinations
- Verify chart interactions
- Check filter behavior
- Test on different screen sizes

---

## Common Patterns

### Summary + Detail

Show high-level summary with drill-down detail using [tabs](../boards/layouts.md#tab-layout):

```yaml {contract=board-fragment}
tabs:
  items:
    - title: "Summary"
      rows: [summary_kpi]
    - title: "Details"
      rows: [detail_table]
```

For click-through drill-down instead of tabs, use chart-level `link:`; see [Interactions](../charts/interactions.md).

### Time Series with Filters

Combine time series with filters:

```yaml {contract=unverified}
variables:
  date_range: ...

queries:
  trends:
    sql: |
      SELECT month, tickets_created FROM dundersign_serving.monthly_metrics
      WHERE {{ filter_date_range('month', date_range) }}
      ORDER BY month
    source: warehouse

charts:
  trend_chart:
    query: trends
    type: line
    x: month
    y: tickets_created
```

### Comparison Views

Compare metrics side by side:

```yaml {contract=board-fragment}
charts:
  comparison:
    query: sales
    type: bar
    x: month
    y: total_revenue
    color: region  # Compare regions
```

---

## Anti-Patterns to Avoid

### ❌ Missing Query References

```yaml {contract=board-root expect=error code=ERR-UNKNOWN-QUERY}
charts:
  chart1:
    type: bar
    x: month
    y: revenue
    query: nonexistent  # Error: query doesn't exist
```

### ❌ Missing Source

```yaml {contract=unverified}
queries:
  sales:
    sql: SELECT * FROM orders  # Error: no source configured for this query
```

### ❌ Circular Dependencies

```yaml {contract=board-root}
variables:
  var1:
    default: "{{ var2 }}"  # var2 depends on var1 - circular!
  var2:
    default: "{{ var1 }}"
```

### ❌ Missing Required Fields

```yaml {contract=board-root expect=error code=ERR-VALIDATION-FIELD}
charts:
  chart1:
    # Missing: query, type
    x: month
```

### ❌ YAML Syntax Errors

Common mistakes:
- Wrong indentation (use spaces, not tabs)
- Missing colons
- Unquoted special characters

---

## Version Control Best Practices

### Commit Dashboard Files

Dashboard YAML files are version-controlled:
- Commit dashboard changes with model changes
- Use descriptive commit messages
- Review dashboard changes in PRs

### Organize by Feature

Group related dashboards:
```text
charts/
  sales/
    overview.yml
    trends.yml
  marketing/
    campaigns.yml
    leads.yml
```

### Document Changes

Add comments for complex logic:

```yaml {contract=board-root}
queries:
  complex:
    sql: |
      SELECT COUNT(*) AS ticket_count FROM dundersign.tickets
      WHERE status = 'new'          -- open tickets only
        AND ticket_type = 'incident'
    source: warehouse
```

---

## Development Workflow

### Validate Before Committing

Always validate your dashboards before committing:

```bash
dct validate charts/
```

See the [CLI Reference](../cli/validate.md) for validation options.

### Inspect Resolved Output for Debugging

When troubleshooting, render the dashboard to JSON to see the resolved layout, charts, and executed query data:

```bash
dct render charts/sales.yml --format json
```

See the [CLI Reference](../cli/render.md) for rendering options.

### Preview While Developing

Use the serve command for fast iteration:

```bash
dct serve
```

`dct serve` auto-discovers the project and prints the URL on startup. See the [CLI Reference](../cli/serve.md) for server options.

## Related

- [CLI Reference](../cli/index.md) - Complete CLI command reference
- [Troubleshooting Guide](troubleshooting.md) - Common issues and solutions
- [YAML Style Guide](yaml-style-guide.md) - YAML formatting best practices
- [Queries Guide](../queries.md) - Query best practices
- [Charts Guide](../charts/index.md) - Chart best practices
- [Examples](../examples/quickstart.md) - Example dashboards

# Troubleshooting (https://docs.dbtcharts.com/guides/troubleshooting/)

# Troubleshooting

Common issues and solutions when working with dbt Charts.

If `dct` can't reach your data (an adapter that won't import, a `profiles.yml` it can't find), run [`dct doctor`](../cli/doctor.md) first. It reports the install method, project, `profiles.yml`, and per-source adapters in one paste-able block.

---

## How Errors Are Displayed

The current product has a few different error paths, and they do not all render the same way:

- **Parse and validation errors** block the render before the dashboard is built.
- **Query execution errors** render inline as a negative-tone callout on the failing chart's tile; sibling charts on the same board still render, and the render response still succeeds.
- **Chart data-shape errors** can render inline in the affected chart cell, the same way.

For a fuller breakdown, including why a single-chart board's callout can look like a full-page error even though the render succeeded, see [Error Handling](error-handling.md), which has a live example of one chart's query failing while its neighbor renders normally.

---

## Validation Errors

### Missing Required Fields

**Error:** `Missing required field: query`

**Solution:** Ensure all charts have `query` and `type` fields:

```yaml {contract=board-fragment}
charts:
  my_chart:
    query: queries.sales  # Required
    type: bar       # Required
    x: month
    y: total_revenue
```

### Invalid Query Reference

**Error:** `Query 'sales' not found`

**Solution:** Ensure the query exists and the name matches exactly:

```yaml {contract=unverified}
queries:
  sales:  # Must match chart query reference
    sql: SELECT month, SUM(revenue) AS total_revenue FROM dundersign.orders GROUP BY 1

charts:
  my_chart:
    type: bar
    x: month
    y: total_revenue
    query: queries.sales  # Must match query name
```

---

## Chart Rendering Issues

### Chart Not Displaying

**Possible causes:**
- Query returns no data
- Invalid chart configuration
- Missing required fields

**Solution:**
1. Check the query returns data and the resolved chart structure: `dct render dashboard.yml --format json --allow-chart-errors`
2. Verify chart fields (`x`, `y`, `type`)
3. Check for validation errors: `dct validate dashboard.yml`

### Wrong Chart Type

**Error:** Chart doesn't match expected type

**Solution:**
- Verify `type` field matches available chart types
- Check [Charts Overview](../charts/index.md)
- Ensure chart type is supported by Vega-Lite

### Data Not Updating

**Issue:** Chart doesn't update when variable changes

**Solution:**
1. Verify variable is referenced in query filters
2. Check variable name matches exactly
3. Ensure query re-executes (check query logs)

---

## Variable Problems

### Variable Not Updating Query

**Issue:** Changing variable doesn't update charts

**Solution:**
1. Verify variable is referenced in the query SQL:
   ```yaml {contract=board-fragment}
   queries:
     tickets:
       sql: |
         SELECT * FROM dundersign.tickets
         WHERE {{ filter('status', status) }}  # Must reference variable
   ```
2. Check variable name matches exactly
3. Ensure the query re-executes after the variable changes

### Missing Required Variable

**Error:** `Missing required variables: ...`

**Solution:**
1. Decide whether the variable really needs `required: true`
2. If it does, supply the value in the board URL query string
3. Or set a variable `default:` so the board has a renderable starting state

This applies to every chart type. There is no special per-chart recovery path.

### Variable Options Not Loading

**Issue:** Dynamic options not appearing

**Solution:**
1. Verify query exists and returns data
2. Check query name matches `dynamic_query` value
3. Ensure query returns the expected column format

### Variable Type Mismatch

**Error:** Variable type doesn't match filter field

**Solution:**
- Ensure `data_type` matches filter field type
- Use appropriate input type for the data type
- Check type conversion in expressions if needed

---

## Performance Issues

### Slow Dashboard Loading

**Possible causes:**
- Large query results
- Complex queries
- Multiple queries executing

**Solutions:**
1. Add a `LIMIT` clause to queries:
   ```yaml {contract=unverified}
   queries:
     sales:
       sql: SELECT * FROM dundersign.orders LIMIT 100
   ```
2. Optimize queries (add filters, aggregate in SQL)
3. Reuse queries across charts
4. Consider caching for static dashboards

### Query Timeout

**Error:** Query execution timeout

**Solution:**
1. Optimize query (add filters, limit results)
2. Check database performance
3. Bucket timestamps with `DATE_TRUNC` in SQL instead of grouping by raw timestamps
4. Consider pre-aggregated models

The timeout itself is a server-side statement timeout, enforced on network warehouses (Postgres, Snowflake, BigQuery, etc.); never a client-side abandon. It's configurable via `execution.max_query_duration_seconds` in `dbt_charts.yml`, with a per-source override under `sources.<name>.max_query_duration_seconds`:

```yaml {contract=project-config}
# dbt_charts.yml
execution:
  max_query_duration_seconds: 60

sources:
  analytics:
    type: snowflake
    max_query_duration_seconds: 120  # override for this source only
```

DuckDB and SQLite are local file databases with no server to enforce a timeout; this setting has no effect on them.

---

## dbt Integration Issues

### Warehouse Adapter Not Installed

**Error:** `ERR-ADAPTER-NOT-INSTALLED`, from a `type: dbt_profile` source or
a direct source alike. `dct init` prints the same text as a `Tip:` when it
detects a dbt project whose profile needs a missing adapter:

```text
ERR-ADAPTER-NOT-INSTALLED  dbt Charts needs the dbt-snowflake adapter to query
'snowflake' sources, and it is not installed in this Python environment.
Install it with: uv tool install "dbt-charts[snowflake]"
```

**Solution:** dbt Charts opens its own connection to your database, through a
Python adapter package that ships as an extra. Run the command the error
names. It matches how dbt Charts was installed:

```bash
uv tool install "dbt-charts[snowflake]"   # or: pip install "dbt-charts[snowflake]"
```

See [Warehouse adapters](installation.md#warehouse-adapters) for the full list.
This is about dbt Charts' own connection, not your dbt installation: dbt Charts
never runs the `dbt` command, so it appears whether you build with dbt v1 or
[dbt v2](dbt-fusion.md).

### Database Connection Issues

**Error:** Cannot connect to database

**Solution:**
1. Check `profiles.yml` configuration
2. Verify database credentials
3. Test dbt connection: `dbt debug`
4. Check network/firewall settings

---

## YAML Syntax Errors

### Indentation Errors

**Error:** YAML parsing errors

**Solution:**
- Use spaces, not tabs
- Check indentation consistency
- Use a YAML validator

### Missing Colons

**Error:** `Expected ':'`

**Solution:**
- Ensure all keys have colons
- Check for typos in field names

### Unquoted Special Characters

**Error:** YAML parsing errors with special characters

**Solution:**
- Quote values with special characters
- Use quotes for strings starting with numbers

---

## Getting Help

### Validation

Always validate your dashboard first:

```bash
dct validate dashboard.yml
```

See the [CLI Reference](../cli/validate.md) for more validation options.

### Resolved output

Render the resolved layout and executed data as JSON to inspect what each chart actually saw. `--allow-chart-errors` keeps this from exiting before writing anything when a chart failed:

```bash
dct render dashboard.yml --format json --allow-chart-errors
```

See the [CLI Reference](../cli/render.md) for rendering options.

### Check Documentation

- [FAQ](../faq.md) - Quick answers to common how-do-I questions
- [CLI Reference](../cli/index.md) - Complete CLI command reference
- [YAML Schema Reference](../reference/yaml-reference.md) - Complete field reference
- [Charts Overview](../charts/index.md) - Chart families and guidance
- [Examples](../examples/quickstart.md) - Example dashboards

---

## Common Error Messages

| Error | Cause | Solution |
|-------|-------|----------|
| `Missing required field` | Required field not provided | Add missing field |
| `Query not found` | Query name mismatch | Check query name spelling |
| `Invalid chart type` | Unsupported chart type | Check chart types reference |
| `YAML syntax error` | YAML formatting issue | Validate YAML syntax |
| `Variable not found` | Variable name mismatch | Check variable name spelling |

---

## Related

- [Installation Guide](installation.md) - Setup and configuration
- [Getting Started Guide](getting-started.md) - First dashboard tutorial
- [FAQ](../faq.md) - Quick answers to common how-do-I questions
- [CLI Reference](../cli/index.md) - Complete CLI command reference
- [Best Practices](best-practices.md) - Dashboard design best practices
- [YAML Schema Reference](../reference/yaml-reference.md) - Complete field reference

# Error Handling (https://docs.dbtcharts.com/guides/error-handling/)

# Error Handling

dbt Charts currently exposes a few distinct classes of errors, and they do not all behave the same way.

## Current Behavior

- Parse errors stop before compilation finishes.
- Validation errors stop before rendering starts.
- Query execution failures and other runtime chart errors render as inline **callout** cards (`tone: negative`) while neighboring charts still render.
- Chart data-shape errors use the same inline callout treatment when the query succeeds but the chart contract is invalid, including data-shape errors caught while the board is being sized, before any chart is drawn (a pie with a NULL in its theta column, say).

For example, a KPI that receives multiple rows renders an inline negative callout while neighboring charts still render successfully. Bad SQL on one chart behaves the same way when other charts on the board succeed: live proof, not just a claim:

```dbt-charts-example
title: "One Broken Query, Healthy Neighbor"
source: examples_db

queries:
  revenue_by_date: |
    SELECT date, SUM(revenue) AS revenue
    FROM ecommerce_orders
    GROUP BY date
    ORDER BY date
  missing_table: SELECT * FROM this_table_does_not_exist

charts:
  revenue_chart:
    query: revenue_by_date
    type: line
    x: date
    y: revenue
  broken_chart:
    query: missing_table
    type: table

rows:
  - cols:
      - revenue_chart
      - broken_chart
```

`broken_chart`'s query fails at runtime (the tile renders the inline `tone: negative` callout) while `revenue_chart` renders normally beside it. The render response still succeeds; only `chart_errors` records the failure.

One broken chart never blanks the board. Whichever stage catches the problem, it stays scoped to that chart's tile and the rest of the board renders.

When a board has only one chart and that chart fails at runtime, the inline callout fills the tile; it can look like a full-page error even though the render response succeeded with `chart_errors` populated.

## Structured Compile Errors

Compile-time failures surface as a list of typed `Diagnostic` objects.

Each `Diagnostic` carries:

| Field | Description |
|---|---|
| `code` | Machine-readable error code (for example, `ERR-EXTRA-FIELD`) |
| `message` | Human-readable description |
| `range` | Source file plus 1-indexed start/end line where the error originates, when available |
| `path` | Dot-separated authoring path to the offending field (for example, `style.charts.bogus_field`) |
| `hint` | Optional fix suggestion |

`doc_url` isn't stored on the diagnostic itself; look it up from the code via the diagnostic registry (`dct docs warnings <CODE>`).

### Playground

The playground renders one card per error (`code` badge + message + optional line pointer) instead of collapsing all errors into a single block.

### VS Code

With the extension's [optional language server](../editor-extension.md#optional-language-server) enabled, compile diagnostics run on save (in addition to fast schema checks on every keystroke) and each `Diagnostic` maps to a squiggle at the correct source line. The language server is off by default; without it, run **dbt Charts: Validate Dashboard** for the same errors on demand.

### CLI

`dct validate` and `dct render` print each `Diagnostic` as a Rich panel.

## Suppressing a Diagnostic

Some diagnostics are informational rather than fatal; you may want to keep the underlying pattern (for example, an intentional average of per-group counts) without the warning noise. Three escape hatches exist, each with its own scope. All draw from the same unified diagnostic registry (`WARN-*` / `ERR-*` codes); a code typo'd or misspelled in any of them fails loudly instead of silently suppressing nothing.

- **Per-query, compile-time:** a query's `ignore:` field lists diagnostic codes to suppress for that query alone.
- **Per-chart, render-time:** a chart's `warnings_ignore:` field lists render-warning codes to suppress for that chart alone.

```yaml {contract=board-root}
queries:
  doc_recipients:
    sql: SELECT AVG(recipient_count) AS avg_recipients FROM (SELECT d.id, COUNT(dr.id) AS recipient_count FROM dundersign.documents d JOIN dundersign.document_recipients dr ON dr.document_id = d.id GROUP BY d.id) per_document
    ignore: [WARN-REAGGREGATION]

charts:
  doc_recipients_chart:
    type: table
    query: doc_recipients
    warnings_ignore: [WARN-QUERY-RETURNED-ZERO-ROWS]
```

- **Project-wide:** a `warnings:` block in `dbt_charts.yml` lists warning codes, query or render, to suppress for every board in the project.

```yaml {contract=project-config}
# dbt_charts.yml
warnings:
  ignore:
    - WARN-REDUNDANT-ENCODING
```

For a single run, `dct render --ignore-warning <CODE>` suppresses a render warning from the [command line](../cli/render.md).

Every one of these takes a list of codes, never a blanket on/off switch; suppress the specific diagnostic you've reviewed, not every diagnostic on that query, chart, or project. The full list of codes lives in two generated references: [Error Reference](../reference/errors.md) and [Warning Reference](../reference/warnings.md). `dct docs errors`/`dct docs warnings` list every code at the CLI, and `dct docs errors <CODE>`/`dct docs warnings <CODE>` print one code's full detector documentation (what it detects, why it fires, how to fix or suppress it); either verb resolves any registered code, regardless of which list it's actually in.

## What Is Not Implemented Yet

Planned behavior not yet implemented:

- Structured streaming progress and verbosity controls across CLI, MCP, and playground surfaces
- A larger, policy-driven error-handling model shared across all consumers

If you specifically want to test a raw YAML syntax error such as a missing bracket or colon, paste that broken YAML directly into the playground editor.

# Statistical Table Design Handbook (https://docs.dbtcharts.com/guides/statistical-table-design-handbook/)

# Statistical Table Design Handbook

This guide is the thick reference layer for the statistical table design work now carried into dbt Charts.

Use it to keep the doctrine, caveats, image evidence, and source distinctions together. For the copied image package and provenance metadata, see [statistical-table-design-assets/manifest.json](statistical-table-design-assets/manifest.json).

## How To Use This Guide

This is not a flat checklist. It is a synthesis of historical and modern table-design research adapted for dbt Charts.

The source spine is:

- William S. Cleveland on exact lookup, scanning, interpolation, and matching
- Karl G. Karsten on stubs, headings, tabulations, worksheets, and totals
- Alberto Cairo on the table-versus-chart decision
- Lisa Charlotte Muth on modern digital table practice
- Jonathan A. Schwabish on headers, spanners, dividers, borders, whitespace, and alignment

Inline attributions name the author and year when the year is available in the research layer.

## Glossary

- `table architecture`: the structural arrangement that makes a table readable as a system rather than a pile of cells
- `stub`: the side label area, usually carrying the dominant row categories
- `classified stub`: a multi-level row-grouping structure
- `column heading`: the label at the top of a column
- `spanner head`: a heading that spans multiple columns
- `spanner rule`: the line associated with a spanning header
- `rule`: a separator line used to distinguish structural transitions
- `border`: the outer edge around a table
- `gridline`: an internal cell-separating line
- `footer`: the bottom area where totals, averages, or summary rows may appear
- `tabulation`: a structured arrangement of data
- `work-sheet`: a proto-table or analytic matrix used to structure and check data before final display

## 1. What Tables Are For

Statistical tables are strongest when the reader needs exact values rather than an overall visual impression. Cleveland (1985) separates table look-up from pattern perception, and Cairo reaches the same practical conclusion in modern terms: when the task is to identify each individual value, a table is often the strongest form.

This is the central doctrinal point for dbt Charts too. A table is not a failed chart. It is a distinct reading instrument optimized for exact retrieval, orderly comparison, and dependable reference.

![Cleveland lookup-oriented graphic](statistical-table-design-assets/cleveland-scale-lines-and-data-rectangle.png)

The important limit is that this is a task-fit rule, not an anti-chart rule. Charts remain stronger for patterns, relationships, anomalies, and distribution shape.

## 2. The Core Reader Tasks

Cleveland (1985) gives the clearest operational model of table reading: scanning, interpolation, and matching.

- `Scanning`: finding the right row, column, label, or key
- `Interpolation`: estimating position between labeled values when the display does not state the exact number immediately
- `Matching`: connecting a symbol, label, or category in one place to its explanation in another

This is a better design frame than generic words like `readability` or `cleanliness`. A good table reduces search friction, back-and-forth eye travel, and memory burden. A bad one forces the reader to reconstruct the lookup path every time.

That is also why more scaffold is not automatically better. Cleveland's research helps explain why some grids and guide structures help pattern comparison without improving exact lookup.

## 3. Rows, Columns, Stubs, And Headings

Karsten is the strongest source in this corpus for formal table structure. His work treats stubs, headings, tabulations, and totals as designed parts, not as typographic afterthoughts.

The key structural rule is that row and column assignment is semantic. The more important grouping series often belongs at the side edge, and the longer series is often better listed downward. That means the stub is not leftover margin space. It is often the right home for the dominant grouping variable because it supports scanning and preserves group structure.

![Karsten condensed worksheet](statistical-table-design-assets/karsten-condensed-worksheet.webp)

Karsten also makes it clear that grouped headings and classified stubs are part of the table's logic. They are not mere decoration.

## 4. Tables As Reasoning Surfaces

Karsten's worksheets broaden the meaning of table design. Tables are not only publication outputs. They are also working structures for sorting, condensing, sequencing, and checking information before final presentation.

That matters for dbt Charts because many table-design problems begin before styling. A table can fail because the grouping logic is weak, the row-column assignment is unhelpful, or the data shape is fighting the intended lookup task.

![Karsten very condensed worksheet](statistical-table-design-assets/karsten-very-condensed-worksheet.webp)

This historical material feels modern because spreadsheet work, pivoting, and intermediate summary tables still operate on the same logic.

## 5. Totals, Subtotals, And Aggregation

Totals and subtotals should be treated as structural guides, not merely as appended arithmetic. Karsten treats the placement of totals as a design problem, and Muth (2018) shows the modern workflow equivalent through pivot tables and grouped summaries.

![Muth pivot table example](statistical-table-design-assets/muth-pivot-table-long-format-example.webp)

The design implication is simple: totals should appear where the reader can understand what they summarize without hunting for context. Aggregate rows and footer rows are part of the table's navigation system.

## 6. Rules, Borders, Spanners, And Whitespace

This is where table purpose becomes table architecture.

The strongest safe synthesis is:

- prefer selective rules over full boxing in finished tables
- use lines where they clarify major transitions such as header-to-body, grouped-column boundaries, or footer separation
- use denser grids mainly for worksheet-like reasoning surfaces
- use grouped headers and spanners when they reduce repetition and clarify column families
- let whitespace do real grouping work instead of relying on heavy gridlines everywhere

Karsten gives the structural doctrine. Schwabish (2020) gives the clearest modern operational language for spanner heads, spanner rules, subtle dividers, optional borders, differentiated footer rows, and spacing.

![Karsten tabulation with selective ruling](statistical-table-design-assets/karsten-tabulation-of-simple-route-chart-data.webp)

The evidence here is strong enough to support selective-rule guidance, but not strong enough to pretend we have a complete doctrine for double rules or every fine publication-style line hierarchy. That uncertainty should stay visible.

## 7. Alignment Should Follow Task And Semantic Role

The best-supported rule is not `left-align everything` or `center the headers`. Alignment should follow the reader's task and the semantic role of the text.

The most useful breakdown is four separate alignment problems:

1. `Stub alignment`
   Row labels, category names, and longer text usually want a stable reading edge. In left-to-right contexts, that usually means left alignment.
2. `Numeric alignment`
   Numbers are comparison-aligned rather than ornamentally right-aligned. Decimal alignment is best when precision comparison matters. Right alignment is the practical fallback when richer layout controls are unavailable.
3. `Header alignment`
   Ordinary one-column headers usually work best when they inherit the logic of the thing they label. This is a weaker doctrine than the others, so the uncertainty should remain visible.
4. `Grouping alignment`
   Spanners and grouped headers often need centering because they label a region of the table rather than a single stream of entries.

This yields a useful dbt Charts default:

- left-align text columns and row labels in LTR contexts
- decimal-align numeric columns when possible
- otherwise right-align numeric columns
- align ordinary one-column headers with the content beneath them
- center spanners and grouped headers

The ambiguity matters. The evidence does not support a universal law that ordinary one-column headers must always be centered or that centered single-column headers are always wrong. The best-supported default is narrower: single-column headers should usually align with the content they govern.

If space becomes too tight for those alignments to work cleanly, Muth's modern examples suggest a better response than forcing awkward alignment: redesign the header architecture first.

## 8. Data Shape Is Part Of Table Design

Muth's table work makes visible something older authors do not name directly: many table failures begin before any styling choice. Long-versus-wide arrangement, pivoting, grouped summaries, and workflow preparation all shape what kinds of tables can be made and how usable they will be.

That means table design in dbt Charts includes deciding whether the data structure supports the intended lookup task before debating borders, alignment, or spacing.

## 9. Modern Table Hybrids

Contemporary table practice includes searchable tables, heatmap tables, icons, and other small visual enrichments. The important limit from the research is that these devices should support lookup, not replace it.

![Muth heatmap table example](statistical-table-design-assets/muth-heatmap-table-life-expectancy.webp)

Add visual reinforcement when it strengthens scanning, grouping, or light comparison inside an intact table logic. If the visual encoding becomes the main reading channel, the display may no longer be functioning as a table.

## 10. Tables And Charts Often Need To Travel Together

The table-versus-chart question is often framed as a winner-take-all decision. The research points to a better answer: many tasks require both.

Cairo argues that tables are strongest for exact values while charts reveal patterns and exceptions. Cleveland's work explains why: exact lookup and pattern perception are genuinely different tasks. A mature dbt Charts view may therefore be strongest when the chart and the table travel together rather than competing for the same role.

![Muth editorial summary table](statistical-table-design-assets/muth-editorial-summary-table.webp)

Use charts for global structure and tables for auditing, reference, or value-by-value reading. When both exactness and overview matter, pairing is often the most honest pattern.

## Practical Defaults For dbt Charts

- Prefer tables when exact value retrieval is the primary task.
- Design tables around scanning, matching, and interpolation rather than generic neatness.
- Treat row and column assignment as semantic.
- Treat totals and subtotals as structural guides.
- Use selective rules and whitespace as quiet scaffolding.
- Use spanners to label regions, not individual reading streams.
- Align text, numbers, headers, and grouped heads according to their distinct roles.
- Treat data shape as part of table design, not a separate preprocessing concern.
- Use modern table enrichments only when they preserve lookup and scanability.
- Pair charts and tables when readers need both overview and exact reference.

## Related dbt Charts References

- [Asset package metadata](statistical-table-design-assets/manifest.json)

# Tonal Foundations (https://docs.dbtcharts.com/guides/tonal-foundations/)

# Tonal Foundations

This note captures an early tonal direction for dbt Charts's neutral palette so
future theme and token work can inherit a shared rationale instead of
re-deciding the same questions ad hoc.

These choices describe the product frame, not a fully settled token system.

## Current Direction

dbt Charts should soften the application frame without making the interface feel
dim or low-contrast.

- darkest default ink: `#222222` (dbt-grays `ink` token; warm-canvas variant `dbt-creams.ink` is `#2A2725`)
- page canvas: a slightly off-white neutral around `96-98%` lightness
- cards and primary working surfaces: `#FFFFFF`
- pure black: not part of the default neutral system for now, but available for
  future rare emphasis if a clear need emerges

The design intent is to avoid the harshness of absolute black and white as the
everyday defaults while preserving white as a valid surface color.

## Rationale

Near-black text is often easier to live with across dense product interfaces
than `#000000`. In a dashboard-heavy UI, pure black can make labels, chrome,
rules, and small text feel heavier than necessary. A softened darkest ink keeps
the product authoritative while reducing visual severity.

The background decision is more mixed. Pure white remains common and fully
valid for app surfaces, but using a subtly off-white canvas can make the app
frame feel calmer and give white cards or chart panels a clearer place to sit.

This leads to a useful separation:

- use a softened neutral for the page-level frame
- keep white available for cards, panels, and chart surfaces

## Evidence From Reference Systems

dbt Charts is not unusual in preferring near-black over pure black for default
ink:

- [USWDS](https://designsystem.digital.gov/utilities/color/) uses `#1B1B1B`
  for its `ink` token rather than `#000000`.
- [IBM Carbon](https://carbondesignsystem.com/elements/color/tokens/) uses a
  near-black primary text color in its light themes rather than pure black.
- [MUI](https://v5-0-6.mui.com/customization/dark-mode/) uses
  `rgba(0, 0, 0, 0.87)` for primary text in light mode rather than `#000000`.

It is also very common to keep using pure white for backgrounds and surfaces:

- [IBM Carbon](https://carbondesignsystem.com/elements/color/overview/) ships a
  default `White` theme with `#FFFFFF` as the global background.
- [MUI](https://v5-0-6.mui.com/guides/migration-v4/) documents `#fff` as the
  default light-mode background.
- [CMS Design System](https://design.cms.gov/utilities/text/text-color/) keeps
  both `#262626` for base text and `#000000` / `#FFFFFF` as available utility
  colors, which reflects how mature systems often soften defaults without
  banning absolutes outright.

Accessibility guidance supports the category of decision rather than a specific
hex. WCAG contrast requirements focus on sufficient contrast, not on using
pure black. Very dark grays such as `#222222` easily clear contrast
requirements on white or near-white surfaces.

- [MDN: Understanding WCAG color contrast](https://developer.mozilla.org/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable/Color_contrast)

## Implications For dbt Charts

- dbt Charts should not assume that `#000000` and `#FFFFFF` are the right default
  neutral pair simply because they are the simplest endpoints.
- dbt Charts can preserve white as a first-class surface color even if the app
  canvas moves slightly off white.
- Warm, cool, and neutral off-white variants are all plausible. The tint should
  remain subtle enough that the canvas still reads as bright and neutral rather
  than obviously beige or blue-gray.

## Open Questions

- Should dbt Charts's neutral system skew slightly warm, slightly cool, or remain
  strictly neutral?
- Should pure black ever appear as a special emphasis color, or should the
  neutral system stop at `#222222`?
- Once a neutral ramp is defined, which semantic roles should be standardized
  first: text, axes, borders, or surfaces?

# Overview (https://docs.dbtcharts.com/reference/)

# Reference

Reference material for dbt Charts fields, layouts, and syntax.

- [YAML Schema Reference](yaml-reference.md)
- [Editor Keybindings](editor-keybindings.md)
- [Layout Types Reference](layout-types.md)
- [Support Table (`chart.support_table`)](chart-support-table.md)
- [Quick Reference Cheat Sheet](quick-reference.md)
- [Error Reference](errors.md)
- [Warning Reference](warnings.md)
- [Telemetry](telemetry.md)

# dbt Charts YAML Schema Reference (https://docs.dbtcharts.com/reference/yaml-reference/)

# dbt Charts YAML Schema Reference

Fields are optional unless they appear under a **Required** label.

<a id="board"></a>
## Board
AuthoredBoard definition from YAML.

| Field | Type | Description |
|-------|------|-------------|
| `title` | str | Heading shown at the top of the board. |
| `notes` | str | Prose summary of what this board covers; read by AI search and board listings. |
| `tags` | list[str] | Keywords for grouping and searching boards. |
| `aliases` | list[str] | Additional URLs that redirect to this board's canonical file-path URL. Each entry must be absolute (leading /). Requests to these URLs are redirected (302) to the board's real path, query string preserved. Valid on .yml, .yaml, .md, and folder index.* boards. |
| `_schema_version` | str | The latest released dbt charts YAML schema version this file was last migrated to, written by `dct migrate` only -- never hand-author this. Informational: nothing reads it back when your board loads, and it is not a validated guarantee about the file's actual grammar (a hand-edit after migration can make it stale). YAML key: _schema_version. |
| `text` | str | Markdown text content for text-only sections. |
| `html_policy` | enum: "none", "safe-subset", "trusted-raw" | HTML rendering policy for the board's body text. Inline nested boards inherit it unless they set their own; tabs always inherit, and imported board files do not. One of: "none" (default): HTML is escaped and rendered as plain markdown; "safe-subset": reserved for a parser-checked allowlist (not yet enforced; currently renders as none); "trusted-raw": raw HTML via foreignObject. TRUSTED-CONTENT ONLY: this is NOT a security sandbox. &lt;script&gt;/event-handlers are stripped as a best-effort guard, not a guarantee. Enable only on first-party boards you fully control. |
| `source` | str | Default source name for all queries in this board. Inheritable via meta.yml cascade. |
| `cache` | bool \| str \| [Cache](#cache) \| const: "forever" | Cache policy for every query in this dashboard, e.g. cache: 1h: queries inherit it and may refine it; cache: false opts the whole dashboard out. Inheritable via the meta.yml cascade. |
| `incremental` | str \| const: false | Default watermark column for incremental refresh: queries in this board fetch only new rows since the last run and merge them with the cached result, keyed on this column. Queries inherit this value and may override it with their own incremental: setting. Set to false on a nested board to opt out of a parent's incremental setting. |
| `variables` | dict[str, [Variable](#variable) \| str \| [VariableRef](#variableref)] | Named inputs that parameterize queries; each renders as a control unless it sets visible: false. |
| `queries` | dict[str, str \| [SqlQuery](#sqlquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [QueryRef](#queryref)] | Named result sets the charts draw from (SQL, CSV, HTTP, and more). |
| `charts` | dict[str, [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| [CustomChart](#customchart) \| str \| [ChartRef](#chartref)] | Named chart definitions. When no explicit layout is present, charts render as an implicit row layout in authored order. |
| `rows` | list[str \| [Board](#board) \| [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| [CustomChart](#customchart) \| dict[str, [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| [CustomChart](#customchart)]] | Vertical stack layout: list of chart names or inline chart/board definitions. |
| `cols` | list[str \| [Board](#board) \| [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| [CustomChart](#customchart) \| dict[str, [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| [CustomChart](#customchart)]] | Horizontal layout: list of chart names or inline chart/board definitions. |
| `grid` | [GridLayout](#gridlayout) | CSS-grid style layout with explicit row/column placement. |
| `tabs` | [TabLayout](#tablayout) | Tabbed navigation layout where each tab contains its own layout. |
| `card_gap` | bool | When True, adds gap between cards. Default: cards are edge-to-edge (0 gap). |
| `chart_focus` | str | Render only this named chart with its dependent variables (useful for embedding or SVG export). |
| `details` | str \| [BoardDetails](#boarddetails) | Collapsible section metadata. String shorthand: details: 'text' → BoardDetails(summary='text'). Block form: details: {summary: ..., expanded_title: ..., expanded: false}. |
| `id` | str | Explicit ID for this board. Auto-generated from filename if omitted. |
| `style` | [Style](#style) | Appearance overrides for this board (background, border, and more). Most fields this board or an ancestor board explicitly authors cascade to nested child boards. Per-board fields (margin, padding): a nested board resolves these against its own theme, never an ancestor's. Root-board-only fields (footer, timestamp): a nested board never draws its own footer or timestamp line, so these never reach it either. background is the one appearance field that never cascades: unset means transparent, not an ancestor's color. |
| `width` | str \| int | Width when nested (e.g., '50%', '400px', or an integer in pixels). On the root board there is no parent to place it into, so it instead sets the board's own width (equivalent to 'style.frame.width'); percentages are rejected there since there's nothing to size relative to. |
| `height` | str \| int | Height when nested (e.g., '300px' or an integer in pixels). |
| `visible` | bool \| str \| [SingleRowBoolProbe](#singlerowboolprobe) | Controls whether this layout item is rendered. Accepts a bool, variable name, Jinja expression, or {query, column} probe. |
| `extends` | str \| list[str] \| enum: "clarity", "neon", "paper", "stark", "vivid" | Board name(s) or relative path(s) this board inherits from, low to high priority. A built-in theme name resolves it directly. |
| `auto_link` | bool | When True, table charts with no explicit link: automatically link each row to its canonical /data/&lt;source&gt;/&lt;schema&gt;/&lt;table&gt;/detail/ page. Default off. An explicit link: always wins; set link: false on a chart to suppress its automatic link. |
| `regional` | [Regional](#regional) | Locale and currency for every number on the board. Set it in charts/meta.yml to cover a folder; a nested board takes its root's. |
| `theme` | enum: "clarity", "neon", "paper", "stark", "vivid" | Built-in theme name; shorthand for `extends: &lt;name&gt;`. |

<a id="cache"></a>
## Cache
Cache policy at one scope: cache: 1h / forever / true / false (the only opt-out).

| Field | Type | Description |
|-------|------|-------------|
| `ttl` | str \| const: "forever" | Expire cached results after this wall-clock age (lazy: the next read recomputes). Short-duration string: units s/m/h/d/w, m = minutes, compound allowed ('1h30m'). Omit to inherit from the parent scope; write 'forever' to override an inherited ttl with never-auto-expire (manual refresh always remains available). |

<a id="variable"></a>
## Variable
Variable definition from YAML.

| Field | Type | Description |
|-------|------|-------------|
| `input` | enum: "auto", "select", "multiselect", "input", "text", "number", "textarea", "slider", "range", "date", "datepicker", "daterange", "checkbox", "radio" | UI control type (select, multiselect, slider, daterange, etc.). 'auto' detects from options. |
| `label` | str | Caption naming what this input sets. |
| `notes` | str | Help text for this input, carried to the host rather than drawn on the board. |
| `default` | Any | Value the variable takes when neither a URL param nor --var supplies one. |
| `placeholder` | str | Hint text shown inside the input while it is empty. |
| `required` | bool | When True, a value must be provided before queries execute. |
| `visible` | bool | When False, the variable is not rendered in the UI but can still be set via URL params. |
| `enabled` | bool \| str \| [SingleRowBoolProbe](#singlerowboolprobe) | Enable this control. Accepts: static bool; a variable name or Jinja boolean expression string (no {{ }} required, bare names auto-wrap); or a {query, column} form that reads a single boolean cell from a named query. None = enabled. Absent variable in a string expression raises (use a default). |
| `column` | str | Table column to draw option values from, as 'table.column'. The table may be schema-qualified ('schema.table.column') when it is not in the connection's default schema. |
| `query` | str \| [SqlQuery](#sqlquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) | Query name or inline query definition for populating options. |
| `options` | [VariableOptions](#variableoptions) | Where the selectable values come from: a written-out list or a query. |
| `data_type` | enum: "string", "number", "date", "boolean", "array" | The type of the values a select, radio or multiselect sends back. 'number', 'date' and 'boolean' convert the value before it reaches SQL; needed when the options come from a query, since a static numeric list already implies 'number'. 'string' and 'array' leave the value as sent. |
| `min` | int \| float | Minimum value for number, slider and range inputs. |
| `max` | int \| float | Maximum value for number, slider and range inputs. |
| `step` | int \| float | Step size for number, slider and range inputs. |
| `operator` | str | SQL operator used when generating filter expressions (e.g., '=', 'IN', 'LIKE'). |

<a id="variableref"></a>
## VariableRef
Cross-file variable reference. Bare string is coerced automatically.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `ref` | str | Reference path: '&lt;file&gt;.variables.&lt;name&gt;'. May start with one or more '../' segments to reach a sibling directory. A bare string value is coerced automatically. |

<a id="sqlquery"></a>
## SqlQuery
Raw SQL query: the default query type.

| Field | Type | Description |
|-------|------|-------------|
| `source` | str \| dict[str, Any] | Source name reference, or an inline file path (e.g. `./data/sales.csv`). File paths are detected by `/` or data file extension. An inline connection-bearing dict (`{type: postgres, ...}`) is rejected at compile time; reference a named source instead. |
| `notes` | str | Prose summary of what this query returns, passed along with its results to tooling. |
| `ignore` | list[one of: 'WARN-ADJACENT-TEXT-ROWS', 'WARN-AREA-UNSTACKED-READS-AS-STACKED', 'WARN-AREA-ZERO-BASELINE-CROPPED', 'WARN-AXIS-ALIGN-DISCARDED', 'WARN-AXIS-LABEL-COLLISION', 'WARN-AXIS-TITLE-TRUNCATED', 'WARN-BAR-BAND-WIDTH-TOO-NARROW', 'WARN-BAR-GROUPED-SERIES-COINCIDE', 'WARN-CALLOUT-TEXT-TRUNCATED', 'WARN-CATEGORY-COLOR-PIN-UNSEEN', 'WARN-CHART-TITLE-TRUNCATED', 'WARN-COLUMN-CHECK-UNAVAILABLE', 'WARN-DATE-AS-TEXT', 'WARN-DBT-MANIFEST-MISSING', 'WARN-DBT-MODEL-COLUMNS-UNRESOLVED', 'WARN-DBT-QUERY-COLUMNS-INDETERMINATE', 'WARN-DEFAULTS-FILE-GIVEN-AS-BOARD', 'WARN-DOUBLE-HEADER', 'WARN-DUAL-AXIS-COMPETING-SCALES', 'WARN-ENDPOINT-LABEL-GAP-OVERFLOW', 'WARN-ENDPOINT-LABEL-RAIL-OVERFLOW', 'WARN-ENDPOINT-LABEL-RAIL-TIED', 'WARN-FACET-PANEL-WIDTH-BELOW-MINIMUM', 'WARN-FANOUT-RISK', 'WARN-FLAT-COLS-UNSIZED-OVERFLOW', 'WARN-FORMAT-UNUSED-NAME', 'WARN-H1-BODY-NO-TITLE', 'WARN-HTML-POLICY-CAPPED', 'WARN-INHERITED-LAYOUT-REPLACED', 'WARN-KPI-ALIGN-OVERFLOW', 'WARN-KPI-INLINE-VARIANT-FALLBACK-TO-STACKED', 'WARN-KPI-LABEL-TRUNCATED', 'WARN-KPI-SUPPORT-TRUNCATED', 'WARN-LAYER-DATA-OUTSIDE-DOMAIN', 'WARN-LAYER-X-DOMAIN-PAINT-ORDER', 'WARN-LAYERED-CHART-SHARED-Y-AXIS-SCALE-MISMATCH', 'WARN-LAYOUT-MIN-EXCEEDS-HEIGHT', 'WARN-LEGEND-POSITION-WIDTH-FALLBACK', 'WARN-LEGEND-VALUES-UNRESOLVED', 'WARN-LIKELY-CURRENCY-OR-PERCENT-MISSING-FORMATTER', 'WARN-LOCAL-TIME-LABEL-EXPR-ON-BUCKETED-AXIS', 'WARN-LOW-TEXT-CONTRAST', 'WARN-MISSING-JOIN-PREDICATE', 'WARN-NORMALIZE-PERCENT-FORMAT-READS-RAW-VALUE', 'WARN-PALETTE-UNSUPPORTED', 'WARN-PARSE-ERROR', 'WARN-PIE-DOMINANT-SEGMENT', 'WARN-PIE-TOO-MANY-SEGMENTS', 'WARN-PIE-TOTAL-EXCEEDS-INNER-RADIUS', 'WARN-PLOT-HEIGHT-BELOW-MINIMUM', 'WARN-PLOT-WIDTH-BELOW-MINIMUM', 'WARN-POINT-MAP-NEGATIVE-SIZE-VALUES', 'WARN-POINT-MAP-OUT-OF-PROJECTION', 'WARN-QUERY-RESULT-TRUNCATED', 'WARN-QUERY-RETURNED-ZERO-ROWS', 'WARN-REAGGREGATION', 'WARN-REDUNDANT-AUTHORED-DEFAULT', 'WARN-REDUNDANT-AUTHORED-LABEL', 'WARN-REDUNDANT-ENCODING', 'WARN-RETIRED-IGNORE-CODE', 'WARN-SCHEMA-MIGRATED', 'WARN-SERIES-LABEL-TRUNCATED', 'WARN-SERIES-LABELS-REPEAT-WORD', 'WARN-SINGLE-CHART-REDUNDANT-TITLE', 'WARN-SPARK-LABEL-TRUNCATED', 'WARN-STATIC-PAGINATION-CAPPED', 'WARN-SUPPORT-TABLE-CELL-OVERFLOW', 'WARN-TABLE-COLUMNS-OVERFLOW', 'WARN-TABLE-CRAMPED', 'WARN-TABLE-PAGE-SQUEEZED', 'WARN-TABLE-TEXT-TRUNCATED', 'WARN-TEMPORAL-SINGLE-POINT', 'WARN-TOO-MANY-COLOR-CATEGORIES', 'WARN-TOO-MANY-X-CATEGORIES', 'WARN-UNREFERENCED-CHART', 'WARN-VALUE-LABELS-CROWD-WIDTH', 'WARN-WAREHOUSE-CHECK-UNAVAILABLE', 'WARN-WIDE-MEASURE-LABEL-COLLISION', 'WARN-Y-ENCODING-MOSTLY-NULL'] | Diagnostic codes to suppress for this query (e.g., ['WARN-MISSING-JOIN-PREDICATE', 'WARN-REAGGREGATION']). |
| `cache` | bool \| str \| [Cache](#cache) \| const: "forever" | Cache policy override for this query, e.g. cache: 5m: refines the policy inherited from the source and project scopes; cache: false opts out of result caching entirely. Queries with cache: false cannot be used as {{ queries.X.cache }} upstream references. |
| `formats` | dict[str, one of: 'compact', 'currency', 'currency_compact', 'currency_full', 'currency_whole', 'date_short', 'delta', 'email', 'id', 'integer', 'latitude', 'longitude', 'number', 'number_full', 'percent', 'percent_delta', 'percent_whole', 'rating', 'time_short', 'url', 'year' \| str] | How the query's columns print, as column: format name. A name is an engine format (`currency`, `percent`, `year`, ...) or one the board defines in `style.formats`; a d3 spec is rejected. Every chart showing the column uses the format unless it sets its own. |
| `incremental` | str \| const: false | Column used as the monotonic watermark for incremental refresh: the executor fetches only rows after the prior watermark and merges them with the cached result. `incremental: false` opts this query out of a board's incremental setting. Inherits from the board-level incremental setting when omitted. |
| `type` | const: "sql" |  |
| `sql` | str | The statement to run, with Jinja2 over board variables, other queries, and the filter helpers. |
| `setup_sql` | str | Non-nestable SQL preamble executed before the main query (e.g., CREATE TEMP FUNCTION). |
| `target` | str | dbt target name for queries against a dbt_profile source (defaults to 'dev'). |
| `dialect` | enum: "athena", "bigquery", "clickhouse", "databricks", "duckdb", "fabric", "lakecompute", "mysql", "postgres", "presto", "redshift", "snowflake", "spark", "sqlite", "sqlserver", "trino" | Warehouse dialect the SQL is written in, translated to the source's. |

<a id="httpquery"></a>
## HttpQuery
REST API query.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `url` | str | HTTP endpoint URL for REST API queries. |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `source` | str \| dict[str, Any] | Source name reference, or an inline file path (e.g. `./data/sales.csv`). File paths are detected by `/` or data file extension. An inline connection-bearing dict (`{type: postgres, ...}`) is rejected at compile time; reference a named source instead. |
| `notes` | str | Prose summary of what this query returns, passed along with its results to tooling. |
| `ignore` | list[one of: 'WARN-ADJACENT-TEXT-ROWS', 'WARN-AREA-UNSTACKED-READS-AS-STACKED', 'WARN-AREA-ZERO-BASELINE-CROPPED', 'WARN-AXIS-ALIGN-DISCARDED', 'WARN-AXIS-LABEL-COLLISION', 'WARN-AXIS-TITLE-TRUNCATED', 'WARN-BAR-BAND-WIDTH-TOO-NARROW', 'WARN-BAR-GROUPED-SERIES-COINCIDE', 'WARN-CALLOUT-TEXT-TRUNCATED', 'WARN-CATEGORY-COLOR-PIN-UNSEEN', 'WARN-CHART-TITLE-TRUNCATED', 'WARN-COLUMN-CHECK-UNAVAILABLE', 'WARN-DATE-AS-TEXT', 'WARN-DBT-MANIFEST-MISSING', 'WARN-DBT-MODEL-COLUMNS-UNRESOLVED', 'WARN-DBT-QUERY-COLUMNS-INDETERMINATE', 'WARN-DEFAULTS-FILE-GIVEN-AS-BOARD', 'WARN-DOUBLE-HEADER', 'WARN-DUAL-AXIS-COMPETING-SCALES', 'WARN-ENDPOINT-LABEL-GAP-OVERFLOW', 'WARN-ENDPOINT-LABEL-RAIL-OVERFLOW', 'WARN-ENDPOINT-LABEL-RAIL-TIED', 'WARN-FACET-PANEL-WIDTH-BELOW-MINIMUM', 'WARN-FANOUT-RISK', 'WARN-FLAT-COLS-UNSIZED-OVERFLOW', 'WARN-FORMAT-UNUSED-NAME', 'WARN-H1-BODY-NO-TITLE', 'WARN-HTML-POLICY-CAPPED', 'WARN-INHERITED-LAYOUT-REPLACED', 'WARN-KPI-ALIGN-OVERFLOW', 'WARN-KPI-INLINE-VARIANT-FALLBACK-TO-STACKED', 'WARN-KPI-LABEL-TRUNCATED', 'WARN-KPI-SUPPORT-TRUNCATED', 'WARN-LAYER-DATA-OUTSIDE-DOMAIN', 'WARN-LAYER-X-DOMAIN-PAINT-ORDER', 'WARN-LAYERED-CHART-SHARED-Y-AXIS-SCALE-MISMATCH', 'WARN-LAYOUT-MIN-EXCEEDS-HEIGHT', 'WARN-LEGEND-POSITION-WIDTH-FALLBACK', 'WARN-LEGEND-VALUES-UNRESOLVED', 'WARN-LIKELY-CURRENCY-OR-PERCENT-MISSING-FORMATTER', 'WARN-LOCAL-TIME-LABEL-EXPR-ON-BUCKETED-AXIS', 'WARN-LOW-TEXT-CONTRAST', 'WARN-MISSING-JOIN-PREDICATE', 'WARN-NORMALIZE-PERCENT-FORMAT-READS-RAW-VALUE', 'WARN-PALETTE-UNSUPPORTED', 'WARN-PARSE-ERROR', 'WARN-PIE-DOMINANT-SEGMENT', 'WARN-PIE-TOO-MANY-SEGMENTS', 'WARN-PIE-TOTAL-EXCEEDS-INNER-RADIUS', 'WARN-PLOT-HEIGHT-BELOW-MINIMUM', 'WARN-PLOT-WIDTH-BELOW-MINIMUM', 'WARN-POINT-MAP-NEGATIVE-SIZE-VALUES', 'WARN-POINT-MAP-OUT-OF-PROJECTION', 'WARN-QUERY-RESULT-TRUNCATED', 'WARN-QUERY-RETURNED-ZERO-ROWS', 'WARN-REAGGREGATION', 'WARN-REDUNDANT-AUTHORED-DEFAULT', 'WARN-REDUNDANT-AUTHORED-LABEL', 'WARN-REDUNDANT-ENCODING', 'WARN-RETIRED-IGNORE-CODE', 'WARN-SCHEMA-MIGRATED', 'WARN-SERIES-LABEL-TRUNCATED', 'WARN-SERIES-LABELS-REPEAT-WORD', 'WARN-SINGLE-CHART-REDUNDANT-TITLE', 'WARN-SPARK-LABEL-TRUNCATED', 'WARN-STATIC-PAGINATION-CAPPED', 'WARN-SUPPORT-TABLE-CELL-OVERFLOW', 'WARN-TABLE-COLUMNS-OVERFLOW', 'WARN-TABLE-CRAMPED', 'WARN-TABLE-PAGE-SQUEEZED', 'WARN-TABLE-TEXT-TRUNCATED', 'WARN-TEMPORAL-SINGLE-POINT', 'WARN-TOO-MANY-COLOR-CATEGORIES', 'WARN-TOO-MANY-X-CATEGORIES', 'WARN-UNREFERENCED-CHART', 'WARN-VALUE-LABELS-CROWD-WIDTH', 'WARN-WAREHOUSE-CHECK-UNAVAILABLE', 'WARN-WIDE-MEASURE-LABEL-COLLISION', 'WARN-Y-ENCODING-MOSTLY-NULL'] | Diagnostic codes to suppress for this query (e.g., ['WARN-MISSING-JOIN-PREDICATE', 'WARN-REAGGREGATION']). |
| `cache` | bool \| str \| [Cache](#cache) \| const: "forever" | Cache policy override for this query, e.g. cache: 5m: refines the policy inherited from the source and project scopes; cache: false opts out of result caching entirely. Queries with cache: false cannot be used as {{ queries.X.cache }} upstream references. |
| `formats` | dict[str, one of: 'compact', 'currency', 'currency_compact', 'currency_full', 'currency_whole', 'date_short', 'delta', 'email', 'id', 'integer', 'latitude', 'longitude', 'number', 'number_full', 'percent', 'percent_delta', 'percent_whole', 'rating', 'time_short', 'url', 'year' \| str] | How the query's columns print, as column: format name. A name is an engine format (`currency`, `percent`, `year`, ...) or one the board defines in `style.formats`; a d3 spec is rejected. Every chart showing the column uses the format unless it sets its own. |
| `incremental` | str \| const: false | Column used as the monotonic watermark for incremental refresh: the executor fetches only rows after the prior watermark and merges them with the cached result. `incremental: false` opts this query out of a board's incremental setting. Inherits from the board-level incremental setting when omitted. |
| `type` | const: "http" |  |
| `method` | enum: "GET", "POST", "PUT", "DELETE", "PATCH" | Verb the request is sent with (GET, POST, PUT, DELETE, PATCH). |
| `headers` | dict[str, str] | Header lines sent with the request, such as auth and content type. |
| `params` | dict[str, Any] | Values appended to the URL after the '?'. |
| `body` | dict[str, Any] \| str | Payload sent with the request, on POST, PUT, and PATCH. |
| `limit` | int | Maximum number of rows returned. |
| `json_path` | str | JSONPath expression to extract tabular data from the HTTP response. |

<a id="valuesquery"></a>
## ValuesQuery
Inline data authored as a list of row mappings.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `rows` | list[dict[str, Any]] | Inline data rows (list of row dicts). Use the compact columns-and-values form instead when row values are positional. |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `source` | str \| dict[str, Any] | Source name reference, or an inline file path (e.g. `./data/sales.csv`). File paths are detected by `/` or data file extension. An inline connection-bearing dict (`{type: postgres, ...}`) is rejected at compile time; reference a named source instead. |
| `notes` | str | Prose summary of what this query returns, passed along with its results to tooling. |
| `ignore` | list[one of: 'WARN-ADJACENT-TEXT-ROWS', 'WARN-AREA-UNSTACKED-READS-AS-STACKED', 'WARN-AREA-ZERO-BASELINE-CROPPED', 'WARN-AXIS-ALIGN-DISCARDED', 'WARN-AXIS-LABEL-COLLISION', 'WARN-AXIS-TITLE-TRUNCATED', 'WARN-BAR-BAND-WIDTH-TOO-NARROW', 'WARN-BAR-GROUPED-SERIES-COINCIDE', 'WARN-CALLOUT-TEXT-TRUNCATED', 'WARN-CATEGORY-COLOR-PIN-UNSEEN', 'WARN-CHART-TITLE-TRUNCATED', 'WARN-COLUMN-CHECK-UNAVAILABLE', 'WARN-DATE-AS-TEXT', 'WARN-DBT-MANIFEST-MISSING', 'WARN-DBT-MODEL-COLUMNS-UNRESOLVED', 'WARN-DBT-QUERY-COLUMNS-INDETERMINATE', 'WARN-DEFAULTS-FILE-GIVEN-AS-BOARD', 'WARN-DOUBLE-HEADER', 'WARN-DUAL-AXIS-COMPETING-SCALES', 'WARN-ENDPOINT-LABEL-GAP-OVERFLOW', 'WARN-ENDPOINT-LABEL-RAIL-OVERFLOW', 'WARN-ENDPOINT-LABEL-RAIL-TIED', 'WARN-FACET-PANEL-WIDTH-BELOW-MINIMUM', 'WARN-FANOUT-RISK', 'WARN-FLAT-COLS-UNSIZED-OVERFLOW', 'WARN-FORMAT-UNUSED-NAME', 'WARN-H1-BODY-NO-TITLE', 'WARN-HTML-POLICY-CAPPED', 'WARN-INHERITED-LAYOUT-REPLACED', 'WARN-KPI-ALIGN-OVERFLOW', 'WARN-KPI-INLINE-VARIANT-FALLBACK-TO-STACKED', 'WARN-KPI-LABEL-TRUNCATED', 'WARN-KPI-SUPPORT-TRUNCATED', 'WARN-LAYER-DATA-OUTSIDE-DOMAIN', 'WARN-LAYER-X-DOMAIN-PAINT-ORDER', 'WARN-LAYERED-CHART-SHARED-Y-AXIS-SCALE-MISMATCH', 'WARN-LAYOUT-MIN-EXCEEDS-HEIGHT', 'WARN-LEGEND-POSITION-WIDTH-FALLBACK', 'WARN-LEGEND-VALUES-UNRESOLVED', 'WARN-LIKELY-CURRENCY-OR-PERCENT-MISSING-FORMATTER', 'WARN-LOCAL-TIME-LABEL-EXPR-ON-BUCKETED-AXIS', 'WARN-LOW-TEXT-CONTRAST', 'WARN-MISSING-JOIN-PREDICATE', 'WARN-NORMALIZE-PERCENT-FORMAT-READS-RAW-VALUE', 'WARN-PALETTE-UNSUPPORTED', 'WARN-PARSE-ERROR', 'WARN-PIE-DOMINANT-SEGMENT', 'WARN-PIE-TOO-MANY-SEGMENTS', 'WARN-PIE-TOTAL-EXCEEDS-INNER-RADIUS', 'WARN-PLOT-HEIGHT-BELOW-MINIMUM', 'WARN-PLOT-WIDTH-BELOW-MINIMUM', 'WARN-POINT-MAP-NEGATIVE-SIZE-VALUES', 'WARN-POINT-MAP-OUT-OF-PROJECTION', 'WARN-QUERY-RESULT-TRUNCATED', 'WARN-QUERY-RETURNED-ZERO-ROWS', 'WARN-REAGGREGATION', 'WARN-REDUNDANT-AUTHORED-DEFAULT', 'WARN-REDUNDANT-AUTHORED-LABEL', 'WARN-REDUNDANT-ENCODING', 'WARN-RETIRED-IGNORE-CODE', 'WARN-SCHEMA-MIGRATED', 'WARN-SERIES-LABEL-TRUNCATED', 'WARN-SERIES-LABELS-REPEAT-WORD', 'WARN-SINGLE-CHART-REDUNDANT-TITLE', 'WARN-SPARK-LABEL-TRUNCATED', 'WARN-STATIC-PAGINATION-CAPPED', 'WARN-SUPPORT-TABLE-CELL-OVERFLOW', 'WARN-TABLE-COLUMNS-OVERFLOW', 'WARN-TABLE-CRAMPED', 'WARN-TABLE-PAGE-SQUEEZED', 'WARN-TABLE-TEXT-TRUNCATED', 'WARN-TEMPORAL-SINGLE-POINT', 'WARN-TOO-MANY-COLOR-CATEGORIES', 'WARN-TOO-MANY-X-CATEGORIES', 'WARN-UNREFERENCED-CHART', 'WARN-VALUE-LABELS-CROWD-WIDTH', 'WARN-WAREHOUSE-CHECK-UNAVAILABLE', 'WARN-WIDE-MEASURE-LABEL-COLLISION', 'WARN-Y-ENCODING-MOSTLY-NULL'] | Diagnostic codes to suppress for this query (e.g., ['WARN-MISSING-JOIN-PREDICATE', 'WARN-REAGGREGATION']). |
| `cache` | bool \| str \| [Cache](#cache) \| const: "forever" | Cache policy override for this query, e.g. cache: 5m: refines the policy inherited from the source and project scopes; cache: false opts out of result caching entirely. Queries with cache: false cannot be used as {{ queries.X.cache }} upstream references. |
| `formats` | dict[str, one of: 'compact', 'currency', 'currency_compact', 'currency_full', 'currency_whole', 'date_short', 'delta', 'email', 'id', 'integer', 'latitude', 'longitude', 'number', 'number_full', 'percent', 'percent_delta', 'percent_whole', 'rating', 'time_short', 'url', 'year' \| str] | How the query's columns print, as column: format name. A name is an engine format (`currency`, `percent`, `year`, ...) or one the board defines in `style.formats`; a d3 spec is rejected. Every chart showing the column uses the format unless it sets its own. |
| `incremental` | str \| const: false | Column used as the monotonic watermark for incremental refresh: the executor fetches only rows after the prior watermark and merges them with the cached result. `incremental: false` opts this query out of a board's incremental setting. Inherits from the board-level incremental setting when omitted. |
| `type` | const: "values" |  |

<a id="compactvaluesquery"></a>
## CompactValuesQuery
Inline data authored as column names plus positional row values.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `columns` | list[str] | Column names for the compact syntax. Every compact values query also requires values. |
| `values` | list[list[Any]] | Inline row-oriented data (list of lists) for the compact syntax. Every compact values query also requires columns. |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `source` | str \| dict[str, Any] | Source name reference, or an inline file path (e.g. `./data/sales.csv`). File paths are detected by `/` or data file extension. An inline connection-bearing dict (`{type: postgres, ...}`) is rejected at compile time; reference a named source instead. |
| `notes` | str | Prose summary of what this query returns, passed along with its results to tooling. |
| `ignore` | list[one of: 'WARN-ADJACENT-TEXT-ROWS', 'WARN-AREA-UNSTACKED-READS-AS-STACKED', 'WARN-AREA-ZERO-BASELINE-CROPPED', 'WARN-AXIS-ALIGN-DISCARDED', 'WARN-AXIS-LABEL-COLLISION', 'WARN-AXIS-TITLE-TRUNCATED', 'WARN-BAR-BAND-WIDTH-TOO-NARROW', 'WARN-BAR-GROUPED-SERIES-COINCIDE', 'WARN-CALLOUT-TEXT-TRUNCATED', 'WARN-CATEGORY-COLOR-PIN-UNSEEN', 'WARN-CHART-TITLE-TRUNCATED', 'WARN-COLUMN-CHECK-UNAVAILABLE', 'WARN-DATE-AS-TEXT', 'WARN-DBT-MANIFEST-MISSING', 'WARN-DBT-MODEL-COLUMNS-UNRESOLVED', 'WARN-DBT-QUERY-COLUMNS-INDETERMINATE', 'WARN-DEFAULTS-FILE-GIVEN-AS-BOARD', 'WARN-DOUBLE-HEADER', 'WARN-DUAL-AXIS-COMPETING-SCALES', 'WARN-ENDPOINT-LABEL-GAP-OVERFLOW', 'WARN-ENDPOINT-LABEL-RAIL-OVERFLOW', 'WARN-ENDPOINT-LABEL-RAIL-TIED', 'WARN-FACET-PANEL-WIDTH-BELOW-MINIMUM', 'WARN-FANOUT-RISK', 'WARN-FLAT-COLS-UNSIZED-OVERFLOW', 'WARN-FORMAT-UNUSED-NAME', 'WARN-H1-BODY-NO-TITLE', 'WARN-HTML-POLICY-CAPPED', 'WARN-INHERITED-LAYOUT-REPLACED', 'WARN-KPI-ALIGN-OVERFLOW', 'WARN-KPI-INLINE-VARIANT-FALLBACK-TO-STACKED', 'WARN-KPI-LABEL-TRUNCATED', 'WARN-KPI-SUPPORT-TRUNCATED', 'WARN-LAYER-DATA-OUTSIDE-DOMAIN', 'WARN-LAYER-X-DOMAIN-PAINT-ORDER', 'WARN-LAYERED-CHART-SHARED-Y-AXIS-SCALE-MISMATCH', 'WARN-LAYOUT-MIN-EXCEEDS-HEIGHT', 'WARN-LEGEND-POSITION-WIDTH-FALLBACK', 'WARN-LEGEND-VALUES-UNRESOLVED', 'WARN-LIKELY-CURRENCY-OR-PERCENT-MISSING-FORMATTER', 'WARN-LOCAL-TIME-LABEL-EXPR-ON-BUCKETED-AXIS', 'WARN-LOW-TEXT-CONTRAST', 'WARN-MISSING-JOIN-PREDICATE', 'WARN-NORMALIZE-PERCENT-FORMAT-READS-RAW-VALUE', 'WARN-PALETTE-UNSUPPORTED', 'WARN-PARSE-ERROR', 'WARN-PIE-DOMINANT-SEGMENT', 'WARN-PIE-TOO-MANY-SEGMENTS', 'WARN-PIE-TOTAL-EXCEEDS-INNER-RADIUS', 'WARN-PLOT-HEIGHT-BELOW-MINIMUM', 'WARN-PLOT-WIDTH-BELOW-MINIMUM', 'WARN-POINT-MAP-NEGATIVE-SIZE-VALUES', 'WARN-POINT-MAP-OUT-OF-PROJECTION', 'WARN-QUERY-RESULT-TRUNCATED', 'WARN-QUERY-RETURNED-ZERO-ROWS', 'WARN-REAGGREGATION', 'WARN-REDUNDANT-AUTHORED-DEFAULT', 'WARN-REDUNDANT-AUTHORED-LABEL', 'WARN-REDUNDANT-ENCODING', 'WARN-RETIRED-IGNORE-CODE', 'WARN-SCHEMA-MIGRATED', 'WARN-SERIES-LABEL-TRUNCATED', 'WARN-SERIES-LABELS-REPEAT-WORD', 'WARN-SINGLE-CHART-REDUNDANT-TITLE', 'WARN-SPARK-LABEL-TRUNCATED', 'WARN-STATIC-PAGINATION-CAPPED', 'WARN-SUPPORT-TABLE-CELL-OVERFLOW', 'WARN-TABLE-COLUMNS-OVERFLOW', 'WARN-TABLE-CRAMPED', 'WARN-TABLE-PAGE-SQUEEZED', 'WARN-TABLE-TEXT-TRUNCATED', 'WARN-TEMPORAL-SINGLE-POINT', 'WARN-TOO-MANY-COLOR-CATEGORIES', 'WARN-TOO-MANY-X-CATEGORIES', 'WARN-UNREFERENCED-CHART', 'WARN-VALUE-LABELS-CROWD-WIDTH', 'WARN-WAREHOUSE-CHECK-UNAVAILABLE', 'WARN-WIDE-MEASURE-LABEL-COLLISION', 'WARN-Y-ENCODING-MOSTLY-NULL'] | Diagnostic codes to suppress for this query (e.g., ['WARN-MISSING-JOIN-PREDICATE', 'WARN-REAGGREGATION']). |
| `cache` | bool \| str \| [Cache](#cache) \| const: "forever" | Cache policy override for this query, e.g. cache: 5m: refines the policy inherited from the source and project scopes; cache: false opts out of result caching entirely. Queries with cache: false cannot be used as {{ queries.X.cache }} upstream references. |
| `formats` | dict[str, one of: 'compact', 'currency', 'currency_compact', 'currency_full', 'currency_whole', 'date_short', 'delta', 'email', 'id', 'integer', 'latitude', 'longitude', 'number', 'number_full', 'percent', 'percent_delta', 'percent_whole', 'rating', 'time_short', 'url', 'year' \| str] | How the query's columns print, as column: format name. A name is an engine format (`currency`, `percent`, `year`, ...) or one the board defines in `style.formats`; a d3 spec is rejected. Every chart showing the column uses the format unless it sets its own. |
| `incremental` | str \| const: false | Column used as the monotonic watermark for incremental refresh: the executor fetches only rows after the prior watermark and merges them with the cached result. `incremental: false` opts this query out of a board's incremental setting. Inherits from the board-level incremental setting when omitted. |
| `type` | const: "values" |  |

<a id="schemaquery"></a>
## SchemaQuery
dbt source schema query.

| Field | Type | Description |
|-------|------|-------------|
| `source` | str \| dict[str, Any] | Source name reference, or an inline file path (e.g. `./data/sales.csv`). File paths are detected by `/` or data file extension. An inline connection-bearing dict (`{type: postgres, ...}`) is rejected at compile time; reference a named source instead. |
| `notes` | str | Prose summary of what this query returns, passed along with its results to tooling. |
| `ignore` | list[one of: 'WARN-ADJACENT-TEXT-ROWS', 'WARN-AREA-UNSTACKED-READS-AS-STACKED', 'WARN-AREA-ZERO-BASELINE-CROPPED', 'WARN-AXIS-ALIGN-DISCARDED', 'WARN-AXIS-LABEL-COLLISION', 'WARN-AXIS-TITLE-TRUNCATED', 'WARN-BAR-BAND-WIDTH-TOO-NARROW', 'WARN-BAR-GROUPED-SERIES-COINCIDE', 'WARN-CALLOUT-TEXT-TRUNCATED', 'WARN-CATEGORY-COLOR-PIN-UNSEEN', 'WARN-CHART-TITLE-TRUNCATED', 'WARN-COLUMN-CHECK-UNAVAILABLE', 'WARN-DATE-AS-TEXT', 'WARN-DBT-MANIFEST-MISSING', 'WARN-DBT-MODEL-COLUMNS-UNRESOLVED', 'WARN-DBT-QUERY-COLUMNS-INDETERMINATE', 'WARN-DEFAULTS-FILE-GIVEN-AS-BOARD', 'WARN-DOUBLE-HEADER', 'WARN-DUAL-AXIS-COMPETING-SCALES', 'WARN-ENDPOINT-LABEL-GAP-OVERFLOW', 'WARN-ENDPOINT-LABEL-RAIL-OVERFLOW', 'WARN-ENDPOINT-LABEL-RAIL-TIED', 'WARN-FACET-PANEL-WIDTH-BELOW-MINIMUM', 'WARN-FANOUT-RISK', 'WARN-FLAT-COLS-UNSIZED-OVERFLOW', 'WARN-FORMAT-UNUSED-NAME', 'WARN-H1-BODY-NO-TITLE', 'WARN-HTML-POLICY-CAPPED', 'WARN-INHERITED-LAYOUT-REPLACED', 'WARN-KPI-ALIGN-OVERFLOW', 'WARN-KPI-INLINE-VARIANT-FALLBACK-TO-STACKED', 'WARN-KPI-LABEL-TRUNCATED', 'WARN-KPI-SUPPORT-TRUNCATED', 'WARN-LAYER-DATA-OUTSIDE-DOMAIN', 'WARN-LAYER-X-DOMAIN-PAINT-ORDER', 'WARN-LAYERED-CHART-SHARED-Y-AXIS-SCALE-MISMATCH', 'WARN-LAYOUT-MIN-EXCEEDS-HEIGHT', 'WARN-LEGEND-POSITION-WIDTH-FALLBACK', 'WARN-LEGEND-VALUES-UNRESOLVED', 'WARN-LIKELY-CURRENCY-OR-PERCENT-MISSING-FORMATTER', 'WARN-LOCAL-TIME-LABEL-EXPR-ON-BUCKETED-AXIS', 'WARN-LOW-TEXT-CONTRAST', 'WARN-MISSING-JOIN-PREDICATE', 'WARN-NORMALIZE-PERCENT-FORMAT-READS-RAW-VALUE', 'WARN-PALETTE-UNSUPPORTED', 'WARN-PARSE-ERROR', 'WARN-PIE-DOMINANT-SEGMENT', 'WARN-PIE-TOO-MANY-SEGMENTS', 'WARN-PIE-TOTAL-EXCEEDS-INNER-RADIUS', 'WARN-PLOT-HEIGHT-BELOW-MINIMUM', 'WARN-PLOT-WIDTH-BELOW-MINIMUM', 'WARN-POINT-MAP-NEGATIVE-SIZE-VALUES', 'WARN-POINT-MAP-OUT-OF-PROJECTION', 'WARN-QUERY-RESULT-TRUNCATED', 'WARN-QUERY-RETURNED-ZERO-ROWS', 'WARN-REAGGREGATION', 'WARN-REDUNDANT-AUTHORED-DEFAULT', 'WARN-REDUNDANT-AUTHORED-LABEL', 'WARN-REDUNDANT-ENCODING', 'WARN-RETIRED-IGNORE-CODE', 'WARN-SCHEMA-MIGRATED', 'WARN-SERIES-LABEL-TRUNCATED', 'WARN-SERIES-LABELS-REPEAT-WORD', 'WARN-SINGLE-CHART-REDUNDANT-TITLE', 'WARN-SPARK-LABEL-TRUNCATED', 'WARN-STATIC-PAGINATION-CAPPED', 'WARN-SUPPORT-TABLE-CELL-OVERFLOW', 'WARN-TABLE-COLUMNS-OVERFLOW', 'WARN-TABLE-CRAMPED', 'WARN-TABLE-PAGE-SQUEEZED', 'WARN-TABLE-TEXT-TRUNCATED', 'WARN-TEMPORAL-SINGLE-POINT', 'WARN-TOO-MANY-COLOR-CATEGORIES', 'WARN-TOO-MANY-X-CATEGORIES', 'WARN-UNREFERENCED-CHART', 'WARN-VALUE-LABELS-CROWD-WIDTH', 'WARN-WAREHOUSE-CHECK-UNAVAILABLE', 'WARN-WIDE-MEASURE-LABEL-COLLISION', 'WARN-Y-ENCODING-MOSTLY-NULL'] | Diagnostic codes to suppress for this query (e.g., ['WARN-MISSING-JOIN-PREDICATE', 'WARN-REAGGREGATION']). |
| `cache` | bool \| str \| [Cache](#cache) \| const: "forever" | Cache policy override for this query, e.g. cache: 5m: refines the policy inherited from the source and project scopes; cache: false opts out of result caching entirely. Queries with cache: false cannot be used as {{ queries.X.cache }} upstream references. |
| `formats` | dict[str, one of: 'compact', 'currency', 'currency_compact', 'currency_full', 'currency_whole', 'date_short', 'delta', 'email', 'id', 'integer', 'latitude', 'longitude', 'number', 'number_full', 'percent', 'percent_delta', 'percent_whole', 'rating', 'time_short', 'url', 'year' \| str] | How the query's columns print, as column: format name. A name is an engine format (`currency`, `percent`, `year`, ...) or one the board defines in `style.formats`; a d3 spec is rejected. Every chart showing the column uses the format unless it sets its own. |
| `incremental` | str \| const: false | Column used as the monotonic watermark for incremental refresh: the executor fetches only rows after the prior watermark and merges them with the cached result. `incremental: false` opts this query out of a board's incremental setting. Inherits from the board-level incremental setting when omitted. |
| `type` | const: "schema" | Never inferred; write `type: schema` explicitly. |
| `schema` | str | Which schema to inspect; lists every schema in the source if omitted (YAML key: schema). |
| `table` | str | Which table to inspect; lists the schema's tables if omitted. |
| `column` | str | Which column to profile; profiles every column in the table if omitted. |
| `fields` | list[str] | Project the result rows to exactly these keys, in this order: the schema-query counterpart of a SQL SELECT list. A projected key a row lacks yields null. Omit to return every key each row carries. |

<a id="queryref"></a>
## QueryRef
Cross-file query reference. Bare string is coerced automatically.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `ref` | str | Reference path: '&lt;file&gt;.queries.&lt;name&gt;'. May start with one or more '../' segments to reach a sibling directory. A bare string value is coerced automatically. |

<a id="barchart"></a>
## BarChart
Authored patch for bar and histogram charts; histogram adds automatic x binning.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `type` | enum: "bar", "histogram" | Selects the chart family. |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `field_labels` | dict[str, str] | Display text per query column, painted as written wherever the chart would otherwise derive text from that column's name: legend titles and entries, tooltip rows, axis titles. x_label/y_label and a layer's label win on their own surface. |
| `id` | str | Identifier for this chart. Generated from its `charts:` key, or, written inline, from its title (its `label:` on type: kpi), falling back to its position. |
| `notes` | str | Human-readable notes used by AI search. Emitted into the SVG DOM as a data-chart-notes attribute; never painted as visible pixels. |
| `query` | str \| [SqlQuery](#sqlquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [QueryRef](#queryref) | Where this chart reads its data: a named query, an inline query block, or a SQL string. |
| `link` | str \| const: false | Click-through URL template for drill-down links. Set to false to suppress this chart's automatic link on a board with auto_link: true; table column links are unaffected. |
| `visible` | bool \| str \| [SingleRowBoolProbe](#singlerowboolprobe) | Controls whether this layout item is rendered. |
| `warnings_ignore` | list[one of: 'WARN-ADJACENT-TEXT-ROWS', 'WARN-AREA-UNSTACKED-READS-AS-STACKED', 'WARN-AREA-ZERO-BASELINE-CROPPED', 'WARN-AXIS-ALIGN-DISCARDED', 'WARN-AXIS-LABEL-COLLISION', 'WARN-AXIS-TITLE-TRUNCATED', 'WARN-BAR-BAND-WIDTH-TOO-NARROW', 'WARN-BAR-GROUPED-SERIES-COINCIDE', 'WARN-CALLOUT-TEXT-TRUNCATED', 'WARN-CATEGORY-COLOR-PIN-UNSEEN', 'WARN-CHART-TITLE-TRUNCATED', 'WARN-COLUMN-CHECK-UNAVAILABLE', 'WARN-DBT-MANIFEST-MISSING', 'WARN-DBT-MODEL-COLUMNS-UNRESOLVED', 'WARN-DBT-QUERY-COLUMNS-INDETERMINATE', 'WARN-DEFAULTS-FILE-GIVEN-AS-BOARD', 'WARN-DOUBLE-HEADER', 'WARN-DUAL-AXIS-COMPETING-SCALES', 'WARN-ENDPOINT-LABEL-GAP-OVERFLOW', 'WARN-ENDPOINT-LABEL-RAIL-OVERFLOW', 'WARN-ENDPOINT-LABEL-RAIL-TIED', 'WARN-FACET-PANEL-WIDTH-BELOW-MINIMUM', 'WARN-FANOUT-RISK', 'WARN-FLAT-COLS-UNSIZED-OVERFLOW', 'WARN-FORMAT-UNUSED-NAME', 'WARN-H1-BODY-NO-TITLE', 'WARN-HTML-POLICY-CAPPED', 'WARN-INHERITED-LAYOUT-REPLACED', 'WARN-KPI-ALIGN-OVERFLOW', 'WARN-KPI-INLINE-VARIANT-FALLBACK-TO-STACKED', 'WARN-KPI-LABEL-TRUNCATED', 'WARN-KPI-SUPPORT-TRUNCATED', 'WARN-LAYER-DATA-OUTSIDE-DOMAIN', 'WARN-LAYER-X-DOMAIN-PAINT-ORDER', 'WARN-LAYERED-CHART-SHARED-Y-AXIS-SCALE-MISMATCH', 'WARN-LAYOUT-MIN-EXCEEDS-HEIGHT', 'WARN-LEGEND-POSITION-WIDTH-FALLBACK', 'WARN-LEGEND-VALUES-UNRESOLVED', 'WARN-LIKELY-CURRENCY-OR-PERCENT-MISSING-FORMATTER', 'WARN-LOCAL-TIME-LABEL-EXPR-ON-BUCKETED-AXIS', 'WARN-LOW-TEXT-CONTRAST', 'WARN-NORMALIZE-PERCENT-FORMAT-READS-RAW-VALUE', 'WARN-PALETTE-UNSUPPORTED', 'WARN-PIE-DOMINANT-SEGMENT', 'WARN-PIE-TOO-MANY-SEGMENTS', 'WARN-PIE-TOTAL-EXCEEDS-INNER-RADIUS', 'WARN-PLOT-HEIGHT-BELOW-MINIMUM', 'WARN-PLOT-WIDTH-BELOW-MINIMUM', 'WARN-POINT-MAP-NEGATIVE-SIZE-VALUES', 'WARN-POINT-MAP-OUT-OF-PROJECTION', 'WARN-QUERY-RESULT-TRUNCATED', 'WARN-QUERY-RETURNED-ZERO-ROWS', 'WARN-REDUNDANT-AUTHORED-DEFAULT', 'WARN-REDUNDANT-AUTHORED-LABEL', 'WARN-REDUNDANT-ENCODING', 'WARN-RETIRED-IGNORE-CODE', 'WARN-SCHEMA-MIGRATED', 'WARN-SERIES-LABEL-TRUNCATED', 'WARN-SERIES-LABELS-REPEAT-WORD', 'WARN-SINGLE-CHART-REDUNDANT-TITLE', 'WARN-SPARK-LABEL-TRUNCATED', 'WARN-STATIC-PAGINATION-CAPPED', 'WARN-SUPPORT-TABLE-CELL-OVERFLOW', 'WARN-TABLE-COLUMNS-OVERFLOW', 'WARN-TABLE-CRAMPED', 'WARN-TABLE-PAGE-SQUEEZED', 'WARN-TABLE-TEXT-TRUNCATED', 'WARN-TEMPORAL-SINGLE-POINT', 'WARN-TOO-MANY-COLOR-CATEGORIES', 'WARN-TOO-MANY-X-CATEGORIES', 'WARN-UNREFERENCED-CHART', 'WARN-VALUE-LABELS-CROWD-WIDTH', 'WARN-WAREHOUSE-CHECK-UNAVAILABLE', 'WARN-WIDE-MEASURE-LABEL-COLLISION', 'WARN-Y-ENCODING-MOSTLY-NULL'] | Codes of render warnings to suppress for this chart. Query-domain codes such as WARN-REAGGREGATION go in `queries.&lt;name&gt;.ignore` instead. |
| `title` | str | Heading naming what the chart shows. Rejected on type: kpi. |
| `subtitle` | str | Supporting text beneath the chart title. |
| `x` | str | X-axis column name from the query result. |
| `y` | str \| list[str] | Y-axis column name(s). Accepts a single column or list for multi-series charts. |
| `x_label` | str | Title for the X axis, replacing the one derived from the x column's name. |
| `y_label` | str | Title for the Y axis, replacing the one the chart derives on its own. |
| `color` | str | 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` | [ChartSort](#chartsort) | Which column orders the marks, and in which direction (asc/desc). |
| `multiples` | [MultiplesConfig](#multiplesconfig) | Partition this chart into small multiples by a `rows` column (vertical stack), a `columns` column (side by side), or both (grid). Panels share one measure scale by default. |
| `support_table` | list[str \| ChartSupportTableSource \| ChartSupportTableAggregate \| ChartSupportTablePerSeries] \| [ChartSupportTable](#chartsupporttable) | Optional mini data-grid attached below/above the chart. |
| `height` | int \| float | Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Valid on cartesian chart families (area, bar, heatmap, histogram, line, scatter), pie/donut, and geo families (geoshape, map, point_map, bubble_map). Other chart families use renderer-owned or layout-owned sizing contracts. |
| `width` | int \| float | Chart width in pixels. Positive number only. In a rows layout the chart's slot pins to this width (a fixed footprint, capped at the row). In cols and grid layouts it contributes to the dashboard's intrinsic width measurement when the board has no width of its own, and the layout still owns the final slot. Valid on cartesian chart families (area, bar, heatmap, histogram, line, scatter), pie/donut, and geo families (geoshape, map, point_map, bubble_map). Other chart families use renderer-owned or layout-owned sizing contracts. |
| `y_start` | str | Column each bar starts from, so it runs from y_start to y instead of from zero. Same kind as y: both numeric, or both dates. Not with stacking. |
| `style` | [BarChartStyle](#barchartstyle) | Appearance overrides for this chart alone. |
| `layers` | list[[BarLayer](#barlayer) \| [LineLayer](#linelayer) \| [AreaLayer](#arealayer) \| [ScatterLayer](#scatterlayer)] | Extra marks drawn over this chart, each with its own type and columns. Not supported when type: histogram: a histogram bins x and aggregates to a count, so there is no shared y measure for an overlay to plot against. |

<a id="linechart"></a>
## LineChart
Authored patch for line charts.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `type` | const: "line" |  |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `field_labels` | dict[str, str] | Display text per query column, painted as written wherever the chart would otherwise derive text from that column's name: legend titles and entries, tooltip rows, axis titles. x_label/y_label and a layer's label win on their own surface. |
| `id` | str | Identifier for this chart. Generated from its `charts:` key, or, written inline, from its title (its `label:` on type: kpi), falling back to its position. |
| `notes` | str | Human-readable notes used by AI search. Emitted into the SVG DOM as a data-chart-notes attribute; never painted as visible pixels. |
| `query` | str \| [SqlQuery](#sqlquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [QueryRef](#queryref) | Where this chart reads its data: a named query, an inline query block, or a SQL string. |
| `link` | str \| const: false | Click-through URL template for drill-down links. Set to false to suppress this chart's automatic link on a board with auto_link: true; table column links are unaffected. |
| `visible` | bool \| str \| [SingleRowBoolProbe](#singlerowboolprobe) | Controls whether this layout item is rendered. |
| `warnings_ignore` | list[one of: 'WARN-ADJACENT-TEXT-ROWS', 'WARN-AREA-UNSTACKED-READS-AS-STACKED', 'WARN-AREA-ZERO-BASELINE-CROPPED', 'WARN-AXIS-ALIGN-DISCARDED', 'WARN-AXIS-LABEL-COLLISION', 'WARN-AXIS-TITLE-TRUNCATED', 'WARN-BAR-BAND-WIDTH-TOO-NARROW', 'WARN-BAR-GROUPED-SERIES-COINCIDE', 'WARN-CALLOUT-TEXT-TRUNCATED', 'WARN-CATEGORY-COLOR-PIN-UNSEEN', 'WARN-CHART-TITLE-TRUNCATED', 'WARN-COLUMN-CHECK-UNAVAILABLE', 'WARN-DBT-MANIFEST-MISSING', 'WARN-DBT-MODEL-COLUMNS-UNRESOLVED', 'WARN-DBT-QUERY-COLUMNS-INDETERMINATE', 'WARN-DEFAULTS-FILE-GIVEN-AS-BOARD', 'WARN-DOUBLE-HEADER', 'WARN-DUAL-AXIS-COMPETING-SCALES', 'WARN-ENDPOINT-LABEL-GAP-OVERFLOW', 'WARN-ENDPOINT-LABEL-RAIL-OVERFLOW', 'WARN-ENDPOINT-LABEL-RAIL-TIED', 'WARN-FACET-PANEL-WIDTH-BELOW-MINIMUM', 'WARN-FANOUT-RISK', 'WARN-FLAT-COLS-UNSIZED-OVERFLOW', 'WARN-FORMAT-UNUSED-NAME', 'WARN-H1-BODY-NO-TITLE', 'WARN-HTML-POLICY-CAPPED', 'WARN-INHERITED-LAYOUT-REPLACED', 'WARN-KPI-ALIGN-OVERFLOW', 'WARN-KPI-INLINE-VARIANT-FALLBACK-TO-STACKED', 'WARN-KPI-LABEL-TRUNCATED', 'WARN-KPI-SUPPORT-TRUNCATED', 'WARN-LAYER-DATA-OUTSIDE-DOMAIN', 'WARN-LAYER-X-DOMAIN-PAINT-ORDER', 'WARN-LAYERED-CHART-SHARED-Y-AXIS-SCALE-MISMATCH', 'WARN-LAYOUT-MIN-EXCEEDS-HEIGHT', 'WARN-LEGEND-POSITION-WIDTH-FALLBACK', 'WARN-LEGEND-VALUES-UNRESOLVED', 'WARN-LIKELY-CURRENCY-OR-PERCENT-MISSING-FORMATTER', 'WARN-LOCAL-TIME-LABEL-EXPR-ON-BUCKETED-AXIS', 'WARN-LOW-TEXT-CONTRAST', 'WARN-NORMALIZE-PERCENT-FORMAT-READS-RAW-VALUE', 'WARN-PALETTE-UNSUPPORTED', 'WARN-PIE-DOMINANT-SEGMENT', 'WARN-PIE-TOO-MANY-SEGMENTS', 'WARN-PIE-TOTAL-EXCEEDS-INNER-RADIUS', 'WARN-PLOT-HEIGHT-BELOW-MINIMUM', 'WARN-PLOT-WIDTH-BELOW-MINIMUM', 'WARN-POINT-MAP-NEGATIVE-SIZE-VALUES', 'WARN-POINT-MAP-OUT-OF-PROJECTION', 'WARN-QUERY-RESULT-TRUNCATED', 'WARN-QUERY-RETURNED-ZERO-ROWS', 'WARN-REDUNDANT-AUTHORED-DEFAULT', 'WARN-REDUNDANT-AUTHORED-LABEL', 'WARN-REDUNDANT-ENCODING', 'WARN-RETIRED-IGNORE-CODE', 'WARN-SCHEMA-MIGRATED', 'WARN-SERIES-LABEL-TRUNCATED', 'WARN-SERIES-LABELS-REPEAT-WORD', 'WARN-SINGLE-CHART-REDUNDANT-TITLE', 'WARN-SPARK-LABEL-TRUNCATED', 'WARN-STATIC-PAGINATION-CAPPED', 'WARN-SUPPORT-TABLE-CELL-OVERFLOW', 'WARN-TABLE-COLUMNS-OVERFLOW', 'WARN-TABLE-CRAMPED', 'WARN-TABLE-PAGE-SQUEEZED', 'WARN-TABLE-TEXT-TRUNCATED', 'WARN-TEMPORAL-SINGLE-POINT', 'WARN-TOO-MANY-COLOR-CATEGORIES', 'WARN-TOO-MANY-X-CATEGORIES', 'WARN-UNREFERENCED-CHART', 'WARN-VALUE-LABELS-CROWD-WIDTH', 'WARN-WAREHOUSE-CHECK-UNAVAILABLE', 'WARN-WIDE-MEASURE-LABEL-COLLISION', 'WARN-Y-ENCODING-MOSTLY-NULL'] | Codes of render warnings to suppress for this chart. Query-domain codes such as WARN-REAGGREGATION go in `queries.&lt;name&gt;.ignore` instead. |
| `title` | str | Heading naming what the chart shows. Rejected on type: kpi. |
| `subtitle` | str | Supporting text beneath the chart title. |
| `x` | str | X-axis column name from the query result. |
| `y` | str \| list[str] | Y-axis column name(s). Accepts a single column or list for multi-series charts. |
| `x_label` | str | Title for the X axis, replacing the one derived from the x column's name. |
| `y_label` | str | Title for the Y axis, replacing the one the chart derives on its own. |
| `color` | str | 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` | [ChartSort](#chartsort) | Which column orders the marks, and in which direction (asc/desc). |
| `multiples` | [MultiplesConfig](#multiplesconfig) | Partition this chart into small multiples by a `rows` column (vertical stack), a `columns` column (side by side), or both (grid). Panels share one measure scale by default. |
| `support_table` | list[str \| ChartSupportTableSource \| ChartSupportTableAggregate \| ChartSupportTablePerSeries] \| [ChartSupportTable](#chartsupporttable) | Optional mini data-grid attached below/above the chart. |
| `height` | int \| float | Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Valid on cartesian chart families (area, bar, heatmap, histogram, line, scatter), pie/donut, and geo families (geoshape, map, point_map, bubble_map). Other chart families use renderer-owned or layout-owned sizing contracts. |
| `width` | int \| float | Chart width in pixels. Positive number only. In a rows layout the chart's slot pins to this width (a fixed footprint, capped at the row). In cols and grid layouts it contributes to the dashboard's intrinsic width measurement when the board has no width of its own, and the layout still owns the final slot. Valid on cartesian chart families (area, bar, heatmap, histogram, line, scatter), pie/donut, and geo families (geoshape, map, point_map, bubble_map). Other chart families use renderer-owned or layout-owned sizing contracts. |
| `style` | [LineChartStyle](#linechartstyle) | Appearance overrides for this chart alone. |
| `layers` | list[[BarLayer](#barlayer) \| [LineLayer](#linelayer) \| [AreaLayer](#arealayer) \| [ScatterLayer](#scatterlayer)] | Extra marks drawn over this chart, each with its own type and columns. |

<a id="areachart"></a>
## AreaChart
Authored patch for area charts.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `type` | const: "area" |  |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `field_labels` | dict[str, str] | Display text per query column, painted as written wherever the chart would otherwise derive text from that column's name: legend titles and entries, tooltip rows, axis titles. x_label/y_label and a layer's label win on their own surface. |
| `id` | str | Identifier for this chart. Generated from its `charts:` key, or, written inline, from its title (its `label:` on type: kpi), falling back to its position. |
| `notes` | str | Human-readable notes used by AI search. Emitted into the SVG DOM as a data-chart-notes attribute; never painted as visible pixels. |
| `query` | str \| [SqlQuery](#sqlquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [QueryRef](#queryref) | Where this chart reads its data: a named query, an inline query block, or a SQL string. |
| `link` | str \| const: false | Click-through URL template for drill-down links. Set to false to suppress this chart's automatic link on a board with auto_link: true; table column links are unaffected. |
| `visible` | bool \| str \| [SingleRowBoolProbe](#singlerowboolprobe) | Controls whether this layout item is rendered. |
| `warnings_ignore` | list[one of: 'WARN-ADJACENT-TEXT-ROWS', 'WARN-AREA-UNSTACKED-READS-AS-STACKED', 'WARN-AREA-ZERO-BASELINE-CROPPED', 'WARN-AXIS-ALIGN-DISCARDED', 'WARN-AXIS-LABEL-COLLISION', 'WARN-AXIS-TITLE-TRUNCATED', 'WARN-BAR-BAND-WIDTH-TOO-NARROW', 'WARN-BAR-GROUPED-SERIES-COINCIDE', 'WARN-CALLOUT-TEXT-TRUNCATED', 'WARN-CATEGORY-COLOR-PIN-UNSEEN', 'WARN-CHART-TITLE-TRUNCATED', 'WARN-COLUMN-CHECK-UNAVAILABLE', 'WARN-DBT-MANIFEST-MISSING', 'WARN-DBT-MODEL-COLUMNS-UNRESOLVED', 'WARN-DBT-QUERY-COLUMNS-INDETERMINATE', 'WARN-DEFAULTS-FILE-GIVEN-AS-BOARD', 'WARN-DOUBLE-HEADER', 'WARN-DUAL-AXIS-COMPETING-SCALES', 'WARN-ENDPOINT-LABEL-GAP-OVERFLOW', 'WARN-ENDPOINT-LABEL-RAIL-OVERFLOW', 'WARN-ENDPOINT-LABEL-RAIL-TIED', 'WARN-FACET-PANEL-WIDTH-BELOW-MINIMUM', 'WARN-FANOUT-RISK', 'WARN-FLAT-COLS-UNSIZED-OVERFLOW', 'WARN-FORMAT-UNUSED-NAME', 'WARN-H1-BODY-NO-TITLE', 'WARN-HTML-POLICY-CAPPED', 'WARN-INHERITED-LAYOUT-REPLACED', 'WARN-KPI-ALIGN-OVERFLOW', 'WARN-KPI-INLINE-VARIANT-FALLBACK-TO-STACKED', 'WARN-KPI-LABEL-TRUNCATED', 'WARN-KPI-SUPPORT-TRUNCATED', 'WARN-LAYER-DATA-OUTSIDE-DOMAIN', 'WARN-LAYER-X-DOMAIN-PAINT-ORDER', 'WARN-LAYERED-CHART-SHARED-Y-AXIS-SCALE-MISMATCH', 'WARN-LAYOUT-MIN-EXCEEDS-HEIGHT', 'WARN-LEGEND-POSITION-WIDTH-FALLBACK', 'WARN-LEGEND-VALUES-UNRESOLVED', 'WARN-LIKELY-CURRENCY-OR-PERCENT-MISSING-FORMATTER', 'WARN-LOCAL-TIME-LABEL-EXPR-ON-BUCKETED-AXIS', 'WARN-LOW-TEXT-CONTRAST', 'WARN-NORMALIZE-PERCENT-FORMAT-READS-RAW-VALUE', 'WARN-PALETTE-UNSUPPORTED', 'WARN-PIE-DOMINANT-SEGMENT', 'WARN-PIE-TOO-MANY-SEGMENTS', 'WARN-PIE-TOTAL-EXCEEDS-INNER-RADIUS', 'WARN-PLOT-HEIGHT-BELOW-MINIMUM', 'WARN-PLOT-WIDTH-BELOW-MINIMUM', 'WARN-POINT-MAP-NEGATIVE-SIZE-VALUES', 'WARN-POINT-MAP-OUT-OF-PROJECTION', 'WARN-QUERY-RESULT-TRUNCATED', 'WARN-QUERY-RETURNED-ZERO-ROWS', 'WARN-REDUNDANT-AUTHORED-DEFAULT', 'WARN-REDUNDANT-AUTHORED-LABEL', 'WARN-REDUNDANT-ENCODING', 'WARN-RETIRED-IGNORE-CODE', 'WARN-SCHEMA-MIGRATED', 'WARN-SERIES-LABEL-TRUNCATED', 'WARN-SERIES-LABELS-REPEAT-WORD', 'WARN-SINGLE-CHART-REDUNDANT-TITLE', 'WARN-SPARK-LABEL-TRUNCATED', 'WARN-STATIC-PAGINATION-CAPPED', 'WARN-SUPPORT-TABLE-CELL-OVERFLOW', 'WARN-TABLE-COLUMNS-OVERFLOW', 'WARN-TABLE-CRAMPED', 'WARN-TABLE-PAGE-SQUEEZED', 'WARN-TABLE-TEXT-TRUNCATED', 'WARN-TEMPORAL-SINGLE-POINT', 'WARN-TOO-MANY-COLOR-CATEGORIES', 'WARN-TOO-MANY-X-CATEGORIES', 'WARN-UNREFERENCED-CHART', 'WARN-VALUE-LABELS-CROWD-WIDTH', 'WARN-WAREHOUSE-CHECK-UNAVAILABLE', 'WARN-WIDE-MEASURE-LABEL-COLLISION', 'WARN-Y-ENCODING-MOSTLY-NULL'] | Codes of render warnings to suppress for this chart. Query-domain codes such as WARN-REAGGREGATION go in `queries.&lt;name&gt;.ignore` instead. |
| `title` | str | Heading naming what the chart shows. Rejected on type: kpi. |
| `subtitle` | str | Supporting text beneath the chart title. |
| `x` | str | X-axis column name from the query result. |
| `y` | str \| list[str] | Y-axis column name(s). Accepts a single column or list for multi-series charts. |
| `x_label` | str | Title for the X axis, replacing the one derived from the x column's name. |
| `y_label` | str | Title for the Y axis, replacing the one the chart derives on its own. |
| `color` | str | 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` | [ChartSort](#chartsort) | Which column orders the marks, and in which direction (asc/desc). |
| `multiples` | [MultiplesConfig](#multiplesconfig) | Partition this chart into small multiples by a `rows` column (vertical stack), a `columns` column (side by side), or both (grid). Panels share one measure scale by default. |
| `support_table` | list[str \| ChartSupportTableSource \| ChartSupportTableAggregate \| ChartSupportTablePerSeries] \| [ChartSupportTable](#chartsupporttable) | Optional mini data-grid attached below/above the chart. |
| `height` | int \| float | Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Valid on cartesian chart families (area, bar, heatmap, histogram, line, scatter), pie/donut, and geo families (geoshape, map, point_map, bubble_map). Other chart families use renderer-owned or layout-owned sizing contracts. |
| `width` | int \| float | Chart width in pixels. Positive number only. In a rows layout the chart's slot pins to this width (a fixed footprint, capped at the row). In cols and grid layouts it contributes to the dashboard's intrinsic width measurement when the board has no width of its own, and the layout still owns the final slot. Valid on cartesian chart families (area, bar, heatmap, histogram, line, scatter), pie/donut, and geo families (geoshape, map, point_map, bubble_map). Other chart families use renderer-owned or layout-owned sizing contracts. |
| `style` | [AreaChartStyle](#areachartstyle) | Appearance overrides for this chart alone. |
| `layers` | list[[BarLayer](#barlayer) \| [LineLayer](#linelayer) \| [AreaLayer](#arealayer) \| [ScatterLayer](#scatterlayer)] | Extra marks drawn over this chart, each with its own type and columns. |

<a id="scatterchart"></a>
## ScatterChart
Authored patch for scatter charts.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `type` | const: "scatter" |  |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `field_labels` | dict[str, str] | Display text per query column, painted as written wherever the chart would otherwise derive text from that column's name: legend titles and entries, tooltip rows, axis titles. x_label/y_label and a layer's label win on their own surface. |
| `id` | str | Identifier for this chart. Generated from its `charts:` key, or, written inline, from its title (its `label:` on type: kpi), falling back to its position. |
| `notes` | str | Human-readable notes used by AI search. Emitted into the SVG DOM as a data-chart-notes attribute; never painted as visible pixels. |
| `query` | str \| [SqlQuery](#sqlquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [QueryRef](#queryref) | Where this chart reads its data: a named query, an inline query block, or a SQL string. |
| `link` | str \| const: false | Click-through URL template for drill-down links. Set to false to suppress this chart's automatic link on a board with auto_link: true; table column links are unaffected. |
| `visible` | bool \| str \| [SingleRowBoolProbe](#singlerowboolprobe) | Controls whether this layout item is rendered. |
| `warnings_ignore` | list[one of: 'WARN-ADJACENT-TEXT-ROWS', 'WARN-AREA-UNSTACKED-READS-AS-STACKED', 'WARN-AREA-ZERO-BASELINE-CROPPED', 'WARN-AXIS-ALIGN-DISCARDED', 'WARN-AXIS-LABEL-COLLISION', 'WARN-AXIS-TITLE-TRUNCATED', 'WARN-BAR-BAND-WIDTH-TOO-NARROW', 'WARN-BAR-GROUPED-SERIES-COINCIDE', 'WARN-CALLOUT-TEXT-TRUNCATED', 'WARN-CATEGORY-COLOR-PIN-UNSEEN', 'WARN-CHART-TITLE-TRUNCATED', 'WARN-COLUMN-CHECK-UNAVAILABLE', 'WARN-DBT-MANIFEST-MISSING', 'WARN-DBT-MODEL-COLUMNS-UNRESOLVED', 'WARN-DBT-QUERY-COLUMNS-INDETERMINATE', 'WARN-DEFAULTS-FILE-GIVEN-AS-BOARD', 'WARN-DOUBLE-HEADER', 'WARN-DUAL-AXIS-COMPETING-SCALES', 'WARN-ENDPOINT-LABEL-GAP-OVERFLOW', 'WARN-ENDPOINT-LABEL-RAIL-OVERFLOW', 'WARN-ENDPOINT-LABEL-RAIL-TIED', 'WARN-FACET-PANEL-WIDTH-BELOW-MINIMUM', 'WARN-FANOUT-RISK', 'WARN-FLAT-COLS-UNSIZED-OVERFLOW', 'WARN-FORMAT-UNUSED-NAME', 'WARN-H1-BODY-NO-TITLE', 'WARN-HTML-POLICY-CAPPED', 'WARN-INHERITED-LAYOUT-REPLACED', 'WARN-KPI-ALIGN-OVERFLOW', 'WARN-KPI-INLINE-VARIANT-FALLBACK-TO-STACKED', 'WARN-KPI-LABEL-TRUNCATED', 'WARN-KPI-SUPPORT-TRUNCATED', 'WARN-LAYER-DATA-OUTSIDE-DOMAIN', 'WARN-LAYER-X-DOMAIN-PAINT-ORDER', 'WARN-LAYERED-CHART-SHARED-Y-AXIS-SCALE-MISMATCH', 'WARN-LAYOUT-MIN-EXCEEDS-HEIGHT', 'WARN-LEGEND-POSITION-WIDTH-FALLBACK', 'WARN-LEGEND-VALUES-UNRESOLVED', 'WARN-LIKELY-CURRENCY-OR-PERCENT-MISSING-FORMATTER', 'WARN-LOCAL-TIME-LABEL-EXPR-ON-BUCKETED-AXIS', 'WARN-LOW-TEXT-CONTRAST', 'WARN-NORMALIZE-PERCENT-FORMAT-READS-RAW-VALUE', 'WARN-PALETTE-UNSUPPORTED', 'WARN-PIE-DOMINANT-SEGMENT', 'WARN-PIE-TOO-MANY-SEGMENTS', 'WARN-PIE-TOTAL-EXCEEDS-INNER-RADIUS', 'WARN-PLOT-HEIGHT-BELOW-MINIMUM', 'WARN-PLOT-WIDTH-BELOW-MINIMUM', 'WARN-POINT-MAP-NEGATIVE-SIZE-VALUES', 'WARN-POINT-MAP-OUT-OF-PROJECTION', 'WARN-QUERY-RESULT-TRUNCATED', 'WARN-QUERY-RETURNED-ZERO-ROWS', 'WARN-REDUNDANT-AUTHORED-DEFAULT', 'WARN-REDUNDANT-AUTHORED-LABEL', 'WARN-REDUNDANT-ENCODING', 'WARN-RETIRED-IGNORE-CODE', 'WARN-SCHEMA-MIGRATED', 'WARN-SERIES-LABEL-TRUNCATED', 'WARN-SERIES-LABELS-REPEAT-WORD', 'WARN-SINGLE-CHART-REDUNDANT-TITLE', 'WARN-SPARK-LABEL-TRUNCATED', 'WARN-STATIC-PAGINATION-CAPPED', 'WARN-SUPPORT-TABLE-CELL-OVERFLOW', 'WARN-TABLE-COLUMNS-OVERFLOW', 'WARN-TABLE-CRAMPED', 'WARN-TABLE-PAGE-SQUEEZED', 'WARN-TABLE-TEXT-TRUNCATED', 'WARN-TEMPORAL-SINGLE-POINT', 'WARN-TOO-MANY-COLOR-CATEGORIES', 'WARN-TOO-MANY-X-CATEGORIES', 'WARN-UNREFERENCED-CHART', 'WARN-VALUE-LABELS-CROWD-WIDTH', 'WARN-WAREHOUSE-CHECK-UNAVAILABLE', 'WARN-WIDE-MEASURE-LABEL-COLLISION', 'WARN-Y-ENCODING-MOSTLY-NULL'] | Codes of render warnings to suppress for this chart. Query-domain codes such as WARN-REAGGREGATION go in `queries.&lt;name&gt;.ignore` instead. |
| `title` | str | Heading naming what the chart shows. Rejected on type: kpi. |
| `subtitle` | str | Supporting text beneath the chart title. |
| `x` | str | X-axis column name from the query result. |
| `y` | str \| list[str] | Y-axis column name(s). Accepts a single column or list for multi-series charts. |
| `x_label` | str | Title for the X axis, replacing the one derived from the x column's name. |
| `y_label` | str | Title for the Y axis, replacing the one the chart derives on its own. |
| `color` | str | 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` | [ChartSort](#chartsort) | Which column orders the marks, and in which direction (asc/desc). |
| `multiples` | [MultiplesConfig](#multiplesconfig) | Partition this chart into small multiples by a `rows` column (vertical stack), a `columns` column (side by side), or both (grid). Panels share one measure scale by default. |
| `support_table` | list[str \| ChartSupportTableSource \| ChartSupportTableAggregate \| ChartSupportTablePerSeries] \| [ChartSupportTable](#chartsupporttable) | Optional mini data-grid attached below/above the chart. |
| `height` | int \| float | Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Valid on cartesian chart families (area, bar, heatmap, histogram, line, scatter), pie/donut, and geo families (geoshape, map, point_map, bubble_map). Other chart families use renderer-owned or layout-owned sizing contracts. |
| `width` | int \| float | Chart width in pixels. Positive number only. In a rows layout the chart's slot pins to this width (a fixed footprint, capped at the row). In cols and grid layouts it contributes to the dashboard's intrinsic width measurement when the board has no width of its own, and the layout still owns the final slot. Valid on cartesian chart families (area, bar, heatmap, histogram, line, scatter), pie/donut, and geo families (geoshape, map, point_map, bubble_map). Other chart families use renderer-owned or layout-owned sizing contracts. |
| `size` | str | Column used to size-encode data points (quantitative). |
| `shape` | str | Column used to shape-encode data points (categorical). |
| `style` | [ScatterChartStyle](#scatterchartstyle) | Appearance overrides for this chart alone. |
| `layers` | list[[BarLayer](#barlayer) \| [LineLayer](#linelayer) \| [AreaLayer](#arealayer) \| [ScatterLayer](#scatterlayer)] | Extra marks drawn over this chart, each with its own type and columns. |

<a id="heatmapchart"></a>
## HeatmapChart
Authored patch for heatmap charts.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `type` | const: "heatmap" |  |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `field_labels` | dict[str, str] | Display text per query column, painted as written wherever the chart would otherwise derive text from that column's name: legend titles and entries, tooltip rows, axis titles. x_label/y_label and a layer's label win on their own surface. |
| `id` | str | Identifier for this chart. Generated from its `charts:` key, or, written inline, from its title (its `label:` on type: kpi), falling back to its position. |
| `notes` | str | Human-readable notes used by AI search. Emitted into the SVG DOM as a data-chart-notes attribute; never painted as visible pixels. |
| `query` | str \| [SqlQuery](#sqlquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [QueryRef](#queryref) | Where this chart reads its data: a named query, an inline query block, or a SQL string. |
| `link` | str \| const: false | Click-through URL template for drill-down links. Set to false to suppress this chart's automatic link on a board with auto_link: true; table column links are unaffected. |
| `visible` | bool \| str \| [SingleRowBoolProbe](#singlerowboolprobe) | Controls whether this layout item is rendered. |
| `warnings_ignore` | list[one of: 'WARN-ADJACENT-TEXT-ROWS', 'WARN-AREA-UNSTACKED-READS-AS-STACKED', 'WARN-AREA-ZERO-BASELINE-CROPPED', 'WARN-AXIS-ALIGN-DISCARDED', 'WARN-AXIS-LABEL-COLLISION', 'WARN-AXIS-TITLE-TRUNCATED', 'WARN-BAR-BAND-WIDTH-TOO-NARROW', 'WARN-BAR-GROUPED-SERIES-COINCIDE', 'WARN-CALLOUT-TEXT-TRUNCATED', 'WARN-CATEGORY-COLOR-PIN-UNSEEN', 'WARN-CHART-TITLE-TRUNCATED', 'WARN-COLUMN-CHECK-UNAVAILABLE', 'WARN-DBT-MANIFEST-MISSING', 'WARN-DBT-MODEL-COLUMNS-UNRESOLVED', 'WARN-DBT-QUERY-COLUMNS-INDETERMINATE', 'WARN-DEFAULTS-FILE-GIVEN-AS-BOARD', 'WARN-DOUBLE-HEADER', 'WARN-DUAL-AXIS-COMPETING-SCALES', 'WARN-ENDPOINT-LABEL-GAP-OVERFLOW', 'WARN-ENDPOINT-LABEL-RAIL-OVERFLOW', 'WARN-ENDPOINT-LABEL-RAIL-TIED', 'WARN-FACET-PANEL-WIDTH-BELOW-MINIMUM', 'WARN-FANOUT-RISK', 'WARN-FLAT-COLS-UNSIZED-OVERFLOW', 'WARN-FORMAT-UNUSED-NAME', 'WARN-H1-BODY-NO-TITLE', 'WARN-HTML-POLICY-CAPPED', 'WARN-INHERITED-LAYOUT-REPLACED', 'WARN-KPI-ALIGN-OVERFLOW', 'WARN-KPI-INLINE-VARIANT-FALLBACK-TO-STACKED', 'WARN-KPI-LABEL-TRUNCATED', 'WARN-KPI-SUPPORT-TRUNCATED', 'WARN-LAYER-DATA-OUTSIDE-DOMAIN', 'WARN-LAYER-X-DOMAIN-PAINT-ORDER', 'WARN-LAYERED-CHART-SHARED-Y-AXIS-SCALE-MISMATCH', 'WARN-LAYOUT-MIN-EXCEEDS-HEIGHT', 'WARN-LEGEND-POSITION-WIDTH-FALLBACK', 'WARN-LEGEND-VALUES-UNRESOLVED', 'WARN-LIKELY-CURRENCY-OR-PERCENT-MISSING-FORMATTER', 'WARN-LOCAL-TIME-LABEL-EXPR-ON-BUCKETED-AXIS', 'WARN-LOW-TEXT-CONTRAST', 'WARN-NORMALIZE-PERCENT-FORMAT-READS-RAW-VALUE', 'WARN-PALETTE-UNSUPPORTED', 'WARN-PIE-DOMINANT-SEGMENT', 'WARN-PIE-TOO-MANY-SEGMENTS', 'WARN-PIE-TOTAL-EXCEEDS-INNER-RADIUS', 'WARN-PLOT-HEIGHT-BELOW-MINIMUM', 'WARN-PLOT-WIDTH-BELOW-MINIMUM', 'WARN-POINT-MAP-NEGATIVE-SIZE-VALUES', 'WARN-POINT-MAP-OUT-OF-PROJECTION', 'WARN-QUERY-RESULT-TRUNCATED', 'WARN-QUERY-RETURNED-ZERO-ROWS', 'WARN-REDUNDANT-AUTHORED-DEFAULT', 'WARN-REDUNDANT-AUTHORED-LABEL', 'WARN-REDUNDANT-ENCODING', 'WARN-RETIRED-IGNORE-CODE', 'WARN-SCHEMA-MIGRATED', 'WARN-SERIES-LABEL-TRUNCATED', 'WARN-SERIES-LABELS-REPEAT-WORD', 'WARN-SINGLE-CHART-REDUNDANT-TITLE', 'WARN-SPARK-LABEL-TRUNCATED', 'WARN-STATIC-PAGINATION-CAPPED', 'WARN-SUPPORT-TABLE-CELL-OVERFLOW', 'WARN-TABLE-COLUMNS-OVERFLOW', 'WARN-TABLE-CRAMPED', 'WARN-TABLE-PAGE-SQUEEZED', 'WARN-TABLE-TEXT-TRUNCATED', 'WARN-TEMPORAL-SINGLE-POINT', 'WARN-TOO-MANY-COLOR-CATEGORIES', 'WARN-TOO-MANY-X-CATEGORIES', 'WARN-UNREFERENCED-CHART', 'WARN-VALUE-LABELS-CROWD-WIDTH', 'WARN-WAREHOUSE-CHECK-UNAVAILABLE', 'WARN-WIDE-MEASURE-LABEL-COLLISION', 'WARN-Y-ENCODING-MOSTLY-NULL'] | Codes of render warnings to suppress for this chart. Query-domain codes such as WARN-REAGGREGATION go in `queries.&lt;name&gt;.ignore` instead. |
| `title` | str | Heading naming what the chart shows. Rejected on type: kpi. |
| `subtitle` | str | Supporting text beneath the chart title. |
| `x` | str | X-axis column name from the query result. |
| `y` | str \| list[str] | Y-axis column name(s). Accepts a single column or list for multi-series charts. |
| `x_label` | str | Title for the X axis, replacing the one derived from the x column's name. |
| `y_label` | str | Title for the Y axis, replacing the one the chart derives on its own. |
| `color` | str | 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` | [ChartSort](#chartsort) | Which column orders the marks, and in which direction (asc/desc). |
| `multiples` | [MultiplesConfig](#multiplesconfig) | Partition this chart into small multiples by a `rows` column (vertical stack), a `columns` column (side by side), or both (grid). Panels share one measure scale by default. |
| `support_table` | list[str \| ChartSupportTableSource \| ChartSupportTableAggregate \| ChartSupportTablePerSeries] \| [ChartSupportTable](#chartsupporttable) | Optional mini data-grid attached below/above the chart. |
| `height` | int \| float | Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Valid on cartesian chart families (area, bar, heatmap, histogram, line, scatter), pie/donut, and geo families (geoshape, map, point_map, bubble_map). Other chart families use renderer-owned or layout-owned sizing contracts. |
| `width` | int \| float | Chart width in pixels. Positive number only. In a rows layout the chart's slot pins to this width (a fixed footprint, capped at the row). In cols and grid layouts it contributes to the dashboard's intrinsic width measurement when the board has no width of its own, and the layout still owns the final slot. Valid on cartesian chart families (area, bar, heatmap, histogram, line, scatter), pie/donut, and geo families (geoshape, map, point_map, bubble_map). Other chart families use renderer-owned or layout-owned sizing contracts. |
| `style` | [HeatmapChartStyle](#heatmapchartstyle) | Appearance overrides for this chart alone. |

<a id="piechart"></a>
## PieChart
Authored patch for pie and donut charts; donut defaults `style.inner_radius` to 0.6.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `type` | enum: "pie", "donut" | Selects the chart family. |
| `theta` | str | Column for angular encoding in pie (arc) charts. |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `field_labels` | dict[str, str] | Display text per query column, painted as written wherever the chart would otherwise derive text from that column's name: legend titles and entries, tooltip rows, axis titles. x_label/y_label and a layer's label win on their own surface. |
| `id` | str | Identifier for this chart. Generated from its `charts:` key, or, written inline, from its title (its `label:` on type: kpi), falling back to its position. |
| `notes` | str | Human-readable notes used by AI search. Emitted into the SVG DOM as a data-chart-notes attribute; never painted as visible pixels. |
| `query` | str \| [SqlQuery](#sqlquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [QueryRef](#queryref) | Where this chart reads its data: a named query, an inline query block, or a SQL string. |
| `link` | str \| const: false | Click-through URL template for drill-down links. Set to false to suppress this chart's automatic link on a board with auto_link: true; table column links are unaffected. |
| `visible` | bool \| str \| [SingleRowBoolProbe](#singlerowboolprobe) | Controls whether this layout item is rendered. |
| `warnings_ignore` | list[one of: 'WARN-ADJACENT-TEXT-ROWS', 'WARN-AREA-UNSTACKED-READS-AS-STACKED', 'WARN-AREA-ZERO-BASELINE-CROPPED', 'WARN-AXIS-ALIGN-DISCARDED', 'WARN-AXIS-LABEL-COLLISION', 'WARN-AXIS-TITLE-TRUNCATED', 'WARN-BAR-BAND-WIDTH-TOO-NARROW', 'WARN-BAR-GROUPED-SERIES-COINCIDE', 'WARN-CALLOUT-TEXT-TRUNCATED', 'WARN-CATEGORY-COLOR-PIN-UNSEEN', 'WARN-CHART-TITLE-TRUNCATED', 'WARN-COLUMN-CHECK-UNAVAILABLE', 'WARN-DBT-MANIFEST-MISSING', 'WARN-DBT-MODEL-COLUMNS-UNRESOLVED', 'WARN-DBT-QUERY-COLUMNS-INDETERMINATE', 'WARN-DEFAULTS-FILE-GIVEN-AS-BOARD', 'WARN-DOUBLE-HEADER', 'WARN-DUAL-AXIS-COMPETING-SCALES', 'WARN-ENDPOINT-LABEL-GAP-OVERFLOW', 'WARN-ENDPOINT-LABEL-RAIL-OVERFLOW', 'WARN-ENDPOINT-LABEL-RAIL-TIED', 'WARN-FACET-PANEL-WIDTH-BELOW-MINIMUM', 'WARN-FANOUT-RISK', 'WARN-FLAT-COLS-UNSIZED-OVERFLOW', 'WARN-FORMAT-UNUSED-NAME', 'WARN-H1-BODY-NO-TITLE', 'WARN-HTML-POLICY-CAPPED', 'WARN-INHERITED-LAYOUT-REPLACED', 'WARN-KPI-ALIGN-OVERFLOW', 'WARN-KPI-INLINE-VARIANT-FALLBACK-TO-STACKED', 'WARN-KPI-LABEL-TRUNCATED', 'WARN-KPI-SUPPORT-TRUNCATED', 'WARN-LAYER-DATA-OUTSIDE-DOMAIN', 'WARN-LAYER-X-DOMAIN-PAINT-ORDER', 'WARN-LAYERED-CHART-SHARED-Y-AXIS-SCALE-MISMATCH', 'WARN-LAYOUT-MIN-EXCEEDS-HEIGHT', 'WARN-LEGEND-POSITION-WIDTH-FALLBACK', 'WARN-LEGEND-VALUES-UNRESOLVED', 'WARN-LIKELY-CURRENCY-OR-PERCENT-MISSING-FORMATTER', 'WARN-LOCAL-TIME-LABEL-EXPR-ON-BUCKETED-AXIS', 'WARN-LOW-TEXT-CONTRAST', 'WARN-NORMALIZE-PERCENT-FORMAT-READS-RAW-VALUE', 'WARN-PALETTE-UNSUPPORTED', 'WARN-PIE-DOMINANT-SEGMENT', 'WARN-PIE-TOO-MANY-SEGMENTS', 'WARN-PIE-TOTAL-EXCEEDS-INNER-RADIUS', 'WARN-PLOT-HEIGHT-BELOW-MINIMUM', 'WARN-PLOT-WIDTH-BELOW-MINIMUM', 'WARN-POINT-MAP-NEGATIVE-SIZE-VALUES', 'WARN-POINT-MAP-OUT-OF-PROJECTION', 'WARN-QUERY-RESULT-TRUNCATED', 'WARN-QUERY-RETURNED-ZERO-ROWS', 'WARN-REDUNDANT-AUTHORED-DEFAULT', 'WARN-REDUNDANT-AUTHORED-LABEL', 'WARN-REDUNDANT-ENCODING', 'WARN-RETIRED-IGNORE-CODE', 'WARN-SCHEMA-MIGRATED', 'WARN-SERIES-LABEL-TRUNCATED', 'WARN-SERIES-LABELS-REPEAT-WORD', 'WARN-SINGLE-CHART-REDUNDANT-TITLE', 'WARN-SPARK-LABEL-TRUNCATED', 'WARN-STATIC-PAGINATION-CAPPED', 'WARN-SUPPORT-TABLE-CELL-OVERFLOW', 'WARN-TABLE-COLUMNS-OVERFLOW', 'WARN-TABLE-CRAMPED', 'WARN-TABLE-PAGE-SQUEEZED', 'WARN-TABLE-TEXT-TRUNCATED', 'WARN-TEMPORAL-SINGLE-POINT', 'WARN-TOO-MANY-COLOR-CATEGORIES', 'WARN-TOO-MANY-X-CATEGORIES', 'WARN-UNREFERENCED-CHART', 'WARN-VALUE-LABELS-CROWD-WIDTH', 'WARN-WAREHOUSE-CHECK-UNAVAILABLE', 'WARN-WIDE-MEASURE-LABEL-COLLISION', 'WARN-Y-ENCODING-MOSTLY-NULL'] | Codes of render warnings to suppress for this chart. Query-domain codes such as WARN-REAGGREGATION go in `queries.&lt;name&gt;.ignore` instead. |
| `title` | str | Heading naming what the chart shows. Rejected on type: kpi. |
| `subtitle` | str | Supporting text beneath the chart title. |
| `color` | str | Column naming each wedge, giving it its own hue. Bare column name only; a literal color goes in `style.color.static`. |
| `total` | [ChartTotal](#charttotal) | Sum of the slice values, drawn in the donut hole. |
| `height` | int \| float | Explicit chart height in pixels. Positive number only. |
| `width` | int \| float | Chart width in pixels. Positive number only. In a rows layout the chart's slot pins to this width (a fixed footprint, capped at the row). In cols and grid layouts it contributes to the dashboard's intrinsic width measurement when the board has no width of its own, and the layout still owns the final slot. |
| `style` | [PieChartStyle](#piechartstyle) | Appearance overrides for this chart alone. |

<a id="kpichart"></a>
## KpiChart
Authored patch for KPI (key performance indicator) charts.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `type` | const: "kpi" |  |
| `value` | str | Column reference (string column name) for the headline number/text. |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | Discrete rule-driven style overrides indexed by column name. Available on type: table and type: kpi only. On a KPI, rules on the `support.value` column style the support row (font.color, glyph, glyph_color, tone); rules on other columns style the headline. |
| `id` | str | Identifier for this chart. Generated from its `charts:` key, or, written inline, from its title (its `label:` on type: kpi), falling back to its position. |
| `notes` | str | Human-readable notes used by AI search. Emitted into the SVG DOM as a data-chart-notes attribute; never painted as visible pixels. |
| `query` | str \| [SqlQuery](#sqlquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [QueryRef](#queryref) | Where this chart reads its data: a named query, an inline query block, or a SQL string. |
| `link` | str \| const: false | Click-through URL template for drill-down links. Set to false to suppress this chart's automatic link on a board with auto_link: true; table column links are unaffected. |
| `visible` | bool \| str \| [SingleRowBoolProbe](#singlerowboolprobe) | Controls whether this layout item is rendered. |
| `warnings_ignore` | list[one of: 'WARN-ADJACENT-TEXT-ROWS', 'WARN-AREA-UNSTACKED-READS-AS-STACKED', 'WARN-AREA-ZERO-BASELINE-CROPPED', 'WARN-AXIS-ALIGN-DISCARDED', 'WARN-AXIS-LABEL-COLLISION', 'WARN-AXIS-TITLE-TRUNCATED', 'WARN-BAR-BAND-WIDTH-TOO-NARROW', 'WARN-BAR-GROUPED-SERIES-COINCIDE', 'WARN-CALLOUT-TEXT-TRUNCATED', 'WARN-CATEGORY-COLOR-PIN-UNSEEN', 'WARN-CHART-TITLE-TRUNCATED', 'WARN-COLUMN-CHECK-UNAVAILABLE', 'WARN-DBT-MANIFEST-MISSING', 'WARN-DBT-MODEL-COLUMNS-UNRESOLVED', 'WARN-DBT-QUERY-COLUMNS-INDETERMINATE', 'WARN-DEFAULTS-FILE-GIVEN-AS-BOARD', 'WARN-DOUBLE-HEADER', 'WARN-DUAL-AXIS-COMPETING-SCALES', 'WARN-ENDPOINT-LABEL-GAP-OVERFLOW', 'WARN-ENDPOINT-LABEL-RAIL-OVERFLOW', 'WARN-ENDPOINT-LABEL-RAIL-TIED', 'WARN-FACET-PANEL-WIDTH-BELOW-MINIMUM', 'WARN-FANOUT-RISK', 'WARN-FLAT-COLS-UNSIZED-OVERFLOW', 'WARN-FORMAT-UNUSED-NAME', 'WARN-H1-BODY-NO-TITLE', 'WARN-HTML-POLICY-CAPPED', 'WARN-INHERITED-LAYOUT-REPLACED', 'WARN-KPI-ALIGN-OVERFLOW', 'WARN-KPI-INLINE-VARIANT-FALLBACK-TO-STACKED', 'WARN-KPI-LABEL-TRUNCATED', 'WARN-KPI-SUPPORT-TRUNCATED', 'WARN-LAYER-DATA-OUTSIDE-DOMAIN', 'WARN-LAYER-X-DOMAIN-PAINT-ORDER', 'WARN-LAYERED-CHART-SHARED-Y-AXIS-SCALE-MISMATCH', 'WARN-LAYOUT-MIN-EXCEEDS-HEIGHT', 'WARN-LEGEND-POSITION-WIDTH-FALLBACK', 'WARN-LEGEND-VALUES-UNRESOLVED', 'WARN-LIKELY-CURRENCY-OR-PERCENT-MISSING-FORMATTER', 'WARN-LOCAL-TIME-LABEL-EXPR-ON-BUCKETED-AXIS', 'WARN-LOW-TEXT-CONTRAST', 'WARN-NORMALIZE-PERCENT-FORMAT-READS-RAW-VALUE', 'WARN-PALETTE-UNSUPPORTED', 'WARN-PIE-DOMINANT-SEGMENT', 'WARN-PIE-TOO-MANY-SEGMENTS', 'WARN-PIE-TOTAL-EXCEEDS-INNER-RADIUS', 'WARN-PLOT-HEIGHT-BELOW-MINIMUM', 'WARN-PLOT-WIDTH-BELOW-MINIMUM', 'WARN-POINT-MAP-NEGATIVE-SIZE-VALUES', 'WARN-POINT-MAP-OUT-OF-PROJECTION', 'WARN-QUERY-RESULT-TRUNCATED', 'WARN-QUERY-RETURNED-ZERO-ROWS', 'WARN-REDUNDANT-AUTHORED-DEFAULT', 'WARN-REDUNDANT-AUTHORED-LABEL', 'WARN-REDUNDANT-ENCODING', 'WARN-RETIRED-IGNORE-CODE', 'WARN-SCHEMA-MIGRATED', 'WARN-SERIES-LABEL-TRUNCATED', 'WARN-SERIES-LABELS-REPEAT-WORD', 'WARN-SINGLE-CHART-REDUNDANT-TITLE', 'WARN-SPARK-LABEL-TRUNCATED', 'WARN-STATIC-PAGINATION-CAPPED', 'WARN-SUPPORT-TABLE-CELL-OVERFLOW', 'WARN-TABLE-COLUMNS-OVERFLOW', 'WARN-TABLE-CRAMPED', 'WARN-TABLE-PAGE-SQUEEZED', 'WARN-TABLE-TEXT-TRUNCATED', 'WARN-TEMPORAL-SINGLE-POINT', 'WARN-TOO-MANY-COLOR-CATEGORIES', 'WARN-TOO-MANY-X-CATEGORIES', 'WARN-UNREFERENCED-CHART', 'WARN-VALUE-LABELS-CROWD-WIDTH', 'WARN-WAREHOUSE-CHECK-UNAVAILABLE', 'WARN-WIDE-MEASURE-LABEL-COLLISION', 'WARN-Y-ENCODING-MOSTLY-NULL'] | Codes of render warnings to suppress for this chart. Query-domain codes such as WARN-REAGGREGATION go in `queries.&lt;name&gt;.ignore` instead. |
| `label` | str | Caption naming what the headline value measures; `style.variant` places it. |
| `glyph` | str | Text shown before the headline value (e.g. '▲', '●'). |
| `support` | [KpiSupportConfig](#kpisupportconfig) | Secondary block, a delta, comparison, or note; `style.variant` places it. |
| `style` | [KpiChartStyle](#kpichartstyle) | Appearance overrides for this chart alone. |
| `background` | str \| dict[str, Any] | Gradient background channel, {column, scale} shape. Paints the card background by the value's position in the scale. |

<a id="tablechart"></a>
## TableChart
Authored patch for table charts.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `type` | const: "table" |  |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | Discrete rule-driven style overrides indexed by column name. Available on type: table and type: kpi only. On a KPI, rules on the `support.value` column style the support row (font.color, glyph, glyph_color, tone); rules on other columns style the headline. |
| `id` | str | Identifier for this chart. Generated from its `charts:` key, or, written inline, from its title (its `label:` on type: kpi), falling back to its position. |
| `notes` | str | Human-readable notes used by AI search. Emitted into the SVG DOM as a data-chart-notes attribute; never painted as visible pixels. |
| `query` | str \| [SqlQuery](#sqlquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [QueryRef](#queryref) | Where this chart reads its data: a named query, an inline query block, or a SQL string. |
| `link` | str \| const: false | Click-through URL template for drill-down links. Set to false to suppress this chart's automatic link on a board with auto_link: true; table column links are unaffected. |
| `visible` | bool \| str \| [SingleRowBoolProbe](#singlerowboolprobe) | Controls whether this layout item is rendered. |
| `warnings_ignore` | list[one of: 'WARN-ADJACENT-TEXT-ROWS', 'WARN-AREA-UNSTACKED-READS-AS-STACKED', 'WARN-AREA-ZERO-BASELINE-CROPPED', 'WARN-AXIS-ALIGN-DISCARDED', 'WARN-AXIS-LABEL-COLLISION', 'WARN-AXIS-TITLE-TRUNCATED', 'WARN-BAR-BAND-WIDTH-TOO-NARROW', 'WARN-BAR-GROUPED-SERIES-COINCIDE', 'WARN-CALLOUT-TEXT-TRUNCATED', 'WARN-CATEGORY-COLOR-PIN-UNSEEN', 'WARN-CHART-TITLE-TRUNCATED', 'WARN-COLUMN-CHECK-UNAVAILABLE', 'WARN-DBT-MANIFEST-MISSING', 'WARN-DBT-MODEL-COLUMNS-UNRESOLVED', 'WARN-DBT-QUERY-COLUMNS-INDETERMINATE', 'WARN-DEFAULTS-FILE-GIVEN-AS-BOARD', 'WARN-DOUBLE-HEADER', 'WARN-DUAL-AXIS-COMPETING-SCALES', 'WARN-ENDPOINT-LABEL-GAP-OVERFLOW', 'WARN-ENDPOINT-LABEL-RAIL-OVERFLOW', 'WARN-ENDPOINT-LABEL-RAIL-TIED', 'WARN-FACET-PANEL-WIDTH-BELOW-MINIMUM', 'WARN-FANOUT-RISK', 'WARN-FLAT-COLS-UNSIZED-OVERFLOW', 'WARN-FORMAT-UNUSED-NAME', 'WARN-H1-BODY-NO-TITLE', 'WARN-HTML-POLICY-CAPPED', 'WARN-INHERITED-LAYOUT-REPLACED', 'WARN-KPI-ALIGN-OVERFLOW', 'WARN-KPI-INLINE-VARIANT-FALLBACK-TO-STACKED', 'WARN-KPI-LABEL-TRUNCATED', 'WARN-KPI-SUPPORT-TRUNCATED', 'WARN-LAYER-DATA-OUTSIDE-DOMAIN', 'WARN-LAYER-X-DOMAIN-PAINT-ORDER', 'WARN-LAYERED-CHART-SHARED-Y-AXIS-SCALE-MISMATCH', 'WARN-LAYOUT-MIN-EXCEEDS-HEIGHT', 'WARN-LEGEND-POSITION-WIDTH-FALLBACK', 'WARN-LEGEND-VALUES-UNRESOLVED', 'WARN-LIKELY-CURRENCY-OR-PERCENT-MISSING-FORMATTER', 'WARN-LOCAL-TIME-LABEL-EXPR-ON-BUCKETED-AXIS', 'WARN-LOW-TEXT-CONTRAST', 'WARN-NORMALIZE-PERCENT-FORMAT-READS-RAW-VALUE', 'WARN-PALETTE-UNSUPPORTED', 'WARN-PIE-DOMINANT-SEGMENT', 'WARN-PIE-TOO-MANY-SEGMENTS', 'WARN-PIE-TOTAL-EXCEEDS-INNER-RADIUS', 'WARN-PLOT-HEIGHT-BELOW-MINIMUM', 'WARN-PLOT-WIDTH-BELOW-MINIMUM', 'WARN-POINT-MAP-NEGATIVE-SIZE-VALUES', 'WARN-POINT-MAP-OUT-OF-PROJECTION', 'WARN-QUERY-RESULT-TRUNCATED', 'WARN-QUERY-RETURNED-ZERO-ROWS', 'WARN-REDUNDANT-AUTHORED-DEFAULT', 'WARN-REDUNDANT-AUTHORED-LABEL', 'WARN-REDUNDANT-ENCODING', 'WARN-RETIRED-IGNORE-CODE', 'WARN-SCHEMA-MIGRATED', 'WARN-SERIES-LABEL-TRUNCATED', 'WARN-SERIES-LABELS-REPEAT-WORD', 'WARN-SINGLE-CHART-REDUNDANT-TITLE', 'WARN-SPARK-LABEL-TRUNCATED', 'WARN-STATIC-PAGINATION-CAPPED', 'WARN-SUPPORT-TABLE-CELL-OVERFLOW', 'WARN-TABLE-COLUMNS-OVERFLOW', 'WARN-TABLE-CRAMPED', 'WARN-TABLE-PAGE-SQUEEZED', 'WARN-TABLE-TEXT-TRUNCATED', 'WARN-TEMPORAL-SINGLE-POINT', 'WARN-TOO-MANY-COLOR-CATEGORIES', 'WARN-TOO-MANY-X-CATEGORIES', 'WARN-UNREFERENCED-CHART', 'WARN-VALUE-LABELS-CROWD-WIDTH', 'WARN-WAREHOUSE-CHECK-UNAVAILABLE', 'WARN-WIDE-MEASURE-LABEL-COLLISION', 'WARN-Y-ENCODING-MOSTLY-NULL'] | Codes of render warnings to suppress for this chart. Query-domain codes such as WARN-REAGGREGATION go in `queries.&lt;name&gt;.ignore` instead. |
| `title` | str | Heading naming what the chart shows. Rejected on type: kpi. |
| `subtitle` | str | Supporting text beneath the chart title. |
| `style` | [TableChartStyle](#tablechartstyle) | Appearance overrides for this chart alone. |
| `rows` | list[str] | Fields whose distinct values form the row dimension of a pivot cross-tab. Each string is a column name from the query result. Omit for flat (non-pivot) tables. |
| `columns` | list[str] | Fields whose distinct values become column headers in a pivot cross-tab. Multiple fields create a nested multi-dimension pivot (outer → inner). Omit for flat tables. |
| `values` | list[str] | Measure fields that fill pivot cells. Each string is a column name from the query result. When omitted, all query columns not claimed by rows or columns are used. |
| `spanners` | list[[TableSpanner](#tablespanner)] | Labels drawn in an extra header row above runs of adjacent columns of a flat table. Not combinable with the pivot rows/columns/values channels. |

<a id="pointmapchart"></a>
## PointMapChart
Authored patch for point_map and bubble_map charts; the two type spellings are synonyms.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `type` | enum: "point_map", "bubble_map" | Selects the chart family. |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `field_labels` | dict[str, str] | Display text per query column, painted as written wherever the chart would otherwise derive text from that column's name: legend titles and entries, tooltip rows, axis titles. x_label/y_label and a layer's label win on their own surface. |
| `id` | str | Identifier for this chart. Generated from its `charts:` key, or, written inline, from its title (its `label:` on type: kpi), falling back to its position. |
| `notes` | str | Human-readable notes used by AI search. Emitted into the SVG DOM as a data-chart-notes attribute; never painted as visible pixels. |
| `query` | str \| [SqlQuery](#sqlquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [QueryRef](#queryref) | Where this chart reads its data: a named query, an inline query block, or a SQL string. |
| `link` | str \| const: false | Click-through URL template for drill-down links. Set to false to suppress this chart's automatic link on a board with auto_link: true; table column links are unaffected. |
| `visible` | bool \| str \| [SingleRowBoolProbe](#singlerowboolprobe) | Controls whether this layout item is rendered. |
| `warnings_ignore` | list[one of: 'WARN-ADJACENT-TEXT-ROWS', 'WARN-AREA-UNSTACKED-READS-AS-STACKED', 'WARN-AREA-ZERO-BASELINE-CROPPED', 'WARN-AXIS-ALIGN-DISCARDED', 'WARN-AXIS-LABEL-COLLISION', 'WARN-AXIS-TITLE-TRUNCATED', 'WARN-BAR-BAND-WIDTH-TOO-NARROW', 'WARN-BAR-GROUPED-SERIES-COINCIDE', 'WARN-CALLOUT-TEXT-TRUNCATED', 'WARN-CATEGORY-COLOR-PIN-UNSEEN', 'WARN-CHART-TITLE-TRUNCATED', 'WARN-COLUMN-CHECK-UNAVAILABLE', 'WARN-DBT-MANIFEST-MISSING', 'WARN-DBT-MODEL-COLUMNS-UNRESOLVED', 'WARN-DBT-QUERY-COLUMNS-INDETERMINATE', 'WARN-DEFAULTS-FILE-GIVEN-AS-BOARD', 'WARN-DOUBLE-HEADER', 'WARN-DUAL-AXIS-COMPETING-SCALES', 'WARN-ENDPOINT-LABEL-GAP-OVERFLOW', 'WARN-ENDPOINT-LABEL-RAIL-OVERFLOW', 'WARN-ENDPOINT-LABEL-RAIL-TIED', 'WARN-FACET-PANEL-WIDTH-BELOW-MINIMUM', 'WARN-FANOUT-RISK', 'WARN-FLAT-COLS-UNSIZED-OVERFLOW', 'WARN-FORMAT-UNUSED-NAME', 'WARN-H1-BODY-NO-TITLE', 'WARN-HTML-POLICY-CAPPED', 'WARN-INHERITED-LAYOUT-REPLACED', 'WARN-KPI-ALIGN-OVERFLOW', 'WARN-KPI-INLINE-VARIANT-FALLBACK-TO-STACKED', 'WARN-KPI-LABEL-TRUNCATED', 'WARN-KPI-SUPPORT-TRUNCATED', 'WARN-LAYER-DATA-OUTSIDE-DOMAIN', 'WARN-LAYER-X-DOMAIN-PAINT-ORDER', 'WARN-LAYERED-CHART-SHARED-Y-AXIS-SCALE-MISMATCH', 'WARN-LAYOUT-MIN-EXCEEDS-HEIGHT', 'WARN-LEGEND-POSITION-WIDTH-FALLBACK', 'WARN-LEGEND-VALUES-UNRESOLVED', 'WARN-LIKELY-CURRENCY-OR-PERCENT-MISSING-FORMATTER', 'WARN-LOCAL-TIME-LABEL-EXPR-ON-BUCKETED-AXIS', 'WARN-LOW-TEXT-CONTRAST', 'WARN-NORMALIZE-PERCENT-FORMAT-READS-RAW-VALUE', 'WARN-PALETTE-UNSUPPORTED', 'WARN-PIE-DOMINANT-SEGMENT', 'WARN-PIE-TOO-MANY-SEGMENTS', 'WARN-PIE-TOTAL-EXCEEDS-INNER-RADIUS', 'WARN-PLOT-HEIGHT-BELOW-MINIMUM', 'WARN-PLOT-WIDTH-BELOW-MINIMUM', 'WARN-POINT-MAP-NEGATIVE-SIZE-VALUES', 'WARN-POINT-MAP-OUT-OF-PROJECTION', 'WARN-QUERY-RESULT-TRUNCATED', 'WARN-QUERY-RETURNED-ZERO-ROWS', 'WARN-REDUNDANT-AUTHORED-DEFAULT', 'WARN-REDUNDANT-AUTHORED-LABEL', 'WARN-REDUNDANT-ENCODING', 'WARN-RETIRED-IGNORE-CODE', 'WARN-SCHEMA-MIGRATED', 'WARN-SERIES-LABEL-TRUNCATED', 'WARN-SERIES-LABELS-REPEAT-WORD', 'WARN-SINGLE-CHART-REDUNDANT-TITLE', 'WARN-SPARK-LABEL-TRUNCATED', 'WARN-STATIC-PAGINATION-CAPPED', 'WARN-SUPPORT-TABLE-CELL-OVERFLOW', 'WARN-TABLE-COLUMNS-OVERFLOW', 'WARN-TABLE-CRAMPED', 'WARN-TABLE-PAGE-SQUEEZED', 'WARN-TABLE-TEXT-TRUNCATED', 'WARN-TEMPORAL-SINGLE-POINT', 'WARN-TOO-MANY-COLOR-CATEGORIES', 'WARN-TOO-MANY-X-CATEGORIES', 'WARN-UNREFERENCED-CHART', 'WARN-VALUE-LABELS-CROWD-WIDTH', 'WARN-WAREHOUSE-CHECK-UNAVAILABLE', 'WARN-WIDE-MEASURE-LABEL-COLLISION', 'WARN-Y-ENCODING-MOSTLY-NULL'] | Codes of render warnings to suppress for this chart. Query-domain codes such as WARN-REAGGREGATION go in `queries.&lt;name&gt;.ignore` instead. |
| `title` | str | Heading naming what the chart shows. Rejected on type: kpi. |
| `subtitle` | str | Supporting text beneath the chart title. |
| `projection` | str \| [Projection](#projection) | Map projection name or Vega-Lite projection config. |
| `color` | str | Column carried on the color channel: fill for geoshape regions, hue for point-map points. Bare column name only; a literal color goes in `style.color.static`. |
| `geo` | str \| dict[str, Any] | Named GeoJSON boundary source, or inline GeoJSON spec, for geoshape charts. |
| `geo_source` | str | Named geographic data source for loading GeoJSON boundaries. |
| `lookup` | str | Data column to join against geographic data (map join key). |
| `value` | str | Data column mapped to the fill color on geoshape, taking precedence over `color:` when both are set. Ignored on point_map and bubble_map. |
| `height` | int \| float | Explicit chart height in pixels. Positive number only. |
| `width` | int \| float | Chart width in pixels. Positive number only. In a rows layout the chart's slot pins to this width (a fixed footprint, capped at the row). In cols and grid layouts it contributes to the dashboard's intrinsic width measurement when the board has no width of its own, and the layout still owns the final slot. |
| `latitude` | str | Column containing latitude values for point/bubble maps. |
| `longitude` | str | Column containing longitude values for point/bubble maps. |
| `size` | str | Quantitative column that scales point area. Mutually exclusive with `collapse`. |
| `collapse` | bool | Collapse marks sharing an exact latitude/longitude into one mark sized by count. Mutually exclusive with `size` and with any color channel. |
| `basemap` | [BasemapConfig](#basemapconfig) | Styled geographic background layer. |
| `style` | [PointMapChartStyle](#pointmapchartstyle) | Appearance overrides for this chart alone. |

<a id="geoshapechart"></a>
## GeoshapeChart
Authored patch for map and geoshape charts; the two type spellings are synonyms.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `type` | enum: "map", "geoshape" | Selects the chart family. |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `field_labels` | dict[str, str] | Display text per query column, painted as written wherever the chart would otherwise derive text from that column's name: legend titles and entries, tooltip rows, axis titles. x_label/y_label and a layer's label win on their own surface. |
| `id` | str | Identifier for this chart. Generated from its `charts:` key, or, written inline, from its title (its `label:` on type: kpi), falling back to its position. |
| `notes` | str | Human-readable notes used by AI search. Emitted into the SVG DOM as a data-chart-notes attribute; never painted as visible pixels. |
| `query` | str \| [SqlQuery](#sqlquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [QueryRef](#queryref) | Where this chart reads its data: a named query, an inline query block, or a SQL string. |
| `link` | str \| const: false | Click-through URL template for drill-down links. Set to false to suppress this chart's automatic link on a board with auto_link: true; table column links are unaffected. |
| `visible` | bool \| str \| [SingleRowBoolProbe](#singlerowboolprobe) | Controls whether this layout item is rendered. |
| `warnings_ignore` | list[one of: 'WARN-ADJACENT-TEXT-ROWS', 'WARN-AREA-UNSTACKED-READS-AS-STACKED', 'WARN-AREA-ZERO-BASELINE-CROPPED', 'WARN-AXIS-ALIGN-DISCARDED', 'WARN-AXIS-LABEL-COLLISION', 'WARN-AXIS-TITLE-TRUNCATED', 'WARN-BAR-BAND-WIDTH-TOO-NARROW', 'WARN-BAR-GROUPED-SERIES-COINCIDE', 'WARN-CALLOUT-TEXT-TRUNCATED', 'WARN-CATEGORY-COLOR-PIN-UNSEEN', 'WARN-CHART-TITLE-TRUNCATED', 'WARN-COLUMN-CHECK-UNAVAILABLE', 'WARN-DBT-MANIFEST-MISSING', 'WARN-DBT-MODEL-COLUMNS-UNRESOLVED', 'WARN-DBT-QUERY-COLUMNS-INDETERMINATE', 'WARN-DEFAULTS-FILE-GIVEN-AS-BOARD', 'WARN-DOUBLE-HEADER', 'WARN-DUAL-AXIS-COMPETING-SCALES', 'WARN-ENDPOINT-LABEL-GAP-OVERFLOW', 'WARN-ENDPOINT-LABEL-RAIL-OVERFLOW', 'WARN-ENDPOINT-LABEL-RAIL-TIED', 'WARN-FACET-PANEL-WIDTH-BELOW-MINIMUM', 'WARN-FANOUT-RISK', 'WARN-FLAT-COLS-UNSIZED-OVERFLOW', 'WARN-FORMAT-UNUSED-NAME', 'WARN-H1-BODY-NO-TITLE', 'WARN-HTML-POLICY-CAPPED', 'WARN-INHERITED-LAYOUT-REPLACED', 'WARN-KPI-ALIGN-OVERFLOW', 'WARN-KPI-INLINE-VARIANT-FALLBACK-TO-STACKED', 'WARN-KPI-LABEL-TRUNCATED', 'WARN-KPI-SUPPORT-TRUNCATED', 'WARN-LAYER-DATA-OUTSIDE-DOMAIN', 'WARN-LAYER-X-DOMAIN-PAINT-ORDER', 'WARN-LAYERED-CHART-SHARED-Y-AXIS-SCALE-MISMATCH', 'WARN-LAYOUT-MIN-EXCEEDS-HEIGHT', 'WARN-LEGEND-POSITION-WIDTH-FALLBACK', 'WARN-LEGEND-VALUES-UNRESOLVED', 'WARN-LIKELY-CURRENCY-OR-PERCENT-MISSING-FORMATTER', 'WARN-LOCAL-TIME-LABEL-EXPR-ON-BUCKETED-AXIS', 'WARN-LOW-TEXT-CONTRAST', 'WARN-NORMALIZE-PERCENT-FORMAT-READS-RAW-VALUE', 'WARN-PALETTE-UNSUPPORTED', 'WARN-PIE-DOMINANT-SEGMENT', 'WARN-PIE-TOO-MANY-SEGMENTS', 'WARN-PIE-TOTAL-EXCEEDS-INNER-RADIUS', 'WARN-PLOT-HEIGHT-BELOW-MINIMUM', 'WARN-PLOT-WIDTH-BELOW-MINIMUM', 'WARN-POINT-MAP-NEGATIVE-SIZE-VALUES', 'WARN-POINT-MAP-OUT-OF-PROJECTION', 'WARN-QUERY-RESULT-TRUNCATED', 'WARN-QUERY-RETURNED-ZERO-ROWS', 'WARN-REDUNDANT-AUTHORED-DEFAULT', 'WARN-REDUNDANT-AUTHORED-LABEL', 'WARN-REDUNDANT-ENCODING', 'WARN-RETIRED-IGNORE-CODE', 'WARN-SCHEMA-MIGRATED', 'WARN-SERIES-LABEL-TRUNCATED', 'WARN-SERIES-LABELS-REPEAT-WORD', 'WARN-SINGLE-CHART-REDUNDANT-TITLE', 'WARN-SPARK-LABEL-TRUNCATED', 'WARN-STATIC-PAGINATION-CAPPED', 'WARN-SUPPORT-TABLE-CELL-OVERFLOW', 'WARN-TABLE-COLUMNS-OVERFLOW', 'WARN-TABLE-CRAMPED', 'WARN-TABLE-PAGE-SQUEEZED', 'WARN-TABLE-TEXT-TRUNCATED', 'WARN-TEMPORAL-SINGLE-POINT', 'WARN-TOO-MANY-COLOR-CATEGORIES', 'WARN-TOO-MANY-X-CATEGORIES', 'WARN-UNREFERENCED-CHART', 'WARN-VALUE-LABELS-CROWD-WIDTH', 'WARN-WAREHOUSE-CHECK-UNAVAILABLE', 'WARN-WIDE-MEASURE-LABEL-COLLISION', 'WARN-Y-ENCODING-MOSTLY-NULL'] | Codes of render warnings to suppress for this chart. Query-domain codes such as WARN-REAGGREGATION go in `queries.&lt;name&gt;.ignore` instead. |
| `title` | str | Heading naming what the chart shows. Rejected on type: kpi. |
| `subtitle` | str | Supporting text beneath the chart title. |
| `projection` | str \| [Projection](#projection) | Map projection name or Vega-Lite projection config. |
| `color` | str | Column carried on the color channel: fill for geoshape regions, hue for point-map points. Bare column name only; a literal color goes in `style.color.static`. |
| `geo` | str \| dict[str, Any] | Named GeoJSON boundary source, or inline GeoJSON spec, for geoshape charts. |
| `geo_source` | str | Named geographic data source for loading GeoJSON boundaries. |
| `lookup` | str | Data column to join against geographic data (map join key). |
| `value` | str | Data column mapped to the fill color on geoshape, taking precedence over `color:` when both are set. Ignored on point_map and bubble_map. |
| `height` | int \| float | Explicit chart height in pixels. Positive number only. |
| `width` | int \| float | Chart width in pixels. Positive number only. In a rows layout the chart's slot pins to this width (a fixed footprint, capped at the row). In cols and grid layouts it contributes to the dashboard's intrinsic width measurement when the board has no width of its own, and the layout still owns the final slot. |
| `style` | [GeoshapeChartStyle](#geoshapechartstyle) | Appearance overrides for this chart alone. |

<a id="calloutchart"></a>
## CalloutChart
Static callout/message chart. Minimal: no chrome, no styling, no query.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `type` | const: "callout" |  |
| `message` | str | Body text the callout displays. |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `title` | str | Optional chart title shown above the message. |
| `style` | [CalloutChartStyle](#calloutchartstyle) | Appearance overrides for this chart alone (tone). |
| `warnings_ignore` | list[str] | Codes of render warnings to suppress for this chart. |

<a id="sparkbarchart"></a>
## SparkBarChart
Authored patch for spark_bar charts (compact horizontal bars).

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `type` | const: "spark_bar" |  |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `id` | str | Identifier for this chart. Generated from its `charts:` key, or, written inline, from its title (its `label:` on type: kpi), falling back to its position. |
| `notes` | str | Human-readable notes used by AI search. Emitted into the SVG DOM as a data-chart-notes attribute; never painted as visible pixels. |
| `query` | str \| [SqlQuery](#sqlquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [QueryRef](#queryref) | Where this chart reads its data: a named query, an inline query block, or a SQL string. |
| `link` | str \| const: false | Click-through URL template for drill-down links. Set to false to suppress this chart's automatic link on a board with auto_link: true; table column links are unaffected. |
| `visible` | bool \| str \| [SingleRowBoolProbe](#singlerowboolprobe) | Controls whether this layout item is rendered. |
| `warnings_ignore` | list[one of: 'WARN-ADJACENT-TEXT-ROWS', 'WARN-AREA-UNSTACKED-READS-AS-STACKED', 'WARN-AREA-ZERO-BASELINE-CROPPED', 'WARN-AXIS-ALIGN-DISCARDED', 'WARN-AXIS-LABEL-COLLISION', 'WARN-AXIS-TITLE-TRUNCATED', 'WARN-BAR-BAND-WIDTH-TOO-NARROW', 'WARN-BAR-GROUPED-SERIES-COINCIDE', 'WARN-CALLOUT-TEXT-TRUNCATED', 'WARN-CATEGORY-COLOR-PIN-UNSEEN', 'WARN-CHART-TITLE-TRUNCATED', 'WARN-COLUMN-CHECK-UNAVAILABLE', 'WARN-DBT-MANIFEST-MISSING', 'WARN-DBT-MODEL-COLUMNS-UNRESOLVED', 'WARN-DBT-QUERY-COLUMNS-INDETERMINATE', 'WARN-DEFAULTS-FILE-GIVEN-AS-BOARD', 'WARN-DOUBLE-HEADER', 'WARN-DUAL-AXIS-COMPETING-SCALES', 'WARN-ENDPOINT-LABEL-GAP-OVERFLOW', 'WARN-ENDPOINT-LABEL-RAIL-OVERFLOW', 'WARN-ENDPOINT-LABEL-RAIL-TIED', 'WARN-FACET-PANEL-WIDTH-BELOW-MINIMUM', 'WARN-FANOUT-RISK', 'WARN-FLAT-COLS-UNSIZED-OVERFLOW', 'WARN-FORMAT-UNUSED-NAME', 'WARN-H1-BODY-NO-TITLE', 'WARN-HTML-POLICY-CAPPED', 'WARN-INHERITED-LAYOUT-REPLACED', 'WARN-KPI-ALIGN-OVERFLOW', 'WARN-KPI-INLINE-VARIANT-FALLBACK-TO-STACKED', 'WARN-KPI-LABEL-TRUNCATED', 'WARN-KPI-SUPPORT-TRUNCATED', 'WARN-LAYER-DATA-OUTSIDE-DOMAIN', 'WARN-LAYER-X-DOMAIN-PAINT-ORDER', 'WARN-LAYERED-CHART-SHARED-Y-AXIS-SCALE-MISMATCH', 'WARN-LAYOUT-MIN-EXCEEDS-HEIGHT', 'WARN-LEGEND-POSITION-WIDTH-FALLBACK', 'WARN-LEGEND-VALUES-UNRESOLVED', 'WARN-LIKELY-CURRENCY-OR-PERCENT-MISSING-FORMATTER', 'WARN-LOCAL-TIME-LABEL-EXPR-ON-BUCKETED-AXIS', 'WARN-LOW-TEXT-CONTRAST', 'WARN-NORMALIZE-PERCENT-FORMAT-READS-RAW-VALUE', 'WARN-PALETTE-UNSUPPORTED', 'WARN-PIE-DOMINANT-SEGMENT', 'WARN-PIE-TOO-MANY-SEGMENTS', 'WARN-PIE-TOTAL-EXCEEDS-INNER-RADIUS', 'WARN-PLOT-HEIGHT-BELOW-MINIMUM', 'WARN-PLOT-WIDTH-BELOW-MINIMUM', 'WARN-POINT-MAP-NEGATIVE-SIZE-VALUES', 'WARN-POINT-MAP-OUT-OF-PROJECTION', 'WARN-QUERY-RESULT-TRUNCATED', 'WARN-QUERY-RETURNED-ZERO-ROWS', 'WARN-REDUNDANT-AUTHORED-DEFAULT', 'WARN-REDUNDANT-AUTHORED-LABEL', 'WARN-REDUNDANT-ENCODING', 'WARN-RETIRED-IGNORE-CODE', 'WARN-SCHEMA-MIGRATED', 'WARN-SERIES-LABEL-TRUNCATED', 'WARN-SERIES-LABELS-REPEAT-WORD', 'WARN-SINGLE-CHART-REDUNDANT-TITLE', 'WARN-SPARK-LABEL-TRUNCATED', 'WARN-STATIC-PAGINATION-CAPPED', 'WARN-SUPPORT-TABLE-CELL-OVERFLOW', 'WARN-TABLE-COLUMNS-OVERFLOW', 'WARN-TABLE-CRAMPED', 'WARN-TABLE-PAGE-SQUEEZED', 'WARN-TABLE-TEXT-TRUNCATED', 'WARN-TEMPORAL-SINGLE-POINT', 'WARN-TOO-MANY-COLOR-CATEGORIES', 'WARN-TOO-MANY-X-CATEGORIES', 'WARN-UNREFERENCED-CHART', 'WARN-VALUE-LABELS-CROWD-WIDTH', 'WARN-WAREHOUSE-CHECK-UNAVAILABLE', 'WARN-WIDE-MEASURE-LABEL-COLLISION', 'WARN-Y-ENCODING-MOSTLY-NULL'] | Codes of render warnings to suppress for this chart. Query-domain codes such as WARN-REAGGREGATION go in `queries.&lt;name&gt;.ignore` instead. |
| `title` | str | Heading naming what the chart shows. Rejected on type: kpi. |
| `subtitle` | str | Supporting text beneath the chart title. |
| `x` | str | Bar-magnitude (numeric) column name. |
| `y` | str \| list[str] | Bar-label (category) column name(s). |
| `style` | [SparkBarChartStyle](#sparkbarchartstyle) | Appearance overrides for this chart alone. |

<a id="customchart"></a>
## CustomChart
Authored patch for custom charts: rows in, SVG out, drawn by a template.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `type` | const: "custom" |  |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `id` | str | Identifier for this chart. Generated from its `charts:` key, or, written inline, from its title (its `label:` on type: kpi), falling back to its position. |
| `notes` | str | Human-readable notes used by AI search. Emitted into the SVG DOM as a data-chart-notes attribute; never painted as visible pixels. |
| `query` | str \| [SqlQuery](#sqlquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [QueryRef](#queryref) | Where this chart reads its data: a named query, an inline query block, or a SQL string. |
| `link` | str \| const: false | Click-through URL template for drill-down links. Set to false to suppress this chart's automatic link on a board with auto_link: true; table column links are unaffected. |
| `visible` | bool \| str \| [SingleRowBoolProbe](#singlerowboolprobe) | Controls whether this layout item is rendered. |
| `warnings_ignore` | list[one of: 'WARN-ADJACENT-TEXT-ROWS', 'WARN-AREA-UNSTACKED-READS-AS-STACKED', 'WARN-AREA-ZERO-BASELINE-CROPPED', 'WARN-AXIS-ALIGN-DISCARDED', 'WARN-AXIS-LABEL-COLLISION', 'WARN-AXIS-TITLE-TRUNCATED', 'WARN-BAR-BAND-WIDTH-TOO-NARROW', 'WARN-BAR-GROUPED-SERIES-COINCIDE', 'WARN-CALLOUT-TEXT-TRUNCATED', 'WARN-CATEGORY-COLOR-PIN-UNSEEN', 'WARN-CHART-TITLE-TRUNCATED', 'WARN-COLUMN-CHECK-UNAVAILABLE', 'WARN-DBT-MANIFEST-MISSING', 'WARN-DBT-MODEL-COLUMNS-UNRESOLVED', 'WARN-DBT-QUERY-COLUMNS-INDETERMINATE', 'WARN-DEFAULTS-FILE-GIVEN-AS-BOARD', 'WARN-DOUBLE-HEADER', 'WARN-DUAL-AXIS-COMPETING-SCALES', 'WARN-ENDPOINT-LABEL-GAP-OVERFLOW', 'WARN-ENDPOINT-LABEL-RAIL-OVERFLOW', 'WARN-ENDPOINT-LABEL-RAIL-TIED', 'WARN-FACET-PANEL-WIDTH-BELOW-MINIMUM', 'WARN-FANOUT-RISK', 'WARN-FLAT-COLS-UNSIZED-OVERFLOW', 'WARN-FORMAT-UNUSED-NAME', 'WARN-H1-BODY-NO-TITLE', 'WARN-HTML-POLICY-CAPPED', 'WARN-INHERITED-LAYOUT-REPLACED', 'WARN-KPI-ALIGN-OVERFLOW', 'WARN-KPI-INLINE-VARIANT-FALLBACK-TO-STACKED', 'WARN-KPI-LABEL-TRUNCATED', 'WARN-KPI-SUPPORT-TRUNCATED', 'WARN-LAYER-DATA-OUTSIDE-DOMAIN', 'WARN-LAYER-X-DOMAIN-PAINT-ORDER', 'WARN-LAYERED-CHART-SHARED-Y-AXIS-SCALE-MISMATCH', 'WARN-LAYOUT-MIN-EXCEEDS-HEIGHT', 'WARN-LEGEND-POSITION-WIDTH-FALLBACK', 'WARN-LEGEND-VALUES-UNRESOLVED', 'WARN-LIKELY-CURRENCY-OR-PERCENT-MISSING-FORMATTER', 'WARN-LOCAL-TIME-LABEL-EXPR-ON-BUCKETED-AXIS', 'WARN-LOW-TEXT-CONTRAST', 'WARN-NORMALIZE-PERCENT-FORMAT-READS-RAW-VALUE', 'WARN-PALETTE-UNSUPPORTED', 'WARN-PIE-DOMINANT-SEGMENT', 'WARN-PIE-TOO-MANY-SEGMENTS', 'WARN-PIE-TOTAL-EXCEEDS-INNER-RADIUS', 'WARN-PLOT-HEIGHT-BELOW-MINIMUM', 'WARN-PLOT-WIDTH-BELOW-MINIMUM', 'WARN-POINT-MAP-NEGATIVE-SIZE-VALUES', 'WARN-POINT-MAP-OUT-OF-PROJECTION', 'WARN-QUERY-RESULT-TRUNCATED', 'WARN-QUERY-RETURNED-ZERO-ROWS', 'WARN-REDUNDANT-AUTHORED-DEFAULT', 'WARN-REDUNDANT-AUTHORED-LABEL', 'WARN-REDUNDANT-ENCODING', 'WARN-RETIRED-IGNORE-CODE', 'WARN-SCHEMA-MIGRATED', 'WARN-SERIES-LABEL-TRUNCATED', 'WARN-SERIES-LABELS-REPEAT-WORD', 'WARN-SINGLE-CHART-REDUNDANT-TITLE', 'WARN-SPARK-LABEL-TRUNCATED', 'WARN-STATIC-PAGINATION-CAPPED', 'WARN-SUPPORT-TABLE-CELL-OVERFLOW', 'WARN-TABLE-COLUMNS-OVERFLOW', 'WARN-TABLE-CRAMPED', 'WARN-TABLE-PAGE-SQUEEZED', 'WARN-TABLE-TEXT-TRUNCATED', 'WARN-TEMPORAL-SINGLE-POINT', 'WARN-TOO-MANY-COLOR-CATEGORIES', 'WARN-TOO-MANY-X-CATEGORIES', 'WARN-UNREFERENCED-CHART', 'WARN-VALUE-LABELS-CROWD-WIDTH', 'WARN-WAREHOUSE-CHECK-UNAVAILABLE', 'WARN-WIDE-MEASURE-LABEL-COLLISION', 'WARN-Y-ENCODING-MOSTLY-NULL'] | Codes of render warnings to suppress for this chart. Query-domain codes such as WARN-REAGGREGATION go in `queries.&lt;name&gt;.ignore` instead. |
| `title` | str | Heading naming what the chart shows. Rejected on type: kpi. |
| `subtitle` | str | Supporting text beneath the chart title. |
| `template` | str | Name of a project template: `templates/&lt;name&gt;.svg.j2`. Exactly one of `template` or `svg` is required. |
| `svg` | str | Inline Jinja SVG template source, used instead of `template`. |
| `x` | str \| list[str] | Column(s) for the template's `x` channel; the template header declares it. |
| `y` | str \| list[str] | Column(s) for the template's `y` channel; the template header declares it. |
| `color` | str \| list[str] | Column(s) for the template's `color` channel; the template header declares it. |
| `size` | str \| list[str] | Column(s) for the template's `size` channel; the template header declares it. |
| `shape` | str \| list[str] | Column(s) for the template's `shape` channel; the template header declares it. |
| `theta` | str \| list[str] | Column(s) for the template's `theta` channel; the template header declares it. |
| `value` | str \| list[str] | Column(s) for the template's `value` channel; the template header declares it. |
| `options` | dict[str, str \| int \| float \| bool \| list[str]] | Values for the options the template declares in its header. |
| `style` | [CustomChartStyle](#customchartstyle) | Sizing overrides for this chart alone. |

<a id="chartref"></a>
## ChartRef
Cross-file chart reference. Bare string is coerced automatically.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `ref` | str | Reference path: '&lt;file&gt;.charts.&lt;name&gt;'. May start with one or more '../' segments to reach a sibling directory. A bare string value is coerced automatically. |

<a id="gridlayout"></a>
## GridLayout
Grid layout configuration.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `items` | list[[GridItem](#griditem)] | Cells of this grid, each pairing content with its placement. |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `columns` | int | Number of grid columns (default: 24). Positive number only. |

<a id="tablayout"></a>
## TabLayout
Tab layout configuration.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `items` | list[[TabItem](#tabitem)] | Tabs in display order. |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `id` | str | Variable name and URL param base for tab selection (auto-generated if omitted). |
| `position` | enum: "top", "left" | Which edge the tab bar sits on (top or left). |
| `default` | str | Title of the tab opened on load; the first tab if omitted. |

<a id="boarddetails"></a>
## BoardDetails
Collapsible section metadata for a board.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `summary` | str | Label shown when the section is collapsed. |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `expanded_title` | str | Label shown when the section is expanded. Defaults to summary. |
| `expanded` | bool | Whether the section is open by default. |

<a id="style"></a>
## Style
Authored overlay for Style: all fields optional.

| Field | Type | Description |
|-------|------|-------------|
| `frame` | [FrameStyle](#framestyle) | Board-level structural frame dimensions. |
| `background` | str | Working-surface background color (board and card fills). |
| `accent` | str | Accent color token cascaded to sparklines, bars, and focus rings. |
| `muted` | str | Muted secondary-text color token (KPI support rows, table and spark subtitles). |
| `font` | [RootFontStyle](#rootfontstyle) | Root font configuration including emoji mode. |
| `border` | str \| [BorderStyle](#borderstyle) | Frame drawn around the whole board; none by default. |
| `box_shadow` | str | Drop shadow under chart cards: x offset, y offset, blur, color. |
| `opacity` | float | Default mark opacity (0–1). |
| `title` | [TitleStyle](#titlestyle) | Typography for every heading: board and prose titles, and chart, table, and spark object titles. |
| `text` | [TextStyle](#textstyle) | Markdown and plain text content style. |
| `placeholder` | [PlaceholderStyle](#placeholderstyle) | Appearance of the stand-in drawn on a chart with no data. |
| `charts` | [ChartsStyle](#chartsstyle) | Root of all chart-type styles and shared chart configuration. |
| `layout` | [LayoutStyle](#layoutstyle) | Spacing and arrangement inside the containers (rows, cols, grid, tabs, details). |
| `variables` | [VariablesStyle](#variablesstyle) | Variable controls chrome style. |
| `footer` | [FooterStyle](#footerstyle) | Page footer chrome visibility. |
| `timestamp` | [TimestampStyle](#timestampstyle) | Data-freshness chrome: visibility, placement, format, and font. |
| `formats` | dict[str, str \| [FormatConfig](#formatconfig)] | Format alias map; None means no aliases at this cascade level. |
| `fonts` | dict[str, [NamedFont](#namedfont)] | Named fonts other font slots reference as ``font: &lt;name&gt;`` or ``font: {extends: &lt;name&gt;, ...}``. ``heading`` carries the H1–H6 ramp in ``sizes``. An entry no slot references paints nothing. |
| `palettes` | dict[str, one of: 'category-6-tonal-blue', 'category-6-tonal-blue.dark', 'category-6-tonal-blue.deep', 'category-6-tonal-blue.light', 'category-6-tonal-blue.pale', 'category-6-tonal-brown', 'category-6-tonal-brown.dark', 'category-6-tonal-brown.deep', 'category-6-tonal-brown.light', 'category-6-tonal-brown.pale', 'category-6-tonal-green', 'category-6-tonal-green.dark', 'category-6-tonal-green.deep', 'category-6-tonal-green.light', 'category-6-tonal-green.pale', 'category-6-tonal-orange', 'category-6-tonal-orange.dark', 'category-6-tonal-orange.deep', 'category-6-tonal-orange.light', 'category-6-tonal-orange.pale', 'category-6-tonal-purple', 'category-6-tonal-purple.dark', 'category-6-tonal-purple.deep', 'category-6-tonal-purple.light', 'category-6-tonal-purple.pale', 'dbt-creams', 'dbt-div-blue-red', 'dbt-div-blue-red-dark', 'dbt-div-coolwarm', 'dbt-div-coolwarm-dark', 'dbt-div-crimson-green', 'dbt-div-crimson-green-dark', 'dbt-div-orange-teal', 'dbt-div-orange-teal-dark', 'dbt-div-sunset', 'dbt-div-sunset-dark', 'dbt-grays', 'dbt-seq-amber', 'dbt-seq-amber-dark', 'dbt-seq-blue', 'dbt-seq-blue-dark', 'dbt-seq-brown', 'dbt-seq-brown-dark', 'dbt-seq-gray', 'dbt-seq-gray-dark', 'dbt-seq-green', 'dbt-seq-green-dark', 'dbt-seq-purple', 'dbt-seq-purple-dark', 'dbt-seq-rust', 'dbt-seq-rust-dark', 'dbt-seq-teal', 'dbt-seq-teal-dark', 'editorial-10', 'editorial-10.dark', 'editorial-10.deep', 'editorial-10.light', 'editorial-10.pale', 'hero-6', 'hero-6.dark', 'hero-6.deep', 'hero-6.light', 'hero-6.pale', 'info', 'negative', 'positive', 'tableau', 'tableau.dark', 'tableau.deep', 'tableau.light', 'tableau.pale', 'vivid-10', 'vivid-10.dark', 'vivid-10.deep', 'vivid-10.light', 'vivid-10.pale', 'warning'] | Theme palette role assignments: open dict mapping role name to palette file name. Default seed: chrome, info, negative, positive, warning, category, sequence, diverge. |
| `tones` | [KpiTonesStyle](#kpitonesstyle) | Semantic tone color palette (positive/negative/warning/info) for KPI support rows, table conditional glyphs, and spark negative_color. |
| `roles` | dict[str, str] | Optional top-level theme role aliases: bare name → role.alias. e.g. ink: chrome.heading |
| `padding` | str \| float \| [SpacingValues](#spacingvalues) | Per-board padding override (CSS shorthand or structured). |
| `margin` | str \| float \| [SpacingValues](#spacingvalues) | Per-board margin override (CSS shorthand or structured). |
| `gap` | str \| float | Gap between layout items in pixels. |

<a id="singlerowboolprobe"></a>
## SingleRowBoolProbe
Single-row boolean query probe.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `query` | str | Name of the query to execute. |
| `column` | str | Column in the single result row holding the boolean value. |

<a id="regional"></a>
## Regional
How a board writes numbers and dates: its d3 locales and currency symbol.

| Field | Type | Description |
|-------|------|-------------|
| `locale` | [RegionalLocale](#regionallocale) | The number and time locales. |
| `currency` | enum: "USD", "EUR", "GBP", "JPY", "CAD", "AUD", "CHF", "SEK", "NOK", "DKK", "INR", "CNY", "BRL", "MXN" | ISO 4217 code whose symbol replaces the locale's own in its currency template, at the locale's placement. Unset prints the locale's own. |

<a id="variableoptions"></a>
## VariableOptions
Options configuration for variable inputs.

| Field | Type | Description |
|-------|------|-------------|
| `static` | list[str] \| list[int \| float] | Option values written out in place, all strings or all numbers. Numeric options type the value the control sends back as a number unless data_type says otherwise. |
| `query` | str | Query name whose result rows provide option values. |
| `column` | str | Column in the query result to use as option values. |
| `label_column` | str | Column in the query result to use as display labels (separate from values). |

<a id="chartsort"></a>
## ChartSort
Chart-level sort configuration for categorical axes.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `by` | str | Column name to sort by. A category holding several rows (a color series, or a y: [...] list) is folded to one value of this column first, and on a bar that fold is the stacked total only when the chart stacks and this names its single y column; everything else, a y: [...] measure included, ranks by the smallest value the column holds in that category. Name a column that is constant within a category, or pre-aggregate in the query. |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `order` | enum: "asc", "desc" | Sort direction (asc or desc). |

<a id="multiplesconfig"></a>
## MultiplesConfig
Small-multiples partition, keyed by layout direction.

| Field | Type | Description |
|-------|------|-------------|
| `rows` | str | Column whose distinct values become vertically stacked panel rows. |
| `columns` | str | Column whose distinct values become side-by-side panel columns. |
| `scale` | enum: "shared", "independent" | Measure-scale sharing across panels. 'shared' (default) makes panels visually comparable; 'independent' gives each panel its own scale. |

<a id="chartsupporttable"></a>
## ChartSupportTable
Container for a chart's support_table block.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `entries` | list[str \| [ChartSupportTableSource](#chartsupporttablesource) \| [ChartSupportTableAggregate](#chartsupporttableaggregate) \| [ChartSupportTablePerSeries](#chartsupporttableperseries)] | List of support-table entries (source, aggregate, or per-series rows). A source entry may be written as a bare column name (`revenue` in place of `{source: revenue}`), the same scalar-listable spelling `y:` uses. |

<a id="barchartstyle"></a>
## BarChartStyle
Authored overlay for BarChartStyle. Bar chart style: chart-level fields + marks sub-block.

| Field | Type | Description |
|-------|------|-------------|
| `axis_quantitative` | [QuantitativeAxisStyle](#quantitativeaxisstyle) | Per-chart-type quantitative-axis overrides; None inherits the global axis_quantitative at render. |
| `title` | [ChartTitleStyle](#charttitlestyle) | Chart-level title style override; None inherits the theme title style. |
| `legend` | [LegendStyle](#legendstyle) | Chart legend style. |
| `preferred_width` | float | Preferred chart width in pixels. Falls back to [`style.charts.preferred_width`](#chartsstyle). |
| `padding` | [PaddingStyle](#paddingstyle) | Per-chart-type padding override; 4 sides in pixels. Unset fields fall back to [`style.charts.padding`](#chartsstyle). |
| `background` | str | Chart-local background color override; None inherits from theme. |
| `aspect_ratio` | float | Chart aspect ratio (width/height). Falls back to [`style.charts.aspect_ratio`](#chartsstyle). |
| `min_height` | float | Minimum chart height in pixels. Falls back to [`style.charts.min_height`](#chartsstyle). |
| `max_height` | float | Maximum chart height in pixels. Falls back to [`style.charts.max_height`](#chartsstyle). |
| `color` | [ColorStyle](#colorstyle) | Chart color: static mark paint, categorical palette, and/or gradient scale. |
| `axis` | [BaseAxisStyle](#baseaxisstyle) | Override applied to both x and y axes; None inherits the global axis at render. |
| `axis_x` | [AxisXStyle](#axisxstyle) | Per-chart-type x-axis style overrides; None inherits the global axis_x at render. |
| `axis_y` | [AxisYStyle](#axisystyle) | Per-chart-type y-axis style overrides; None inherits the global axis_y at render. |
| `axis_band` | [BandAxisStyle](#bandaxisstyle) | Per-chart-type categorical (band) axis overrides; None inherits the global band axis at render. |
| `support_table` | [SupportTableStyle](#supporttablestyle) | Per-chart-type support_table style override. Unset fields fall back to [`style.charts.support_table`](#chartsstyle). |
| `orientation` | enum: "horizontal", "vertical", "auto" | Preferred bar orientation; None behaves like 'auto', which picks horizontal for a categorical x and vertical for a continuous one (temporal, quantitative, or date-like). Never remaps x/y. |
| `stack` | enum: "none", "zero", "normalize", "center" | Default stack mode for bar charts; none renders side-by-side columns. |
| `overlap` | float \| enum: "auto", "none", "flush", "partial", "full" | Within-group spacing for grouped bars. Keywords: 'auto' (2 series → partial, 3+ → none), 'none' (small gap), 'flush' (bars touch), 'partial' (25% overlap), 'full' (bars coincide; an error unless each category holds one color). Or a number as a fraction of bar width: &gt;0 overlaps, 0 touches, &lt;0 gaps; 1 or more is 'full'. None uses the renderer default ('auto'). Only applies to grouped bars; setting it together with an active stack mode is an error. |
| `stack_order` | enum: "value", "data", "alphabetical" | Z-order of stacked segments. None/'value' puts the largest aggregate at baseline. 'data' stacks series in first-appearance order: SQL row order for color:, the listed order for y: [a, b, ...] (a measure null in the first rows appears later). 'alphabetical' sorts by series name. Ignored when stacking is off or there is only one series. |
| `endpoint_labels` | [EndpointLabelsConfig](#endpointlabelsconfig) | Series names printed on stacked bars instead of in a legend. |
| `grouped` | [BarGroupedStyle](#bargroupedstyle) | Band-scale padding for grouped bars. |
| `marks` | [BarChartMarksStyle](#barchartmarksstyle) | Bar-family mark overrides. Unset fields fall back to [`style.charts.marks`](#chartsstyle). |

<a id="barlayer"></a>
## BarLayer
A bar-type layer on a cartesian chart.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `type` | const: "bar" |  |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `query` | str | Query name for this layer's data (overrides chart-level query). |
| `x` | str | X-axis column name for this layer. |
| `y` | str | Y-axis column name for this layer. |
| `label` | str | Name for this layer's measure wherever the layer is identified. Defaults to its y column name. |
| `color` | str | Column whose values split this layer into colored series; bare column name only. Paint belongs under the layer's `style.marks`. |
| `axis_y` | [LayerAxisYStyle](#layeraxisystyle) | This layer's own y axis: which side it sits on, its title, scale, ticks, grid. |
| `style` | [BarLayerStyle](#barlayerstyle) | Appearance overrides for this layer's bar marks. |
| `y_start` | str | Column each bar starts from, so it runs from y_start to y instead of from zero. Same kind as the chart's y: both numeric, or both dates. |

<a id="linelayer"></a>
## LineLayer
A line-type layer on a cartesian chart.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `type` | const: "line" |  |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `query` | str | Query name for this layer's data (overrides chart-level query). |
| `x` | str | X-axis column name for this layer. |
| `y` | str | Y-axis column name for this layer. |
| `label` | str | Name for this layer's measure wherever the layer is identified. Defaults to its y column name. |
| `color` | str | Column whose values split this layer into colored series; bare column name only. Paint belongs under the layer's `style.marks`. |
| `axis_y` | [LayerAxisYStyle](#layeraxisystyle) | This layer's own y axis: which side it sits on, its title, scale, ticks, grid. |
| `style` | [LineLayerStyle](#linelayerstyle) | Appearance overrides for this layer's line marks. |

<a id="arealayer"></a>
## AreaLayer
An area-type layer on a cartesian chart.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `type` | const: "area" |  |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `query` | str | Query name for this layer's data (overrides chart-level query). |
| `x` | str | X-axis column name for this layer. |
| `y` | str | Y-axis column name for this layer. |
| `label` | str | Name for this layer's measure wherever the layer is identified. Defaults to its y column name. |
| `color` | str | Column whose values split this layer into colored series; bare column name only. Paint belongs under the layer's `style.marks`. |
| `axis_y` | [LayerAxisYStyle](#layeraxisystyle) | This layer's own y axis: which side it sits on, its title, scale, ticks, grid. |
| `style` | [AreaLayerStyle](#arealayerstyle) | Appearance overrides for this layer's area marks. |

<a id="scatterlayer"></a>
## ScatterLayer
A scatter-type layer on a cartesian chart.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `type` | const: "scatter" |  |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `query` | str | Query name for this layer's data (overrides chart-level query). |
| `x` | str | X-axis column name for this layer. |
| `y` | str | Y-axis column name for this layer. |
| `label` | str | Name for this layer's measure wherever the layer is identified. Defaults to its y column name. |
| `color` | str | Column whose values split this layer into colored series; bare column name only. Paint belongs under the layer's `style.marks`. |
| `axis_y` | [LayerAxisYStyle](#layeraxisystyle) | This layer's own y axis: which side it sits on, its title, scale, ticks, grid. |
| `style` | [ScatterLayerStyle](#scatterlayerstyle) | Appearance overrides for this layer's point marks. |

<a id="linechartstyle"></a>
## LineChartStyle
Authored overlay for LineChartStyle. Line chart style: chart-level fields + marks sub-block.

| Field | Type | Description |
|-------|------|-------------|
| `axis_quantitative` | [QuantitativeAxisStyle](#quantitativeaxisstyle) | Per-chart-type quantitative-axis overrides; None inherits the global axis_quantitative at render. |
| `title` | [ChartTitleStyle](#charttitlestyle) | Chart-level title style override; None inherits the theme title style. |
| `legend` | [LegendStyle](#legendstyle) | Chart legend style. |
| `preferred_width` | float | Preferred chart width in pixels. Falls back to [`style.charts.preferred_width`](#chartsstyle). |
| `padding` | [PaddingStyle](#paddingstyle) | Per-chart-type padding override; 4 sides in pixels. Unset fields fall back to [`style.charts.padding`](#chartsstyle). |
| `background` | str | Chart-local background color override; None inherits from theme. |
| `aspect_ratio` | float | Chart aspect ratio (width/height). Falls back to [`style.charts.aspect_ratio`](#chartsstyle). |
| `min_height` | float | Minimum chart height in pixels. Falls back to [`style.charts.min_height`](#chartsstyle). |
| `max_height` | float | Maximum chart height in pixels. Falls back to [`style.charts.max_height`](#chartsstyle). |
| `color` | [ColorStyle](#colorstyle) | Chart color: static mark paint, categorical palette, and/or gradient scale. |
| `axis` | [BaseAxisStyle](#baseaxisstyle) | Override applied to both x and y axes; None inherits the global axis at render. |
| `axis_x` | [AxisXStyle](#axisxstyle) | Per-chart-type x-axis style overrides; None inherits the global axis_x at render. |
| `axis_y` | [AxisYStyle](#axisystyle) | Per-chart-type y-axis style overrides; None inherits the global axis_y at render. |
| `axis_band` | [BandAxisStyle](#bandaxisstyle) | Per-chart-type categorical (band) axis overrides; None inherits the global band axis at render. |
| `support_table` | [SupportTableStyle](#supporttablestyle) | Per-chart-type support_table style override. Unset fields fall back to [`style.charts.support_table`](#chartsstyle). |
| `endpoint_labels` | [EndpointLabelsConfig](#endpointlabelsconfig) | Series names printed at the end of each line instead of in a legend. |
| `marks` | [LineChartMarksStyle](#linechartmarksstyle) | Line-family mark overrides. Unset fields fall back to [`style.charts.marks`](#chartsstyle). |

<a id="areachartstyle"></a>
## AreaChartStyle
Authored overlay for AreaChartStyle. Area chart style: chart-level fields + marks sub-block.

| Field | Type | Description |
|-------|------|-------------|
| `axis_quantitative` | [QuantitativeAxisStyle](#quantitativeaxisstyle) | Per-chart-type quantitative-axis overrides; None inherits the global axis_quantitative at render. |
| `title` | [ChartTitleStyle](#charttitlestyle) | Chart-level title style override; None inherits the theme title style. |
| `legend` | [LegendStyle](#legendstyle) | Chart legend style. |
| `preferred_width` | float | Preferred chart width in pixels. Falls back to [`style.charts.preferred_width`](#chartsstyle). |
| `padding` | [PaddingStyle](#paddingstyle) | Per-chart-type padding override; 4 sides in pixels. Unset fields fall back to [`style.charts.padding`](#chartsstyle). |
| `background` | str | Chart-local background color override; None inherits from theme. |
| `aspect_ratio` | float | Chart aspect ratio (width/height). Falls back to [`style.charts.aspect_ratio`](#chartsstyle). |
| `min_height` | float | Minimum chart height in pixels. Falls back to [`style.charts.min_height`](#chartsstyle). |
| `max_height` | float | Maximum chart height in pixels. Falls back to [`style.charts.max_height`](#chartsstyle). |
| `color` | [ColorStyle](#colorstyle) | Chart color: static mark paint, categorical palette, and/or gradient scale. |
| `axis` | [BaseAxisStyle](#baseaxisstyle) | Override applied to both x and y axes; None inherits the global axis at render. |
| `axis_x` | [AxisXStyle](#axisxstyle) | Per-chart-type x-axis style overrides; None inherits the global axis_x at render. |
| `axis_y` | [AxisYStyle](#axisystyle) | Per-chart-type y-axis style overrides; None inherits the global axis_y at render. |
| `axis_band` | [BandAxisStyle](#bandaxisstyle) | Per-chart-type categorical (band) axis overrides; None inherits the global band axis at render. |
| `support_table` | [SupportTableStyle](#supporttablestyle) | Per-chart-type support_table style override. Unset fields fall back to [`style.charts.support_table`](#chartsstyle). |
| `stack` | enum: "none", "zero", "normalize", "center" | Default stack mode for area charts: 'none', 'zero', 'normalize', or 'center'. |
| `stack_order` | enum: "value", "data", "alphabetical" | Z-order of stacked segments. None/'value' puts the largest aggregate at baseline. 'data' stacks series in first-appearance order: SQL row order for color:, the listed order for y: [a, b, ...] (a measure null in the first rows appears later). 'alphabetical' sorts by series name. Ignored when stacking is off or there is only one series. |
| `endpoint_labels` | [EndpointLabelsConfig](#endpointlabelsconfig) | Series names printed on the bands instead of in a legend. |
| `marks` | [AreaChartMarksStyle](#areachartmarksstyle) | Area-family mark overrides. Unset fields fall back to [`style.charts.marks`](#chartsstyle). |

<a id="scatterchartstyle"></a>
## ScatterChartStyle
Authored overlay for ScatterChartStyle. Scatter chart style: chart-level fields + marks sub-block.

| Field | Type | Description |
|-------|------|-------------|
| `axis_quantitative` | [QuantitativeAxisStyle](#quantitativeaxisstyle) | Per-chart-type quantitative-axis overrides; None inherits the global axis_quantitative at render. |
| `title` | [ChartTitleStyle](#charttitlestyle) | Chart-level title style override; None inherits the theme title style. |
| `legend` | [LegendStyle](#legendstyle) | Chart legend style. |
| `preferred_width` | float | Preferred chart width in pixels. Falls back to [`style.charts.preferred_width`](#chartsstyle). |
| `padding` | [PaddingStyle](#paddingstyle) | Per-chart-type padding override; 4 sides in pixels. Unset fields fall back to [`style.charts.padding`](#chartsstyle). |
| `background` | str | Chart-local background color override; None inherits from theme. |
| `aspect_ratio` | float | Chart aspect ratio (width/height). Falls back to [`style.charts.aspect_ratio`](#chartsstyle). |
| `min_height` | float | Minimum chart height in pixels. Falls back to [`style.charts.min_height`](#chartsstyle). |
| `max_height` | float | Maximum chart height in pixels. Falls back to [`style.charts.max_height`](#chartsstyle). |
| `color` | [ColorStyle](#colorstyle) | Chart color: static mark paint, categorical palette, and/or gradient scale. |
| `axis` | [BaseAxisStyle](#baseaxisstyle) | Override applied to both x and y axes; None inherits the global axis at render. |
| `axis_x` | [AxisXStyle](#axisxstyle) | Per-chart-type x-axis style overrides; None inherits the global axis_x at render. |
| `axis_y` | [AxisYStyle](#axisystyle) | Per-chart-type y-axis style overrides; None inherits the global axis_y at render. |
| `axis_band` | [BandAxisStyle](#bandaxisstyle) | Per-chart-type categorical (band) axis overrides; None inherits the global band axis at render. |
| `support_table` | [SupportTableStyle](#supporttablestyle) | Per-chart-type support_table style override. Unset fields fall back to [`style.charts.support_table`](#chartsstyle). |
| `marks` | [ScatterChartMarksStyle](#scatterchartmarksstyle) | Scatter-family mark overrides. Unset fields fall back to [`style.charts.marks`](#chartsstyle). |

<a id="heatmapchartstyle"></a>
## HeatmapChartStyle
Authored overlay for HeatmapChartStyle. Heatmap chart style.

| Field | Type | Description |
|-------|------|-------------|
| `title` | [ChartTitleStyle](#charttitlestyle) | Chart-level title style override; None inherits the theme title style. |
| `legend` | [LegendStyle](#legendstyle) | Chart legend style. |
| `preferred_width` | float | Preferred chart width in pixels. Falls back to [`style.charts.preferred_width`](#chartsstyle). |
| `padding` | [PaddingStyle](#paddingstyle) | Per-chart-type padding override; 4 sides in pixels. Unset fields fall back to [`style.charts.padding`](#chartsstyle). |
| `background` | str | Chart-local background color override; None inherits from theme. |
| `aspect_ratio` | float | Chart aspect ratio (width/height). Falls back to [`style.charts.aspect_ratio`](#chartsstyle). |
| `min_height` | float | Minimum chart height in pixels. Falls back to [`style.charts.min_height`](#chartsstyle). |
| `max_height` | float | Maximum chart height in pixels. Falls back to [`style.charts.max_height`](#chartsstyle). |
| `color` | [ColorStyle](#colorstyle) | Chart color: static mark paint, categorical palette, and/or gradient scale. |
| `axis` | [BaseAxisStyle](#baseaxisstyle) | Override applied to both x and y axes; None inherits the global axis at render. |
| `axis_x` | [AxisXStyle](#axisxstyle) | Per-chart-type x-axis style overrides; None inherits the global axis_x at render. |
| `axis_y` | [AxisYStyle](#axisystyle) | Per-chart-type y-axis style overrides; None inherits the global axis_y at render. |
| `axis_band` | [BandAxisStyle](#bandaxisstyle) | Per-chart-type categorical (band) axis overrides; None inherits the global band axis at render. |
| `support_table` | [SupportTableStyle](#supporttablestyle) | Per-chart-type support_table style override. Unset fields fall back to [`style.charts.support_table`](#chartsstyle). |
| `cell_padding` | float | Padding between heatmap cells in pixels. |
| `marks` | [HeatmapChartMarksStyle](#heatmapchartmarksstyle) | Heatmap-family mark overrides. Unset fields fall back to [`style.charts.marks`](#chartsstyle). |

<a id="charttotal"></a>
## ChartTotal
Donut center total: auto-rendered sum at the center of a donut, with author override.

| Field | Type | Description |
|-------|------|-------------|
| `visible` | bool | Whether to render the donut center total. Defaults True; set False to suppress the auto-rendered center on donuts whose theta values aren't a meaningful sum (e.g. pre-aggregated percentage shares). |
| `label` | str | Caption text displayed below the center total value. |

<a id="piechartstyle"></a>
## PieChartStyle
Authored overlay for PieChartStyle. Pie/donut chart style: geometry + total (flat) + marks sub-block.

| Field | Type | Description |
|-------|------|-------------|
| `title` | [ChartTitleStyle](#charttitlestyle) | Chart-level title style override; None inherits the theme title style. |
| `legend` | [PieLegendStyle](#pielegendstyle) | Pie key style. |
| `preferred_width` | float | Preferred chart width in pixels. Falls back to [`style.charts.preferred_width`](#chartsstyle). |
| `padding` | [PaddingStyle](#paddingstyle) | Per-chart-type padding override; 4 sides in pixels. Unset fields fall back to [`style.charts.padding`](#chartsstyle). |
| `background` | str | Chart-local background color override; None inherits from theme. |
| `aspect_ratio` | float | Aspect ratio (width/height) of the pie chart viewport. |
| `min_height` | float | Minimum chart height in pixels. Falls back to [`style.charts.min_height`](#chartsstyle). |
| `max_height` | float | Maximum chart height in pixels. Falls back to [`style.charts.max_height`](#chartsstyle). |
| `color` | [ColorStyle](#colorstyle) | Chart color: static mark paint, categorical palette, and/or gradient scale. |
| `inner_radius` | float | Hole-to-disk ratio 0–1 (inner radius / outer radius). 0 is a solid pie. A `type: donut` chart reads `charts.donut` over this. |
| `total` | [TotalStyle](#totalstyle) | Donut center total paint (value and label). |
| `marks` | [PieChartMarksStyle](#piechartmarksstyle) | Pie-family mark overrides. Unset fields fall back to [`style.charts.marks`](#chartsstyle). |

<a id="fieldconditionalformatting"></a>
## FieldConditionalFormatting
Conditional formatting rules scoped to a single column.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `when` | list[[ConditionalRule](#conditionalrule)] | Ordered list of conditional rules. The first matching rule applies; a 'default: true' rule must be last. |

<a id="kpisupportconfig"></a>
## KpiSupportConfig
Support-line block authored alongside a KPI's main value.

| Field | Type | Description |
|-------|------|-------------|
| `value` | str | Column reference (string column name) for the support number/text. |
| `label` | str | Trailing explainer text rendered beside the support value. |
| `glyph` | str | Text shown before the value (e.g. '▲', '▼', '●'). |

<a id="kpichartstyle"></a>
## KpiChartStyle
Authored overlay for KpiChartStyle. Produced by cascade from theme YAML.

| Field | Type | Description |
|-------|------|-------------|
| `preferred_width` | float | Preferred chart width in pixels. Falls back to [`style.charts.preferred_width`](#chartsstyle). |
| `padding` | [PaddingStyle](#paddingstyle) | Per-chart-type padding override; 4 sides in pixels. Unset fields fall back to [`style.charts.padding`](#chartsstyle). |
| `background` | str | Chart-local background color override; None inherits from theme. |
| `font` | [SingleLineFontStyle](#singlelinefontstyle) | Font every KPI text slot starts from. Unset fields fall back to [`style.charts.font`](#chartsstyle). |
| `variant` | enum: "stacked", "inline", "compact" | Card layout. 'stacked' puts value, label, and support on three lines; 'inline' sets them on one baseline; 'compact' puts the value left and up to two lines right. |
| `value` | [KpiValueStyle](#kpivaluestyle) | KPI headline value slot. |
| `label` | [KpiLabelStyle](#kpilabelstyle) | KPI card label slot. |
| `support` | [KpiSupportStyle](#kpisupportstyle) | KPI support row slot. |
| `min_card_width` | float | Minimum KPI card width in pixels. |
| `default_height` | float | Default KPI card height in pixels. |
| `border` | str \| [BorderStyle](#borderstyle) | KPI card border style. Unset fields fall back to [`style.charts.border`](#chartsstyle). |
| `content_padding` | str \| float \| [SpacingValues](#spacingvalues) | Inner inset (top/right/bottom/left) for KPI card content in pixels. |
| `align` | enum: "left", "center", "right" | Horizontal alignment of the value, label, and support text within the card. |

<a id="tablechartstyle"></a>
## TableChartStyle
Authored overlay for TableChartStyle. Table chart style overrides layered on top of shared chart defaults.

| Field | Type | Description |
|-------|------|-------------|
| `title` | [ChartTitleStyle](#charttitlestyle) | Chart-level title style override; None inherits the theme title style. |
| `preferred_width` | float | Width the board asks for when sizing to a table before its data is known. With data, a board with no width measures the table's columns instead. Only a value set on the chart itself pins the width; a board- or theme-level value is just the estimate used before data is known. Falls back to [`style.charts.preferred_width`](#chartsstyle). |
| `padding` | [PaddingStyle](#paddingstyle) | Per-chart-type padding override; 4 sides in pixels. Unset fields fall back to [`style.charts.padding`](#chartsstyle). |
| `background` | str | Table background color; None inherits from theme. |
| `font` | [FontStyle](#fontstyle) | Table chart-level font overrides. Unset fields fall back to [`style.charts.font`](#chartsstyle). |
| `border` | str \| [BorderStyle](#borderstyle) | Chart card border style. Unset fields fall back to [`style.charts.border`](#chartsstyle). |
| `color` | [StaticGradientColorStyle](#staticgradientcolorstyle) | Table color: static text paint or gradient scale only (no categorical arm). |
| `outer_padding` | float | Outer table padding in pixels. |
| `bottom_padding` | float | Extra bottom padding below the last row in pixels. |
| `column_layout` | [TableColumnsStyle](#tablecolumnsstyle) | Default column width and cell padding settings. |
| `header` | [TableHeaderStyle](#tableheaderstyle) | Table header row style. |
| `row` | [TableRowStyle](#tablerowstyle) | Table body row style. |
| `row_numbers` | [TableRowNumbersStyle](#tablerownumbersstyle) | Leading row-number column configuration. |
| `title_row` | [TableTitleStyle](#tabletitlestyle) | Title block rendered above the header row. |
| `wrap` | bool | Allow cell text wrapping; false clips to single line. |
| `pagination` | [PaginationConfig](#paginationconfig) | Client-side pagination defaults for table charts. |
| `column_defaults` | [TableColumnDefaultsConfig](#tablecolumndefaultsconfig) | Table-level column defaults applied to every column; None means no defaults authored. |
| `columns` | dict[str, [TableColumnConfig](#tablecolumnconfig)] | Per-column display configuration keyed by column name (label, format, width, etc.). |
| `header_overflow` | enum: "clip", "truncate", "wrap-two", "wrap" | Table column header text overflow mode; None inherits from theme. |
| `paginator` | [PaginatorStyle](#paginatorstyle) | Visual style for the paginator control (chevrons + page numbers). |
| `symbol_mode` | enum: "all", "anchors" | Where to show currency-prefix and magnitude/unit suffix symbols in a numeric column. 'all' shows the full formatted value on every row; 'anchors' shows it only on the first data row and summary/total rows, stripping prefix and suffix from plain middle rows so the anchors guide the reader at the top and bottom of the value field. |
| `more_rows` | [TableEdgeStyle](#tableedgestyle) | Style for the 'more rows' edge-case indicator. |
| `empty_state` | [TableEdgeStyle](#tableedgestyle) | Style for the empty-state (no data) indicator. |
| `spark` | [SparkStyle](#sparkstyle) | Inline sparkline defaults for table cells. |
| `transpose` | bool | When True, render a single wide data row as N (label, value) rows, one per column. Raises ChartDataError when data has more than one row. Used for Looker single-value summary tiles with multiple measures. |
| `text_baseline_offset` | float | Vertical offset to align SVG text baseline with cell grid in pixels. |
| `title_subtitle_gap` | float | Pure whitespace between the title's descent and the subtitle's ascent, in pixels, not a baseline-to-baseline distance. Combined with the title and subtitle font sizes to reproduce Vega-Lite's title-&gt;subtitle spacing at any font size, not one calibrated pair. Font size and color for the subtitle itself come from style.title.subtitle (the same source chart-family titles use), not a table-local constant. |

<a id="tablespanner"></a>
## TableSpanner
One authored spanner: a label drawn over a run of adjacent columns.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `label` | str | Group label for the listed columns. |
| `columns` | list[str] | Query columns the spanner covers. Must be adjacent in the query's column order and unique; a column may sit in at most one spanner. |

<a id="projection"></a>
## Projection
A Vega-Lite projection; any other Vega-Lite projection property is accepted.

| Field | Type | Description |
|-------|------|-------------|
| `type` | str | Projection name, such as mercator. |

<a id="basemapconfig"></a>
## BasemapConfig
Styled geographic background layer for point_map and bubble_map charts.

| Field | Type | Description |
|-------|------|-------------|
| `source` | str | Named geographic boundary source (e.g. 'us-states') for overlay rendering. |
| `fill` | str | Fill color for geographic boundary overlay. |
| `stroke` | str | Stroke color for geographic boundary overlay. |

<a id="pointmapchartstyle"></a>
## PointMapChartStyle
Authored overlay for PointMapChartStyle. Point map chart style.

| Field | Type | Description |
|-------|------|-------------|
| `title` | [ChartTitleStyle](#charttitlestyle) | Chart-level title style override; None inherits the theme title style. |
| `legend` | [LegendStyle](#legendstyle) | Chart legend style. |
| `preferred_width` | float | Preferred chart width in pixels. Falls back to [`style.charts.preferred_width`](#chartsstyle). |
| `padding` | [PaddingStyle](#paddingstyle) | Per-chart-type padding override; 4 sides in pixels. Unset fields fall back to [`style.charts.padding`](#chartsstyle). |
| `background` | str | Chart-local background color override; None inherits from theme. |
| `aspect_ratio` | float | Chart aspect ratio (width/height). Falls back to [`style.charts.aspect_ratio`](#chartsstyle). |
| `min_height` | float | Minimum chart height in pixels. Falls back to [`style.charts.min_height`](#chartsstyle). |
| `max_height` | float | Maximum chart height in pixels. Falls back to [`style.charts.max_height`](#chartsstyle). |
| `color` | [StaticGradientColorStyle](#staticgradientcolorstyle) | Geo color: static paint or gradient scale only (no categorical arm). |
| `font` | [FontStyle](#fontstyle) | Chart-level font overrides. |
| `border` | str \| [BorderStyle](#borderstyle) | Chart card border style. Unset fields fall back to [`style.charts.border`](#chartsstyle). |
| `projection` | [ProjectionStyle](#projectionstyle) | Vega-Lite projection configuration for this geo family. |
| `basemap` | [BasemapStyle](#basemapstyle) | Background map layer; None source = no topo layer. |
| `marks` | [PointMapChartMarksStyle](#pointmapchartmarksstyle) | Point-map-family mark overrides. Unset fields fall back to [`style.charts.marks`](#chartsstyle). |

<a id="geoshapechartstyle"></a>
## GeoshapeChartStyle
Authored overlay for GeoshapeChartStyle. Geoshape (choropleth) chart style.

| Field | Type | Description |
|-------|------|-------------|
| `title` | [ChartTitleStyle](#charttitlestyle) | Chart-level title style override; None inherits the theme title style. |
| `legend` | [LegendStyle](#legendstyle) | Chart legend style. |
| `preferred_width` | float | Preferred chart width in pixels. Falls back to [`style.charts.preferred_width`](#chartsstyle). |
| `padding` | [PaddingStyle](#paddingstyle) | Per-chart-type padding override; 4 sides in pixels. Unset fields fall back to [`style.charts.padding`](#chartsstyle). |
| `background` | str | Chart-local background color override; None inherits from theme. |
| `aspect_ratio` | float | Chart aspect ratio (width/height). Falls back to [`style.charts.aspect_ratio`](#chartsstyle). |
| `min_height` | float | Minimum chart height in pixels. Falls back to [`style.charts.min_height`](#chartsstyle). |
| `max_height` | float | Maximum chart height in pixels. Falls back to [`style.charts.max_height`](#chartsstyle). |
| `color` | [StaticGradientColorStyle](#staticgradientcolorstyle) | Geo color: static paint or gradient scale only (no categorical arm). |
| `font` | [FontStyle](#fontstyle) | Chart-level font overrides. |
| `border` | str \| [BorderStyle](#borderstyle) | Chart card border style. Unset fields fall back to [`style.charts.border`](#chartsstyle). |
| `projection` | [ProjectionStyle](#projectionstyle) | Vega-Lite projection configuration for this geo family. |
| `basemap` | [BasemapStyle](#basemapstyle) | Background map layer; None source = no topo layer. |
| `marks` | [GeoshapeChartMarksStyle](#geoshapechartmarksstyle) | Geoshape-family mark overrides. Unset fields fall back to [`style.charts.marks`](#chartsstyle). |

<a id="calloutchartstyle"></a>
## CalloutChartStyle
Authored overlay for CalloutChartStyle. Chart-family style for ``type: callout`` charts and runtime chart-error fallback cards.

| Field | Type | Description |
|-------|------|-------------|
| `preferred_width` | float | Preferred callout width in pixels. |
| `tone` | enum: "positive", "negative", "warning", "info" | Semantic tone for palette-role lookup (info \| positive \| negative \| warning). |
| `background` | str | Callout card background color. `by_tone` is the tone's color. |
| `border` | str \| [BorderStyle](#borderstyle) | Callout card border style. A color of `by_tone` is the tone's color. |
| `padding` | [PaddingStyle](#paddingstyle) | Per-chart-type padding override; 4 sides in pixels. Unset fields fall back to [`style.charts.padding`](#chartsstyle). |
| `section_gap` | float | Vertical gap between callout title and message in pixels. |
| `title` | [CalloutElementStyle](#calloutelementstyle) | Callout title element style. |
| `message` | [CalloutElementStyle](#calloutelementstyle) | Callout message element style. |

<a id="sparkbarchartstyle"></a>
## SparkBarChartStyle
Authored overlay for SparkBarChartStyle. Produced by cascade from theme YAML.

| Field | Type | Description |
|-------|------|-------------|
| `preferred_width` | float | Preferred spark_bar chart width in pixels. |
| `min_width` | float | Minimum spark_bar chart width in pixels. |
| `padding` | [PaddingStyle](#paddingstyle) | Per-chart-type padding override; 4 sides in pixels. Unset fields fall back to [`style.charts.padding`](#chartsstyle). |
| `bar` | [SparkBarBarStyle](#sparkbarbarstyle) | Bar geometry (height, padding, color). |
| `label` | [SparkBarChartLabelStyle](#sparkbarchartlabelstyle) | Category-label column (visibility, reserved width). |
| `count` | [SparkBarCountStyle](#sparkbarcountstyle) | Count-value column (visibility, reserved width). |
| `max_bars` | int | Maximum number of bars to render. |
| `font` | [FontStyle](#fontstyle) | Spark_bar font style overrides. Unset fields fall back to [`style.charts.font`](#chartsstyle). |
| `border` | [CornerStyle](#cornerstyle) | Spark_bar outer corner rounding. |
| `subtitle` | [SubtitleStyle](#subtitlestyle) | Spark_bar subtitle font-sizing constants. |

<a id="customchartstyle"></a>
## CustomChartStyle
Sizing for a custom chart; its look comes from the board's `style:`.

| Field | Type | Description |
|-------|------|-------------|
| `aspect_ratio` | float | Chart aspect ratio (width/height). |
| `min_height` | float | Minimum chart height in pixels. |
| `max_height` | float | Maximum chart height in pixels. |

<a id="griditem"></a>
## GridItem
Grid layout item with position and span.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `item` | str \| [Board](#board) \| [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| [CustomChart](#customchart) \| dict[str, [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| [CustomChart](#customchart)] | Chart name or inline chart/board definition to place in this grid cell. |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `col` | int | Column position (0-indexed). Auto-placed if omitted. |
| `row` | int | Row position (0-indexed). Auto-placed if omitted. |
| `col_span` | int | Number of columns to span (width in grid units). Zero or a positive number; 0 is treated as unset and falls back to width, then to 1. |
| `row_span` | int | Number of rows to span (height in grid units). Zero or a positive number; 0 is treated as unset and falls back to height, then to 1. |
| `width` | int | Alias for col_span (more intuitive name). Zero or a positive number; used only when col_span is unset or 0, and 0 here also falls back to 1. |
| `height` | int | Alias for row_span (more intuitive name). Zero or a positive number; used only when row_span is unset or 0, and 0 here also falls back to 1. |
| `notes` | str | Optional metadata for AI search. Emitted into the SVG DOM as a data-layout-notes attribute; never painted as visible pixels. |

<a id="tabitem"></a>
## TabItem
Tab layout item.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `title` | str | Tab label displayed in the tab bar. |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `icon` | str | Optional icon shown in the tab (e.g., emoji or icon name). |
| `notes` | str | Optional metadata for AI search. Emitted into the SVG DOM as a data-layout-notes attribute; never painted as visible pixels. |
| `text` | str | Markdown text content shown in this tab. |
| `style` | [Style](#style) | Appearance overrides for this tab's content area. |
| `rows` | list[str \| [Board](#board) \| [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| [CustomChart](#customchart) \| dict[str, [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| [CustomChart](#customchart)]] | Vertical stack layout for this tab's content. |
| `cols` | list[str \| [Board](#board) \| [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| [CustomChart](#customchart) \| dict[str, [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| [CustomChart](#customchart)]] | Horizontal layout for this tab's content. |
| `grid` | [GridLayout](#gridlayout) | CSS-grid layout for this tab's content. |
| `tabs` | [TabLayout](#tablayout) | A further set of tabs opening inside this one. |

<a id="framestyle"></a>
## FrameStyle
Authored overlay for FrameStyle. Board-level structural dimensions; cascades to child boards.

| Field | Type | Description |
|-------|------|-------------|
| `width` | float | Exact board width in pixels. Set it, on a board, a template it extends, or a project's meta.yml, and the board is exactly this wide; the layout distributes it. Leave it unset and the board sizes itself to its content, bounded by max_width. Rendered as an on-screen pixel size everywhere except the dct HTML page (dct serve, dct render --format html), which scales the board to its container. |
| `max_width` | float | Widest a board without an exact width may grow, in pixels. A board with no width of its own measures its charts' preferred widths and hugs them up to this bound: a single small chart stays a small card. Ignored when width is set. Themes supply the default; a project's meta.yml can lower or raise it. |
| `min_height` | float | Minimum board height in pixels. |
| `margin` | float | Board outer margin in pixels. |
| `card_padding` | float | Padding added to each card side in pixels. |
| `card_gap` | float | Gap between cards in pixels. |

<a id="rootfontstyle"></a>
## RootFontStyle
Authored overlay for RootFontStyle. Root-level font configuration: FontStyle fields plus a required emoji mode.

| Field | Type | Description |
|-------|------|-------------|
| `family` | str | Font family name (e.g., 'sans-serif', 'Roboto'). |
| `color` | str | Text color as a CSS color string. |
| `size` | float | Font size in pixels. |
| `weight` | str \| float | How heavy the type is drawn (e.g., 'bold', 400, 700). |
| `style` | enum: "normal", "italic" | Upright or slanted type (normal or italic). |
| `decoration` | enum: "none", "line-through", "underline" | Line drawn on the text (underline, line-through, or none). |
| `case` | enum: "none", "sentence", "title", "upper", "lower", "slug", "camel" | Letter-case transform applied at render time. 'title' uses Chicago/Gruber rules and preserves tokens with internal capitals (ARR, iPhone). 'sentence' uppercases only the first character. 'none' (default) emits the string without any letter-case change. |
| `line_height` | float | Line height as a unitless multiple of font size. Cascades through Style.font to all text roles that carry a FontStyle slot. Body prose defaults to 1.25; titles override tighter via their font patch in theme YAML. |
| `emoji` | enum: "monochrome", "system-default", "disabled" | Emoji rendering mode for the dashboard font stack. |

<a id="borderstyle"></a>
## BorderStyle
Box border. Does NOT cascade: box properties reset per level.

| Field | Type | Description |
|-------|------|-------------|
| `radius` | float | Border corner radius in pixels. |
| `color` | str | Border color (CSS color string). |
| `width` | float | Border width in pixels. |
| `dash_array` | list[float] | SVG stroke-dasharray pattern in pixels (e.g. [4, 4]). None means a solid border. |
| `line_cap` | enum: "butt", "round", "square" | How each dash's ends are finished on a dashed border. None uses the renderer default (butt). |
| `dash_offset` | float | How far into the dash pattern the line starts, in pixels. None means 0. |

<a id="titlestyle"></a>
## TitleStyle
Authored overlay for TitleStyle. Typography shared by every heading: board, prose, chart, table, and spark titles.

| Field | Type | Description |
|-------|------|-------------|
| `compact_weight` | str \| float | Object-title font weight on tiny cards. |
| `width_offsets` | [TitleWidthOffsetsStyle](#titlewidthoffsetsstyle) | Additive level offsets by card width (tiny/narrow/medium/wide). Object titles add the tier offset to a fixed anchor to pick an H slot from ``style.fonts.heading.sizes``. Board/prose titles are level-only and do not consult these. |
| `min_height` | float | Minimum title row height in pixels. |
| `overflow` | enum: "clip", "truncate", "wrap-two", "wrap" | Text overflow mode (clip, truncate, wrap-two, wrap). |
| `position` | [TitlePositionStyle](#titlepositionstyle) | Vega-Lite title positioning: anchor, angle, offset, baseline. |
| `level` | int \| const: "auto" | Heading level override for board titles. ``'auto'`` (default) computes the level semantically as the count of titled ancestors. An integer value locks all titles in this board and its descendants to that H-level. |
| `subtitle` | [TitleSubtitleStyle](#titlesubtitlestyle) | Subtitle font styles. |
| `font` | [FontStyle](#fontstyle) | Title font style overrides. Unset fields fall back to [`style.font`](#style). |

<a id="textstyle"></a>
## TextStyle
Authored overlay for TextStyle. Markdown / plain text content.

| Field | Type | Description |
|-------|------|-------------|
| `font` | [FontStyle](#fontstyle) | Text font style overrides. Unset fields fall back to [`style.font`](#style). |
| `align` | enum: "left", "center", "right" | Text alignment for the board body-text block. |
| `paragraph` | [BlockMarginStyle](#blockmarginstyle) | Spacing above/below each paragraph block (in line-height units). |
| `heading` | [BlockMarginStyle](#blockmarginstyle) | Spacing above/below heading blocks (H1–H6) in line-height units. |
| `column` | [TextColumnStyle](#textcolumnstyle) | Multi-column layout for the board body-text block. |
| `code` | [TextCodeStyle](#textcodestyle) | Inline + fenced code box styling (font, background, border). |
| `blockquote` | [TextBlockquoteStyle](#textblockquotestyle) | Blockquote box styling (font, background, border/left bar). |
| `bold` | [TextBoldStyle](#textboldstyle) | Inline bold-run styling (weight), distinct from heading weight. |
| `divider` | [DividerStyle](#dividerstyle) | Markdown horizontal rules (`---`) and markdown-table gridlines. |

<a id="placeholderstyle"></a>
## PlaceholderStyle
Authored overlay for PlaceholderStyle.

| Field | Type | Description |
|-------|------|-------------|
| `opacity` | float | Opacity of the placeholder overlay (0–1). |
| `overlay` | [PlaceholderOverlay](#placeholderoverlay) | Overlay text and background style. |

<a id="chartsstyle"></a>
## ChartsStyle
Authored overlay for ChartsStyle. Registry of all chart-type styles plus shared chart configuration.

| Field | Type | Description |
|-------|------|-------------|
| `legend` | [LegendStyle](#legendstyle) | Chart legend style. |
| `preferred_width` | float | Preferred chart width in pixels. |
| `padding` | [PaddingStyle](#paddingstyle) | Per-chart-type padding override; 4 sides in pixels. |
| `background` | str | Chart canvas background; None inherits from the board background via apply_inherit. Falls back to [`style.background`](#style). |
| `aspect_ratio` | float | Chart aspect ratio (width/height). |
| `min_height` | float | Minimum chart height in pixels. |
| `max_height` | float | Maximum chart height in pixels. |
| `color` | [ColorStyle](#colorstyle) | Chart color: static mark paint, categorical palette, and/or gradient scale. |
| `font` | [FontStyle](#fontstyle) | Chart-level font overrides. Unset fields fall back to [`style.font`](#style). |
| `border` | str \| [BorderStyle](#borderstyle) | Border around every chart card; callout cards keep their own. |
| `title` | [ChartTitleStyle](#charttitlestyle) | Title style for every chart's title. Unset fields fall back to [`style.title`](#style). |
| `category_colors` | dict[str, [CategoryColorBinding](#categorycolorbinding)] | Board-wide category→color bindings, keyed by data field name. Pins a category to one swatch across every chart on the board. |
| `tooltip` | [TooltipStyle](#tooltipstyle) | Board-wide chart tooltip style. |
| `hover_emphasis` | [HoverEmphasisStyle](#hoveremphasisstyle) | Board-wide switch for hover emphasis on charts. |
| `dashes` | list[list[int]] | Ordered list of Vega-Lite strokeDash arrays for line-family categorical encoding; None disables dash emission. |
| `default_chart_height` | float | Fallback chart height in pixels when aspect-ratio sizing is unavailable. |
| `default_table_height` | float | Placeholder table height in pixels; replaced by data-aware row-count sizing at render time. |
| `label_usable_ratio` | float | Fraction of chart width usable for axis labels (0–1); labels are tilted when full labels exceed this width. |
| `axis` | [BaseAxisStyle](#baseaxisstyle) | Shared axis style applied to all axes before per-axis overrides. |
| `axis_x` | [AxisXStyle](#axisxstyle) | X-axis style overrides applied after the shared axis. Unset fields fall back to style.charts.axis. |
| `axis_y` | [AxisYStyle](#axisystyle) | Y-axis style overrides applied after the shared axis. Unset fields fall back to style.charts.axis. |
| `axis_quantitative` | [QuantitativeAxisStyle](#quantitativeaxisstyle) | Quantitative axis style overrides applied after axis_x/axis_y. Unset fields fall back to style.charts.axis. |
| `view` | [ViewStyle](#viewstyle) | Vega-Lite view dimensions and border. |
| `marks` | [GlobalMarksStyle](#globalmarksstyle) | Global mark defaults (tier-1 of the marks cascade). |
| `bar` | [BarChartStyle](#barchartstyle) | Bar chart style; histogram has its own block. |
| `line` | [LineChartStyle](#linechartstyle) | Line chart style. |
| `area` | [AreaChartStyle](#areachartstyle) | Area chart style. |
| `scatter` | [ScatterChartStyle](#scatterchartstyle) | Scatter chart style. |
| `histogram` | [HistogramChartStyle](#histogramchartstyle) | Histogram chart style. |
| `heatmap` | [HeatmapChartStyle](#heatmapchartstyle) | Heatmap chart style. |
| `geoshape` | [GeoshapeChartStyle](#geoshapechartstyle) | Geoshape (choropleth) chart style. |
| `point_map` | [PointMapChartStyle](#pointmapchartstyle) | Point map chart style. |
| `pie` | [PieChartStyle](#piechartstyle) | Pie/donut chart style. |
| `donut` | [PieChartStyle](#piechartstyle) | Donut overrides, applied over `pie`: a board's pie or donut style reaches every donut, and `donut` styles donuts only. |
| `series_label` | [SeriesLabelStyle](#serieslabelstyle) | Shared series-label typography for endpoint and stack labels. |
| `kpi` | [KpiChartStyle](#kpichartstyle) | KPI card chart style. |
| `table` | [TableChartStyle](#tablechartstyle) | Table chart style. |
| `spark_bar` | [SparkBarChartStyle](#sparkbarchartstyle) | Spark_bar (full-chart horizontal bar) style. |
| `support_table` | [SupportTableStyle](#supporttablestyle) | Attached support_table strip style. |
| `callout` | [CalloutChartStyle](#calloutchartstyle) | Callout chart-family style for type:callout and runtime fallback cards. |

<a id="layoutstyle"></a>
## LayoutStyle
Authored overlay for LayoutStyle.

| Field | Type | Description |
|-------|------|-------------|
| `rows` | [LayoutGapStyle](#layoutgapstyle) | Gap sizing between rows. |
| `cols` | [LayoutGapStyle](#layoutgapstyle) | Gap sizing between columns. |
| `grid` | [GridLayoutStyle](#gridlayoutstyle) | Grid layout configuration. |
| `tabs` | [TabsStyle](#tabsstyle) | Tabs layout style. |
| `details` | [DetailsStyle](#detailsstyle) | Details (accordion) layout style. |

<a id="variablesstyle"></a>
## VariablesStyle
Authored overlay for VariablesStyle. Variable controls chrome styling.

| Field | Type | Description |
|-------|------|-------------|
| `visible` | bool | Show the variables control panel. |
| `position` | enum: "top", "bottom", "title-inline" | Variables strip placement: stacked under the title (top/bottom) or on one horizontal band with the board title (title-inline). |
| `title_inline_band_bottom_pad` | float | Bottom padding in pixels added below the title-inline band. |
| `gap` | float | Gap between variable controls in pixels. |
| `label_position` | str | Position of labels relative to their input controls (e.g. 'left', 'top'). |
| `title_inline_title_max_width` | float | When position is title-inline: max title column width in px. 0 means no cap (title uses remaining width after reserving space for variables). |
| `font` | [FontStyle](#fontstyle) | Variables panel base font style overrides. Unset fields fall back to [`style.font`](#style). |
| `label` | [VariablesLabelStyle](#variableslabelstyle) | Variable label typography. |
| `value` | [VariablesValueStyle](#variablesvaluestyle) | Variable value typography. |
| `placeholder` | [VariablesPlaceholderStyle](#variablesplaceholderstyle) | Style for unselected/hint text in variable inputs. |
| `container_height` | float | Height of the variables panel container in pixels. |
| `border` | str \| [BorderStyle](#borderstyle) | Variables panel border style. |
| `control_gap` | float | Gap between label and input within a single control in pixels. |
| `input` | [InputStyle](#inputstyle) | Input control style. |

<a id="footerstyle"></a>
## FooterStyle
Authored overlay for FooterStyle. Page footer chrome: visibility, attribution text, font, and divider.

| Field | Type | Description |
|-------|------|-------------|
| `visible` | bool | Show the footer attribution line. |
| `text` | str | Attribution text shown in the footer. |
| `link` | str | URL the footer brand phrase 'dbt charts' links to; null renders plain text. |
| `font` | [FontStyle](#fontstyle) | Footer text font style (size and color required). Unset fields fall back to [`style.font`](#style). |
| `y_offset` | float | Vertical offset from bottom edge in pixels. |
| `brand_weight` | enum: 500, 600 | Font weight of the footer brand phrase. |
| `divider` | [FooterDividerStyle](#footerdividerstyle) | Hairline above the footer text. |

<a id="timestampstyle"></a>
## TimestampStyle
Authored overlay for TimestampStyle. Authored data-freshness chrome: visibility, placement, strftime format, font, and y-offset.

| Field | Type | Description |
|-------|------|-------------|
| `visible` | bool | Show the data-freshness line. |
| `position` | enum: "top", "footer" | Timestamp row: top page chrome or footer baseline. |
| `align` | enum: "left", "right" | Timestamp horizontal alignment within its row. |
| `format` | str | strftime format for the data-freshness line, including any literal label text (e.g. '%H:%M %Z on %-d %b %Y'). The value is always UTC; a format that prints a clock must disclose the zone (%Z or a literal 'UTC'), else compile rejects it: an unlabeled clock reads as local. |
| `y` | float | Y-coordinate for top-positioned timestamp in pixels. |
| `gap` | float | Horizontal gap between the footer timestamp and the attribution. |
| `font` | [FontStyle](#fontstyle) | Timestamp font style overrides (size, color, weight, ...). Unset fields fall back to [`style.font`](#style). |

<a id="formatconfig"></a>
## FormatConfig
Format configuration for value display.

| Field | Type | Description |
|-------|------|-------------|
| `spec` | str | D3 format string (e.g., ',.0f'), preset name (e.g., 'currency'), or Excel pattern. |
| `prefix` | str | Text placed before the formatted value (e.g., '$'). |
| `suffix` | str | Text placed after the formatted value (e.g., ' USD', '%'). |
| `notation` | enum: "analytic", "narrative" | Notation style: 'analytic' for SI-prefix (1B, 1M) or 'narrative' for prose-style (1bn, 1mn). |
| `sign_placement` | enum: "before_prefix", "after_prefix" | Where a negative sign sits against the prefix: 'before_prefix' (−€500) or 'after_prefix' (EUR −500). Unset: after_prefix when the prefix ends in a space or paints on one value only, else before_prefix. Table columns keep the sign with the digits and reject it. |
| `repeat` | enum: "every", "anchor" | Whether the prefix/suffix paints on 'every' value of an axis, table column or support_table row, or on one 'anchor' value. Unset keeps each surface's default. Single-value slots ignore it. |

<a id="namedfont"></a>
## NamedFont
A ``style.fonts`` registry entry: a font other slots reference by name.

| Field | Type | Description |
|-------|------|-------------|
| `extends` | str | Name of a ``style.fonts`` entry this slot starts from; the fields set beside it override that entry. |
| `family` | str | Font family name (e.g., 'sans-serif', 'Roboto'). |
| `color` | str | Text color as a CSS color string. |
| `size` | float | Font size in pixels. |
| `weight` | str \| float | How heavy the type is drawn (e.g., 'bold', 400, 700). |
| `style` | enum: "normal", "italic" | Upright or slanted type (normal or italic). |
| `decoration` | enum: "none", "line-through", "underline" | Line drawn on the text (underline, line-through, or none). |
| `case` | enum: "none", "sentence", "title", "upper", "lower", "slug", "camel" | Letter-case transform applied at render time. 'title' uses Chicago/Gruber rules and preserves tokens with internal capitals (ARR, iPhone). 'sentence' uppercases only the first character. 'none' (default) emits the string without any letter-case change. |
| `line_height` | float | Line height as a unitless multiple of font size. Cascades through Style.font to all text roles that carry a FontStyle slot. Body prose defaults to 1.25; titles override tighter via their font patch in theme YAML. |
| `sizes` | list[float] | The H1–H6 heading ramp (six sizes, indexed by heading level - 1). Valid only on the ``heading`` font. |

<a id="kpitonesstyle"></a>
## KpiTonesStyle
Authored overlay for KpiTonesStyle. Semantic tone palette shared by the KPI support row and table conditional glyphs.

| Field | Type | Description |
|-------|------|-------------|
| `positive` | str | Color for positive/good tone indicators. |
| `negative` | str | Color for negative/bad tone indicators. |
| `warning` | str | Color for warning/caution tone indicators. |
| `info` | str | Color for neutral/informational tone indicators. |

<a id="spacingvalues"></a>
## SpacingValues
Pre-parsed CSS spacing (margin/padding).

| Field | Type | Description |
|-------|------|-------------|
| `top` | float | Top spacing in pixels. |
| `right` | float | Right spacing in pixels. |
| `bottom` | float | Bottom spacing in pixels. |
| `left` | float | Left spacing in pixels. |

<a id="regionallocale"></a>
## RegionalLocale
The d3 locales a board writes numbers and dates in.

| Field | Type | Description |
|-------|------|-------------|
| `number` | [NumberLocale](#numberlocale) \| enum: "ar-AE", "ar-BH", "ar-DJ", "ar-DZ", "ar-EG", "ar-EH", "ar-ER", "ar-IL", "ar-IQ", "ar-JO", "ar-KM", "ar-KW", "ar-LB", "ar-LY", "ar-MA", "ar-MR", "ar-OM", "ar-PS", "ar-QA", "ar-SA", … (38 more; see the JSON Schema) | A d3-format locale name or definition. |
| `time` | [TimeLocale](#timelocale) \| enum: "ar-EG", "ar-SY", "ca-ES", "cs-CZ", "da-DK", "de-CH", "de-DE", "en-CA", "en-GB", "en-US", "es-ES", "es-MX", "fa-IR", "fi-FI", "fr-CA", "fr-FR", "he-IL", "hr-HR", "hu-HU", "it-IT", … (15 more; see the JSON Schema) | A d3-time-format locale name or definition. |

<a id="chartsupporttablesource"></a>
## ChartSupportTableSource
A support_table row that reads a column's raw per-x value.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `source` | str | Query column the row reads from (per-x raw value). |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `format` | str \| [FormatConfig](#formatconfig) \| enum: "compact", "currency", "currency_compact", "currency_full", "currency_whole", "date_short", "delta", "email", "id", "integer", "latitude", "longitude", "number", "number_full", "percent", "percent_delta", "percent_whole", "rating", "time_short", "url", … (1 more; see the JSON Schema) | D3 format string or format config object. Optional; inherits the chart measure format when omitted and source matches chart.y. |
| `label` | str | Left-stub row label. Optional. |

<a id="chartsupporttableaggregate"></a>
## ChartSupportTableAggregate
A support_table row that reads an aggregate of a column grouped by x.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `aggregate` | enum: "sum", "avg", "min", "max", "median", "count", "count_distinct" | Aggregate operation applied per x-group. One of: sum, avg, min, max, median, count, count_distinct. Exact names only: no aliases (spec G4). |
| `source` | str | Query column being aggregated. Always required alongside `aggregate:` (spec G2). |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `format` | str \| [FormatConfig](#formatconfig) \| enum: "compact", "currency", "currency_compact", "currency_full", "currency_whole", "date_short", "delta", "email", "id", "integer", "latitude", "longitude", "number", "number_full", "percent", "percent_delta", "percent_whole", "rating", "time_short", "url", … (1 more; see the JSON Schema) | D3 format string or format config object for the aggregated value. Optional. |
| `label` | str | Column header label override for this row. |

<a id="chartsupporttableperseries"></a>
## ChartSupportTablePerSeries
A support_table entry that expands into one row per color: series.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `per_series` | str | Query column the row reads from (per-x, per-series value). |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `by_measure` | bool | When True, expand one row reading the named measure field directly (no color: groupby). Required for multi-y charts where each measure is its own y-field rather than a color-encoded series. |
| `label` | str | Row label for a by_measure=True row; when None and by_measure=True, the per_series column name is used. Also the header of a horizontal grouped bar's single per_series column. Not allowed on a non-by_measure strip row or stacked-bar column. |
| `format` | str \| [FormatConfig](#formatconfig) \| enum: "compact", "currency", "currency_compact", "currency_full", "currency_whole", "date_short", "delta", "email", "id", "integer", "latitude", "longitude", "number", "number_full", "percent", "percent_delta", "percent_whole", "rating", "time_short", "url", … (1 more; see the JSON Schema) | D3 format string or format config object. Optional. |

<a id="quantitativeaxisstyle"></a>
## QuantitativeAxisStyle
Authored overlay for QuantitativeAxisStyle. Scale-type overlay for quantitative axes. Theme slot: axis_quantitative.

| Field | Type | Description |
|-------|------|-------------|
| `grid` | [BaseAxisGridStyle](#baseaxisgridstyle) | Grid line style for this axis. |
| `line` | [AxisLineStyle](#axislinestyle) | Domain line style for this axis. |
| `ticks` | [AxisTicksStyle](#axisticksstyle) | Tick mark style for this axis. |
| `labels` | [AxisLabelStyle](#axislabelstyle) | Axis label style. |
| `title` | [AxisTitleStyle](#axistitlestyle) | Axis title style. |
| `scale` | [BaseScaleStyle](#basescalestyle) | Per-axis scale overrides; None means no override. |

<a id="charttitlestyle"></a>
## ChartTitleStyle
Authored overlay for ChartTitleStyle. A chart's title style, whose font also takes ``auto``.

| Field | Type | Description |
|-------|------|-------------|
| `compact_weight` | str \| float | Object-title font weight on tiny cards. |
| `width_offsets` | [TitleWidthOffsetsStyle](#titlewidthoffsetsstyle) | Additive level offsets by card width (tiny/narrow/medium/wide). Object titles add the tier offset to a fixed anchor to pick an H slot from ``style.fonts.heading.sizes``. Board/prose titles are level-only and do not consult these. |
| `min_height` | float | Minimum title row height in pixels. |
| `overflow` | enum: "clip", "truncate", "wrap-two", "wrap" | Text overflow mode (clip, truncate, wrap-two, wrap). |
| `position` | [TitlePositionStyle](#titlepositionstyle) | Vega-Lite title positioning: anchor, angle, offset, baseline. |
| `level` | int \| const: "auto" | Heading level override for board titles. ``'auto'`` (default) computes the level semantically as the count of titled ancestors. An integer value locks all titles in this board and its descendants to that H-level. |
| `subtitle` | [TitleSubtitleStyle](#titlesubtitlestyle) | Subtitle font styles. |
| `font` | [ChartTitleFontStyle](#charttitlefontstyle) | Title font style overrides. Unset fields fall back to [`style.font`](#style). |

<a id="legendstyle"></a>
## LegendStyle
Authored overlay for LegendStyle.

| Field | Type | Description |
|-------|------|-------------|
| `direction` | enum: "horizontal", "vertical" | Legend layout direction. Omit to infer it from the edge: horizontal on top/bottom, vertical on left/right. |
| `columns` | int | Legend entry columns. Zero keeps the renderer default; positive values set Vega-Lite legend columns. |
| `compact_columns` | int | Entry columns when a horizontal legend wraps: the automatic compact top legend, or an inferred-horizontal legend too wide for one row. |
| `row` | [LegendRowStyle](#legendrowstyle) | Chrome around each entry of a single-row top legend. |
| `label` | [LegendLabelStyle](#legendlabelstyle) | Legend label style. |
| `title` | [LegendTitleStyle](#legendtitlestyle) | Legend title style. |
| `visible` | bool \| const: "auto" | Show the legend. 'auto' shows it unless direct labeling (endpoint labels, or a pie's slice labels) names the series instead; true keeps it beside direct labels and false hides it. |
| `symbol_limit` | int | Maximum number of legend entries to display; maps to VL symbolLimit. None uses Vega-Lite's default (no cap). Set to a positive integer to prevent legend overflow on high-cardinality series. |
| `values` | list[str] | Explicit legend entry order/filter; each entry resolves against the real legend domain by its rendered text or its column/measure name (case/separator-insensitive). None lets the renderer infer order from the data. |
| `symbol_shape` | str | Override the legend glyph shape; maps to VL legend.symbolType. None uses the mark-aware glyph derived from the chart's mark type. |
| `symbol_fill` | bool | When False, emits symbolFillColor='transparent' to produce a hollow legend glyph. None uses Vega-Lite's default (filled symbol). |
| `position` | [LegendPositionStyle](#legendpositionstyle) | Legend placement: edge, align along the edge, overlay or reserve. |

<a id="paddingstyle"></a>
## PaddingStyle
Authored overlay for PaddingStyle. Per-chart padding inset (px). All 4 sides required; theme YAML supplies defaults.

| Field | Type | Description |
|-------|------|-------------|
| `left` | float | Left padding in pixels. |
| `right` | float | Right padding in pixels. |
| `top` | float | Top padding in pixels. |
| `bottom` | float | Bottom padding in pixels. |

<a id="colorstyle"></a>
## ColorStyle
Authored overlay for ColorStyle. Unified chart color config: static paint, categorical palette, gradient scale.

| Field | Type | Description |
|-------|------|-------------|
| `static` | str | One explicit color: the marks on most families when no color column is encoded, the cell text on a table. |
| `gradient` | [ScaleTargetConfig](#scaletargetconfig) | Continuous gradient scale for the color encoding. |
| `categorical` | [CategoricalColorStyle](#categoricalcolorstyle) | Palettes used when color encodes distinct categories, or a lone series. |

<a id="baseaxisstyle"></a>
## BaseAxisStyle
Authored overlay for BaseAxisStyle. Universal axis surface: grid/line/ticks/labels/title/scale.

| Field | Type | Description |
|-------|------|-------------|
| `grid` | [BaseAxisGridStyle](#baseaxisgridstyle) | Grid line style for this axis. |
| `line` | [AxisLineStyle](#axislinestyle) | Domain line style for this axis. |
| `ticks` | [AxisTicksStyle](#axisticksstyle) | Tick mark style for this axis. |
| `labels` | [AxisLabelStyle](#axislabelstyle) | Axis label style. |
| `title` | [AxisTitleStyle](#axistitlestyle) | Axis title style. |
| `scale` | [BaseScaleStyle](#basescalestyle) | Per-axis scale overrides; None means no override. |

<a id="axisxstyle"></a>
## AxisXStyle
Authored overlay for AxisXStyle. Dimension/category-time axis style. Theme slot: axis_x.

| Field | Type | Description |
|-------|------|-------------|
| `grid` | [BaseAxisGridStyle](#baseaxisgridstyle) | Grid line style for this axis. |
| `line` | [AxisLineStyle](#axislinestyle) | Domain line style for this axis. |
| `ticks` | [DimensionTicksStyle](#dimensionticksstyle) | Dimension axis tick style. |
| `labels` | [DimensionLabelStyle](#dimensionlabelstyle) | Dimension axis label style. |
| `title` | [AxisTitleStyle](#axistitlestyle) | Axis title style. |
| `scale` | [XScaleStyle](#xscalestyle) | X-axis scale overrides including x_reverse; None means no override. |
| `position` | enum: "top", "bottom" | X-axis position; None uses Vega-Lite's default (bottom). |
| `time_unit` | enum: "auto", "year", "yearquarter", "yearmonth", "yearweek", "yearmonthdate", "monthofyear", "dayofweek", "dayofmonth", "dayofyear", "hourofday", "none" | Time-unit bucketing for temporal x-axes; None or 'auto' auto-detects from data. |
| `type` | enum: "auto", "ordinal", "temporal" | Scale type for bucketed-time x-axes; None/'auto' infers from time_unit grain. |
| `fill` | enum: "null", "zero", "linear", "step-after", "step-before", "step-center", "curve" | Fill for synthesized missing-bucket rows: null, zero, linear, step-after / step-before / step-center (Looker step), or curve (smoothstep). |
| `fiscal_year_start_month` | int | Calendar month (1=Jan..12=Dec) that opens a fiscal year/quarter for year/yearquarter bucketing; theme default 1 is the calendar convention (Q1=Jan-Mar). A non-default value always wins over axis_x.type: temporal for year/yearquarter grains - Vega-Lite's native timeUnit transform has no fiscal-offset concept and would otherwise silently discard the offset. |

<a id="axisystyle"></a>
## AxisYStyle
Authored overlay for AxisYStyle. Measure axis style. Theme slot: axis_y.

| Field | Type | Description |
|-------|------|-------------|
| `grid` | [BaseAxisGridStyle](#baseaxisgridstyle) | Grid line style for this axis. |
| `line` | [AxisLineStyle](#axislinestyle) | Domain line style for this axis. |
| `ticks` | [AxisTicksStyle](#axisticksstyle) | Tick mark style for this axis. |
| `labels` | [AxisLabelStyle](#axislabelstyle) | Axis label style. |
| `title` | [AxisTitleStyle](#axistitlestyle) | Axis title style. |
| `scale` | [BaseScaleStyle](#basescalestyle) | Per-axis scale overrides; None means no override. |
| `position` | enum: "left", "right", "auto" | Y-axis position; auto flips when endpoint labels are on the right. |
| `mirror` | bool \| [AxisMirrorStyle](#axismirrorstyle) | Draw the y-scale on both left and right edges (wide charts). true mirrors the primary axis's label verbatim; an object (format/expr) relabels only the mirrored edge (e.g. a percent-of-total right axis next to an absolute-value left axis) while ticks stay aligned to the single shared scale. Only meaningful on axis_y. |

<a id="bandaxisstyle"></a>
## BandAxisStyle
Authored overlay for BandAxisStyle. Scale-type overlay for band (categorical) axes. Theme slot: axis_band.

| Field | Type | Description |
|-------|------|-------------|
| `grid` | [BaseAxisGridStyle](#baseaxisgridstyle) | Grid line style for this axis. |
| `line` | [AxisLineStyle](#axislinestyle) | Domain line style for this axis. |
| `ticks` | [AxisTicksStyle](#axisticksstyle) | Tick mark style for this axis. |
| `labels` | [AxisLabelStyle](#axislabelstyle) | Axis label style. |
| `title` | [AxisTitleStyle](#axistitlestyle) | Axis title style. |
| `scale` | [BaseScaleStyle](#basescalestyle) | Per-axis scale overrides; None means no override. |
| `band_position` | float | Band position within the step (0–1); None uses Vega-Lite's default. |

<a id="supporttablestyle"></a>
## SupportTableStyle
Authored overlay for SupportTableStyle. Attached support_table style. Lives at style.charts.support_table.*.

| Field | Type | Description |
|-------|------|-------------|
| `font` | [SupportTableFontStyle](#supporttablefontstyle) | Support_table font style overrides. Unset fields fall back to [`style.charts.font`](#chartsstyle). |
| `neutral_color` | str | Ink for cells that belong to no series (totals, source columns, labels) when `font.color` is 'auto'. Falls back to [`style.charts.font.color`](#fontstyle). |
| `divider` | [SupportTableDividerStyle](#supporttabledividerstyle) | Line at the boundary between the chart plot and the data strip. For position='bottom': the line sits above the strip (below the axis). For position='top': the line sits below the strip rows (above the plot top). |
| `row` | [SupportTableRowStyle](#supporttablerowstyle) | Support_table row padding and divider style. |
| `label` | [SupportTableLabelStyle](#supporttablelabelstyle) | Row label (series name) style. |
| `padding_top` | float | Padding above the topmost strip row in pixels. For position='bottom': gap between axis labels and the first row. For position='top': space above the topmost row (outer edge of strip). |
| `padding_bottom` | float | Padding below the last strip row in pixels. For position='bottom': space below the last row. For position='top': gap between the last row and the plot top edge. |
| `label_max_lines` | int | Number of x-axis label lines to reserve in the axis gap (only used for position='bottom'; ignored for position='top'). Typically 1 or 2. |
| `position` | enum: "top", "bottom", "left", "right" | Strip placement relative to the chart plot. 'top'/'bottom' apply when the chart's category axis is horizontal (vertical bar, line, area): 'top' places the strip above the plot, 'bottom' places it below with the x-axis between plot and strip. 'left'/'right' apply when the category axis is vertical (a horizontal bar): the strip renders as value columns beside the plot instead of rows above or below it. Left unset, 'top' is used on a horizontal category axis and the side the category labels are on is used on a vertical one. |

<a id="endpointlabelsconfig"></a>
## EndpointLabelsConfig
Authored overlay for EndpointLabelsConfig. Series names printed on the chart itself instead of in a legend.

| Field | Type | Description |
|-------|------|-------------|
| `visible` | bool \| const: "auto" | Print series names on the chart instead of in a legend. 'auto' on every built-in theme: used wherever the shape can name every series (line and area charts, and stacked bars), with a legend on grouped bars, layered charts, small multiples, and very narrow cards. Set true to print them on every shape that can, or false to move the names back into a legend everywhere. Where the labels do appear they replace the color legend, so this setting and not `legend` is what removes them. |
| `label_offset` | float | Gap in pixels between the plot and the series labels. |
| `height` | float | Height in pixels of the label strip above a horizontal stacked bar. |

<a id="bargroupedstyle"></a>
## BarGroupedStyle
Authored overlay for BarGroupedStyle. Band-scale padding for grouped (side-by-side) bars.

| Field | Type | Description |
|-------|------|-------------|
| `padding_inner` | float | Gap between groups, as a share of the band step. |
| `padding_outer` | float | Margin at both plot edges, as a share of the band step. |

<a id="barchartmarksstyle"></a>
## BarChartMarksStyle
Authored overlay for BarChartMarksStyle. Bar-family mark overrides. Only bar and text (endpoint labels) are valid.

| Field | Type | Description |
|-------|------|-------------|
| `bar` | [BarMarkStyle](#barmarkstyle) | Bar mark overrides for bar charts; inherits from global. |
| `text` | [TextMarkStyle](#textmarkstyle) | Text mark overrides for bar endpoint labels; inherits from global. |

<a id="layeraxisystyle"></a>
## LayerAxisYStyle
Per-layer y-axis settings on a layered chart.

| Field | Type | Description |
|-------|------|-------------|
| `position` | enum: "left", "right" | Y-axis side for this layer (left or right). |
| `title` | str | Title on this layer's own y axis; defaults to the layer's label. |
| `scale` | [LayerAxisYScale](#layeraxisyscale) | Scale options for this layer's y axis, holding the [min, max] domain. |
| `ticks` | [LayerAxisYTicks](#layeraxisyticks) | Tick options for this layer's y axis, holding the target count. |
| `grid` | [LayerAxisYGrid](#layeraxisygrid) | Grid options for this layer's y axis, holding its visibility. |
| `labels` | [LayerAxisYLabels](#layeraxisylabels) | Tick-label options for this layer's y axis, holding the number format. |

<a id="barlayerstyle"></a>
## BarLayerStyle
Authored overlay for BarLayerStyle. Required wrapper for bar-layer mark overrides (built into a Patch by build_patch_model).

| Field | Type | Description |
|-------|------|-------------|
| `marks` | [BarChartMarksStyle](#barchartmarksstyle) | Mark overrides for this bar layer. |

<a id="linelayerstyle"></a>
## LineLayerStyle
Authored overlay for LineLayerStyle. Required wrapper for line-layer mark overrides (built into a Patch by build_patch_model).

| Field | Type | Description |
|-------|------|-------------|
| `marks` | [LineChartMarksStyle](#linechartmarksstyle) | Mark overrides for this line layer. |

<a id="arealayerstyle"></a>
## AreaLayerStyle
Authored overlay for AreaLayerStyle. Required wrapper for area-layer mark overrides (built into a Patch by build_patch_model).

| Field | Type | Description |
|-------|------|-------------|
| `marks` | [AreaChartMarksStyle](#areachartmarksstyle) | Mark overrides for this area layer. |

<a id="scatterlayerstyle"></a>
## ScatterLayerStyle
Authored overlay for ScatterLayerStyle. Required wrapper for scatter-layer mark overrides (built into a Patch by build_patch_model).

| Field | Type | Description |
|-------|------|-------------|
| `marks` | [ScatterChartMarksStyle](#scatterchartmarksstyle) | Mark overrides for this scatter layer. |

<a id="linechartmarksstyle"></a>
## LineChartMarksStyle
Authored overlay for LineChartMarksStyle. Line-family mark overrides.

| Field | Type | Description |
|-------|------|-------------|
| `line` | [LineMarkStyle](#linemarkstyle) | Line mark overrides; inherits from global. |
| `point` | [PointMarkStyle](#pointmarkstyle) | Point mark overrides; inherits from global. |
| `text` | [TextMarkStyle](#textmarkstyle) | Text mark overrides; inherits from global. |
| `rule` | [RuleMarkStyle](#rulemarkstyle) | Rule mark overrides; None inherits global. |

<a id="areachartmarksstyle"></a>
## AreaChartMarksStyle
Authored overlay for AreaChartMarksStyle. Area-family mark overrides.

| Field | Type | Description |
|-------|------|-------------|
| `area` | [AreaMarkStyle](#areamarkstyle) | Area fill mark overrides; inherits from global. |
| `line` | [AreaLineStyle](#arealinestyle) | Top-edge line stroke/halo/label overrides; inherits from global. |
| `point` | [PointMarkStyle](#pointmarkstyle) | Point-overlay mark overrides; inherits from global. |

<a id="scatterchartmarksstyle"></a>
## ScatterChartMarksStyle
Authored overlay for ScatterChartMarksStyle. Scatter-family mark overrides.

| Field | Type | Description |
|-------|------|-------------|
| `point` | [PointMarkStyle](#pointmarkstyle) | Point mark overrides; inherits from global. |
| `text` | [TextMarkStyle](#textmarkstyle) | Text mark overrides; inherits from global. |

<a id="heatmapchartmarksstyle"></a>
## HeatmapChartMarksStyle
Authored overlay for HeatmapChartMarksStyle. Heatmap-family mark overrides.

| Field | Type | Description |
|-------|------|-------------|
| `rect` | [RectMarkStyle](#rectmarkstyle) | Rect mark overrides; inherits from global. |
| `text` | [TextMarkStyle](#textmarkstyle) | Text mark overrides; None inherits global. |

<a id="pielegendstyle"></a>
## PieLegendStyle
Authored overlay for PieLegendStyle.

| Field | Type | Description |
|-------|------|-------------|
| `direction` | enum: "horizontal", "vertical" | Legend layout direction. Omit to infer it from the edge: horizontal on top/bottom, vertical on left/right. |
| `columns` | int | Legend entry columns. Zero keeps the renderer default; positive values set Vega-Lite legend columns. |
| `compact_columns` | int | Entry columns when a horizontal legend wraps: the automatic compact top legend, or an inferred-horizontal legend too wide for one row. |
| `row` | [LegendRowStyle](#legendrowstyle) | Chrome around each entry of a single-row top legend. |
| `label` | [LegendLabelStyle](#legendlabelstyle) | Legend label style. |
| `title` | [LegendTitleStyle](#legendtitlestyle) | Legend title style. |
| `visible` | bool \| const: "auto" | Show the legend. 'auto' shows it unless direct labeling (endpoint labels, or a pie's slice labels) names the series instead; true keeps it beside direct labels and false hides it. |
| `symbol_limit` | int | Maximum number of legend entries to display; maps to VL symbolLimit. None uses Vega-Lite's default (no cap). Set to a positive integer to prevent legend overflow on high-cardinality series. |
| `values` | list[str] | Explicit legend entry order/filter; each entry resolves against the real legend domain by its rendered text or its column/measure name (case/separator-insensitive). None lets the renderer infer order from the data. |
| `symbol_shape` | str | Override the legend glyph shape; maps to VL legend.symbolType. None uses the mark-aware glyph derived from the chart's mark type. |
| `symbol_fill` | bool | When False, emits symbolFillColor='transparent' to produce a hollow legend glyph. None uses Vega-Lite's default (filled symbol). |
| `position` | [PiePositionStyle](#piepositionstyle) | Pie key placement: edge and align along it. |

<a id="totalstyle"></a>
## TotalStyle
Authored overlay for TotalStyle. Donut center total paint: value (the number) and label (the caption).

| Field | Type | Description |
|-------|------|-------------|
| `value` | [TotalValueSlotStyle](#totalvalueslotstyle) | Style for the donut center value (the number), including its format. |
| `label` | [TotalSlotStyle](#totalslotstyle) | Style for the donut center label (the caption). |

<a id="piechartmarksstyle"></a>
## PieChartMarksStyle
Authored overlay for PieChartMarksStyle. Pie/donut-family mark overrides.

| Field | Type | Description |
|-------|------|-------------|
| `slice` | [SliceMarkStyle](#slicemarkstyle) | Slice mark overrides; inherits from global. |
| `text` | [TextMarkStyle](#textmarkstyle) | Text mark overrides; None inherits global. |

<a id="conditionalrule"></a>
## ConditionalRule
A single conditional formatting rule.

| Field | Type | Description |
|-------|------|-------------|
| `eq` | Any | Match rows where the column value equals this value. |
| `ne` | Any | Match rows where the column value does not equal this value. |
| `lt` | int \| float | Match rows where the column value is less than this number. |
| `lte` | int \| float | Match rows where the column value is less than or equal to this number. |
| `gt` | int \| float | Match rows where the column value is greater than this number. |
| `gte` | int \| float | Match rows where the column value is greater than or equal to this number. |
| `between` | list[int \| float] | Match rows where the column value falls in [low, high] (inclusive). |
| `in` | list[Any] | Match rows where the column value is in this list. |
| `is_null` | bool | Match null rows (true) or non-null rows (false). |
| `default` | const: true | Catch-all rule that matches any row not matched by earlier rules. Must be the last entry. |
| `background` | str | Cell background color applied when the rule matches. |
| `font` | [FontStyle](#fontstyle) | Font style overrides (color, weight, style, decoration) applied when the rule matches. |
| `glyph` | str | Text shown before the cell value when the rule matches. |
| `glyph_color` | str | Color for the glyph when the rule matches. Requires glyph to be set. |
| `tone` | enum: "positive", "negative", "warning", "info" | Semantic tone (positive\|negative\|warning\|info) that colors the glyph via the theme's tone palette; the preferred, theme-adaptive alternative to a raw glyph_color. Requires glyph. Explicit glyph_color wins. |

<a id="singlelinefontstyle"></a>
## SingleLineFontStyle
Text appearance for a slot that always paints one line.

| Field | Type | Description |
|-------|------|-------------|
| `extends` | str | Name of a ``style.fonts`` entry this slot starts from; the fields set beside it override that entry. |
| `family` | str | Font family name (e.g., 'sans-serif', 'Roboto'). |
| `color` | str | Text color as a CSS color string. |
| `size` | float | Font size in pixels. |
| `weight` | str \| float | How heavy the type is drawn (e.g., 'bold', 400, 700). |
| `style` | enum: "normal", "italic" | Upright or slanted type (normal or italic). |
| `decoration` | enum: "none", "line-through", "underline" | Line drawn on the text (underline, line-through, or none). |
| `case` | enum: "none", "sentence", "title", "upper", "lower", "slug", "camel" | Letter-case transform applied at render time. 'title' uses Chicago/Gruber rules and preserves tokens with internal capitals (ARR, iPhone). 'sentence' uppercases only the first character. 'none' (default) emits the string without any letter-case change. |

<a id="kpivaluestyle"></a>
## KpiValueStyle
Authored overlay for KpiValueStyle. KPI headline value slot: font, format, and the affix and glyph beside it.

| Field | Type | Description |
|-------|------|-------------|
| `font` | [SingleLineFontStyle](#singlelinefontstyle) | Headline value font. Unset fields fall back to [`style.charts.kpi.font`](#kpichartstyle). |
| `format` | str \| [FormatConfig](#formatconfig) \| enum: "compact", "currency", "currency_compact", "currency_full", "currency_whole", "date_short", "delta", "email", "id", "integer", "latitude", "longitude", "number", "number_full", "percent", "percent_delta", "percent_whole", "rating", "time_short", "url", … (1 more; see the JSON Schema) | Format for the KPI headline value: D3 format string, preset name, or FormatConfig object. A date value defaults to date_short when unformatted. |
| `compact` | [KpiCompactStyle](#kpicompactstyle) | Compaction applied to an unformatted headline number. |
| `affix` | [KpiTextSlotStyle](#kpitextslotstyle) | Currency or percent sign written around the headline number. |
| `glyph` | [KpiTextSlotStyle](#kpitextslotstyle) | Indicator glyph drawn before the headline value. |

<a id="kpilabelstyle"></a>
## KpiLabelStyle
Authored overlay for KpiLabelStyle. KPI label slot: font and how a long label fits the card.

| Field | Type | Description |
|-------|------|-------------|
| `font` | [SingleLineFontStyle](#singlelinefontstyle) | Label font. Unset fields fall back to [`style.charts.kpi.font`](#kpichartstyle). |
| `overflow` | enum: "clip", "truncate", "wrap-two", "wrap" | How a label too wide for the card is fit. Falls back to [`style.charts.title.overflow`](#charttitlestyle). |

<a id="kpisupportstyle"></a>
## KpiSupportStyle
Authored overlay for KpiSupportStyle. KPI support row: font, format, tone, and its glyph.

| Field | Type | Description |
|-------|------|-------------|
| `font` | [KpiSupportFontStyle](#kpisupportfontstyle) | Support row font; its color paints the support value. Unset fields fall back to [`style.charts.kpi.font`](#kpichartstyle). |
| `format` | str \| [FormatConfig](#formatconfig) \| enum: "compact", "currency", "currency_compact", "currency_full", "currency_whole", "date_short", "delta", "email", "id", "integer", "latitude", "longitude", "number", "number_full", "percent", "percent_delta", "percent_whole", "rating", "time_short", "url", … (1 more; see the JSON Schema) | How the support value is written: a D3 spec, a preset name, or a format block. |
| `tone` | enum: "positive", "negative", "warning", "info" | Semantic color for the support value and glyph. |
| `glyph` | [KpiSupportGlyphStyle](#kpisupportglyphstyle) | Glyph drawn before the support value. |

<a id="fontstyle"></a>
## FontStyle
Text appearance, including leading for text that wraps. Merged as a unit.

| Field | Type | Description |
|-------|------|-------------|
| `extends` | str | Name of a ``style.fonts`` entry this slot starts from; the fields set beside it override that entry. |
| `family` | str | Font family name (e.g., 'sans-serif', 'Roboto'). |
| `color` | str | Text color as a CSS color string. |
| `size` | float | Font size in pixels. |
| `weight` | str \| float | How heavy the type is drawn (e.g., 'bold', 400, 700). |
| `style` | enum: "normal", "italic" | Upright or slanted type (normal or italic). |
| `decoration` | enum: "none", "line-through", "underline" | Line drawn on the text (underline, line-through, or none). |
| `case` | enum: "none", "sentence", "title", "upper", "lower", "slug", "camel" | Letter-case transform applied at render time. 'title' uses Chicago/Gruber rules and preserves tokens with internal capitals (ARR, iPhone). 'sentence' uppercases only the first character. 'none' (default) emits the string without any letter-case change. |
| `line_height` | float | Line height as a unitless multiple of font size. Cascades through Style.font to all text roles that carry a FontStyle slot. Body prose defaults to 1.25; titles override tighter via their font patch in theme YAML. |

<a id="staticgradientcolorstyle"></a>
## StaticGradientColorStyle
Authored overlay for StaticGradientColorStyle. Color config for geo/point_map/table families, no categorical arm.

| Field | Type | Description |
|-------|------|-------------|
| `static` | str | One explicit color: the marks on most families when no color column is encoded, the cell text on a table. |
| `gradient` | [ScaleTargetConfig](#scaletargetconfig) | Continuous gradient scale for the color encoding. |

<a id="tablecolumnsstyle"></a>
## TableColumnsStyle
Authored overlay for TableColumnsStyle.

| Field | Type | Description |
|-------|------|-------------|
| `default_width` | float | Default column width in pixels. |
| `cell_padding` | float | Horizontal padding inside table cells in pixels. |
| `width_similarity_threshold` | float | Auto-width columns whose min/max ratio &gt;= this threshold are snapped to a shared width before budget allocation. 1.0 disables clustering; 0.0 forces all auto-columns to equal width. |
| `content_headroom` | float | Fractional breathing room added above the raw p95 column demand when pinning compact columns in mixed (compact + text) tables.  0.10 means each compact column is pinned at 10 % above its measured demand; the extra width is funded by the text-column budget.  Has no effect on all-compact tables (proportional scaling already fills the budget).  0.0 disables headroom. |

<a id="tableheaderstyle"></a>
## TableHeaderStyle
Authored overlay for TableHeaderStyle.

| Field | Type | Description |
|-------|------|-------------|
| `visible` | bool | Show the header row (column labels + divider). Set to False on series-keyed tables where column meanings are obvious from context (e.g. donut-attached tables: swatch / share / name / value). Theme YAML supplies the UX default (true) via _base.yaml. |
| `height` | float | Header row height in pixels. |
| `font` | [FontStyle](#fontstyle) | Header font style overrides. Unset fields fall back to [`style.charts.table.font`](#tablechartstyle). |
| `font_compact` | [FontStyle](#fontstyle) | Compact-tier font overrides applied when body size ≤11px; None means no compact override. |
| `background` | str | Header background color; None means no fill (the divider alone separates header from body). |
| `overflow` | enum: "clip", "truncate", "wrap-two", "wrap" | What happens to header text too wide for its column (clip, truncate, wrap-two, wrap). |
| `divider` | [TableDividerStyle](#tabledividerstyle) | Line between the header row and the body. |

<a id="tablerowstyle"></a>
## TableRowStyle
Authored overlay for TableRowStyle.

| Field | Type | Description |
|-------|------|-------------|
| `height` | float | Body row height in pixels. |
| `stripe` | [TableRowStripeStyle](#tablerowstripestyle) | Alternating row stripe style; None means no stripe. |
| `divider` | [TableDividerStyle](#tabledividerstyle) | Line under each body row. |
| `role` | str | Default row role assignment; None means plain body row. |
| `roles` | [TableRowRolesStyle](#tablerowrolesstyle) | Per-role style overrides for summary and total rows. |

<a id="tablerownumbersstyle"></a>
## TableRowNumbersStyle
Authored overlay for TableRowNumbersStyle. Leading row-number column (style.table.row_numbers).

| Field | Type | Description |
|-------|------|-------------|
| `visible` | bool | Show a leading row-number column; false by default. |
| `header` | str | Header label for the row-number column. |
| `align` | enum: "left", "right" | Text alignment for the row-number column. |

<a id="tabletitlestyle"></a>
## TableTitleStyle
Authored overlay for TableTitleStyle.

| Field | Type | Description |
|-------|------|-------------|
| `height` | float | Minimum title-block height in pixels. Applies as a floor only when a subtitle is present; a title-only block sizes to its natural content height instead. |
| `font` | [FontStyle](#fontstyle) | Table title font style overrides. Unset fields fall back to [`style.charts.table.font`](#tablechartstyle). |

<a id="paginationconfig"></a>
## PaginationConfig
Table pagination configuration.

| Field | Type | Description |
|-------|------|-------------|
| `enabled` | bool | Enable client-side pagination for table charts. |
| `page_rows` | int | Rows per page, a ceiling bounded by the tile height. The theme defaults it to 20; null means unlimited (the tile height alone sizes the page). |

<a id="tablecolumndefaultsconfig"></a>
## TableColumnDefaultsConfig
Table-level defaults applied to every column unless overridden per-column.

| Field | Type | Description |
|-------|------|-------------|
| `width` | int \| str | Override column width in pixels (integer) or a CSS width string. |
| `align` | enum: "left", "center", "right" | Override cell text alignment (left, center, or right). |
| `format` | str \| [FormatConfig](#formatconfig) \| enum: "compact", "currency", "currency_compact", "currency_full", "currency_whole", "date_short", "delta", "email", "id", "integer", "latitude", "longitude", "number", "number_full", "percent", "percent_delta", "percent_whole", "rating", "time_short", "url", … (1 more; see the JSON Schema) | How values are written in every column, unless a column sets its own. |
| `background` | str | Override cell background color (CSS color string), or a column ID: a value matching a query column name uses that row's value. |
| `font` | [ColumnFontStyle](#columnfontstyle) | Override cell font style (size, weight, color, family). |

<a id="tablecolumnconfig"></a>
## TableColumnConfig
Configuration for a single table column.

| Field | Type | Description |
|-------|------|-------------|
| `visible` | bool | Whether this column renders. Defaults to true: style.columns is styling only, so naming a column here never hides it or any other column. Set false to hide it while keeping its values available to link: templates and style-input references. A column consumed as a style input (another column's background / font.color / font.weight names it) is hidden automatically unless it has its own style.columns entry; an explicit entry is a display signal and the column renders. |
| `label` | str | Display header label (defaults to column name). |
| `format` | str \| [FormatConfig](#formatconfig) \| enum: "compact", "currency", "currency_compact", "currency_full", "currency_whole", "date_short", "delta", "email", "id", "integer", "latitude", "longitude", "number", "number_full", "percent", "percent_delta", "percent_whole", "rating", "time_short", "url", … (1 more; see the JSON Schema) | How the number is written: a D3 spec, a preset name, or a format block. |
| `spark` | [SparkConfig](#sparkconfig) \| enum: "line", "area", "bar", "bar-normalize", "column", "columns" | Miniature chart drawn inside each cell: a type name, or a full block. |
| `swatch` | bool | When True, render this column's cells as small rounded color squares instead of text. Cell value must be a CSS color string (e.g. '#3164a3'). Useful for series-keyed tables, e.g. a 'Series' column where each row is identified by its color in the parent chart's palette. |
| `width` | int \| str | Column width (integer pixels or CSS string like '10%'). |
| `max_width` | int \| str | Maximum column width for auto-sized text columns (integer pixels or CSS string like '30%'). Cannot be set together with width:. |
| `align` | enum: "left", "center", "right" | Text alignment in cells (left, center, right). |
| `header_overflow` | enum: "clip", "truncate", "wrap-two", "wrap" | What happens to header text too wide for its column (clip, truncate, wrap-two, wrap). |
| `header_link` | str | URL template that makes the column header clickable. |
| `link` | str | URL template for cell values (Jinja template with row fields available). |
| `background` | str | Cell background color (hex string, or 'transparent'/'none'), or a column ID: a value matching a query column name uses that row's value in the named column instead of the literal string. |
| `font` | [ColumnFontStyle](#columnfontstyle) | Cell font style overrides. `color` and `weight` resolve column-ID-first, the same as `background`: a value matching a query column name uses that row's value in the named column. |
| `scale` | [ColumnScaleConfig](#columnscaleconfig) | Continuous color mapping configuration for this column. |
| `glyph` | str | Text shown before every cell value; fills the same slot as format.prefix and wins over it. |
| `glyph_color` | str | Color for the glyph. Requires glyph to be set. |

<a id="paginatorstyle"></a>
## PaginatorStyle
Authored overlay for PaginatorStyle. Visual style for the paginator control (chevrons + page numbers).

| Field | Type | Description |
|-------|------|-------------|
| `color_active` | str | Current page and live chevron color (theme body ink). |
| `color_inactive` | str | Other pages and ellipsis color (theme secondary text). |
| `color_disabled` | str | Chevron color when at first/last page (signals disabled by tone). |
| `font` | [FontStyle](#fontstyle) | Paginator font overrides (size, family). |
| `weight_active` | int | Font weight for the current (selected) page number. |
| `weight_inactive` | int | Font weight for other pages and ellipsis. |
| `weight_chevron` | int | Font weight for the prev/next chevrons (live and disabled). Usually heavier than weight_active so the chevrons read as interactive affordances against the lighter page numbers. |
| `item_width` | float | Per-item slot width in pixels (drives layout step). |

<a id="tableedgestyle"></a>
## TableEdgeStyle
Authored overlay for TableEdgeStyle. more_rows or empty_state edge-case UI.

| Field | Type | Description |
|-------|------|-------------|
| `font` | [FontStyle](#fontstyle) | Edge-case UI (more_rows / empty_state) font style overrides. Unset fields fall back to [`style.charts.table.font`](#tablechartstyle). |

<a id="sparkstyle"></a>
## SparkStyle
Authored overlay for SparkStyle. Inline sparkline defaults (inside table cells).

| Field | Type | Description |
|-------|------|-------------|
| `color` | str | Sparkline line/point color; None seeds from style.charts.color.categorical.single_series_palette[0]. |
| `padding` | str \| float \| [SpacingValues](#spacingvalues) | Cell padding around the sparkline in pixels. |
| `empty` | [SparkEmptyStyle](#sparkemptystyle) | Style for empty/no-data sparklines. |
| `single_value` | [SparkSingleValueStyle](#sparksinglevaluestyle) | Style for single-data-point sparklines. |
| `columns` | [SparkColumnsStyle](#sparkcolumnsstyle) | Style for column-type sparklines. |
| `column` | [SparkColumnStyle](#sparkcolumnstyle) | Style for the single vertical `column` spark mark. |
| `bar` | [SparkBarCellStyle](#sparkbarcellstyle) | Style for bar/bar-normalize sparklines. |
| `area` | [SparkAreaStyle](#sparkareastyle) | Style for area sparklines. |

<a id="projectionstyle"></a>
## ProjectionStyle
Authored overlay for ProjectionStyle. Vega-Lite map projection configuration for geo chart families.

| Field | Type | Description |
|-------|------|-------------|
| `type` | str | Vega-Lite projection type (e.g. 'mercator', 'albersUsa', 'equalEarth'). |

<a id="basemapstyle"></a>
## BasemapStyle
Authored overlay for BasemapStyle. Background map layer for geo charts (especially point maps).

| Field | Type | Description |
|-------|------|-------------|
| `source` | str | Background topo source identifier; None means no base layer. |

<a id="pointmapchartmarksstyle"></a>
## PointMapChartMarksStyle
Authored overlay for PointMapChartMarksStyle. Point map-family mark overrides.

| Field | Type | Description |
|-------|------|-------------|
| `point` | [PointMarkStyle](#pointmarkstyle) | Point mark overrides; inherits from global. |

<a id="geoshapechartmarksstyle"></a>
## GeoshapeChartMarksStyle
Authored overlay for GeoshapeChartMarksStyle. Geoshape-family mark overrides.

| Field | Type | Description |
|-------|------|-------------|
| `geoshape` | [GeoshapeMarkStyle](#geoshapemarkstyle) | Geoshape mark overrides; inherits from global. |

<a id="calloutelementstyle"></a>
## CalloutElementStyle
Authored overlay for CalloutElementStyle. Font + y_offset for a callout title or message.

| Field | Type | Description |
|-------|------|-------------|
| `font` | [FontStyle](#fontstyle) | Element font style overrides. A color of `by_tone` is the tone's color. Unset fields fall back to [`style.charts.font`](#chartsstyle). |
| `y_offset` | float | Vertical offset from the element's anchor in pixels. |

<a id="sparkbarbarstyle"></a>
## SparkBarBarStyle
Authored overlay for SparkBarBarStyle. Bar geometry sub-block for SparkBarChartStyle.

| Field | Type | Description |
|-------|------|-------------|
| `height` | float | Height of each bar in pixels. |
| `padding` | float | Vertical padding between bars in pixels. |
| `color` | str | Bar fill color; None seeds from style.charts.color.categorical.single_series_palette[0]. |
| `background` | str | Bar track background color - fill-grade, pinned per theme. |

<a id="sparkbarchartlabelstyle"></a>
## SparkBarChartLabelStyle
Authored overlay for SparkBarChartLabelStyle. Category-label sub-block for SparkBarChartStyle.

| Field | Type | Description |
|-------|------|-------------|
| `visible` | bool | Show series label text next to bars. |
| `width` | float | Reserved width for bar label text in pixels. |

<a id="sparkbarcountstyle"></a>
## SparkBarCountStyle
Authored overlay for SparkBarCountStyle. Count-value sub-block for SparkBarChartStyle.

| Field | Type | Description |
|-------|------|-------------|
| `visible` | bool | Show count/value text next to bars. |
| `width` | float | Reserved width for bar count text in pixels. |

<a id="cornerstyle"></a>
## CornerStyle
Authored overlay for CornerStyle. Corner rounding only, for a slot whose renderer never draws a stroke.

| Field | Type | Description |
|-------|------|-------------|
| `radius` | float | Corner radius in pixels. |

<a id="subtitlestyle"></a>
## SubtitleStyle
Authored overlay for SubtitleStyle. Subtitle font style for chart subtitles (Table, SparkBar).

| Field | Type | Description |
|-------|------|-------------|
| `font` | [FontStyle](#fontstyle) | Subtitle font style; theme populates font.size directly. |

<a id="titlewidthoffsetsstyle"></a>
## TitleWidthOffsetsStyle
Authored overlay for TitleWidthOffsetsStyle. Additive level offsets applied to a board/chart title's heading level, by card pixel width.

| Field | Type | Description |
|-------|------|-------------|
| `tiny` | int | Level offset for the tiny tier (cards narrower than ~360px). |
| `narrow` | int | Level offset for the narrow tier (cards ~360–559px). |
| `medium` | int | Level offset for the medium tier (cards ~560–1099px). |
| `wide` | int | Level offset for the wide tier (cards ~1100px and up). |

<a id="titlepositionstyle"></a>
## TitlePositionStyle
Authored overlay for TitlePositionStyle. Vega-Lite title positioning pass-throughs grouped as a sub-object.

| Field | Type | Description |
|-------|------|-------------|
| `anchor` | str | Title anchor position; theme always sets this. |
| `angle` | float | Title rotation angle in degrees; None lets Vega-Lite choose. |
| `offset` | float | Title offset from its anchor in pixels; None uses Vega-Lite's default. |
| `baseline` | str | Title text baseline alignment; None uses Vega-Lite's default. |

<a id="titlesubtitlestyle"></a>
## TitleSubtitleStyle
Authored overlay for TitleSubtitleStyle. VL subtitle font pass-through, grouped for consistency with TitleStyle.font.

| Field | Type | Description |
|-------|------|-------------|
| `font` | [FontStyle](#fontstyle) | Subtitle font style overrides (color, family, size, weight). Unset fields fall back to [`style.font`](#style). |
| `overflow` | enum: "clip", "truncate", "wrap-two", "wrap" | Text overflow mode for the subtitle (clip, truncate, wrap-two, wrap). None means not set at this cascade level (theme floor is wrap-two). |

<a id="blockmarginstyle"></a>
## BlockMarginStyle
Authored overlay for BlockMarginStyle. Top and bottom margin for a prose block role, in line-height units.

| Field | Type | Description |
|-------|------|-------------|
| `margin_top` | float | Space above the block, in line-height units (lh × font_size × value). |
| `margin_bottom` | float | Space below the block, in line-height units (lh × font_size × value). |

<a id="textcolumnstyle"></a>
## TextColumnStyle
Authored overlay for TextColumnStyle. Author overrides for the column layout of board body text.

| Field | Type | Description |
|-------|------|-------------|
| `max_number` | int | Ceiling on the column count. The renderer may choose fewer when there is not enough text to fill them. None = no ceiling. |
| `divider` | [DividerStyle](#dividerstyle) | Vertical line drawn between columns. |
| `max_chars` | int | Column text width as a character count, overriding the shipped measure. It caps the text inside a column, and is the width prose and board titles ask a content-sized board for; a column narrower than this limits the text first. |

<a id="textcodestyle"></a>
## TextCodeStyle
Authored overlay for TextCodeStyle. Inline and fenced code spans in markdown prose. Box group; mono font by default.

| Field | Type | Description |
|-------|------|-------------|
| `font` | [FontStyle](#fontstyle) | Box text font overrides: full FontStyle (family, color, size, weight, style, decoration, case). |
| `background` | str | Box background fill. |
| `border` | str \| [BorderStyle](#borderstyle) | Box border (width, color, radius). |
| `highlight` | bool | Syntax-highlight fenced markdown code blocks. |
| `theme` | enum: "abap", "algol", "algol_nu", "arduino", "autumn", "borland", "bw", "coffee", "colorful", "default", "dracula", "emacs", "friendly", "friendly_grayscale", "fruity", "github-dark", "gruvbox-dark", "gruvbox-light", "igor", "inkpot", … (30 more; see the JSON Schema) | Pygments style name for fenced markdown code tokens. |

<a id="textblockquotestyle"></a>
## TextBlockquoteStyle
Authored overlay for TextBlockquoteStyle. Blockquote prose. Box group; border is the left bar.

| Field | Type | Description |
|-------|------|-------------|
| `font` | [FontStyle](#fontstyle) | Box text font overrides: full FontStyle (family, color, size, weight, style, decoration, case). |
| `background` | str | Box background fill. |
| `border` | str \| [BorderStyle](#borderstyle) | Box border (width, color, radius). |

<a id="textboldstyle"></a>
## TextBoldStyle
Authored overlay for TextBoldStyle. Inline **bold** text runs in markdown prose, distinct from heading weight.

| Field | Type | Description |
|-------|------|-------------|
| `weight` | enum: "normal", "bold", "100", "200", "300", "400", "500", "600", "700", "800", "900", 100, 200, 300, 400, 500, 600, 700, 800, 900 | CSS font-weight for bold text runs and bold table cells. |

<a id="dividerstyle"></a>
## DividerStyle
Authored overlay for DividerStyle. A separator line: whether it draws, and its color, width and line style.

| Field | Type | Description |
|-------|------|-------------|
| `visible` | bool | Draw the divider. |
| `color` | str | Divider color. |
| `width` | float | Divider line width in pixels. |
| `dasharray` | str | Dash pattern in pixels, such as "6 3" (6 drawn, 3 gap); unset draws a solid line. |

<a id="placeholderoverlay"></a>
## PlaceholderOverlay
Authored overlay for PlaceholderOverlay.

| Field | Type | Description |
|-------|------|-------------|
| `text` | str | Placeholder overlay text shown on empty charts. |
| `background` | str | Overlay background color. |
| `font` | [FontStyle](#fontstyle) | Overlay font style overrides. Unset fields fall back to [`style.font`](#style). |

<a id="categorycolorbinding"></a>
## CategoryColorBinding
Value→color assignments for one data field, shared by every chart.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `values` | dict[str, one of: 'category[1]', 'category[2]', 'category[3]', 'category[4]', 'category[5]', 'category[6]', 'category[7]', 'category[8]', 'category[9]', 'category[10]' \| str] | Data value → palette token (`category[1]`, `dbt-grays.muted`) or literal hex. Tokens resolve against the board's theme. |

<a id="tooltipstyle"></a>
## TooltipStyle
Authored overlay for TooltipStyle. Tooltip box style: all cascade keys for the hover bubble.

| Field | Type | Description |
|-------|------|-------------|
| `format` | str \| enum: "compact", "currency", "currency_compact", "currency_full", "currency_whole", "date_short", "delta", "email", "id", "integer", "latitude", "longitude", "number", "number_full", "percent", "percent_delta", "percent_whole", "rating", "time_short", "url", … (1 more; see the JSON Schema) | Default tooltip value format string; theme always provides this. |
| `background` | str | Tooltip background color (CSS color string); theme always provides this. |
| `line_height` | float | Tooltip line-height multiplier; theme always provides this. |
| `max_width` | float | Maximum tooltip width in pixels; theme always provides this. |
| `gap` | float | Gap in pixels between label and value columns; theme always provides this. |
| `font` | [FontStyle](#fontstyle) | Tooltip font overrides (size etc.); cascade fills missing fields. Unset fields fall back to [`style.charts.font`](#chartsstyle). |
| `padding` | [PaddingStyle](#paddingstyle) | Tooltip inner padding (4 sides in pixels); theme always provides this. |
| `label` | [TooltipSlotStyle](#tooltipslotstyle) | Label-column font overrides (color, weight). |
| `value` | [TooltipSlotStyle](#tooltipslotstyle) | Value-column font overrides (color, weight). |
| `border` | [TooltipBorderStyle](#tooltipborderstyle) | Tooltip border style; theme always provides this. |
| `shadow` | [TooltipShadowStyle](#tooltipshadowstyle) | Tooltip drop-shadow config; theme always provides this. |
| `swatch` | [TooltipSwatchStyle](#tooltipswatchstyle) | Series color swatch size/shape; theme always provides this. |
| `active_marker` | enum: "fill", "triangle" | How the hovered row is marked in a multi-row (x-unified) tooltip: 'fill' tints the row background (default); 'triangle' draws an edge-flush wedge in the box's left padding instead. Theme always provides this. |

<a id="hoveremphasisstyle"></a>
## HoverEmphasisStyle
Authored overlay for HoverEmphasisStyle. Whether a chart visually answers "what am I pointing at", beyond the tooltip.

| Field | Type | Description |
|-------|------|-------------|
| `visible` | bool | Whether hovering a mark visually emphasizes it; theme always provides this. |
| `dimmed_opacity` | float | Share of its own color a receded bar/arc keeps while another mark is hovered. |
| `drop_line_color` | str | Color of the vertical drop line from a hovered line/area datum down to its axis. |
| `drop_line_width` | float | Width, in pixels, of the vertical drop line from a hovered line/area datum down to its axis. |

<a id="viewstyle"></a>
## ViewStyle
Authored overlay for ViewStyle.

| Field | Type | Description |
|-------|------|-------------|
| `stroke` | str | Plot area border stroke color; None means no border. |
| `continuous_width` | float | Default plot width for continuous (quantitative) scales in pixels. |
| `continuous_height` | float | Default plot height for continuous (quantitative) scales in pixels. |
| `discrete_width` | float | Default plot width for discrete (ordinal/nominal) scales in pixels; None means auto. |
| `discrete_height` | float | Default plot height for discrete (ordinal/nominal) scales in pixels; None means auto. |

<a id="globalmarksstyle"></a>
## GlobalMarksStyle
Authored overlay for GlobalMarksStyle. Global mark defaults: one <Mark>MarkStyle per VL mark type.

| Field | Type | Description |
|-------|------|-------------|
| `bar` | [BarMarkStyle](#barmarkstyle) | Global bar mark defaults. |
| `line` | [LineMarkStyle](#linemarkstyle) | Global line mark defaults. |
| `area` | [AreaMarkStyle](#areamarkstyle) | Global area mark defaults. |
| `point` | [PointMarkStyle](#pointmarkstyle) | Global point mark defaults. |
| `slice` | [SliceMarkStyle](#slicemarkstyle) | Global slice (arc/pie) mark defaults. |
| `text` | [TextMarkStyle](#textmarkstyle) | Global text mark defaults. |
| `rule` | [RuleMarkStyle](#rulemarkstyle) | Global rule mark defaults. |
| `rect` | [RectMarkStyle](#rectmarkstyle) | Global rect mark defaults. |
| `circle` | [CircleMarkStyle](#circlemarkstyle) | Global circle mark defaults. |
| `geoshape` | [GeoshapeMarkStyle](#geoshapemarkstyle) | Global geoshape mark defaults. |

<a id="histogramchartstyle"></a>
## HistogramChartStyle
Authored overlay for HistogramChartStyle. Histogram chart style.

| Field | Type | Description |
|-------|------|-------------|
| `axis_quantitative` | [QuantitativeAxisStyle](#quantitativeaxisstyle) | Per-chart-type quantitative-axis overrides; None inherits the global axis_quantitative at render. |
| `title` | [ChartTitleStyle](#charttitlestyle) | Chart-level title style override; None inherits the theme title style. |
| `legend` | [LegendStyle](#legendstyle) | Chart legend style. |
| `preferred_width` | float | Preferred chart width in pixels. Falls back to [`style.charts.preferred_width`](#chartsstyle). |
| `padding` | [PaddingStyle](#paddingstyle) | Per-chart-type padding override; 4 sides in pixels. Unset fields fall back to [`style.charts.padding`](#chartsstyle). |
| `background` | str | Chart-local background color override; None inherits from theme. |
| `aspect_ratio` | float | Chart aspect ratio (width/height). Falls back to [`style.charts.aspect_ratio`](#chartsstyle). |
| `min_height` | float | Minimum chart height in pixels. Falls back to [`style.charts.min_height`](#chartsstyle). |
| `max_height` | float | Maximum chart height in pixels. Falls back to [`style.charts.max_height`](#chartsstyle). |
| `color` | [ColorStyle](#colorstyle) | Chart color: static mark paint, categorical palette, and/or gradient scale. |
| `axis` | [BaseAxisStyle](#baseaxisstyle) | Override applied to both x and y axes; None inherits the global axis at render. |
| `axis_x` | [AxisXStyle](#axisxstyle) | Per-chart-type x-axis style overrides; None inherits the global axis_x at render. |
| `axis_y` | [AxisYStyle](#axisystyle) | Per-chart-type y-axis style overrides; None inherits the global axis_y at render. |
| `axis_band` | [BandAxisStyle](#bandaxisstyle) | Per-chart-type categorical (band) axis overrides; None inherits the global band axis at render. |
| `support_table` | [SupportTableStyle](#supporttablestyle) | Per-chart-type support_table style override. Unset fields fall back to [`style.charts.support_table`](#chartsstyle). |
| `bin_maxbins` | int | Maximum number of bins for auto-binning. |
| `marks` | [HistogramChartMarksStyle](#histogramchartmarksstyle) | Histogram-family mark overrides. Unset fields fall back to [`style.charts.marks`](#chartsstyle). |

<a id="serieslabelstyle"></a>
## SeriesLabelStyle
Authored overlay for SeriesLabelStyle. Series-label primitive: typography for any text mark that names a

| Field | Type | Description |
|-------|------|-------------|
| `font` | [SeriesLabelFontStyle](#serieslabelfontstyle) | Series label font style overrides; cascade fills missing fields from charts.font. Unset fields fall back to [`style.charts.font`](#chartsstyle). |

<a id="layoutgapstyle"></a>
## LayoutGapStyle
Authored overlay for LayoutGapStyle.

| Field | Type | Description |
|-------|------|-------------|
| `gap` | float | Gap between layout items in pixels. |

<a id="gridlayoutstyle"></a>
## GridLayoutStyle
Authored overlay for GridLayoutStyle.

| Field | Type | Description |
|-------|------|-------------|
| `columns` | int | Number of columns in the grid layout. |
| `gap` | float | Gap between grid cells in pixels. |

<a id="tabsstyle"></a>
## TabsStyle
Authored overlay for TabsStyle.

| Field | Type | Description |
|-------|------|-------------|
| `bar_height` | float | Tab bar height in pixels. |
| `border` | str \| [BorderStyle](#borderstyle) | Tab bar border style. |
| `font` | [FontStyle](#fontstyle) | Tab label font style overrides. Unset fields fall back to [`style.font`](#style). |
| `active_weight` | str | Font weight for the active tab label. |
| `inactive_weight` | str | Font weight for inactive tab labels. |
| `title_baseline_offset` | float | Vertical offset to align SVG tab label baseline in pixels. |

<a id="detailsstyle"></a>
## DetailsStyle
Authored overlay for DetailsStyle.

| Field | Type | Description |
|-------|------|-------------|
| `summary_height` | float | Height of the details summary (collapsed) row in pixels. |
| `border` | str \| [BorderStyle](#borderstyle) | Details element border style. |
| `font` | [FontStyle](#fontstyle) | Details summary font style overrides. Unset fields fall back to [`style.font`](#style). |
| `arrow` | [DetailsArrowStyle](#detailsarrowstyle) | Expand/collapse arrow glyph layout and font style. |
| `label_x` | float | X position of the details summary label text in pixels. |
| `text_baseline_offset` | float | Vertical offset to align SVG details text baseline in pixels. |
| `content_y_offset` | float | Y offset of the expanded details content area in pixels. |

<a id="variableslabelstyle"></a>
## VariablesLabelStyle
Authored overlay for VariablesLabelStyle. Per-label font substyle for variable controls. Cascades from variables.font.

| Field | Type | Description |
|-------|------|-------------|
| `font` | [FontStyle](#fontstyle) | Variable label font style overrides. Unset fields fall back to [`style.variables.font`](#variablesstyle). |

<a id="variablesvaluestyle"></a>
## VariablesValueStyle
Authored overlay for VariablesValueStyle. Per-value font substyle for variable controls. Cascades from variables.font.

| Field | Type | Description |
|-------|------|-------------|
| `font` | [FontStyle](#fontstyle) | Variable value font style overrides. Unset fields fall back to [`style.variables.font`](#variablesstyle). |

<a id="variablesplaceholderstyle"></a>
## VariablesPlaceholderStyle
Authored overlay for VariablesPlaceholderStyle. Per-placeholder font substyle for variable controls.

| Field | Type | Description |
|-------|------|-------------|
| `font` | [FontStyle](#fontstyle) | Variable placeholder-text font style overrides. Unset fields fall back to [`style.variables.font`](#variablesstyle). |

<a id="inputstyle"></a>
## InputStyle
Authored overlay for InputStyle.

| Field | Type | Description |
|-------|------|-------------|
| `height` | float | Input control height in pixels. |
| `border` | [CornerStyle](#cornerstyle) | Corner rounding for input controls. |
| `focus_color` | str | Input focus ring color. Falls back to [`style.accent`](#style). |
| `background` | str | Input background color. |
| `padding` | str \| float \| [SpacingValues](#spacingvalues) | Input inner padding in pixels. |
| `widths` | [InputWidths](#inputwidths) | Per-input-type default widths. |
| `range` | [RangeDefaults](#rangedefaults) | Range input default min/max/step values. |

<a id="footerdividerstyle"></a>
## FooterDividerStyle
Authored overlay for FooterDividerStyle. The footer hairline, plus the gap it reserves above the footer text.

| Field | Type | Description |
|-------|------|-------------|
| `visible` | bool | Draw the divider. |
| `color` | str | Divider color. |
| `width` | float | Divider line width in pixels. |
| `dasharray` | str | Dash pattern in pixels, such as "6 3" (6 drawn, 3 gap); unset draws a solid line. |
| `gap` | float | Vertical gap between the footer text and its divider. |

<a id="numberlocale"></a>
## NumberLocale
A d3 formatLocale definition.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `decimal` | str | The decimal mark (e.g. `"."`). |
| `thousands` | str | The group separator (e.g. `","`). |
| `grouping` | tuple[int, ...] | The group sizes (e.g. `[3]`), cycled as needed. |
| `currency` | tuple[str, str] | The currency prefix and suffix (e.g. `["$", ""]`) a `$` in a d3 spec prints. |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `percent` | str | The percent sign. |
| `minus` | str | The minus sign. |
| `analytic` | tuple[str, str, str, str] | The extra-short thousand, million, billion and trillion suffixes, where a magnitude is declared once (en-US: K, M, B, T). A leading space, where a locale wants one, is part of the suffix. |
| `narrative` | tuple[str, str, str, str] | The abbreviated thousand, million, billion and trillion suffixes on every value (en-US: `["k", "mn", "bn", "trn"]`). |

<a id="timelocale"></a>
## TimeLocale
A d3 timeFormatLocale definition.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `date_time` | str | The `%c` pattern. |
| `date` | str | The `%x` pattern. |
| `time` | str | The `%X` pattern. |
| `periods` | tuple[str, str] | The AM and PM names. |
| `days` | tuple[str, str, str, str, str, str, str] | The weekday names, Sunday first. |
| `short_days` | tuple[str, str, str, str, str, str, str] | The abbreviated weekday names. |
| `months` | tuple[str, str, str, str, str, str, str, str, str, str, str, str] | The month names, January first. |
| `short_months` | tuple[str, str, str, str, str, str, str, str, str, str, str, str] | The abbreviated month names. |
| `week_start` | enum: "sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday" | The first day of the calendar week. |

<a id="baseaxisgridstyle"></a>
## BaseAxisGridStyle
Authored overlay for BaseAxisGridStyle. Grid line style for all axis variants.

| Field | Type | Description |
|-------|------|-------------|
| `visible` | bool | Show grid lines; None inherits from parent axis. |
| `opacity` | float | Grid line opacity; None uses Vega-Lite's default. |
| `width` | float | Grid line width in pixels; None uses Vega-Lite's default. |
| `color` | str | Grid line color; None uses Vega-Lite's default. |
| `dash` | list[float] | Dash pattern for grid lines; None renders a solid line. |
| `threshold` | [AxisGridThresholdStyle](#axisgridthresholdstyle) | Threshold-rule gridline style; None inherits from parent axis. |

<a id="axislinestyle"></a>
## AxisLineStyle
Authored overlay for AxisLineStyle. Axis domain/baseline line style. Renamed from ``AxisDomainStyle``:

| Field | Type | Description |
|-------|------|-------------|
| `visible` | bool | Show the axis domain line; None inherits from parent axis. |
| `width` | float | Domain line width in pixels; None uses Vega-Lite's default. |
| `color` | str | Domain line color; None uses Vega-Lite's default. |

<a id="axisticksstyle"></a>
## AxisTicksStyle
Authored overlay for AxisTicksStyle. Tick marks on an axis: visibility, color, size, and cadence.

| Field | Type | Description |
|-------|------|-------------|
| `visible` | bool | Show axis ticks; None inherits from parent axis. |
| `color` | str | Tick color; None uses Vega-Lite's default. |
| `length` | float | Tick length in pixels; None uses Vega-Lite's default. |
| `width` | float | Tick stroke width in pixels; None uses Vega-Lite's default. |
| `offset` | float | Pixel offset of ticks from their default position; None means no offset. |
| `count` | int \| const: "auto" | Target number of axis ticks, or 'auto' for the engine's own sparse ladder: a target everywhere, never an exact count. On the measure axis (axis_y) the renderer computes an explicit round-numbered ladder of at most this many ticks. On axis_x it passes through as VL's axis.tickCount: a temporal scale honors it closely, a quantitative one rounds to a nearby round-numbered ladder. To name the interval instead of the count, author ticks.step on a quantitative axis_x. An ordinal axis_x has no tick-count concept and ignores this. |
| `step` | int | Tick interval on axis_x. Alongside ticks.time_unit it is a multiple of that calendar grain (time_unit: year, step: 5 -&gt; a tick every 5 years). On its own it is a numeric interval for a quantitative axis (step: 1000 -&gt; a tick every 1000), and acts as a floor rather than a fixed ladder, so the axis keeps covering the data as its range grows. A bare step on an axis that is not quantitative is an error, not a no-op; axis_y rejects step entirely (set ticks.count there instead). |

<a id="axislabelstyle"></a>
## AxisLabelStyle
Authored overlay for AxisLabelStyle. Axis label: font + padding + VL-passthrough.

| Field | Type | Description |
|-------|------|-------------|
| `font` | [FontStyle](#fontstyle) | Axis element font style overrides. Unset fields fall back to [`style.charts.font`](#chartsstyle). |
| `padding` | float | Padding between axis labels and ticks in pixels; None inherits from parent axis. |
| `max_width` | float | Maximum label width in pixels; None uses Vega-Lite's default (180px). |
| `angle` | float | Label rotation angle in degrees; None uses Vega-Lite's default. |
| `align` | enum: "left", "right", "center", "inward", "outward" | Horizontal text alignment of labels. 'left'/'right'/'center' are absolute. 'inward' hugs the plot (own-side: left on a left axis, right on a right axis); 'outward' hugs away from the plot (Vega-Lite's default growth direction). inward/outward are a no-op on an axis with no left/right edge. None uses Vega-Lite's default. |
| `overlap` | [AxisLabelOverlapConfig](#axislabeloverlapconfig) | Label overlap strategy enablement. None inherits from the theme cascade. Set individual bools to enable/disable; they are applied in fixed order skip→tilt. On bucketed temporal axes, skip thins label visibility to a coarser calendar period without changing the axis or label time unit. |
| `min_gap` | float | Minimum pixel gap between labels; None uses Vega-Lite's default (0px). |
| `visible` | bool | Show axis labels; None uses Vega-Lite's default (labels shown). |
| `expr` | str | Custom Vega expression for label text; None uses smart temporal defaults when applicable. |
| `bound` | bool \| float | Hide labels that overflow the axis range; None uses Vega-Lite's default. |
| `flush` | bool \| float | Align first/last label flush with the scale range; None uses Vega-Lite's default. |
| `offset` | float | Pixel offset of the label from its tick anchor; None uses Vega-Lite's default. |
| `format` | str \| [FormatConfig](#formatconfig) \| enum: "compact", "currency", "currency_compact", "currency_full", "currency_whole", "date_short", "delta", "email", "id", "integer", "latitude", "longitude", "number", "number_full", "percent", "percent_delta", "percent_whole", "rating", "time_short", "url", … (1 more; see the JSON Schema) | Tick value format string; None uses auto-format. |

<a id="axistitlestyle"></a>
## AxisTitleStyle
Authored overlay for AxisTitleStyle. Axis title typography, deliberately thin. A title is one short static

| Field | Type | Description |
|-------|------|-------------|
| `font` | [FontStyle](#fontstyle) | Axis title font style overrides. Unset fields fall back to [`style.charts.font`](#chartsstyle). |
| `padding` | float | Padding between axis title and labels in pixels; None uses Vega-Lite's default. |
| `angle` | float | Title rotation angle in degrees; None uses Vega-Lite's default. |
| `align` | enum: "left", "right", "center", "inward", "outward" | Horizontal text alignment of the title. 'left'/'right'/'center' are absolute. 'inward'/'outward' resolve against the axis's own left/right edge, same as label.align; a no-op on an axis with no left/right edge. None uses Vega-Lite's default. |
| `visible` | bool \| const: "auto" | Show the axis title; None uses Vega-Lite's default (title shown). 'auto' shows it only when the chart authors an x_label/y_label. An explicit true/false from any tier wins. |

<a id="basescalestyle"></a>
## BaseScaleStyle
Authored overlay for BaseScaleStyle. Universal + continuous-only scale config.

| Field | Type | Description |
|-------|------|-------------|
| `round` | bool | Round scale outputs to nearest integer; None uses Vega-Lite's default (no rounding). |
| `clamp` | bool | Clamp values to scale domain; None uses Vega-Lite's default (no clamping). |
| `nice` | bool | Round the axis domain to nice values; None uses Vega-Lite's default. Forwards natively to Vega-Lite's scale.nice. |
| `padding` | float | Unified scale padding shortcut; dispatches to band, point, or continuous padding per scale type. |
| `headroom` | float | Fractional breathing room at measure-axis edges, exact (never nice-rounded). Zero-anchored axes (bar; line/area/scatter near zero): domain_max = data_max * (1 + headroom). Zoomed axes (line/area/scatter far from zero): both edges expand: domain_max = data_max + headroom * span; domain_min = data_min - headroom * span. None inherits the theme default; 0 disables headroom. Ignored with an explicit `domain` or `stack: normalize`. |
| `values` | list[Any] | Explicit tick values; None uses Vega-Lite's auto tick values. |
| `continuous` | [ScaleContinuousStyle](#scalecontinuousstyle) | Continuous-scale overrides (type, domain, zero, log/pow/symlog params); None means no override. |

<a id="charttitlefontstyle"></a>
## ChartTitleFontStyle
A chart title's font: a font whose ``size``, ``weight`` and ``family`` also

| Field | Type | Description |
|-------|------|-------------|
| `extends` | str | Name of a ``style.fonts`` entry this slot starts from; the fields set beside it override that entry. |
| `family` | str \| const: "auto" | Font family name, or 'auto' to follow the card width. |
| `color` | str | Text color as a CSS color string. |
| `size` | float \| const: "auto" | Font size in pixels, or 'auto' to follow the card width. |
| `weight` | str \| float \| const: "auto" | How heavy the type is drawn (e.g., 'bold', 400, 700), or 'auto' to follow the card width. |
| `style` | enum: "normal", "italic" | Upright or slanted type (normal or italic). |
| `decoration` | enum: "none", "line-through", "underline" | Line drawn on the text (underline, line-through, or none). |
| `case` | enum: "none", "sentence", "title", "upper", "lower", "slug", "camel" | Letter-case transform applied at render time. |
| `line_height` | float | Line height as a unitless multiple of font size. |

<a id="legendrowstyle"></a>
## LegendRowStyle
Authored overlay for LegendRowStyle. Fixed chrome around each entry of a single-row top legend.

| Field | Type | Description |
|-------|------|-------------|
| `swatch_width` | float | Swatch box width in pixels. |
| `entry_gap` | float | Gap in pixels between one entry and the next. |

<a id="legendlabelstyle"></a>
## LegendLabelStyle
Authored overlay for LegendLabelStyle.

| Field | Type | Description |
|-------|------|-------------|
| `font` | [FontStyle](#fontstyle) | Legend element font style overrides. Unset fields fall back to [`style.charts.font`](#chartsstyle). |
| `padding` | float | Padding between legend symbol and element text in pixels. |
| `max_width` | float | Maximum label width in pixels; maps to VL labelLimit. None uses Vega-Lite's default. |

<a id="legendtitlestyle"></a>
## LegendTitleStyle
Authored overlay for LegendTitleStyle.

| Field | Type | Description |
|-------|------|-------------|
| `font` | [FontStyle](#fontstyle) | Legend element font style overrides. Unset fields fall back to [`style.charts.font`](#chartsstyle). |
| `padding` | float | Padding between legend symbol and element text in pixels. |
| `visible` | bool \| const: "auto" | Show the legend title. 'auto' shows it except on a top legend that runs horizontally; false suppresses it (VL legend.title: null). |

<a id="legendpositionstyle"></a>
## LegendPositionStyle
Authored overlay for LegendPositionStyle. Cartesian and geo legend placement: edge, align along it, overlay or reserve.

| Field | Type | Description |
|-------|------|-------------|
| `edge` | enum: "left", "right", "top", "bottom" | Side of the plot the legend sits on. 'auto' = the engine decides. |
| `align` | enum: "start", "center", "end" | Position along the edge. 'auto' = the engine decides. |
| `overlay` | bool \| const: "auto" | True floats the legend over the plot, reserving no space; False reserves a strip for it. 'auto' = the engine decides. |

<a id="scaletargetconfig"></a>
## ScaleTargetConfig
Authored overlay for ScaleTargetConfig. Scale configuration for a single style target (background or color).

| Field | Type | Description |
|-------|------|-------------|
| `palette` | str \| list[str] \| list[float] \| enum: "accent", "bluegreen", "blueorange", "bluepurple", "blues", "brownbluegreen", "browns", "category-6-tonal-blue", "category-6-tonal-blue.dark", "category-6-tonal-blue.deep", "category-6-tonal-blue.light", "category-6-tonal-blue.pale", "category-6-tonal-brown", "category-6-tonal-brown.dark", "category-6-tonal-brown.deep", "category-6-tonal-brown.light", "category-6-tonal-brown.pale", "category-6-tonal-green", "category-6-tonal-green.dark", "category-6-tonal-green.deep", … (120 more; see the JSON Schema) | Which colors the scale draws from: a built-in palette name or Vega scheme, a CSS color list for categorical, or a float list for relative stops. |
| `domain` | const: "data" | Scale domain source ('data' uses the data extent, widened to nice round bounds when nice is true; None uses explicit min/max). |
| `min` | float \| int | Minimum scale domain value (overrides data minimum). |
| `max` | float \| int | Maximum scale domain value (overrides data maximum). |
| `nice` | bool | Widen a data-derived domain to round ('nice') bounds and label every nice tick on the legend, mirroring Vega-Lite's own scale.nice. Applies to the color scale a gradient legend labels, not the x/y position scale. Ignored once min or max is set; a single-sided bound already fixes that edge exactly. Widening is currently honored on heatmap's themed color gradient only; geoshape's choropleth honors `nice: false` (exact endpoint labels) but not `nice: true`'s widening. |
| `null_color` | str | Color assigned to null values. |
| `hinge` | float \| const: "auto" | Diverging scale midpoint value, or 'auto' to use the data midpoint. |
| `arm_mode` | enum: "asymmetric", "symmetric" | How diverging scale arms are stretched: 'asymmetric' (proportional) or 'symmetric' (equal arms). |

<a id="categoricalcolorstyle"></a>
## CategoricalColorStyle
Authored overlay for CategoricalColorStyle. Categorical palette config: per-series colors and single-series ink list.

| Field | Type | Description |
|-------|------|-------------|
| `palette` | str \| list[str] \| enum: "category-6-tonal-blue", "category-6-tonal-blue.dark", "category-6-tonal-blue.deep", "category-6-tonal-blue.light", "category-6-tonal-blue.pale", "category-6-tonal-brown", "category-6-tonal-brown.dark", "category-6-tonal-brown.deep", "category-6-tonal-brown.light", "category-6-tonal-brown.pale", "category-6-tonal-green", "category-6-tonal-green.dark", "category-6-tonal-green.deep", "category-6-tonal-green.light", "category-6-tonal-green.pale", "category-6-tonal-orange", "category-6-tonal-orange.dark", "category-6-tonal-orange.deep", "category-6-tonal-orange.light", "category-6-tonal-orange.pale", … (53 more; see the JSON Schema) | Categorical color palette: list of stops or a named palette. Expanded to list[str] at validation time. |
| `single_series_palette` | str \| list[str] \| enum: "category-6-tonal-blue", "category-6-tonal-blue.dark", "category-6-tonal-blue.deep", "category-6-tonal-blue.light", "category-6-tonal-blue.pale", "category-6-tonal-brown", "category-6-tonal-brown.dark", "category-6-tonal-brown.deep", "category-6-tonal-brown.light", "category-6-tonal-brown.pale", "category-6-tonal-green", "category-6-tonal-green.dark", "category-6-tonal-green.deep", "category-6-tonal-green.light", "category-6-tonal-green.pale", "category-6-tonal-orange", "category-6-tonal-orange.dark", "category-6-tonal-orange.deep", "category-6-tonal-orange.light", "category-6-tonal-orange.pale", … (53 more; see the JSON Schema) | Ordered list of single-series mark inks (must be non-empty when set), or a palette name. |

<a id="dimensionticksstyle"></a>
## DimensionTicksStyle
Authored overlay for DimensionTicksStyle. axis_x-only: adds the calendar unit that anchors a step cadence.

| Field | Type | Description |
|-------|------|-------------|
| `visible` | bool \| const: "auto" | Show axis ticks. "auto" shows the tick only where the gridlines can't reach all the way to the labels on their own; None inherits from parent axis. |
| `color` | str | Tick color; None uses Vega-Lite's default. |
| `length` | float | Tick length in pixels; None uses Vega-Lite's default. |
| `width` | float | Tick stroke width in pixels; None uses Vega-Lite's default. |
| `offset` | float | Pixel offset of ticks from their default position; None means no offset. |
| `count` | int \| const: "auto" | Target number of axis ticks, or 'auto' for the engine's own sparse ladder: a target everywhere, never an exact count. On the measure axis (axis_y) the renderer computes an explicit round-numbered ladder of at most this many ticks. On axis_x it passes through as VL's axis.tickCount: a temporal scale honors it closely, a quantitative one rounds to a nearby round-numbered ladder. To name the interval instead of the count, author ticks.step on a quantitative axis_x. An ordinal axis_x has no tick-count concept and ignores this. |
| `step` | int | Tick interval on axis_x. Alongside ticks.time_unit it is a multiple of that calendar grain (time_unit: year, step: 5 -&gt; a tick every 5 years). On its own it is a numeric interval for a quantitative axis (step: 1000 -&gt; a tick every 1000), and acts as a floor rather than a fixed ladder, so the axis keeps covering the data as its range grows. A bare step on an axis that is not quantitative is an error, not a no-op; axis_y rejects step entirely (set ticks.count there instead). |
| `time_unit` | enum: "auto", "year", "yearquarter", "yearmonth", "yearweek", "yearmonthdate", "monthofyear", "dayofweek", "dayofmonth", "dayofyear", "hourofday", "none" | Step-anchored tick cadence unit; None disables step-anchored ticks. |

<a id="dimensionlabelstyle"></a>
## DimensionLabelStyle
Authored overlay for DimensionLabelStyle. AxisLabelStyle + dimension-axis-only label fields.

| Field | Type | Description |
|-------|------|-------------|
| `font` | [FontStyle](#fontstyle) | Axis element font style overrides. Unset fields fall back to [`style.charts.font`](#chartsstyle). |
| `padding` | float | Padding between axis labels and ticks in pixels; None inherits from parent axis. |
| `max_width` | float | Maximum label width in pixels; None uses Vega-Lite's default (180px). |
| `angle` | float | Label rotation angle in degrees; None uses Vega-Lite's default. |
| `align` | enum: "left", "right", "center", "inward", "outward" | Horizontal text alignment of labels. 'left'/'right'/'center' are absolute. 'inward' hugs the plot (own-side: left on a left axis, right on a right axis); 'outward' hugs away from the plot (Vega-Lite's default growth direction). inward/outward are a no-op on an axis with no left/right edge. None uses Vega-Lite's default. |
| `overlap` | [AxisLabelOverlapConfig](#axislabeloverlapconfig) | Label overlap strategy enablement. None inherits from the theme cascade. Set individual bools to enable/disable; they are applied in fixed order skip→tilt. On bucketed temporal axes, skip thins label visibility to a coarser calendar period without changing the axis or label time unit. |
| `min_gap` | float | Minimum pixel gap between labels; None uses Vega-Lite's default (0px). |
| `visible` | bool | Show axis labels; None uses Vega-Lite's default (labels shown). |
| `expr` | str | Custom Vega expression for label text; None uses smart temporal defaults when applicable. |
| `bound` | bool \| float | Hide labels that overflow the axis range; None uses Vega-Lite's default. |
| `flush` | bool \| float | Align first/last label flush with the scale range; None uses Vega-Lite's default. |
| `offset` | float | Pixel offset of the label from its tick anchor; None uses Vega-Lite's default. |
| `format` | str \| [FormatConfig](#formatconfig) \| enum: "compact", "currency", "currency_compact", "currency_full", "currency_whole", "date_short", "delta", "email", "id", "integer", "latitude", "longitude", "number", "number_full", "percent", "percent_delta", "percent_whole", "rating", "time_short", "url", … (1 more; see the JSON Schema) | Tick value format string; None uses auto-format. |
| `time_unit` | enum: "auto", "year", "yearquarter", "yearmonth", "yearweek", "yearmonthdate", "monthofyear", "dayofweek", "dayofmonth", "dayofyear", "hourofday", "none" | Label cadence for temporal axes; None inherits from the parent axis time_unit. |
| `clock` | enum: 24, 12 | Sub-day clock register for a continuous temporal x-axis: 24 for the unambiguous, meridiem-free 24-hour clock, or 12 for the 12-hour clock with the Noon/Midnight word vocabulary. None leaves the value to the theme cascade. |
| `tilt_increments` | list[float] | Descending tilt angles for label overlap resolution on discrete x-axes; None disables tilt. |
| `values` | list[Any] | Dates to keep label text on, chosen from among the axis's ticks (whatever axis_x.scale.values or the auto-fill cadence already produced): this filters which ticks show text, it does not add or remove ticks. Every tick not in this list keeps its position and gridline but has its label blanked. Set axis_x.scale.values separately to change tick/grid density itself. Temporal x-axes only; not supported on a horizontal bar's categorical axis. None labels every tick as usual. |

<a id="xscalestyle"></a>
## XScaleStyle
Authored overlay for XScaleStyle. Scale config for axis_x.scale only.

| Field | Type | Description |
|-------|------|-------------|
| `round` | bool | Round scale outputs to nearest integer; None uses Vega-Lite's default (no rounding). |
| `clamp` | bool | Clamp values to scale domain; None uses Vega-Lite's default (no clamping). |
| `nice` | bool | Round the axis domain to nice values; None uses Vega-Lite's default. Forwards natively to Vega-Lite's scale.nice. |
| `padding` | float | Unified scale padding shortcut; dispatches to band, point, or continuous padding per scale type. |
| `headroom` | float | Fractional breathing room at measure-axis edges, exact (never nice-rounded). Zero-anchored axes (bar; line/area/scatter near zero): domain_max = data_max * (1 + headroom). Zoomed axes (line/area/scatter far from zero): both edges expand: domain_max = data_max + headroom * span; domain_min = data_min - headroom * span. None inherits the theme default; 0 disables headroom. Ignored with an explicit `domain` or `stack: normalize`. |
| `values` | list[Any] | Explicit tick values; None uses Vega-Lite's auto tick values. |
| `continuous` | [ScaleContinuousStyle](#scalecontinuousstyle) | Continuous-scale overrides (type, domain, zero, log/pow/symlog params); None means no override. |
| `x_reverse` | bool | Reverse the x-axis scale direction; None means no reversal. |

<a id="axismirrorstyle"></a>
## AxisMirrorStyle
Per-edge label override for the mirrored ``axis_y.mirror`` ghost axis.

| Field | Type | Description |
|-------|------|-------------|
| `format` | str \| [FormatConfig](#formatconfig) \| enum: "compact", "currency", "currency_compact", "currency_full", "currency_whole", "date_short", "delta", "email", "id", "integer", "latitude", "longitude", "number", "number_full", "percent", "percent_delta", "percent_whole", "rating", "time_short", "url", … (1 more; see the JSON Schema) | Tick value format string for the mirrored edge; None reuses the primary axis's format. |
| `expr` | str | Custom Vega expression for the mirrored edge's label text; None reuses the primary axis's label expression. |

<a id="supporttablefontstyle"></a>
## SupportTableFontStyle
The support_table font. ``color`` also takes ``auto``.

| Field | Type | Description |
|-------|------|-------------|
| `extends` | str | Name of a ``style.fonts`` entry this slot starts from; the fields set beside it override that entry. |
| `family` | str | Font family name (e.g., 'sans-serif', 'Roboto'). |
| `color` | str | Text color. 'auto' paints a per-series cell in its series' dark ink and every other cell in `neutral_color`. A color paints every cell. |
| `size` | float | Font size in pixels. |
| `weight` | str \| float | How heavy the type is drawn (e.g., 'bold', 400, 700). |
| `style` | enum: "normal", "italic" | Upright or slanted type (normal or italic). |
| `decoration` | enum: "none", "line-through", "underline" | Line drawn on the text (underline, line-through, or none). |
| `case` | enum: "none", "sentence", "title", "upper", "lower", "slug", "camel" | Letter-case transform applied at render time. 'title' uses Chicago/Gruber rules and preserves tokens with internal capitals (ARR, iPhone). 'sentence' uppercases only the first character. 'none' (default) emits the string without any letter-case change. |
| `line_height` | float | Line height as a unitless multiple of font size. Cascades through Style.font to all text roles that carry a FontStyle slot. Body prose defaults to 1.25; titles override tighter via their font patch in theme YAML. |

<a id="supporttabledividerstyle"></a>
## SupportTableDividerStyle
Authored overlay for SupportTableDividerStyle. The rule between plot and strip, plus the gap it reserves before the first row.

| Field | Type | Description |
|-------|------|-------------|
| `visible` | bool | Draw the divider. |
| `color` | str | Divider color. |
| `width` | float | Divider line width in pixels. |
| `dasharray` | str | Dash pattern in pixels, such as "6 3" (6 drawn, 3 gap); unset draws a solid line. |
| `gap` | float | Vertical gap between the divider and the first strip row. |

<a id="supporttablerowstyle"></a>
## SupportTableRowStyle
Authored overlay for SupportTableRowStyle.

| Field | Type | Description |
|-------|------|-------------|
| `padding` | [SupportTableRowPaddingStyle](#supporttablerowpaddingstyle) | Row padding style. |
| `divider` | [DividerStyle](#dividerstyle) | Line under each strip row. |

<a id="supporttablelabelstyle"></a>
## SupportTableLabelStyle
Authored overlay for SupportTableLabelStyle. Row label styling.

| Field | Type | Description |
|-------|------|-------------|
| `font` | [SupportTableFontStyle](#supporttablefontstyle) | Row label font style overrides. An 'auto' color follows the table's own font color, or `neutral_color` when that is also 'auto'. Unset fields fall back to [`style.charts.support_table.font`](#supporttablestyle). |

<a id="barmarkstyle"></a>
## BarMarkStyle
Authored overlay for BarMarkStyle. Bar mark geometry and stroke. Chart-level bar fields live on BarChartStyle.

| Field | Type | Description |
|-------|------|-------------|
| `border` | str \| [BorderStyle](#borderstyle) | Bar border style (color/width also serve as the bar stroke). |
| `padding` | float | Padding around bar marks in pixels. |
| `size` | float | Bar width in pixels; overrides all other sizing. |
| `band_width` | float | Bar width as a fraction of the band step (0–1). |
| `gap` | float | Target pixel gap between adjacent bars on a continuous scale. |
| `min_size` | float | Narrowest a computed bar width may shrink to on a continuous scale. |
| `max_size` | float | Thickest a bar may be, in pixels: caps a band-scale bar's band fraction and a continuous scale's computed width. Unset, band bars are uncapped and a continuous scale applies a built-in ceiling. Also stands in for an unauthored `size` when reserving axis padding and when budgeting a horizontal bar chart's minimum height. |
| `opacity` | float | Bar fill opacity (0–1); None uses VL default. |
| `labels` | [BarLabelsStyle](#barlabelsstyle) | Value label style for bar marks. |
| `total_label` | [BarTotalLabelStyle](#bartotallabelstyle) | Stack total label style. Only takes effect on stacked bar charts; ignored otherwise. |

<a id="textmarkstyle"></a>
## TextMarkStyle
Authored overlay for TextMarkStyle.

| Field | Type | Description |
|-------|------|-------------|
| `font` | [FontStyle](#fontstyle) | Text mark font style overrides. Unset fields fall back to [`style.charts.font`](#chartsstyle). |
| `align` | str | Horizontal text alignment for text marks. |

<a id="layeraxisyscale"></a>
## LayerAxisYScale
Per-layer y-axis scale patch.

| Field | Type | Description |
|-------|------|-------------|
| `domain` | list[float] | Explicit [min, max] domain for this layer's y scale. |
| `clip` | bool | Whether marks outside the domain are cut off at the plot edge. False lets them run past the plot. |

<a id="layeraxisyticks"></a>
## LayerAxisYTicks
Per-layer y-axis tick patch.

| Field | Type | Description |
|-------|------|-------------|
| `count` | int | Target number of ticks on this layer's y axis; a target, never an exact count. |

<a id="layeraxisygrid"></a>
## LayerAxisYGrid
Per-layer y-axis grid patch.

| Field | Type | Description |
|-------|------|-------------|
| `visible` | bool | Whether to show grid lines on this layer's y axis. |

<a id="layeraxisylabels"></a>
## LayerAxisYLabels
Per-layer y-axis tick-label format patch.

| Field | Type | Description |
|-------|------|-------------|
| `format` | str \| [FormatConfig](#formatconfig) \| enum: "compact", "currency", "currency_compact", "currency_full", "currency_whole", "date_short", "delta", "email", "id", "integer", "latitude", "longitude", "number", "number_full", "percent", "percent_delta", "percent_whole", "rating", "time_short", "url", … (1 more; see the JSON Schema) | d3 format string for this layer's y-axis tick labels. |

<a id="linemarkstyle"></a>
## LineMarkStyle
Authored overlay for LineMarkStyle. Line mark stroke, interpolation, and halo. Point mark lives on PointMarkStyle.

| Field | Type | Description |
|-------|------|-------------|
| `stroke` | [StrokeStyle](#strokestyle) | Line stroke style. |
| `curve` | enum: "linear", "monotone", "natural", "basis", "cardinal", "step", "step-before", "step-after" | Line interpolation curve, one of a fixed set: 'linear', 'monotone', 'natural', 'basis', 'cardinal', 'step', 'step-before', 'step-after'. On a categorical (nominal/ordinal) x-axis, 'step' draws a full-band-width plateau per x-value instead of VL's centered step; on a continuous (temporal/quantitative) x-axis it passes straight through to VL's native step. |
| `connect` | bool | For curve='step' on a categorical (band) x-axis, whether adjacent band plateaus are joined by vertical jumps (True/None) or left as disconnected segments (False). No-op for other curves or a continuous x-axis. |
| `disconnected_cap` | enum: "butt", "round", "square" | Stroke line cap for the sub-paths of a disconnected band-step (curve='step' + connect=False on a categorical x-axis). Each band is its own flat path there, so the cap lands on every band edge rather than only the two ends of one continuous line; 'butt' keeps plateaus flush with the band. Overrides stroke.cap in that geometry only; every other line keeps stroke.cap. |
| `disconnected_width` | float | Share of the band width a disconnected band-step plateau spans (curve='step' + connect=False on a categorical x-axis). Below 1 leaves a gap between neighboring plateaus so they don't weld into one bar. Connected lines keep the full band. |
| `halo_multiplier` | float | Halo stroke width multiplier relative to stroke.width; 0 disables the halo. |
| `labels` | [PointLabelsStyle](#pointlabelsstyle) | Value label style for line marks. |

<a id="pointmarkstyle"></a>
## PointMarkStyle
Authored overlay for PointMarkStyle. Point mark style (data-point markers on scatter/point/line/area charts).

| Field | Type | Description |
|-------|------|-------------|
| `size` | float | Point size in square pixels; 0 disables points on line charts. |
| `color` | str | Point color. On a single-series scatter it recolors the dots, over color.static and the palette; None inherits the series color. |
| `shape` | str | Point shape (e.g. 'circle', 'square'); None uses VL default. |
| `opacity` | float | Point opacity 0–1; None uses VL default. |
| `filled` | bool | Whether points are filled; None uses VL default. |
| `fill` | str | Point interior fill color; only applied when filled=false. |
| `stroke_width` | float | Stroke width in pixels for hollow point rings; None uses VL default. |
| `labels` | [PointLabelsStyle](#pointlabelsstyle) | Value label style for point marks. On line charts, setting marks.point.labels is an alias for marks.line.labels. |

<a id="rulemarkstyle"></a>
## RuleMarkStyle
Authored overlay for RuleMarkStyle. Rule (reference line) mark opacity and stroke.

| Field | Type | Description |
|-------|------|-------------|
| `opacity` | float | Mark opacity (0–1); None means not overridden at this level. |
| `stroke` | [FontColorStrokeStyle](#fontcolorstrokestyle) | Mark stroke style. |

<a id="areamarkstyle"></a>
## AreaMarkStyle
Authored overlay for AreaMarkStyle. Area mark fill opacity and shape.

| Field | Type | Description |
|-------|------|-------------|
| `opacity` | float | Area fill opacity (0–1). |
| `curve` | enum: "linear", "monotone", "natural", "basis", "cardinal", "step", "step-before", "step-after" | Area interpolation curve, one of a fixed set: 'linear', 'monotone', 'natural', 'basis', 'cardinal', 'step', 'step-before', 'step-after'. On a categorical (nominal/ordinal) x-axis, 'step' draws a full-band-width plateau per x-value instead of VL's centered step; on a continuous (temporal/quantitative) x-axis it passes straight through to VL's native step. Applied to both the fill and its edge line (marks.line) so they trace the same path. |
| `backdrop` | bool | Whether to paint an opaque fill backdrop behind the area. |
| `stacked` | [AreaStackedMarkStyle](#areastackedmarkstyle) | Recipe override applied when the chart is stacked or has a single series: solid fill + background-color separator stroke. |

<a id="arealinestyle"></a>
## AreaLineStyle
Authored overlay for AreaLineStyle. Stroke/halo/labels for an area chart's top-edge line and value labels.

| Field | Type | Description |
|-------|------|-------------|
| `stroke` | [StrokeStyle](#strokestyle) | Area top-edge line stroke style. |
| `halo_multiplier` | float | Halo stroke width multiplier relative to stroke.width; 0 disables the halo. |
| `labels` | [PointLabelsStyle](#pointlabelsstyle) | Value label style for the area's plotted points; inherits from global. |

<a id="rectmarkstyle"></a>
## RectMarkStyle
Authored overlay for RectMarkStyle. Rect mark opacity and stroke.

| Field | Type | Description |
|-------|------|-------------|
| `opacity` | float | Mark opacity (0–1); None means not overridden at this level. |
| `stroke` | [StrokeStyle](#strokestyle) | Mark stroke style; None means not overridden at this level. |

<a id="piepositionstyle"></a>
## PiePositionStyle
Authored overlay for PiePositionStyle. Pie key placement: edge and align, never overlay.

| Field | Type | Description |
|-------|------|-------------|
| `edge` | enum: "left", "right", "top", "bottom" | Side of the wheel the key (legend or attached table) sits on. 'auto' = the engine decides. |
| `align` | enum: "start", "center", "end" | Position of the key along that edge. 'auto' = the engine decides. |

<a id="totalvalueslotstyle"></a>
## TotalValueSlotStyle
Authored overlay for TotalValueSlotStyle. Theme slot for the donut center value (the number): paint plus its format.

| Field | Type | Description |
|-------|------|-------------|
| `font` | [FontStyle](#fontstyle) | Donut center total element font style overrides. Unset fields fall back to [`style.charts.font`](#chartsstyle). |
| `format` | str \| [FormatConfig](#formatconfig) \| enum: "compact", "currency", "currency_compact", "currency_full", "currency_whole", "date_short", "delta", "email", "id", "integer", "latitude", "longitude", "number", "number_full", "percent", "percent_delta", "percent_whole", "rating", "time_short", "url", … (1 more; see the JSON Schema) | How the donut center value is written: a D3 spec, a preset name, or a format block. |

<a id="totalslotstyle"></a>
## TotalSlotStyle
Authored overlay for TotalSlotStyle. Theme slot for one text element of the donut center total.

| Field | Type | Description |
|-------|------|-------------|
| `font` | [FontStyle](#fontstyle) | Donut center total element font style overrides. Unset fields fall back to [`style.charts.font`](#chartsstyle). |

<a id="slicemarkstyle"></a>
## SliceMarkStyle
Authored overlay for SliceMarkStyle. Pie/donut slice mark: mark-level paint and layout only.

| Field | Type | Description |
|-------|------|-------------|
| `opacity` | float | Arc slice opacity (0–1); None means not overridden at this level. |
| `gap` | float | Angular gap between slices in radians. |
| `corner_radius` | float | Corner radius of arc slices in pixels. |
| `stroke` | [StrokeStyle](#strokestyle) | Arc slice stroke style. |
| `labels` | [SliceLabelsStyle](#slicelabelsstyle) | Per-slice label style. |

<a id="kpicompactstyle"></a>
## KpiCompactStyle
Authored overlay for KpiCompactStyle. When an unformatted KPI headline compacts, and to what.

| Field | Type | Description |
|-------|------|-------------|
| `spec` | str | D3 format spec the headline compacts to. |
| `threshold` | float | Smallest absolute value that compacts; below it, exact digits. |

<a id="kpitextslotstyle"></a>
## KpiTextSlotStyle
Authored overlay for KpiTextSlotStyle. A KPI text slot styled by its font alone (affix, headline glyph).

| Field | Type | Description |
|-------|------|-------------|
| `font` | [SingleLineFontStyle](#singlelinefontstyle) | Slot font. Unset fields fall back to [`style.charts.kpi.font`](#kpichartstyle). |

<a id="kpisupportfontstyle"></a>
## KpiSupportFontStyle
The support row and glyph font. ``color`` also takes ``auto``.

| Field | Type | Description |
|-------|------|-------------|
| `extends` | str | Name of a ``style.fonts`` entry this slot starts from; the fields set beside it override that entry. |
| `family` | str | Font family name (e.g., 'sans-serif', 'Roboto'). |
| `color` | str | Text color. 'auto' is the support tone's color, or the muted ink when the row has no tone. |
| `size` | float | Font size in pixels. |
| `weight` | str \| float | How heavy the type is drawn (e.g., 'bold', 400, 700). |
| `style` | enum: "normal", "italic" | Upright or slanted type (normal or italic). |
| `decoration` | enum: "none", "line-through", "underline" | Line drawn on the text (underline, line-through, or none). |
| `case` | enum: "none", "sentence", "title", "upper", "lower", "slug", "camel" | Letter-case transform applied at render time. 'title' uses Chicago/Gruber rules and preserves tokens with internal capitals (ARR, iPhone). 'sentence' uppercases only the first character. 'none' (default) emits the string without any letter-case change. |

<a id="kpisupportglyphstyle"></a>
## KpiSupportGlyphStyle
Authored overlay for KpiSupportGlyphStyle. KPI support-row glyph slot.

| Field | Type | Description |
|-------|------|-------------|
| `font` | [KpiSupportFontStyle](#kpisupportfontstyle) | Glyph font. Unset fields fall back to [`style.charts.kpi.support.font`](#kpisupportstyle). |

<a id="tabledividerstyle"></a>
## TableDividerStyle
Authored overlay for TableDividerStyle. A table divider that also chooses how far the line runs.

| Field | Type | Description |
|-------|------|-------------|
| `visible` | bool | Draw the divider. |
| `color` | str | Divider color. |
| `width` | float | Divider line width in pixels. |
| `dasharray` | str | Dash pattern in pixels, such as "6 3" (6 drawn, 3 gap); unset draws a solid line. |
| `continuous` | bool | Draw one unbroken line across the full table width (true) or only under each column (false). |

<a id="tablerowstripestyle"></a>
## TableRowStripeStyle
Authored overlay for TableRowStripeStyle. Alternating row stripe style.

| Field | Type | Description |
|-------|------|-------------|
| `color` | str | Alternating stripe background color; None means no alternating row fill. |

<a id="tablerowrolesstyle"></a>
## TableRowRolesStyle
Authored overlay for TableRowRolesStyle.

| Field | Type | Description |
|-------|------|-------------|
| `summary` | [TableRowRoleStyle](#tablerowrolestyle) | Style for summary role rows. |
| `total` | [TableRowRoleStyle](#tablerowrolestyle) | Style for total role rows. |

<a id="columnfontstyle"></a>
## ColumnFontStyle
A table column's font. ``color`` may name a query column, so it is not a color field.

| Field | Type | Description |
|-------|------|-------------|
| `extends` | str | Name of a ``style.fonts`` entry this slot starts from; the fields set beside it override that entry. |
| `family` | str | Font family name (e.g., 'sans-serif', 'Roboto'). |
| `color` | str | Text color (CSS color string), or a column ID: a value matching a query column name uses that row's value in the named column. |
| `size` | float | Font size in pixels. |
| `weight` | str \| float | How heavy the type is drawn (e.g., 'bold', 400, 700). |
| `style` | enum: "normal", "italic" | Upright or slanted type (normal or italic). |
| `decoration` | enum: "none", "line-through", "underline" | Line drawn on the text (underline, line-through, or none). |
| `case` | enum: "none", "sentence", "title", "upper", "lower", "slug", "camel" | Letter-case transform applied at render time. 'title' uses Chicago/Gruber rules and preserves tokens with internal capitals (ARR, iPhone). 'sentence' uppercases only the first character. 'none' (default) emits the string without any letter-case change. |
| `line_height` | float | Line height as a unitless multiple of font size. Cascades through Style.font to all text roles that carry a FontStyle slot. Body prose defaults to 1.25; titles override tighter via their font patch in theme YAML. |

<a id="sparkconfig"></a>
## SparkConfig
Configuration for spark charts (inline sparklines) in table columns.

| Field | Type | Description |
|-------|------|-------------|
| `type` | enum: "line", "area", "bar", "bar-normalize", "column", "columns" | Spark chart type (line, area, bar, bar-normalize, column, columns). |
| `color` | str | Color for the spark mark. |
| `height` | int | Spark chart height in pixels. |
| `width` | int | Spark chart width in pixels. |
| `last_visible` | bool | Highlight the last data point (line/area spark charts). |
| `min_max_visible` | bool | Annotate the min and max data points (line spark charts only). |
| `fill_opacity` | float | Fill opacity for area spark charts (0–1). |
| `max` | float | Scaling ceiling: bar-normalize and column clamp the value to it; bar uses it in place of the column's data max. |
| `thresholds` | dict[int \| float, str] | Color thresholds for bar / bar-normalize / column: {value: CSS color string}. |
| `background` | str | Background track color for bar-normalize chart. |
| `border_radius` | float | Corner radius in pixels for bar, bar-normalize, and column bars, and for the bar-normalize track. |
| `value_visible` | bool | Show numeric value label alongside the bar. |
| `value_suffix` | str | Text placed after the displayed value (e.g., '%'). |
| `negative_color` | bool | Paint negative values (bar / column / columns) with the theme's tones.negative color instead of the shared spark color. Has no effect on columns with no negative values. |

<a id="columnscaleconfig"></a>
## ColumnScaleConfig
Scale-based continuous color mapping for a table column.

| Field | Type | Description |
|-------|------|-------------|
| `background` | [ColumnScaleTargetConfig](#columnscaletargetconfig) | Continuous background color mapping for this column. |
| `color` | [ColumnScaleTargetConfig](#columnscaletargetconfig) | Continuous text color mapping for this column. |

<a id="sparkemptystyle"></a>
## SparkEmptyStyle
Authored overlay for SparkEmptyStyle.

| Field | Type | Description |
|-------|------|-------------|
| `inset_x` | float | Horizontal inset for the empty sparkline placeholder in pixels. |
| `stroke` | [StrokeStyle](#strokestyle) | Empty-state placeholder stroke style. |

<a id="sparksinglevaluestyle"></a>
## SparkSingleValueStyle
Authored overlay for SparkSingleValueStyle.

| Field | Type | Description |
|-------|------|-------------|
| `inset_x` | float | Horizontal inset for the single-value sparkline in pixels. |
| `marker_radius` | float | Radius of the single-value marker circle in pixels. |

<a id="sparkcolumnsstyle"></a>
## SparkColumnsStyle
Authored overlay for SparkColumnsStyle. Inline `spark.type: columns` (multi-value vertical bars) defaults.

| Field | Type | Description |
|-------|------|-------------|
| `gap` | float | Gap between column bars in pixels. |
| `padding` | float | Horizontal outer padding of the columns sparkline in pixels. |
| `min_bar_height` | float | Minimum rendered bar height in pixels. |
| `border` | [CornerStyle](#cornerstyle) | Column bar corner rounding. |

<a id="sparkcolumnstyle"></a>
## SparkColumnStyle
Authored overlay for SparkColumnStyle. Inline `spark.type: column` (single vertical bar) defaults.

| Field | Type | Description |
|-------|------|-------------|
| `width` | float | Spark column default width in pixels. |
| `height` | float | Spark column default height in pixels. |

<a id="sparkbarcellstyle"></a>
## SparkBarCellStyle
Authored overlay for SparkBarCellStyle. Inline `spark.type: bar` and `bar-normalize` (single horizontal bar) defaults.

| Field | Type | Description |
|-------|------|-------------|
| `background` | str | Track background color - fill-grade, pinned per theme. |
| `color` | str | Bar fill color; None seeds from style.charts.color.categorical.single_series_palette[0]. |
| `default_max` | float | Default maximum value for bar scale when no explicit max is authored. |
| `border` | [CornerStyle](#cornerstyle) | Corner rounding for spark bar cells. |
| `font` | [FontStyle](#fontstyle) | Spark bar cell font style overrides. Unset fields fall back to [`style.charts.font`](#chartsstyle). |
| `label` | [SparkBarLabelStyle](#sparkbarlabelstyle) | Spark bar inline label style. |

<a id="sparkareastyle"></a>
## SparkAreaStyle
Authored overlay for SparkAreaStyle.

| Field | Type | Description |
|-------|------|-------------|
| `fill_opacity` | float | Spark area fill opacity (0–1). |

<a id="geoshapemarkstyle"></a>
## GeoshapeMarkStyle
Authored overlay for GeoshapeMarkStyle. Geoshape (choropleth) mark fill and boundary stroke.

| Field | Type | Description |
|-------|------|-------------|
| `fill` | str | Neutral geoshape fill color. |
| `stroke` | [StrokeStyle](#strokestyle) | Geoshape boundary stroke style. |

<a id="tooltipslotstyle"></a>
## TooltipSlotStyle
Authored overlay for TooltipSlotStyle. Typography for a single tooltip slot (label or value).

| Field | Type | Description |
|-------|------|-------------|
| `font` | [FontStyle](#fontstyle) | Font overrides for this tooltip slot (color, weight). Unset fields fall back to [`style.charts.font`](#chartsstyle). |

<a id="tooltipborderstyle"></a>
## TooltipBorderStyle
Authored overlay for TooltipBorderStyle. Tooltip box border: all fields required; theme YAML supplies defaults.

| Field | Type | Description |
|-------|------|-------------|
| `color` | str | Border color as a CSS color string. |
| `width` | float | Border width in pixels. |
| `radius` | float | Border corner radius in pixels. |

<a id="tooltipshadowstyle"></a>
## TooltipShadowStyle
Authored overlay for TooltipShadowStyle. Tooltip drop-shadow toggle. JS applies the shadow expression when visible=true.

| Field | Type | Description |
|-------|------|-------------|
| `visible` | bool | Show a drop-shadow on the tooltip box; theme always provides this. |

<a id="tooltipswatchstyle"></a>
## TooltipSwatchStyle
Authored overlay for TooltipSwatchStyle. Series color swatch in the tooltip: the mark-colored chip next to each

| Field | Type | Description |
|-------|------|-------------|
| `size` | float | Swatch edge length in pixels (square). |
| `radius` | float | Swatch corner radius in pixels (0 = square, ~half of size = circle). |

<a id="circlemarkstyle"></a>
## CircleMarkStyle
Authored overlay for CircleMarkStyle. Circle mark opacity and stroke.

| Field | Type | Description |
|-------|------|-------------|
| `opacity` | float | Mark opacity (0–1); None means not overridden at this level. |
| `stroke` | [StrokeStyle](#strokestyle) | Unset emits no stroke; Vega-Lite's default applies. |

<a id="histogramchartmarksstyle"></a>
## HistogramChartMarksStyle
Authored overlay for HistogramChartMarksStyle. Histogram-family mark overrides.

| Field | Type | Description |
|-------|------|-------------|
| `bar` | [BarMarkStyle](#barmarkstyle) | Bar mark overrides; inherits from global. |
| `rule` | [RuleMarkStyle](#rulemarkstyle) | Rule mark overrides; None inherits global. |

<a id="serieslabelfontstyle"></a>
## SeriesLabelFontStyle
Authored overlay for SeriesLabelFontStyle. Series-label typography with a compact width-tier size.

| Field | Type | Description |
|-------|------|-------------|
| `extends` | str | Name of a ``style.fonts`` entry this slot starts from; the fields set beside it override that entry. |
| `family` | str | Font family name (e.g., 'sans-serif', 'Roboto'). |
| `color` | str | Text color as a CSS color string. |
| `size` | float | Font size in pixels. |
| `weight` | str \| float | How heavy the type is drawn (e.g., 'bold', 400, 700). |
| `style` | enum: "normal", "italic" | Upright or slanted type (normal or italic). |
| `decoration` | enum: "none", "line-through", "underline" | Line drawn on the text (underline, line-through, or none). |
| `case` | enum: "none", "sentence", "title", "upper", "lower", "slug", "camel" | Letter-case transform applied at render time. 'title' uses Chicago/Gruber rules and preserves tokens with internal capitals (ARR, iPhone). 'sentence' uppercases only the first character. 'none' (default) emits the string without any letter-case change. |
| `line_height` | float | Line height as a unitless multiple of font size. Cascades through Style.font to all text roles that carry a FontStyle slot. Body prose defaults to 1.25; titles override tighter via their font patch in theme YAML. |
| `compact_size` | float | Series-label font size in pixels on tiny and narrow cards. |
| `compact_weight` | str \| float | Series-label font weight on tiny and narrow cards. |

<a id="detailsarrowstyle"></a>
## DetailsArrowStyle
Authored overlay for DetailsArrowStyle. Layout and font style for the expand/collapse arrow chevron.

| Field | Type | Description |
|-------|------|-------------|
| `x` | float | X position of the arrow in pixels. |
| `font` | [DetailsArrowFontStyle](#detailsarrowfontstyle) | Arrow glyph font style. |

<a id="inputwidths"></a>
## InputWidths
Authored overlay for InputWidths.

| Field | Type | Description |
|-------|------|-------------|
| `text` | float | Default width for text inputs in pixels. |
| `number` | float | Default width for number inputs in pixels. |
| `range` | float | Default width for range inputs in pixels. |
| `slider_value_min` | float | Minimum width for slider value display in pixels. |
| `checkbox` | float | Default width for checkbox inputs in pixels. |
| `daterange` | float | Default width for daterange chip triggers in pixels. |

<a id="rangedefaults"></a>
## RangeDefaults
Authored overlay for RangeDefaults.

| Field | Type | Description |
|-------|------|-------------|
| `default_min` | float | Default minimum value for range inputs. |
| `default_max` | float | Default maximum value for range inputs. |
| `default_step` | float | Default step size for range inputs. |

<a id="axisgridthresholdstyle"></a>
## AxisGridThresholdStyle
Authored overlay for AxisGridThresholdStyle. Threshold-rule color, width, and visibility overrides.

| Field | Type | Description |
|-------|------|-------------|
| `visible` | bool | Show the threshold rule; None inherits from parent axis. |
| `color` | str | Color of the threshold rule; None inherits from parent axis. |
| `width` | float | Width of the threshold rule in pixels; None inherits from parent axis. |

<a id="axislabeloverlapconfig"></a>
## AxisLabelOverlapConfig
Authored overlay for AxisLabelOverlapConfig. Two-bool overlap strategy enablement for x-axis labels.

| Field | Type | Description |
|-------|------|-------------|
| `tilt` | bool | Enable label tilt strategy; None inherits from parent axis. |
| `skip` | bool | Enable temporal label thinning; ignored on categorical axes; None inherits from parent axis. |

<a id="scalecontinuousstyle"></a>
## ScaleContinuousStyle
Authored overlay for ScaleContinuousStyle. Continuous-scale-only config: type, domain, zero-baseline, log/pow/symlog params.

| Field | Type | Description |
|-------|------|-------------|
| `zero` | bool \| const: "auto" | Force scale zero-baseline: True/False pins it; "auto" runs the dbt charts smart-zero heuristic; None passes through to Vega-Lite. |
| `type` | enum: "linear", "log", "pow", "sqrt", "symlog", "temporal" | Scale type override. 'linear'/'log'/'pow'/'sqrt'/'symlog' pass straight through to Vega-Lite's quantitative scale.type. 'temporal' is a dbt charts escape hatch for a cartesian x-axis: it forces a continuous temporal scale instead of the auto-inferred ordinal/nominal bucketed type, which is required before an authored ``domain`` of ISO dates can extend the visible range past the data extent. None lets dbt charts/Vega-Lite infer from the field type. |
| `domain` | tuple[int \| float \| str, int \| float \| str] | Explicit [low, high] scale domain; None lets Vega-Lite auto-determine from data. Must have exactly 2 elements: dbt charts only wires a continuous range override through to Vega-Lite, not an explicit category enumeration. Neither element may be null; pin both bounds, or omit the key to fit the data. When ``type: temporal`` is set, both elements must be ISO-8601 date/datetime strings. |
| `log` | [ScaleLogStyle](#scalelogstyle) | Log-scale param (base); only meaningful with type: log. |
| `pow` | [ScalePowStyle](#scalepowstyle) | Power-scale param (exponent); only meaningful with type: pow. |
| `symlog` | [ScaleSymlogStyle](#scalesymlogstyle) | Symlog-scale param (constant); only meaningful with type: symlog. |

<a id="supporttablerowpaddingstyle"></a>
## SupportTableRowPaddingStyle
Authored overlay for SupportTableRowPaddingStyle.

| Field | Type | Description |
|-------|------|-------------|
| `vertical` | float | Vertical (top/bottom) padding inside support_table rows in pixels. |
| `horizontal` | float | Horizontal (left/right) padding inside support_table rows in pixels. |

<a id="barlabelsstyle"></a>
## BarLabelsStyle
Authored overlay for BarLabelsStyle. Bar mark value-label config. Extends MarkLabelsStyle with bar-specific positions.

| Field | Type | Description |
|-------|------|-------------|
| `visible` | bool | Show numeric value labels on each mark; False by default. |
| `field` | str | Column to source label text from; None uses the chart's y-field. |
| `format` | str \| [FormatConfig](#formatconfig) \| enum: "compact", "currency", "currency_compact", "currency_full", "currency_whole", "date_short", "delta", "email", "id", "integer", "latitude", "longitude", "number", "number_full", "percent", "percent_delta", "percent_whole", "rating", "time_short", "url", … (1 more; see the JSON Schema) | Number format string for value labels. |
| `dx` | int | Horizontal pixel offset for value labels; overrides the position default. |
| `dy` | int | Vertical pixel offset for value labels; overrides the position default. |
| `font` | [FontStyle](#fontstyle) | Value label font style (color, size, family, etc.). |
| `position` | enum: "above", "top", "middle", "middle_aligned", "bottom" | Label position relative to the bar. 'above' places labels above the bar top (outside). 'top' places labels just inside the top edge. 'middle' centers labels vertically in the bar. 'middle_aligned' centers all labels at a common height (mean of bar heights / 2). 'bottom' places labels just inside the bottom edge. |
| `stacked` | bool | Label each segment of a stacked bar. False leaves stacked segments unlabeled, so a stack shows a label only if total_label is visible; plain bars keep their labels either way. |

<a id="bartotallabelstyle"></a>
## BarTotalLabelStyle
Authored overlay for BarTotalLabelStyle. Stack total label style for bar marks.

| Field | Type | Description |
|-------|------|-------------|
| `visible` | bool | Show stack total labels above each bar stack. Only takes effect on stacked bar charts; ignored otherwise. |
| `format` | str \| [FormatConfig](#formatconfig) \| enum: "compact", "currency", "currency_compact", "currency_full", "currency_whole", "date_short", "delta", "email", "id", "integer", "latitude", "longitude", "number", "number_full", "percent", "percent_delta", "percent_whole", "rating", "time_short", "url", … (1 more; see the JSON Schema) | Number format string for stack total labels. |
| `dx` | int | Horizontal pixel offset for stack total labels. |
| `dy` | int | Vertical pixel offset for stack total labels. |
| `font` | [FontStyle](#fontstyle) | Stack total label font style overrides; cascade fills missing fields from charts.font. Unset fields fall back to [`style.charts.font`](#chartsstyle). |

<a id="strokestyle"></a>
## StrokeStyle
Authored overlay for StrokeStyle. Stroke appearance sub-block shared across mark families.

| Field | Type | Description |
|-------|------|-------------|
| `color` | str | Stroke color as a CSS color string. |
| `width` | float | Stroke width in pixels. |
| `cap` | enum: "butt", "round", "square" | How the stroke's ends are finished (butt, round, or square). |
| `join` | enum: "miter", "round", "bevel" | How two stroke segments are joined (miter, round, or bevel). |
| `dasharray` | str | Lengths of the dashes and the blanks between them (e.g. '4 2'). |

<a id="pointlabelsstyle"></a>
## PointLabelsStyle
Authored overlay for PointLabelsStyle. Point/line mark value-label config. Used by both LineMarkStyle and PointMarkStyle.

| Field | Type | Description |
|-------|------|-------------|
| `visible` | bool | Show numeric value labels on each mark; False by default. |
| `field` | str | Column to source label text from; None uses the chart's y-field. |
| `format` | str \| [FormatConfig](#formatconfig) \| enum: "compact", "currency", "currency_compact", "currency_full", "currency_whole", "date_short", "delta", "email", "id", "integer", "latitude", "longitude", "number", "number_full", "percent", "percent_delta", "percent_whole", "rating", "time_short", "url", … (1 more; see the JSON Schema) | Number format string for value labels. |
| `dx` | int | Horizontal pixel offset for value labels; overrides the position default. |
| `dy` | int | Vertical pixel offset for value labels; overrides the position default. |
| `font` | [FontStyle](#fontstyle) | Value label font style (color, size, family, etc.). |
| `position` | enum: "top", "bottom", "left", "right", "middle" | Label position relative to the point. 'top' places labels above the point. 'bottom' places labels below. 'left' to the left. 'right' to the right. 'middle' centers on the point. |

<a id="fontcolorstrokestyle"></a>
## FontColorStrokeStyle
Authored overlay for FontColorStrokeStyle. Stroke for rule marks whose color defaults to the root font color.

| Field | Type | Description |
|-------|------|-------------|
| `color` | str | Stroke color for rule marks. Falls back to [`style.font.color`](#rootfontstyle). |
| `width` | float | Stroke width in pixels. |
| `cap` | enum: "butt", "round", "square" | How the stroke's ends are finished (butt, round, or square). |
| `join` | enum: "miter", "round", "bevel" | How two stroke segments are joined (miter, round, or bevel). |
| `dasharray` | str | Lengths of the dashes and the blanks between them (e.g. '4 2'). |

<a id="areastackedmarkstyle"></a>
## AreaStackedMarkStyle
Authored overlay for AreaStackedMarkStyle. Stacked / streamgraph area recipe override: solid fill + perimeter stroke.

| Field | Type | Description |
|-------|------|-------------|
| `opacity` | float | Area fill opacity (0–1) for the stacked recipe. |
| `stroke` | [StrokeStyle](#strokestyle) | Perimeter stroke style for the stacked recipe. |
| `halo_multiplier` | float | Halo stroke width multiplier for the stacked recipe; 0 disables the halo. |

<a id="slicelabelsstyle"></a>
## SliceLabelsStyle
Authored overlay for SliceLabelsStyle. Pie labels: typography + positioning offsets for per-slice text.

| Field | Type | Description |
|-------|------|-------------|
| `offset` | float | Radial offset of slice labels from the arc in pixels. |
| `line_height` | float | Line height for slice labels in pixels. Reserved vertical space above the disk is ``line_height × &lt;rendered lines&gt;`` per row, so the same value handles 1-line, 2-line, and multi-line templates. |
| `font` | [SliceLabelFontStyle](#slicelabelfontstyle) | Slice label font style overrides. ``color`` only takes effect on single-series pies (no ``color:`` channel authored); multi-series pies always paint each label with ink derived from its own wedge color against the chart's canvas, and ignore an authored ``color`` here. Unset fields fall back to [`style.charts.font`](#chartsstyle). |
| `default_template` | [LabelsDefaultTemplate](#labelsdefaulttemplate) | Default Jinja templates for per-slice labels when template is not authored. |
| `template` | str | Jinja2 label template. Overrides default_template when authored. |
| `where` | str | Jinja2 boolean filter; labels only render on rows where this is truthy. |

<a id="tablerowrolestyle"></a>
## TableRowRoleStyle
Authored overlay for TableRowRoleStyle.

| Field | Type | Description |
|-------|------|-------------|
| `divider` | [DividerStyle](#dividerstyle) | Line above rows with this role. |
| `font` | [FontStyle](#fontstyle) | Per-role font style override; None uses the default row font. |
| `background` | str | Per-role row background color; None means no override. |

<a id="columnscaletargetconfig"></a>
## ColumnScaleTargetConfig
A table column's scale target: CSS color strings only.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `palette` | str \| list[str] \| enum: "accent", "bluegreen", "blueorange", "bluepurple", "blues", "brownbluegreen", "browns", "category-6-tonal-blue", "category-6-tonal-blue.dark", "category-6-tonal-blue.deep", "category-6-tonal-blue.light", "category-6-tonal-blue.pale", "category-6-tonal-brown", "category-6-tonal-brown.dark", "category-6-tonal-brown.deep", "category-6-tonal-brown.light", "category-6-tonal-brown.pale", "category-6-tonal-green", "category-6-tonal-green.dark", "category-6-tonal-green.deep", … (120 more; see the JSON Schema) | Which colors the scale draws from: a built-in palette name or Vega scheme, or a CSS color list. |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `domain` | const: "data" | Scale domain source ('data' uses the data extent, widened to nice round bounds when nice is true; None uses explicit min/max). |
| `min` | float \| int | Minimum scale domain value (overrides data minimum). |
| `max` | float \| int | Maximum scale domain value (overrides data maximum). |
| `nice` | bool | Widen a data-derived domain to round ('nice') bounds and label every nice tick on the legend, mirroring Vega-Lite's own scale.nice. Applies to the color scale a gradient legend labels, not the x/y position scale. Ignored once min or max is set; a single-sided bound already fixes that edge exactly. Widening is currently honored on heatmap's themed color gradient only; geoshape's choropleth honors `nice: false` (exact endpoint labels) but not `nice: true`'s widening. |
| `null_color` | str | Color assigned to null values. |
| `hinge` | float \| const: "auto" | Diverging scale midpoint value, or 'auto' to use the data midpoint. |
| `arm_mode` | enum: "asymmetric", "symmetric" | How diverging scale arms are stretched: 'asymmetric' (proportional) or 'symmetric' (equal arms). |

<a id="sparkbarlabelstyle"></a>
## SparkBarLabelStyle
Authored overlay for SparkBarLabelStyle.

| Field | Type | Description |
|-------|------|-------------|
| `inset_x` | float | Horizontal inset for the spark bar label in pixels. |
| `fill` | str | Label text fill color. |
| `fill_opacity` | float | Label text fill opacity (0–1). |
| `min_size` | float | Minimum bar fill width required to show the label in pixels. |
| `height_offset` | float | Vertical offset of the label from its bar top in pixels. |

<a id="detailsarrowfontstyle"></a>
## DetailsArrowFontStyle
Authored overlay for DetailsArrowFontStyle. Font style for the expand/collapse arrow glyph.

| Field | Type | Description |
|-------|------|-------------|
| `size` | float | Font size of the arrow glyph in pixels. |

<a id="scalelogstyle"></a>
## ScaleLogStyle
Authored overlay for ScaleLogStyle. Log-scale-only param.

| Field | Type | Description |
|-------|------|-------------|
| `base` | float | Log base; only meaningful with type: log. None lets Vega-Lite apply its own default (10). |

<a id="scalepowstyle"></a>
## ScalePowStyle
Authored overlay for ScalePowStyle. Power-scale-only param.

| Field | Type | Description |
|-------|------|-------------|
| `exponent` | float | Power exponent; only meaningful with type: pow. None uses Vega-Lite's default. |

<a id="scalesymlogstyle"></a>
## ScaleSymlogStyle
Authored overlay for ScaleSymlogStyle. Symlog-scale-only param.

| Field | Type | Description |
|-------|------|-------------|
| `constant` | float | Symlog constant; only meaningful with type: symlog. None uses Vega-Lite's default. |

<a id="slicelabelfontstyle"></a>
## SliceLabelFontStyle
The pie slice label font. ``color`` also takes ``auto``.

| Field | Type | Description |
|-------|------|-------------|
| `extends` | str | Name of a ``style.fonts`` entry this slot starts from; the fields set beside it override that entry. |
| `family` | str | Font family name (e.g., 'sans-serif', 'Roboto'). |
| `color` | str | Text color. 'auto' paints each label in the dark ink of its wedge's color. |
| `size` | float | Font size in pixels. |
| `weight` | str \| float | How heavy the type is drawn (e.g., 'bold', 400, 700). |
| `style` | enum: "normal", "italic" | Upright or slanted type (normal or italic). |
| `decoration` | enum: "none", "line-through", "underline" | Line drawn on the text (underline, line-through, or none). |
| `case` | enum: "none", "sentence", "title", "upper", "lower", "slug", "camel" | Letter-case transform applied at render time. 'title' uses Chicago/Gruber rules and preserves tokens with internal capitals (ARR, iPhone). 'sentence' uppercases only the first character. 'none' (default) emits the string without any letter-case change. |
| `line_height` | float | Line height as a unitless multiple of font size. Cascades through Style.font to all text roles that carry a FontStyle slot. Body prose defaults to 1.25; titles override tighter via their font patch in theme YAML. |

<a id="labelsdefaulttemplate"></a>
## LabelsDefaultTemplate
Authored overlay for LabelsDefaultTemplate. Default Jinja templates for per-slice pie/donut labels.

| Field | Type | Description |
|-------|------|-------------|
| `with_color` | str | Default per-slice label template when the chart has a color binding. `{value_line}` stands for the slice value in the slice tooltip's format. |
| `no_color` | str | Default per-slice label template when the chart has no color binding. `{value_line}` stands for the slice value in the slice tooltip's format. |

<a id="postgressourceconfig"></a>
## PostgresSourceConfig
Postgres source configuration.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `type` | const: "postgres" |  |
| `host` | str | Database host name or IP address. |
| `dbname` | str | Database name (dbt accepts database as an input alias). |
| `user` | str | Database user name. |
| `password` | str | Database password (dbt accepts pass as an input alias). |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `cache` | bool \| str \| [Cache](#cache) \| const: "forever" | Cache policy default for every query against this source, e.g. cache: 1h: queries inherit it and may refine it; cache: false opts them out. |
| `max_query_duration_seconds` | int | Maximum execution time for one query in seconds. Overrides execution.max_query_duration_seconds for this source. |
| `attribution` | dict[str, str] | Cost-attribution pairs sent with every query against this source, e.g. attribution: {team: analytics}. Emitted as BigQuery job labels and as a query comment elsewhere. Keys and values must match BigQuery's label rules ([a-z][a-z0-9_-]{0,62} / [a-z0-9_-]{0,63}). The dbt_charts_ prefix and the app key are reserved for the engine's own identity. |
| `port` | int | Database port number. |
| `schema` | str | Default schema for queries. |
| `connect_timeout` | int | Connection timeout in seconds. |
| `role` | str | PostgreSQL role to assume after connecting. |
| `search_path` | str | PostgreSQL search_path for the connection. |
| `keepalives_idle` | int | Idle seconds before TCP keepalives begin. |
| `sslmode` | enum: "disable", "allow", "prefer", "require", "verify-ca", "verify-full" | libpq SSL mode forwarded to psycopg2. None lets libpq decide its default. |
| `sslcert` | str | Path to the client SSL certificate. |
| `sslkey` | str | Path to the client SSL private key. |
| `sslrootcert` | str | Path to the trusted SSL certificate authority file. |
| `application_name` | str | Application name reported to PostgreSQL. |
| `retries` | int | Number of connection retry attempts. |

<a id="snowflakesourceconfig"></a>
## SnowflakeSourceConfig
Snowflake source configuration.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `type` | const: "snowflake" |  |
| `account` | str | Snowflake account identifier (e.g. xy12345.us-east-1). |
| `database` | str | Snowflake database name. |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `cache` | bool \| str \| [Cache](#cache) \| const: "forever" | Cache policy default for every query against this source, e.g. cache: 1h: queries inherit it and may refine it; cache: false opts them out. |
| `max_query_duration_seconds` | int | Maximum execution time for one query in seconds. Overrides execution.max_query_duration_seconds for this source. |
| `attribution` | dict[str, str] | Cost-attribution pairs sent with every query against this source, e.g. attribution: {team: analytics}. Emitted as BigQuery job labels and as a query comment elsewhere. Keys and values must match BigQuery's label rules ([a-z][a-z0-9_-]{0,62} / [a-z0-9_-]{0,63}). The dbt_charts_ prefix and the app key are reserved for the engine's own identity. |
| `user` | str | Snowflake user name. Omit for token-based authentication when supported. |
| `password` | str | Snowflake password. Omit when using OAuth or key-pair auth. |
| `warehouse` | str | Snowflake virtual warehouse name. |
| `schema` | str | Default schema for queries. |
| `role` | str | Snowflake role to assume for the session. |
| `authenticator` | str | Snowflake authenticator name or external-browser mode. |
| `private_key` | str | PEM private key used for key-pair authentication. |
| `private_key_path` | str | Path to a PEM private key for key-pair authentication. |
| `private_key_passphrase` | str | Passphrase for the configured private key. |
| `token` | str | OAuth access token for token authentication. |
| `oauth_client_id` | str | OAuth client identifier. |
| `oauth_client_secret` | str | OAuth client secret. |
| `query_tag` | str | Snowflake query tag applied to statements. |
| `client_session_keep_alive` | bool | Whether Snowflake keeps the client session alive. |
| `host` | str | Snowflake host override. |
| `port` | int | Snowflake port override. |
| `proxy_host` | str | HTTP proxy host for Snowflake connections. |
| `proxy_port` | int | HTTP proxy port for Snowflake connections. |
| `protocol` | str | Network protocol for the Snowflake connection. |
| `connect_retries` | int | Number of retries while opening a connection. |
| `connect_timeout` | int | Connection timeout in seconds. |
| `retry_on_database_errors` | bool | Whether database errors are retried. |
| `retry_all` | bool | Whether all connection errors are retried. |
| `insecure_mode` | bool | Whether TLS certificate verification is disabled. |
| `reuse_connections` | bool | Whether dbt reuses Snowflake connections. |
| `s3_stage_vpce_dns_name` | str | Private VPC endpoint DNS name for S3 staging. |
| `platform_detection_timeout_seconds` | float | Timeout for Snowflake platform detection. |

<a id="bigquerysourceconfig"></a>
## BigQuerySourceConfig
BigQuery source configuration.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `type` | const: "bigquery" |  |
| `project` | str | GCP project ID. |
| `dataset` | str | BigQuery dataset name (equivalent to schema). |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `cache` | bool \| str \| [Cache](#cache) \| const: "forever" | Cache policy default for every query against this source, e.g. cache: 1h: queries inherit it and may refine it; cache: false opts them out. |
| `max_query_duration_seconds` | int | Maximum execution time for one query in seconds. Overrides execution.max_query_duration_seconds for this source. |
| `attribution` | dict[str, str] | Cost-attribution pairs sent with every query against this source, e.g. attribution: {team: analytics}. Emitted as BigQuery job labels and as a query comment elsewhere. Keys and values must match BigQuery's label rules ([a-z][a-z0-9_-]{0,62} / [a-z0-9_-]{0,63}). The dbt_charts_ prefix and the app key are reserved for the engine's own identity. |
| `keyfile` | str | Path to service account JSON key file. |
| `keyfile_json` | dict[str, str \| int \| float \| bool] | Inline service account JSON dict. |
| `location` | str | Dataset location (e.g. US, EU). |
| `method` | enum: "oauth", "oauth-secrets", "service-account", "service-account-json", "external-oauth-wif" | dbt-bigquery authentication method. Inferred from keyfile/keyfile_json when omitted: 'service-account-json' if keyfile_json set, 'service-account' if keyfile set, 'oauth' (Application Default Credentials) otherwise. |
| `execution_project` | str | GCP project billed for BigQuery execution. |
| `quota_project` | str | GCP project used for quota attribution. |
| `api_endpoint` | str | BigQuery API endpoint override. |
| `priority` | enum: "interactive", "batch" | BigQuery job priority. |
| `maximum_bytes_billed` | int | Maximum bytes a BigQuery job may bill. |
| `impersonate_service_account` | str | Service account to impersonate for BigQuery jobs. |
| `job_retry_deadline_seconds` | int | Deadline in seconds for retrying a BigQuery job. |
| `job_retries` | int | Number of BigQuery job retry attempts (dbt accepts retries as an input alias). |
| `job_creation_timeout_seconds` | int | Timeout in seconds while creating a BigQuery job. |
| `job_execution_timeout_seconds` | int | Timeout in seconds while executing a BigQuery job. |
| `token` | str | OAuth access token. |
| `refresh_token` | str | OAuth refresh token. |
| `client_id` | str | OAuth client identifier. |
| `client_secret` | str | OAuth client secret. |
| `token_uri` | str | OAuth token endpoint URI. |
| `workload_pool_provider_path` | str | Workload identity pool provider resource path. |
| `service_account_impersonation_url` | str | Service-account impersonation endpoint URL. |
| `token_endpoint` | dict[str, str] | OAuth token endpoint configuration. |
| `compute_region` | str | Dataproc compute region. |
| `dataproc_cluster_name` | str | Dataproc cluster name. |
| `gcs_bucket` | str | Cloud Storage bucket for Dataproc submission. |
| `submission_method` | str | dbt-bigquery Dataproc submission method. |
| `dataproc_batch` | dict[str, str \| int \| float \| bool] | Dataproc batch configuration. |
| `scopes` | list[str] | OAuth scopes requested for BigQuery credentials. |

<a id="redshiftsourceconfig"></a>
## RedshiftSourceConfig
Redshift source configuration.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `type` | const: "redshift" |  |
| `host` | str | Redshift cluster host name. |
| `dbname` | str | Redshift database name (dbt accepts database as an input alias). |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `cache` | bool \| str \| [Cache](#cache) \| const: "forever" | Cache policy default for every query against this source, e.g. cache: 1h: queries inherit it and may refine it; cache: false opts them out. |
| `max_query_duration_seconds` | int | Maximum execution time for one query in seconds. Overrides execution.max_query_duration_seconds for this source. |
| `attribution` | dict[str, str] | Cost-attribution pairs sent with every query against this source, e.g. attribution: {team: analytics}. Emitted as BigQuery job labels and as a query comment elsewhere. Keys and values must match BigQuery's label rules ([a-z][a-z0-9_-]{0,62} / [a-z0-9_-]{0,63}). The dbt_charts_ prefix and the app key are reserved for the engine's own identity. |
| `port` | int | Redshift port number. |
| `schema` | str | Default schema for queries. |
| `user` | str | Redshift user name. Omit for IAM-based authentication when supported. |
| `password` | str | Redshift password. Omit for IAM-based authentication when supported. |
| `method` | str | Redshift authentication method. |
| `cluster_id` | str | Redshift cluster identifier for IAM authentication. |
| `iam_profile` | str | IAM profile ARN used for Redshift authentication. |
| `autocreate` | bool | Whether dbt may create the database user. |
| `db_groups` | list[str] | Redshift database groups assigned to the user. |
| `ra3_node` | bool | Whether the target uses Redshift RA3 nodes. |
| `connect_timeout` | int | Socket timeout in seconds for the whole connection, including every read. Unset: dbt Charts uses max_query_duration_seconds plus headroom so the server's statement timeout fires first. A larger authored value wins. |
| `role` | str | IAM role ARN used for Redshift operations. |
| `sslmode` | str | SSL verification mode for the Redshift connection. |
| `retries` | int | Number of Redshift connection retry attempts. |
| `retry_all` | bool | Whether all connection errors are retried. |
| `region` | str | AWS region containing the Redshift target. |
| `access_key_id` | str | AWS access key identifier. |
| `secret_access_key` | str | AWS secret access key. |
| `idc_region` | str | AWS IAM Identity Center region. |
| `issuer_url` | str | Identity-provider issuer URL. |
| `idp_listen_port` | int | Local port used for identity-provider callbacks. |
| `idc_client_display_name` | str | IAM Identity Center client display name. |
| `idp_response_timeout` | int | Identity-provider response timeout in seconds. |
| `token_endpoint` | dict[str, str] | Identity-provider token endpoint configuration. |
| `is_serverless` | bool | Whether the target is Redshift Serverless. |
| `serverless_work_group` | str | Redshift Serverless workgroup name. |
| `serverless_acct_id` | str | AWS account identifier for Redshift Serverless. |
| `tcp_keepalive` | bool | Whether TCP keepalives are enabled. |
| `tcp_keepalive_idle` | int | Idle seconds before TCP keepalives begin. |
| `tcp_keepalive_interval` | int | Seconds between TCP keepalive probes. |
| `tcp_keepalive_count` | int | Number of TCP keepalive probes before failure. |
| `datasharing` | bool | Whether Redshift datashare metadata is queried. |
| `query_group` | str | Redshift query group applied to each session. |
| `allow_concurrent_drops` | bool | Whether dbt may run drops concurrently. |
| `drop_without_cascade` | bool | Whether dbt drops relations without CASCADE. |

<a id="databrickssourceconfig"></a>
## DatabricksSourceConfig
Databricks source configuration.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `type` | const: "databricks" |  |
| `host` | str | Databricks workspace host name. |
| `http_path` | str | HTTP path of the SQL warehouse. |
| `catalog` | str | Unity Catalog catalog name. |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `cache` | bool \| str \| [Cache](#cache) \| const: "forever" | Cache policy default for every query against this source, e.g. cache: 1h: queries inherit it and may refine it; cache: false opts them out. |
| `max_query_duration_seconds` | int | Maximum execution time for one query in seconds. Overrides execution.max_query_duration_seconds for this source. |
| `attribution` | dict[str, str] | Cost-attribution pairs sent with every query against this source, e.g. attribution: {team: analytics}. Emitted as BigQuery job labels and as a query comment elsewhere. Keys and values must match BigQuery's label rules ([a-z][a-z0-9_-]{0,62} / [a-z0-9_-]{0,63}). The dbt_charts_ prefix and the app key are reserved for the engine's own identity. |
| `token` | str | Personal access token. Use this or client_id with client_secret. |
| `client_id` | str | Application ID of an OAuth service principal. Set with client_secret. |
| `client_secret` | str | OAuth secret of the service principal. Set with client_id. |
| `schema` | str | Default schema for queries. |
| `connect_retries` | int | Number of times to retry a failed connection. Has no effect unless retry_all is also set to true. |
| `connect_timeout` | int | Seconds a connection attempt may keep retrying while the SQL warehouse starts. Replaces the driver's own retry budget, which defaults to about 15 minutes. |
| `socket_timeout` | int | Socket read timeout in seconds for the SQL warehouse connection. |
| `retry_all` | bool | Whether dbt Charts itself retries a failed connection attempt, with connect_retries setting how many attempts. False (the default) means dbt Charts does not retry; the Databricks driver still retries certain connection failures on its own regardless of this setting. |

<a id="trinosourceconfig"></a>
## TrinoSourceConfig
Trino / Presto source configuration.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `type` | const: "trino" |  |
| `host` | str | Trino coordinator host name. |
| `database` | str | Trino catalog name (`catalog` is accepted too). |
| `schema` | str | Default schema for queries. |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `cache` | bool \| str \| [Cache](#cache) \| const: "forever" | Cache policy default for every query against this source, e.g. cache: 1h: queries inherit it and may refine it; cache: false opts them out. |
| `max_query_duration_seconds` | int | Maximum execution time for one query in seconds. Overrides execution.max_query_duration_seconds for this source. |
| `attribution` | dict[str, str] | Cost-attribution pairs sent with every query against this source, e.g. attribution: {team: analytics}. Emitted as BigQuery job labels and as a query comment elsewhere. Keys and values must match BigQuery's label rules ([a-z][a-z0-9_-]{0,62} / [a-z0-9_-]{0,63}). The dbt_charts_ prefix and the app key are reserved for the engine's own identity. |
| `port` | int | Trino coordinator port number. |
| `user` | str | Trino user name. Required by the none, LDAP, Kerberos, and GSSAPI methods. |
| `method` | enum: "ldap", "certificate", "kerberos", "gssapi", "jwt", "oauth", "oauth_console" | Trino authentication method. Omit for unauthenticated mode. |
| `password` | str | LDAP password. Required when method is ldap. |
| `impersonation_user` | str | User to impersonate with LDAP authentication. |
| `client_tags` | list[str] | Client tags sent with Trino queries. |
| `roles` | dict[str, str] | Catalog-to-role mapping for the Trino session. |
| `cert` | str \| bool | CA certificate path or TLS verification flag. |
| `http_scheme` | enum: "http", "https" | HTTP scheme used to connect to Trino. |
| `http_headers` | dict[str, str] | Additional HTTP headers sent to Trino. |
| `session_properties` | dict[str, str \| int \| float \| bool] | Trino session properties. |
| `prepared_statements_enabled` | bool | Accepted so a dbt profile target maps over; has no effect. |
| `retries` | int | Maximum request retry attempts. |
| `timezone` | str | Session time zone. |
| `suppress_cert_warning` | bool | Whether TLS certificate warnings are suppressed. |
| `client_certificate` | str | Client certificate path for certificate authentication. |
| `client_private_key` | str | Client private-key path for certificate authentication. |
| `keytab` | str | Unsupported; set KRB5_CLIENT_KTNAME in the environment instead. |
| `principal` | str | Kerberos or GSSAPI principal. |
| `krb5_config` | str | Kerberos configuration file path. |
| `service_name` | str | Kerberos or GSSAPI service name. |
| `mutual_authentication` | bool \| enum: "REQUIRED", "OPTIONAL", "DISABLED" | Kerberos or GSSAPI mutual-authentication setting. |
| `force_preemptive` | bool | Whether Kerberos or GSSAPI auth is sent preemptively. |
| `hostname_override` | str | Kerberos or GSSAPI host name override. |
| `sanitize_mutual_error_response` | bool | Whether mutual-authentication errors are sanitized. |
| `delegate` | bool | Whether Kerberos or GSSAPI credentials are delegated. |
| `jwt_token` | str | JWT token. Required when method is jwt. |

<a id="duckdbsourceconfig"></a>
## DuckDBSourceConfig
DuckDB source configuration.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `type` | const: "duckdb" |  |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `cache` | bool \| str \| [Cache](#cache) \| const: "forever" | Cache policy default for every query against this source, e.g. cache: 1h: queries inherit it and may refine it; cache: false opts them out. |
| `max_query_duration_seconds` | int | Maximum execution time for one query in seconds. Overrides execution.max_query_duration_seconds for this source. |
| `path` | str | DuckDB file path or ':memory:' for an in-memory database. |
| `schema` | str | Default schema for unqualified table names (sets search_path). |
| `duckdb_config` | dict[str, str \| int \| float \| bool] | DuckDB connection configuration values, such as enable_external_access. |
| `extensions` | list[str \| [DuckDBExtensionConfig](#duckdbextensionconfig)] | DuckDB extensions to install and load. |
| `settings` | dict[str, str \| int \| float \| bool] | DuckDB settings and pragma values. |
| `secrets` | list[[DuckDBSecretConfig](#duckdbsecretconfig)] | DuckDB secret definitions for external services. |
| `external_root` | str | Root path for dbt-duckdb external materializations. |
| `attach` | list[[DuckDBAttachmentConfig](#duckdbattachmentconfig)] | Databases to attach to the DuckDB connection. |
| `disable_transactions` | bool | Whether dbt-duckdb disables statement transactions. |
| `keep_open` | bool | Whether dbt-duckdb holds its connection open between queries. Off by default: a held handle pins the database file at one DuckDB config, and DuckDB refuses any other connection to a pinned file whose config differs. Ignored for ':memory:' and MotherDuck, which dbt-duckdb holds open either way; closing an in-memory database would destroy it. |
| `module_paths` | list[str] | Python module paths dbt-duckdb loads. |
| `retries` | [DuckDBRetriesConfig](#duckdbretriesconfig) | dbt-duckdb connection and query retry configuration. |
| `is_ducklake` | bool | Whether this source uses DuckLake. |

<a id="sqlitesourceconfig"></a>
## SQLiteSourceConfig
SQLite source configuration.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `type` | const: "sqlite" |  |
| `path` | str | Path to the SQLite database file. |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `cache` | bool \| str \| [Cache](#cache) \| const: "forever" | Cache policy default for every query against this source, e.g. cache: 1h: queries inherit it and may refine it; cache: false opts them out. |

<a id="csvsourceconfig"></a>
## CsvSourceConfig
CSV file source configuration.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `type` | const: "csv" |  |
| `files` | dict[str, str] | Mapping of table_name → file path or glob (``*``/``?``), relative to the project root. A glob must match at least one file; matched files must share one column schema and concatenate into one table. Limits: max 1000 files per glob, max 500 tables, max 5 GB per table (``execution.max_glob_file_count`` / ``file_source_max_tables`` / ``file_source_max_bytes``). Required, non-empty. |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `cache` | bool \| str \| [Cache](#cache) \| const: "forever" | Cache policy default for every query against this source, e.g. cache: 1h: queries inherit it and may refine it; cache: false opts them out. |
| `delimiter` | str | Field delimiter character. |
| `encoding` | str | File encoding. |

<a id="parquetsourceconfig"></a>
## ParquetSourceConfig
Parquet file source configuration.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `type` | const: "parquet" |  |
| `files` | dict[str, str] | Mapping of table_name → file path or glob (``*``/``?``), relative to the project root. A glob must match at least one file; matched files must share one column schema and concatenate into one table. Limits: max 1000 files per glob, max 500 tables, max 5 GB per table (``execution.max_glob_file_count`` / ``file_source_max_tables`` / ``file_source_max_bytes``). Required, non-empty. |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `cache` | bool \| str \| [Cache](#cache) \| const: "forever" | Cache policy default for every query against this source, e.g. cache: 1h: queries inherit it and may refine it; cache: false opts them out. |

<a id="jsonsourceconfig"></a>
## JsonSourceConfig
JSON file source configuration.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `type` | const: "json" |  |
| `files` | dict[str, str] | Mapping of table_name → file path or glob (``*``/``?``), relative to the project root. A glob must match at least one file; matched files concatenate into one table. Limits: max 1000 files per glob, max 500 tables, max 5 GB per table (``execution.max_glob_file_count`` / ``file_source_max_tables`` / ``file_source_max_bytes``). Required, non-empty. |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `cache` | bool \| str \| [Cache](#cache) \| const: "forever" | Cache policy default for every query against this source, e.g. cache: 1h: queries inherit it and may refine it; cache: false opts them out. |
| `union_by_name` | bool | When True, rows from different files in a glob set are unified by column name: columns absent in a particular file are filled with NULL.  When False (default), all files in a glob set must share the same column schema; a mismatch raises an error. |

<a id="httpsourceconfig"></a>
## HttpSourceConfig
HTTP/REST API source configuration.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `type` | const: "http" |  |
| `url` | str | Base URL for HTTP requests. |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `cache` | bool \| str \| [Cache](#cache) \| const: "forever" | Cache policy default for every query against this source, e.g. cache: 1h: queries inherit it and may refine it; cache: false opts them out. |
| `headers` | dict[str, str] | Default HTTP headers (e.g. Authorization). |

<a id="dbtprofilesourceconfig"></a>
## DbtProfileSourceConfig
Reference to a dbt profile.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `type` | const: "dbt_profile" |  |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `cache` | bool \| str \| [Cache](#cache) \| const: "forever" | Cache policy default for every query against this source, e.g. cache: 1h: queries inherit it and may refine it; cache: false opts them out. |
| `attribution` | dict[str, str] | Cost-attribution pairs sent with every query against this source, e.g. attribution: {team: analytics}. Emitted as BigQuery job labels and as a query comment elsewhere. Keys and values must match BigQuery's label rules ([a-z][a-z0-9_-]{0,62} / [a-z0-9_-]{0,63}). The dbt_charts_ prefix and the app key are reserved for the engine's own identity. |
| `profile` | str | dbt profile name from profiles.yml. Defaults to $DBT_PROFILE, then the `profile:` of the linked dbt project's dbt_project.yml. |
| `target` | str | dbt target to use; defaults to the profile's default target. |
| `profiles_dir` | str | Directory containing profiles.yml, relative to the linked dbt project directory (see --dbt-project-dir). Use when profiles.yml is in a subdirectory (e.g. services/dbt). Resolution order: profiles_dir → $DBT_PROFILES_DIR → linked dbt project → ~/.dbt. |
| `target_path` | str | Directory holding the manifest.json built for this target, relative to the linked dbt project directory; same meaning as dbt's --target-path. ref() and source() resolve against &lt;target_path&gt;/manifest.json. Build it with `dbt parse --target &lt;target&gt; --target-path &lt;target_path&gt;`. Defaults to dbt's own resolution: $DBT_TARGET_PATH → dbt_project.yml target-path → target. |

<a id="lakecomputetokensource"></a>
## LakeComputeTokenSource
Lake compute authenticated with an access token (the default method).

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `type` | const: "lakecompute" |  |
| `token` | str | Lake compute access token. |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `cache` | bool \| str \| [Cache](#cache) \| const: "forever" | Cache policy default for every query against this source, e.g. cache: 1h: queries inherit it and may refine it; cache: false opts them out. |
| `max_query_duration_seconds` | int | Maximum execution time for one query in seconds. Overrides execution.max_query_duration_seconds for this source. |
| `base_url` | str | Lake compute API endpoint. |
| `catalog_bundle` | str | Catalog bundle the lake compute session reads. |
| `method` | const: "token" | Authentication method. |

<a id="lakecomputeapikeysource"></a>
## LakeComputeApiKeySource
Lake compute authenticated with an API key.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `type` | const: "lakecompute" |  |
| `method` | const: "api_key" | Authentication method. |
| `api_key` | str | Lake compute API key. |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `cache` | bool \| str \| [Cache](#cache) \| const: "forever" | Cache policy default for every query against this source, e.g. cache: 1h: queries inherit it and may refine it; cache: false opts them out. |
| `max_query_duration_seconds` | int | Maximum execution time for one query in seconds. Overrides execution.max_query_duration_seconds for this source. |
| `base_url` | str | Lake compute API endpoint. |
| `catalog_bundle` | str | Catalog bundle the lake compute session reads. |

<a id="lakecomputeoktasource"></a>
## LakeComputeOktaSource
Lake compute authenticated through Okta in the browser.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `type` | const: "lakecompute" |  |
| `method` | const: "okta_browser" | Authentication method. |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `cache` | bool \| str \| [Cache](#cache) \| const: "forever" | Cache policy default for every query against this source, e.g. cache: 1h: queries inherit it and may refine it; cache: false opts them out. |
| `max_query_duration_seconds` | int | Maximum execution time for one query in seconds. Overrides execution.max_query_duration_seconds for this source. |
| `base_url` | str | Lake compute API endpoint. |
| `catalog_bundle` | str | Catalog bundle the lake compute session reads. |
| `okta_auth_url` | str | Okta authorization endpoint. |
| `okta_token_url` | str | Okta token endpoint. |
| `okta_client_id` | str | Okta application client ID. |

<a id="lakecomputefivetransource"></a>
## LakeComputeFivetranSource
Lake compute authenticated with a Fivetran credential.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `type` | const: "lakecompute" |  |
| `method` | const: "fivetran" | Authentication method. |
| `fivetran_credential` | str | Fivetran API credential. |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `cache` | bool \| str \| [Cache](#cache) \| const: "forever" | Cache policy default for every query against this source, e.g. cache: 1h: queries inherit it and may refine it; cache: false opts them out. |
| `max_query_duration_seconds` | int | Maximum execution time for one query in seconds. Overrides execution.max_query_duration_seconds for this source. |
| `base_url` | str | Lake compute API endpoint. |
| `catalog_bundle` | str | Catalog bundle the lake compute session reads. |
| `fivetran_auth_url` | str | Fivetran API endpoint for exchanging the credential. |

<a id="duckdbextensionconfig"></a>
## DuckDBExtensionConfig
One DuckDB extension installed from a custom repository.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `name` | str | Extension name to install and load. |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `repo` | str | Repository to install the extension from. Omit to use DuckDB's default repository. |

<a id="duckdbsecretconfig"></a>
## DuckDBSecretConfig
One DuckDB CREATE SECRET declaration.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `type` | str | DuckDB secret type, e.g. s3, gcs, azure. |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `name` | str | Optional secret name. |
| `persistent` | bool | Whether the secret persists to disk (~/.duckdb/stored_secrets). |
| `scope` | str \| list[str] | Optional URL scope(s) this secret applies to. |

<a id="duckdbattachmentconfig"></a>
## DuckDBAttachmentConfig
One dbt-duckdb ATTACH declaration.

**Required**

| Field | Type | Description |
|-------|------|-------------|
| `path` | str | DuckDB database path or URL to attach. |

**Optional**

| Field | Type | Description |
|-------|------|-------------|
| `type` | str | Attached database type supplied by its extension. |
| `alias` | str | Optional name for the attached database. |
| `secret` | str | Name of the DuckDB secret used for this attachment. |
| `read_only` | bool | Whether the attached database is read-only. Honored as written when the adapter itself is read-write; when the adapter is read_only (the default), the in-process DuckDB adapter forces every attachment read-only regardless of this flag. |
| `options` | dict[str, str \| int \| float \| bool] | Additional scalar DuckDB ATTACH options. |
| `is_ducklake` | bool | Whether the attachment is a DuckLake database. |

<a id="duckdbretriesconfig"></a>
## DuckDBRetriesConfig
dbt-duckdb retry settings.

| Field | Type | Description |
|-------|------|-------------|
| `connect_attempts` | int | Number of connection attempts before failure. |
| `query_attempts` | int | Number of attempts for a retryable query failure. |
| `retryable_exceptions` | list[str] | Exception names that dbt-duckdb may retry. |

# dbt charts Project Config Reference: execution settings

Settings authored under `execution:` in `dbt_charts.yml` at the project root, not in a board. The file's other sections (`sources:`, `server:`, `cache:`, ...) are not generated here yet.

<a id="executionconfig"></a>
## ExecutionConfig

| Field | Type | Description |
|-------|------|-------------|
| `max_workers` | int | Maximum parallel query workers for a render. DuckDB serializes access regardless, so this only moves external warehouses. |
| `max_query_duration_seconds` | int | Maximum seconds a single query may run (must be &gt; 0). |
| `max_glob_file_count` | int | Maximum files a single glob may match (must be &gt; 0). |
| `file_source_max_tables` | int | Max tables in a files: map (must be &gt; 0). |
| `file_source_max_bytes` | int | Max uncompressed bytes per file-source table (must be &gt; 0). |
| `max_rows` | int | Maximum rows a single query may return (must be &gt; 0). |
| `max_result_bytes` | int | Maximum serialized byte size of a single query result (must be &gt; 0). |
| `max_template_output_bytes` | int | Maximum cumulative bytes of Jinja-emitted template output for a single board render (must be &gt; 0). |
| `dialect_aliases` | dict[str, str] | Maps a dbt charts dialect name to its sqlglot equivalent before parsing. |
| `lakecompute` | LakeComputeExecutionConfig | Lake compute connection defaults. |

# dbt Charts Error Reference (https://docs.dbtcharts.com/reference/errors/)

# dbt Charts Error Reference


Auto-generated from `dbt_charts.core.diagnostics.REGISTRY`. Every `ERR-*` code dbt charts can raise, grouped by docs topic.


## board


### ERR-CONFIG-KEY-MOVED: dbt_charts.yml key moved out of project config {: #err-config-key-moved }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
dbt_charts.yml key {key!r} has moved: {replacement}
```

Fired when dbt_charts.yml sets a key that no longer exists there. Design values (formerly under `chart_rendering:`, and the `vega:` block) are theme fields: set the successor named in the message under `style:` in charts/meta.yml. Engine constants are not configurable; delete the key.

### ERR-EXTENDS-UNRESOLVED: extends entry names neither a theme nor a board {: #err-extends-unresolved }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Unresolvable `theme:`/`extends:` value {entry!r}: not a built-in theme, and no board by that name at the project root. Use a built-in theme, a project-root board name, or a relative path such as `./base.yaml`. Available built-in themes: {available}.
```

Fired by the extends layer when a board's `extends:` entry resolves to nothing: not a built-in theme, and no matching `.yaml`/`.yml` at the project root. This is the project lane's counterpart to ERR-UNKNOWN-THEME; it fires only where the board lookup was actually attempted, so it can offer that lookup as a fix.

### ERR-EXTRA-FIELD: Unknown field in board YAML {: #err-extra-field }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Unknown field {field_path!r} in board YAML. Remove it or check the schema for supported keys.
```

Fired when the board YAML contains a field name that the schema does not recognize. Remove the unknown field or refer to the YAML reference for the supported keys. When the key is one a past grammar renamed, moved, or removed, the hint names its successor and the version that retired it.

### ERR-INVALID-DEFAULT-THEME: Invalid theme name in configuration {: #err-invalid-default-theme }

- **Level:** error
- **Domain:** serve
- **Suppressible:** no

**Message template:**

```
{source} ({theme!r}) is not a valid theme name. Available built-in themes: {available}.
```

Fired when the configured default theme name is not a recognized built-in theme. Check the available theme names and correct the configuration.

### ERR-META-SCHEMA: Board fragment contains an unknown or invalid field {: #err-meta-schema }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Board fragment schema error: {message}. Check that all keys are valid board fields.
```

Fired when a meta.yml file or a private (`_`-prefixed) partial contains a field that is not recognized by the board schema, or a field with an invalid value. Check that all keys match the supported board fields and remove any extras. The offending file is named separately, in the diagnostic's `file` location.

### ERR-NOTHING-TO-RENDER: None of the paths given is a board {: #err-nothing-to-render }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Nothing to render: none of the paths given is a board.
```

Fired when `dct render` has no board left to render after skipping the paths that are not boards. Each skipped path gets its own warning saying why. Pass at least one board file.

### ERR-PROJECT-CONFIG-SCHEMA: dbt_charts.yml contains an unknown or invalid field {: #err-project-config-schema }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Project config schema error: {message}. Check that all keys are valid project config fields.
```

Fired when dbt_charts.yml (the project config file) contains a top-level field that is not recognized (e.g. `style:`, which belongs in charts/meta.yml instead), or a field with an invalid value. Check the project config reference for the supported keys.

### ERR-TEXT-EMPTY-SEQUENCE: Text took an item from an empty list {: #err-text-empty-sequence }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
{detail} Guard with `{{% if ... %}}` or fix the query.
```

Fired when text (board text and titles, chart text) applies `first`, `last`, `min`, `max` or `random` to an empty list, such as the rows of a query that returned none. The text would otherwise render empty.

### ERR-TEXT-FORMAT-USAGE: Text format filter used incorrectly {: #err-text-format-usage }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Text `format` takes one dbt Charts format spec (preset, alias, d3 or strftime), as in `value | format('currency')`. Printf-style `'...' | format(x)` is not supported. Got: {detail}.
```

Fired when `format` in text is called without a spec, with a spec that is not a preset, alias, d3 or strftime spec, with extra arguments, or on a value that is not a number or date. It is not Jinja's printf-style `format`.

### ERR-TEXT-NULL-COMPARISON: Text compared a NULL value {: #err-text-null-comparison }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Ordering comparison on a NULL value in text; guard with 'is none'.
```

Fired when text orders a NULL value (a query cell or a variable) with `<`, `>`, `<=` or `>=`. Guard the comparison with `x is none`.

### ERR-TEXT-QUERIES-NONLITERAL: Text uses queries without a literal name {: #err-text-queries-nonliteral }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Text must reference queries by literal name (queries.<name> or queries['<name>']).
```

Fired when board `text:` or `title:`, or chart text, uses `queries` in any way other than `queries.<name>` or `queries['<name>']`, such as `queries[var]`, `queries | list` or `{% set q = queries %}`. The queries a board reads must be known before it runs.

### ERR-TEXT-QUERY-ACCESS: Text accessed a query result incorrectly {: #err-text-query-access }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Query {query_name!r} {access}. Use {use}.
```

Fired when text reads an attribute other than `.one`, `.rows` or `.columns` from `queries.<name>`, prints a result or row directly, reads an underscore column as `row._col` instead of `row['_col']`, or names a query the text does not reference.

### ERR-TEXT-QUERY-INDEX: Text indexed past the end of a query's rows or columns {: #err-text-query-index }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Query {query_name!r} has no {noun} {index} ({extent}).
```

Fired when text reads `queries.<name>.rows[i]` or `.columns[i]` with an index the result does not have, such as `rows[0]` on a query that returned no rows. Guard with `{% if queries.<name>.rows %}` or fix the query.

### ERR-TEXT-QUERY-ROW-COUNT: Text read .one from a query without exactly one row {: #err-text-query-row-count }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Query {query_name!r} returned {row_count} rows; .one needs exactly 1. Use .rows for multi-row results.
```

Fired when text reads `queries.<name>.one` and the query returned zero rows or more than one. Limit the query to one row or iterate `queries.<name>.rows`.

### ERR-TEXT-QUERY-UNKNOWN-COLUMN: Text read a column the query does not return {: #err-text-query-unknown-column }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Query {query_name!r} has no column {column!r}. Available: {available}.
```

Fired when text reads a column from a query row that the query does not return. Check the column name against the query's `select` list.

### ERR-TEXT-TYPE-ERROR: Text applied an operator to a value of the wrong type {: #err-text-type-error }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Text applied an operator to a value of the wrong type: {detail}. Guard NULL cells with 'is none' and convert strings before arithmetic.
```

Fired when text, such as board `text:` or `title:` or a chart's title, adds, subtracts or compares query values of incompatible types, for example arithmetic on a NULL or string cell.

### ERR-TEXT-UNKNOWN-QUERY: Text references an unknown query {: #err-text-unknown-query }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
{surface} references unknown query {query_name!r}. Defined queries: {defined}.
```

Fired when board `text:` or `title:`, or a chart's `title`, `subtitle`, KPI `label` or callout `title` or `message`, reads `queries.<name>` for a query that is not defined on the board, its `extends:` parents or its imports. Check for typos and declare the query under `queries:`.

### ERR-THEME-AND-EXTENDS: Board sets both theme: and extends: {: #err-theme-and-extends }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Cannot set both 'theme: {theme}' and 'extends:'; 'theme:' is shorthand for 'extends:'. Use one key: extends: {combined}
```

Fired when a board or board fragment authors both `theme:` and `extends:`. `theme: X` is sugar for `extends: X`, so the two would compete for one slot. List the theme first in `extends:`, lowest priority, ahead of the boards it already extends.

### ERR-UNKNOWN-THEME: Theme name is not a built-in theme {: #err-unknown-theme }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Unknown theme {theme!r}. Available built-in themes: {available}.
```

Fired during board validation when `theme:`, or a plain (non-path) `extends:` entry, names something that is not a built-in theme. Without it the name is dropped and the board renders on the default theme with no sign the request was ignored. Raised at positions where nothing resolves the entry as a board: a standalone or in-memory compile, and any nested board. A project board compiled through its file gets ERR-EXTENDS-UNRESOLVED from the extends layer instead, which can also report the board lookup it tried.

### ERR-VALIDATION-FIELD: Board YAML field failed Pydantic validation {: #err-validation-field }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Field {field_path!r}: {pydantic_msg}
```

Fired when a board YAML field fails Pydantic's type or constraint validation, or a normalize-stage rule on one field that Pydantic cannot express (a cross-field exclusion, a root-only constraint). The message carries the specific error. Check the field value against the schema.

### ERR-WRONG-SHAPE: Field expects a mapping but got a scalar {: #err-wrong-shape }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Field {field_path!r} expects a mapping, not a scalar. Provide a YAML block with keys: {available_keys}.
```

Fired when a board YAML field that expects a mapping (nested object) receives a plain scalar value instead. Provide a YAML block with the appropriate keys.

## charts


### ERR-AREA-ENCODING-SWAPPED: Area chart x/y encoding looks swapped {: #err-area-encoding-swapped }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r} (area): {reason} Area charts always plot x as the dimension and y as the value; there is no orientation knob to rotate an area chart, so a swapped x/y silently bakes a broken axis.
```

Fired when an area chart's encoding looks incorrect: either y is non-numeric (should be the measure), or x is a numeric measure with stack enabled. Area charts always plot x as the dimension and y as the value; there is no orientation knob.

### ERR-AREA-LOG-SCALE-INDEPENDENT-MULTIPLES: Log-scale area and independent-scale multiples are incompatible {: #err-area-log-scale-independent-multiples }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r} (area): axis_y.scale.type: log with multiples scale: independent is not supported: the explicit domain area bakes on a log scale (to avoid Vega-Lite's degenerate log-area rendering) is computed once from every panel's data combined, so it would apply the same domain to every panel regardless of scale: independent. Use multiples scale: shared, or drop the log scale.
```

Fired when an area chart authors both `axis_y.scale.type: log` and `multiples: {scale: independent}`. Area on a log scale needs an explicit baked domain to avoid Vega-Lite's degenerate rendering (see ERR-AREA-STACKED-LOG-SCALE-NOT-SUPPORTED's sibling note), but that domain is necessarily one shared value; baking it would contradict `scale: independent`'s promise of a per-panel domain, and suppressing it would silently reintroduce the degenerate rendering. Use `scale: shared`, or drop the log scale.

### ERR-AREA-STACKED-LOG-SCALE-NOT-SUPPORTED: Stacked area and log scale are incompatible {: #err-area-stacked-log-scale-not-supported }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r} (area): `style.stack: {stack}` with axis_y.scale.type: log is not supported: a stacked band's top encodes a cumulative sum, which a log scale can't represent (the baked domain would be computed from unstacked values and clip the real stacked extent). Use `stack: none`, or drop the log scale.
```

Fired when a stacked area chart (`style.stack: zero/normalize/center`) is combined with `axis_y.scale.type: log`. A cumulative stack top is meaningless on a log scale. Use `stack: none`, or drop the log scale.

### ERR-AREA-STACKED-MARK-STYLE-CLEARED: marks.area.stacked was cleared to null {: #err-area-stacked-mark-style-cleared }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r} (area): `marks.area.stacked` resolved to null. Stacked and single-series area charts both need this recipe -- a single-series area takes it in full even when the chart itself isn't stacked -- but a board or chart in this chart's style cascade authored `marks.area.stacked: null` explicitly, which clears the inherited theme default instead of leaving it alone. Remove that null override.
```

Fired when `marks.area.stacked` resolves to null after the style cascade. Every built-in theme declares this key, so the only way to reach null is a board or chart explicitly authoring `marks.area.stacked: null` -- which clears the inherited value rather than leaving it untouched. Remove the null override.

### ERR-AREA-STACKED-STROKE-INCOMPLETE: marks.area.stacked.stroke is missing, or lacks width, cap or join {: #err-area-stacked-stroke-incomplete }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r} (area): `marks.area.stacked.stroke` must declare `width`, `cap` and `join`. Stacked and single-series area charts replace `marks.line.stroke` with it wholesale, so a property it omits is dropped rather than inherited and the edge falls back to SVG butt/miter, spiking each vertex. Set all three explicitly (`cap: butt` for the renderer's own default).
```

Fired when the area stacked recipe's stroke is null or is missing a width, cap or join, usually because a board or chart authored one of them as null. The recipe's stroke replaces the top-edge line stroke wholesale rather than merging into it, so an omitted property is not inherited. Set width, cap and join explicitly.

### ERR-AXIS-COLUMN-REQUIRES-TABULAR-FONT: A column-forming quantitative axis needs a tabular label font {: #err-axis-column-requires-tabular-font }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r}: axis label font {family!r} does not guarantee tabular figures, but its tick ladder compacts to a shared magnitude and forms a column; the digits only stack into a column when every digit shares one advance, which a proportional font does not give, so the column would misalign silently. A quantitative axis takes its label font from the `numeral` slot (style.fonts.numeral), any other axis from the `label` slot (style.fonts.label); one of those slots, or an axis override (style.axis_y.labels.font.family on this chart, style.charts.axis_quantitative.labels.font.family on the board), carries this family.
```

**Fix:** Put the body typeface on `style.fonts.body` (and `style.fonts.heading`), and leave `style.fonts.label` and `style.fonts.numeral` on a tabular family (e.g. 'dbt Sans Tabular'). To keep a different family on the axis itself, set a tabular one on `style.axis_y.labels.font.family` for this chart, or on `style.charts.axis_quantitative.labels.font.family` to cover every chart.

Fired at resolve when a column-forming quantitative axis (a vertical ruler) resolves a shared magnitude scale but its label font is not vendor-registered as tabular. Ticks that carry no magnitude suffix are padded to the width of the one that does, so their digits stack under it; that column only holds when every digit shares a single advance, which is what a tabular board guarantees and a proportional one does not. A horizontal ruler is exempt (its ticks form no column) regardless of font.

### ERR-BAND-STEP-MULTI-METRIC: Band-aware step curve on a multi-metric chart {: #err-band-step-multi-metric }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
{chart_type} chart '{chart_id}': band-aware step curve is not supported for multi-metric (y: [...]) charts -- use a single y field or choose a different curve style.
```

Fired when a line or area chart with several y fields uses `curve: step` on a band x-axis. Use a single y field or another curve.

### ERR-BAR-DUPLICATE-ROWS: Chart data has duplicate rows that require aggregation {: #err-bar-duplicate-rows }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
{chart_type} chart {chart_id!r} requires pre-aggregated data with at most one row per plotted key ({field_list}). Found duplicate rows for {duplicate_preview}. Aggregate in the query before rendering.
```

Fired when a bar, line, or area chart receives data with more than one row per plotted key. These chart types require pre-aggregated data; aggregate in the query before rendering.

### ERR-BAR-LOG-SCALE-NOT-SUPPORTED: Log scale is not supported on bar charts {: #err-bar-log-scale-not-supported }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r} (bar): axis_y.scale.continuous.type: log is not supported: a bar's length encodes magnitude from zero, which a log scale makes meaningless. Use axis_y.scale.continuous.type: symlog on the bar chart, or switch to a line or area chart for a log scale.
```

Fired when a bar chart's y axis is set to `axis_y.scale.continuous.type: log`. A bar's length encodes magnitude from zero, which a log scale makes meaningless. Use `axis_y.scale.continuous.type: symlog` on the bar chart, or switch to a line or area chart for a log scale.

### ERR-BAR-MULTI-METRIC-NO-X: Multi-metric bar chart without an x field {: #err-bar-multi-metric-no-x }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Bar chart '{chart_id}': multi-metric (y: [...]) charts require an x field.
```

Fired when a bar chart with several y fields has no x field.

### ERR-BAR-OVERLAP-CONTINUOUS-AXIS: Bar overlap on a continuous axis {: #err-bar-overlap-continuous-axis }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Bar chart '{chart_id}': style.overlap is not supported on a continuous {axis}-axis -- overlap is a fraction of the categorical band width, and a quantitative (or wide temporal) {axis} has no band to divide. Group the {axis} into categories or buckets, or drop the overlap setting.
```

Fired when `style.overlap` is authored on a bar chart whose categorical axis is continuous and has no band to divide.

### ERR-BAR-OVERLAP-FULL-NON-UNIQUE-COLOR: overlap: full needs a color with one value per category {: #err-bar-overlap-full-non-unique-color }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Bar chart {chart_id!r}: style.overlap: full cannot lay out {series!r}, which has several values within one category; the series would stack end to end past the axis instead of overlapping. Use a color that is unique per category, a smaller overlap, or stack: zero.
```

Fired when a bar chart authors a full overlap (`overlap: full` or a fraction of 1 or more) over a color field with several values inside one category. A full overlap draws every series on top of the others, which only reads correctly when each category holds one color. Group the bars with a smaller overlap, or stack them.

### ERR-BAR-OVERLAP-SERIES-COUNT: Positive bar overlap needs exactly two series {: #err-bar-overlap-series-count }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Bar chart '{chart_id}': positive overlap is only supported for exactly 2 series (got {n_series}) -- 3+ series buries the middle one. Use 'none'/'flush', or rely on the 'auto' default.
```

Fired when a positive `style.overlap` is authored on a bar chart that does not have exactly two series.

### ERR-BAR-Y-NOT-NUMERIC: Bar chart y column is not numeric {: #err-bar-y-not-numeric }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r} (bar): y column {y_field!r} is not numeric. Bar charts always plot x as the category and y as the measure, regardless of orientation; use a numeric column for y.
```

Fired when a bar chart's `y:` column contains non-numeric data. Bar charts always use y as the measure axis regardless of orientation; use a numeric column for y.

### ERR-BAR-Y-START-KIND: Bar y and y_start are different kinds {: #err-bar-y-start-kind }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r}: column {y_field!r} is {y_kind} but column {y_start_field!r} is {y_start_kind}. A bar's start and end sit on one value axis: make them all numeric, or all dates.
```

Fired when a bar's `y:` and `y_start:` columns (or a bar layer's, against the chart's own) are not the same kind. Both must be numeric, or both dates.

### ERR-BAR-Y-START-NULL: Bar y_start column has an empty cell {: #err-bar-y-start-null }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r}: bar y_start column {y_start_field!r} is empty in row {row}. Every row needs a start; write 0 for a bar that starts at zero.
```

Fired when a bar's or bar layer's `y_start:` column holds a NULL. A missing start is never read as zero: have the query write an explicit 0 for a bar that starts at zero.

### ERR-BAR-ZERO-BASELINE-CROPPED: A bar chart cannot drop its zero baseline {: #err-bar-zero-baseline-cropped }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r} sets {field_path} to false, but a bar's length is measured from zero, so a bar cropped away from it misstates the quantity (and paints nothing). Remove axis_y.scale.continuous.zero, or use `type: line` to zoom into a range.
```

A bar encodes its value as length from the zero baseline, so `style.axis_y.scale.continuous.zero: false` on a bar chart would crop the bars and misstate the values. Remove the key to keep the zero baseline, or use `type: line` for a zoomed range. A floating bar (`y_start:`) has no zero baseline and is exempt.

### ERR-CATEGORY-COLOR-PALETTE-EXHAUSTED: An authored category_colors field has more values than the palette has swatches {: #err-category-color-palette-exhausted }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
{value_count} values for `{field}` need a palette swatch, but the board's categorical palette has {swatch_count}. Pick a wider palette, or pin the extra values in `style.charts.category_colors.{field}` to a color outside it (a variant like `category[3].light`, or a hex).
```

Fired when an authored `style.charts.category_colors.<field>` field has more values needing a palette swatch (unpinned values plus pins naming a palette color) than the board's categorical palette has. Pins to a color outside the palette (a variant or a hex) need no swatch. Two categories must never share a swatch, so an authored field raises instead of silently declining to bind (an unauthored field just declines). Pick a wider palette, or pin the extra values to colors outside it.

### ERR-CATEGORY-COLOR-PIN-DUPLICATE: Two category_colors pins name the same color {: #err-category-color-pin-duplicate }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
`style.charts.category_colors.{field}` pins both `{first_value}` and `{second_value}` to `{color}`: two categories cannot share a swatch. Give one of them a different color.
```

Fired when two values pinned under `style.charts.category_colors.<field>` resolve to the same color (case-insensitively), which would seat two categories on one swatch. Give one of the pins a different color.

### ERR-CHART-PAINTED-NO-MARKS: Chart received rows but painted no marks {: #err-chart-painted-no-marks }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r} received {row_count} row(s) but every mark it drew has zero width or height. Its card is {card_width}px wide, which is likely too narrow to leave the plot any room; otherwise check whether the x/y fields and scale types match the data's actual shape.
```

Fired when a plotting-family chart's query returns at least one row but the rendered SVG contains no mark with visible extent: every bar, line, area, point, wedge, or shape it drew is degenerate. `WARN-QUERY-RETURNED-ZERO-ROWS` covers the honest empty case (no rows); this covers the dishonest one: rows arrived, the renderer just didn't paint anything visible with them. The message states the card's measured width, because a card too narrow to leave the plot any room (axis labels take the width first) is a likely cause; otherwise the x/y fields and scale types do not match the data's shape.

### ERR-COLOR-NULL-SERIES: Color column contains NULL values {: #err-color-null-series }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
{chart_type} chart {chart_id!r} has {null_rows} row(s) with a NULL value in its color column {color_field!r}. A NULL category cannot be painted or named in the legend, but its rows still occupy stack space; the chart would read as bars floating off the baseline. Give every row a category in the query (e.g. COALESCE({color_field}, 'Unknown')).
```

Fired when the column bound to a chart's `color` channel contains NULL values. The renderer cannot assign a NULL a palette slot or a legend entry, so the series would consume stack space while being invisible and unattributable. Fix the grain in the query: the most common cause is a `CASE` with no `ELSE`, or an `ELSE` that passes the raw column through unchanged.

### ERR-COLOR-TOKEN: Style color token does not resolve {: #err-color-token }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Color token in {scope} does not resolve: {reason}
```

Fired when a color in a `style:` block is a palette token (`palette.slot`, `role.alias`, `role[N]`) that no palette or theme role resolves: a misspelled palette, an alias or slot the palette lacks, or a role the theme does not bind. A bad token in a chart's own style names the chart, and other charts on the board render normally; one in board style names the field.

### ERR-CONCAT-OVERSHOOT-NONPOSITIVE: Overshoot correction produced a non-positive pane width {: #err-concat-overshoot-nonpositive }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Overshoot correction produced a non-positive pane width ({new_w:.1f}px): pane width {orig_w:.1f}px minus overshoot {overshoot:.1f}px. The chart content (title, subtitle, axis labels, series labels, or legend) is wider than the available canvas ({target_width:.1f}px).
```

Fired when the overshoot correction algorithm for a concatenated layout produces a non-positive pane width. The chart content (title, subtitle, axis labels, series labels, or legend) is wider than the available canvas. Series labels come from the column bound to `color:`, and are the usual cause when that column holds long text.

### ERR-CSS-COLOR-INVALID-AT-RENDER: A style="..." color value does not parse as exactly one color {: #err-css-color-invalid-at-render }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Color {value!r} is not a valid CSS color ({detail}). Use a hex color, a CSS named color, or transparent/none.
```

Fired when a value destined for a style="..." CSS declaration (a table row/cell link color, a board title's font color, or the variables strip's border color) does not parse as exactly one CSS color. Escaping alone cannot make such a value safe: a string like `red; background-image:url(//evil)` needs no quote or angle bracket to open a second declaration, so the value itself must be proven to be nothing but a color before it reaches the attribute.

### ERR-CUSTOM-FIELDS: Custom chart channels or options do not match the template {: #err-custom-fields }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r} (custom): {reason}
```

Fired when a `type: custom` chart's channels (`x`, `y`, `color`, ...) or `options:` disagree with what its template declares in its header: an undeclared channel or option, a required one left out, a list on a channel without `multiple: true`, a value of the wrong type, or a color option that is not a color. A template with no header accepts no channels and no options.

### ERR-CUSTOM-RENDER: Custom chart template failed to render {: #err-custom-render }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r} (custom): {reason}
```

Fired when a `type: custom` chart's template fails while rendering: a Jinja runtime error, a misspelled column, param, or style key (templates use strict undefined), a column param naming a column the query did not return, or the template calling `raise_error()`.

### ERR-CUSTOM-SVG: Custom chart template produced disallowed SVG {: #err-custom-svg }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r} (custom): {reason}
```

Fired when a `type: custom` chart's template output is not well-formed SVG or uses a construct outside the allowlist: `script`, `foreignObject`, `style`, `image`, or animation elements; `on*`, `role`, `aria-*` or `data-*` attributes; a `role-`/`dbt-` class; a paint attribute that is not a color; an `<a href>` outside the link rules (board path, http, https, mailto); any other `href` that is not a `#local` reference; `url(...)` that is not `url(#local)`; `javascript:`; nesting past 64 levels; or a DOCTYPE or ENTITY declaration. Nothing is stripped; the chart fails.

### ERR-CUSTOM-TEMPLATE: Custom chart template is missing or invalid {: #err-custom-template }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r} (custom): {reason}
```

Fired when a `type: custom` chart's template cannot be loaded: `template:` names no `templates/<name>.svg.j2` file in the project, the board has no project to read it from, the `{#--- ... ---#}` header is not valid YAML or declares an unknown param type, or the Jinja source has a syntax error.

### ERR-ENDPOINT-LABELS-CENTER-STACK: stack: center is not supported for horizontal endpoint labels {: #err-endpoint-labels-center-stack }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r}: stack: center is not supported for horizontal stacked bar endpoint labels — the rail anchors on the cumulative (0..Σ) axis, which a center stack (-Σ/2..+Σ/2) does not have. Use stack: zero, or set style.endpoint_labels.visible: false on this chart.
```

Fired when a horizontal stacked bar chart uses `stack: center` while its endpoint-label rail is forced on. The rail anchors each label at its segment's cumulative midpoint from zero; a center stack has no such axis. Use `stack: zero`, or turn the rail off with `style.endpoint_labels.visible: false`.

### ERR-ENDPOINT-LABELS-NEGATIVE-STACK: negative values are not supported for stacked endpoint labels {: #err-endpoint-labels-negative-stack }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r}: negative values are not supported for stacked bar/area endpoint labels — they break the cumulative-midpoint computation. Set style.endpoint_labels.visible: false on this chart.
```

Fired when a stacked bar or area chart's data carries a negative measure while its endpoint-label rail is visible. The rail anchors each label at its segment's cumulative midpoint, a computation that assumes every segment in the stack contributes in the same direction; a negative value crosses zero and breaks it. Turn the rail off with `style.endpoint_labels.visible: false`.

### ERR-ENDPOINT-LABELS-RECASCADE-RATIO: Endpoint-label re-cascade needs a positive height ratio {: #err-endpoint-labels-recascade-ratio }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
could not re-cascade endpoint labels: height_correction_ratio must be positive, got {ratio}
```

Fired when the endpoint-label rail is re-cascaded against a non-positive height correction ratio.

### ERR-ENDPOINT-LABELS-UNORDERABLE-SORT: sort by a non-numeric column cannot be combined with stacked endpoint labels {: #err-endpoint-labels-unorderable-sort }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r}: chart.sort by {sort_by!r} cannot be combined with stacked bar endpoint labels. The rail places its labels from the order the sorted axis draws, and dbt Charts confirms that order only for a column carrying numeric values. Sort by a measure instead, or set style.endpoint_labels.visible: false on this chart.
```

Fired when a stacked bar chart authors `sort:` by a column that carries no numeric values while its endpoint-label rail is visible. The rail places its labels from the order the sorted axis draws (a vertical rail anchors each series at its own last drawn column, a horizontal one anchors every series on the top row), so it has to know that order before the chart renders. dbt Charts confirms it only for a numeric sort column, and labels placed from the wrong order name series in the wrong place, which is worse than a legend. Sort by a measure, or turn the rail off with `style.endpoint_labels.visible: false`.

### ERR-ENGINE-REFUSED: the render engine cannot draw this chart yet {: #err-engine-refused }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
The render engine cannot draw this chart yet: {message}
```

Fired when the Rust render engine meets a chart shape it does not model yet. It names an engine gap, not a mistake in the board.

### ERR-FIELD-LABELS-FIELD-NOT-FOUND: field_labels key names no column the chart reads {: #err-field-labels-field-not-found }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
field_labels key(s) {fields} name no column of the chart's query. Available columns: {available}.
```

Fired when a `field_labels` key is neither a column of the chart's query result nor a field one of its layers names. The label would never paint. Check for a typo, including letter case.

### ERR-FIELD-LABELS-WIDE-COLLISION: field_labels gives two wide measures the same label {: #err-field-labels-wide-collision }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
field_labels makes measures {measures} of `y:` share the label {label!r}, so their series cannot be told apart.
```

Fired when a `field_labels` entry for a `y: [...]` measure equals another measure's label. Derived labels fall back to the raw column name on a collision; an authored label never does. Give each measure distinct text.

### ERR-FONT-REGISTRY: style.fonts entries do not resolve {: #err-font-registry }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
{message}
```

Fired when `style.fonts` entries extend one another in a cycle (`a` extends `b` extends `a`; the message names the path), or when the `heading` entry inherits a `size` from the font it extends (`heading` takes the `sizes` ramp, never `size`). Break the cycle, or extend a font that sets no size.

### ERR-FONT-UNKNOWN: Font name is not an entry in style.fonts {: #err-font-unknown }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
{message}
```

Fired when a font slot or a `style.fonts` entry names a font (`font: label`, `font: {extends: label}`, `fonts.h2: {extends: heading}`) that `style.fonts` does not define. The message lists the known names. Define the font under `style.fonts`, or fix the name.

### ERR-FORMAT-AFFIX-NOMINAL-AXIS-UNSUPPORTED: A FormatConfig prefix/suffix/notation cannot reach a categorical axis {: #err-format-affix-nominal-axis-unsupported }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
{field_path} authors a prefix/suffix/notation, but the {axis} channel resolves to a {channel_type} scale, whose tick labels paint from the plain format string. Drop the prefix/suffix/notation, or author a plain spec.
```

An affix applies to a quantitative axis only. A categorical (nominal or ordinal) axis paints its tick labels from the plain format string, so a prefix, suffix or notation there cannot paint. Remove it, or author the affix on the measure axis.

### ERR-FORMAT-AFFIX-TIME-UNSUPPORTED: A FormatConfig prefix/suffix/notation is a number-format feature only {: #err-format-affix-time-unsupported }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Format at {field_path} combines a prefix/suffix/notation with time-format spec {spec!r}. A temporal axis paints through a date formatter that has no place for an affix. Drop the prefix/suffix/notation, or move a prefix/suffix to a number slot, a KPI value, or a table column; notation never applies to a date.
```

A prefix, suffix or notation next to a strftime spec ('%b %Y') is rejected on a temporal axis's format: it paints through a date formatter, which has no place for an affix. Author a prefix/suffix on a number slot (`axis_y.labels.format`), or on a KPI value or table column format, which paint it around the date (`FY Jan 2026`). `notation` only affects an SI number spec; it does nothing to a date anywhere, so drop it.

### ERR-FORMAT-ALIAS-CYCLE: style.formats aliases point at each other in a circle {: #err-format-alias-cycle }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
style.formats.{name} leads into a circle: {chain}. Give one of them a d3 spec of its own.
```

A `style.formats` entry whose target is another entry's name (`currency: currency_whole`) resolves through that entry. When the entries lead around a circle, no format is ever reached. Break the circle by giving one entry a literal d3 spec.

### ERR-FORMAT-GRAIN-NAME-NOT-REDEFINED: An engine date grain name used as a format without being redefined {: #err-format-grain-name-not-redefined }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Format {spec!r} at {field_path} names the engine's own {spec} axis labels, which only a date axis that detects that grain can paint. Redefine it in `style.formats` with a strftime spec (`{spec}: "%b %Y"`) to relabel that grain across the board, or use a strftime spec here.
```

`date_year`, `date_quarter`, `date_month` and `date_week` mean the engine's own labels for a grain, which no single format expresses. They only take effect once a board redefines one in `style.formats`; used in a slot without that, the name would silently print something else, so it is rejected.

### ERR-FORMAT-INVALID: Format spec is not a predefined name, a style.formats alias, or a valid d3-format/d3-time-format spec {: #err-format-invalid }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Unknown {kind_noun} format {spec!r} at {field_path}: {explanation}
```

Fired when an authored `format:` string is not one of the engine's predefined format names (e.g. `currency`, `number`, `percent_number`), not a key defined in `style.formats`, and fails to parse as a d3-format spec. Check for typos against the predefined names or your `style.formats` keys, or use a valid d3-format spec (https://d3js.org/d3-format). In a slot that accepts a raw strftime spec (`%b %Y`), the same code also fires for a directive the engine does not implement (`%K`); the message names the accepted directives.

### ERR-FORMAT-KIND-MISMATCH: A redefined format name has the wrong kind {: #err-format-kind-mismatch }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Format {spec!r} at {field_path} is not a {kind} format. This name takes only a {kind} spec; the engine's {kind} names are: {available}. {escape_hatch}
```

Fired when `style.formats` redefines an engine format name as a spec of the other kind: a number name (`currency`, `percent`) must stay a number spec and a date name (`date_short`) a strftime spec, because every slot that reads the name expects its kind. A number spec baked onto a date axis paints garbage tick labels rather than failing. A plain `format:` slot is judged by the column it paints and takes either.

### ERR-FORMAT-NATIVE-IN-VEGA-SLOT: Native formatter used in a Vega-rendered format slot {: #err-format-native-in-vega-slot }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Format {spec!r} at {field_path} is a native formatter with no Vega arm and cannot be used in Vega-rendered slots (axis labels, mark value labels, support_table, heatmap and map tooltips). Move it to a table cell (or a KPI value, for the percent names), or transform the value in the query to match a plain d3 spec (for a whole-number percent, divide by 100 and then use a d3 percent spec such as ".1%"). Valid alternatives: {available}.
```

Fired when a native name appears in a Vega-rendered format slot it cannot paint: `percent_number`, `percent_number_delta` and `percentage_points_delta` anywhere Vega paints (axis label, mark value-label format), and every native (`duration` and `bytes` too) in a support_table format or a heatmap or map tooltip. These names bypass d3 entirely and are only valid in Python-rendered slots (KPI headline and table cells). To keep the value in a Vega-rendered slot, transform it in the query to match a plain d3 spec: for a whole-number percent, divide by 100 and then use a d3 percent spec such as `.1%`.

### ERR-FORMAT-SIGN-BEFORE-ANCHORED-PREFIX: A sign cannot lead a prefix that paints on one value only {: #err-format-sign-before-anchored-prefix }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Format at {field_path} sets sign_placement: before_prefix, but its prefix is anchored on one value: the anchor would read '−EUR 50' beside a bare '−40'. Drop sign_placement (the anchor then reads 'EUR −50'), or set repeat: every.
```

Where an authored prefix paints on one value of an axis or support_table row (`repeat: anchor`, or that surface's default), the sign follows the prefix (`EUR −50`, `€−50`) so the anchor's digits line up with the bare `−40` beside it. `sign_placement: before_prefix` there is rejected; drop it, or set `repeat: every` to put the prefix on every value.

### ERR-FORMAT-SIGN-PLACEMENT-TABLE-UNSUPPORTED: A table column keeps the sign with the digits {: #err-format-sign-placement-table-unsupported }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Format at {field_path} sets sign_placement, but a table column paints its prefix in its own lane and keeps the sign with the digits ('€  −500'). Drop sign_placement from this column's format.
```

A table column paints the prefix in a lane of its own, aligned down the column, and the sign beside the digits (`€  −500`), so `sign_placement` has nothing to move there and is rejected. Drop it, or give the column a format without it.

### ERR-FORMAT-TEXT-IN-VEGA-SLOT: Text format name used in a Vega-rendered format slot {: #err-format-text-in-vega-slot }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Format {spec!r} at {field_path} is a text format and cannot be used in Vega-rendered slots (axis labels, mark value labels, support_table). Use it on a table column or KPI value; a number or date slot takes a number or time name or a d3 spec.
```

Fired when `email` or `url` appears in a slot Vega paints. They name text a table cell or KPI value links, and have no number or date spec for Vega to apply.

### ERR-FORMAT-TEXT-REDEFINED: A text format name cannot be redefined {: #err-format-text-redefined }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
`{field_path}` redefines the engine's text format {name!r}. {name!r} is a text format with no spec; it cannot be redefined.
```

Fired when `style.formats` has a key named `email` or `url`. Those names format a value as itself and mark the column as an email address or a web URL, so a table cell or KPI value can link it. They carry no spec for an alias to replace. Pick another alias name for your own spec.

### ERR-FORMAT-TIME-DIRECTIVE-UNSUPPORTED: strftime directive in a Vega-rendered time format cannot be measured {: #err-format-time-directive-unsupported }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Format {spec!r} at {field_path} uses {directives}, which dbt Charts cannot render identically to what Vega paints on the axis: either it is not part of d3-time-format's directive set at all (Vega paints the literal letter), or Python renders it through the host's C locale or local timezone rather than d3's UTC/en-US output. This slot is baked onto a Vega-painted axis, whose label width is also measured from this same spec -- a mismatch here is a wrong render that looks right until the label overlaps its neighbor. Supported directives: {available}.
```

Fired when an authored Vega-painted time slot (an axis `labels.format`) uses a strftime directive dbt Charts cannot render byte-identical to what Vega's `utcFormat` paints. `%C`/`%k`/`%l`/`%z` and most other letters are not d3-time-format grammar at all -- Vega paints the literal letter, not a computed value. `%Z` is real d3 grammar too but empty on a naive datetime, unlike d3's `+0000`-style offset. `%s` is real d3 grammar but Python's value follows the host's local timezone rather than a true UTC epoch count; `%Q` (epoch milliseconds) is the supported equivalent. A format string outside a Vega-painted slot (a table column, the footer timestamp) is unaffected -- those render through Python directly, so no measure-vs-paint divergence is possible there.

### ERR-GAP-FILL-BUCKET-COLLISION: Two rows collapse to the same gap-fill bucket {: #err-gap-fill-bucket-collision }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Rows with {x_field!r} values {value_a!r} and {value_b!r} both collapse to the {time_unit!r} bucket {bucket!r}{dim_desc}. Aggregate to {time_unit} grain in the query before rendering.
```

Fired when gap-filling an ordinal bucketed-time axis finds two rows whose x-values fall inside the same bucket: two timestamps on one calendar day under `yearmonthdate`, or a finer-grained series under a coarser authored `time_unit` (monthly rows under `yearquarter`, daily rows under `yearmonth`). A coarser grain places rows in buckets; it does not combine them, and a last-wins merge would silently discard all but one. Aggregate to the bucket grain in the query before rendering.

### ERR-GEOSHAPE-SHADING-WITHOUT-LOOKUP: A geoshape shades from a column but has no lookup {: #err-geoshape-shading-without-lookup }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Geoshape shades from column {value_field!r}, but {field_path} is not set, so nothing joins the data to the map. Set `lookup:` to the data column that matches the geo source's {geo_join_key!r} key.
```

A choropleth shades each region by joining a data column to the geo source's key property. `value:` (or a data-driven `color:`) without `lookup:` has nothing to join on and would render an unshaded base map. Set `lookup:` to the column holding the region identifiers, or drop `value:`/`color:` to draw a plain base map.

### ERR-HISTOGRAM-NON-NUMERIC: Histogram x field is not numeric {: #err-histogram-non-numeric }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Histogram chart {chart_id!r} requires a numeric x field for binning, but {field!r} is {vl_type!r}. Use a quantitative (numeric) column as x.
```

Fired when a histogram chart's x field is not numeric (quantitative). Histograms bin values into ranges, which requires a numeric column. Use a quantitative column as x.

### ERR-HISTOGRAM-PREAGGREGATED: Histogram data looks pre-aggregated, not raw rows {: #err-histogram-preaggregated }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Histogram chart {chart_id!r} received data where {field!r} forms a gapless run of whole numbers alongside unused numeric column(s) {count_fields}: this looks like pre-aggregated data (one row per bucket, e.g. `GROUP BY {field}`), not the raw, ungrouped rows a histogram bins itself. Vega-Lite would bin and count these already-counted rows again, silently discarding whatever real measure they carry. Use `type: bar` with `x: {field}` and one of {count_fields} as `y` to chart pre-aggregated data instead.
```

Fired when a histogram chart receives data where its x field forms a gapless run of whole numbers alongside an unused numeric column, the shape of already-aggregated, one-row-per-bucket data. Histograms rely on Vega-Lite's own binning + counting over raw, ungrouped rows; pre-aggregated data silently produces a wrong, miscounted histogram instead of erroring. Aggregate in the query and use `type: bar` instead.

### ERR-IMAGE-REF-UNRESOLVED: an image reference could not be resolved {: #err-image-ref-unresolved }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
image {ref!r} could not be resolved: {reason}
```

Fired when an image in a `text:` block, a title, or a callout message or title cannot be embedded. A relative path resolves against the directory of the file it is written in, and a path starting with `/` against the project's `charts/` directory; this fires when that path does not exist, escapes the project root, carries an unsupported file suffix (a `?query` or `#fragment` included), the render has no project or the content no location to resolve it against, a Jinja template renders it (a project image path is written out; a template may put `{% if %}` around whole images), or the image's own content is malformed. An `http(s)://` reference is never fetched or resolved, and never raises this code.

### ERR-INPUT-INVALID: Invalid render input {: #err-input-invalid }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
{message}
```

Fired when the render layer receives input data that fails a structural check. The message carries the specific validation error.

### ERR-KPI-FORMAT-KIND-MISMATCH: KPI support format does not match a temporal value {: #err-kpi-format-kind-mismatch }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
KPI chart {chart_id!r} support value is a date/time, but its format {spec!r} is not a date format. Use date_short, a strftime spec via a style.formats alias, or remove format: to use date_short.
```

Fired when a KPI's style.support.format is a number format (not date_short, time_short, or a style.formats alias resolving to a strftime spec) and support.value is a date/datetime column. Unlike the headline value's format, which falls back to date_short, a support format mismatch always fails.

### ERR-KPI-MULTIROW: KPI query returned more than one row {: #err-kpi-multirow }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
KPI chart {chart_id!r} expects exactly 1 row, got {row_count}. Use a query that returns a single row (e.g. SELECT SUM(...) or LIMIT 1).
```

Fired when a KPI chart's query returns more than one row. KPI charts display exactly one value; use a query that returns a single row (e.g. SELECT SUM(...) or LIMIT 1).

### ERR-KPI-NO-DATA: KPI query returned no rows {: #err-kpi-no-data }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
KPI chart {chart_id!r} has no data: its query returned 0 rows.
```

Fired when a KPI chart's query returns zero rows. A KPI displays exactly one value, so an empty result has nothing to show. Make the query return one row, for example an aggregate without a GROUP BY.

### ERR-KPI-TEMPORAL-FORMAT-INVALID: KPI temporal format spec could not be applied {: #err-kpi-temporal-format-invalid }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
KPI chart {chart_id!r} could not format value {cell!r} with spec {spec!r}: {reason}
```

Fired when a KPI's resolved date/time format spec is itself invalid (an unknown strftime directive) or the cell's value cannot be parsed as a calendar date/time (e.g. an out-of-range hour in an ISO timestamp string).

### ERR-KPI-VALUE-COLUMN-NOT-FOUND: KPI value names a column not in the query result {: #err-kpi-value-column-not-found }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
KPI chart {chart_id!r}: value column {value_column!r} not found in the query result. Channels are always column references; constant values come from the query. For a string status value, add `rows: [{{status: {value_column!r}}}]` to the query and set `value: status`. For a numeric literal, add `rows: [{{count: <value>}}]` and set `value: count`.
```

Fired when a KPI's `value` (or a support value) names a column that is not in the query result row. Chart channels are column references, never literals, so a constant must come from the query itself.

### ERR-LABEL-FORMAT-AXIS-MISMATCH: a non-time axis format needs numeric tick values {: #err-label-format-axis-mismatch }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
style.{setting} ({fmt!r}) cannot be read on this axis: {field!r} holds non-numeric tick labels. {remedy}
```

Fired when `style.axis_x.labels.format`, `style.axis_y.labels.format` or `style.axis_y.mirror.format` is anything but a d3 time spec on an axis whose field resolves to nominal, ordinal or temporal. All three matter: nominal is a plain category column, ordinal covers the date-like buckets (`2024-01`, `Q1 2024`, `FY2024`) that are still band-scale strings, and temporal is a real date/time field. On a band scale Vega coerces every tick to `NaN` rather than failing; on a temporal one it reads the spec as a time spec instead and paints its literal text (`$,.0f`) across the axis. Either way it raises here now. A horizontal bar is the case worth calling out: its `axis_x` addresses the categories, which the rotation draws down the left edge, so an author formatting what looks like the value axis reaches the wrong channel. The measure is `axis_y` in both orientations; on a heatmap the value is the color channel and neither axis carries it; on a scatter dot plot the measure is `axis_x` instead, since the categorical channel there is `axis_y`. Numeric categories on a band scale are NOT gated: they format cleanly, so nothing distinguishes an intended format from a misaddressed one — a temporal axis has no such exemption, since no reading of a number format over dates was ever the author's intent.

### ERR-LABEL-VALUES-INVALID-DATE: labels.values entry is not a valid ISO date {: #err-label-values-invalid-date }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
style.axis_x.labels.values entries must be ISO date or datetime strings (e.g. '2024-01-01') or date/datetime objects; got {value!r}.
```

Fired when an entry in `style.axis_x.labels.values` cannot be parsed as an ISO date or datetime. Use ISO date strings (e.g. '2024-01-01') or date/datetime objects.

### ERR-LABEL-VALUES-NOT-TEMPORAL: labels.values requires a temporal x-axis {: #err-label-values-not-temporal }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
style.axis_x.labels.values isn't usable on {field!r}: {cause}. {remedy}
```

Fired when `style.axis_x.labels.values` is set on an x-axis that can't honor it: either the x-axis values aren't valid ISO dates or datetime objects, or the chart's horizontal-bar categorical axis never applies label filtering regardless of date format.

### ERR-LABELS-FIELD-NOT-FOUND: labels.field names a column not in the query result {: #err-labels-field-not-found }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r}: labels.field {field!r} on {source} names a column not present in its data. Available columns: {available}.
```

Fired when `labels.field` names a column that is not present in the query result. `source` identifies which slot fired: the base chart's own labels, or a specific overlay layer (by position, type, and query), since a chart's overlay `layers:` can each carry their own `labels.field`. Check the column name against the actual columns returned by that slot's query.

### ERR-LAYER-AXIS-POSITION-ENDPOINT-LABELS: axis_y.position on a layer cannot be combined with endpoint labels {: #err-layer-axis-position-endpoint-labels }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r}: style.endpoint_labels.visible is not supported on a layered chart whose layers pin an explicit axis_y.position — the label rail anchors on one shared y-scale, and a dual-axis layer renders on a different one. Remove the per-layer axis_y.position override, or set style.endpoint_labels.visible: false on this chart.
```

Fired when a layered chart's endpoint-label rail is visible (authored or theme-set) while one of its layers pins its own `axis_y.position`. The rail anchors every layer's labels on the base chart's single shared y-scale; a layer with a pinned `axis_y.position` is a genuine dual-axis layer rendering on a different scale, which the rail has no way to represent. Remove the per-layer `axis_y.position`, or turn the rail off with `style.endpoint_labels.visible: false`.

### ERR-LAYER-AXIS-POSITION-ORIENTATION: axis_y.position on a layer needs a vertical base chart {: #err-layer-axis-position-orientation }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r}: a layer's `axis_y.position` names a left or right side, and `style.orientation: horizontal` measures along the horizontal axis, whose sides are top and bottom. Drop `axis_y.position`, or set `style.orientation: vertical`.
```

Fired when a layer pins `axis_y.position` on a chart whose base is horizontal. The resolved model always measures on `y` and carries its category on `x`; a horizontal bar paints that same model with the pair swapped, so its measure axis runs horizontally and has no left or right side to pin a second axis to. Whether left/right should map onto bottom/top is a design decision nobody has taken, so this refuses rather than drawing the layer against a side the author did not ask for.

### ERR-LAYER-AXIS-TITLE-WITHOUT-POSITION: A layer's y-axis title has no axis of its own to land on {: #err-layer-axis-title-without-position }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
{field_path} sets a title, but no layer on this chart pins `axis_y.position`, so every layer shares the base chart's y axis and a layer title has nowhere to go. Pin `axis_y.position` on a layer of a vertical base chart to give it its own axis, or drop the layer `axis_y.title`.
```

A layer's `axis_y.title` names that layer's own y axis. A layer only gets its own axis when some layer pins `axis_y.position` to a side; until then all layers share the base chart's axis, which has a single title slot that several layers could claim. Pin a side to split the axes, or remove the layer title.

### ERR-LAYER-LABEL-COLLISION: Layer label collides with an existing color scale entry {: #err-layer-label-collision }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
layer label {label!r} collides with an existing color scale entry. To fix: give this layer (or the colliding series) a distinct label:.
```

Fired when a layer's label equals an existing color scale entry on a chart whose endpoint-label rail or field color would silently merge them.

### ERR-LAYER-ORDER-TRANSFORM-MISSING: Base order encoding has no matching calculate transform {: #err-layer-order-transform-missing }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
base spec carries order encoding for field {order_field!r} but no matching calculate transform was found
```

Fired when a layered chart's base order encoding has no calculate transform to hoist.

### ERR-LAYER-STEP-ORIENTATION: curve: step on a layer needs a vertical base chart {: #err-layer-step-orientation }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r}: a layer's `curve: step` builds its band offset along the horizontal axis, which `style.orientation: horizontal` uses for the measure. Drop `curve: step` on the layer, or set `style.orientation: vertical`.
```

Fired when a layer authors `style.marks.line.curve: step` on a chart whose base is horizontal. The band-aware step transform doubles each row to its band edges and separates them with an `xOffset` scale sized by `bandwidth('x')`: the channel a horizontal base measures on rather than the one it bands. Refused rather than offsetting the layer along an axis that has no bands to measure.

### ERR-LAYER-X-DOMAIN-MISMATCH: Layer x does not share the base's discrete-label domain {: #err-layer-x-domain-mismatch }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
chart '{chart_id}': layer x '{x_field}' resolved to a {layer_type} scale, but the base x '{base_field}' is {base_type} -- layers sharing the x axis with the base must resolve to the same discrete-label domain.
```

Fired when a layer's x field resolves to a type that cannot share the base's discrete x domain.

### ERR-LAYER-X-NOT-QUANTITATIVE: Layer x resolved to a non-quantitative scale under a quantitative base {: #err-layer-x-not-quantitative }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
chart '{chart_id}': layer x '{x_field}' resolved to a {layer_type} scale, but the base x '{base_field}' is {base_type} -- a layer sharing the x axis with a quantitative base must itself resolve to a quantitative type.
```

Fired when a layer's x field is not quantitative while the base x axis is.

### ERR-LAYERED-NO-COLOR-SCALE: Layered chart has no shared color scale for its endpoint-label rail {: #err-layered-no-color-scale }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
layered chart has no shared color scale for its endpoint-label rail
```

Fired when a layered chart with endpoint labels has no layer carrying a categorical color scale.

### ERR-LAYERED-NO-PALETTE: Layered chart has no color palette {: #err-layered-no-palette }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
layered chart has no color palette
```

Fired when layers need palette colors and the resolved palette is empty.

### ERR-LAYERS-AMBIGUOUS-Y-DOMAIN: Chart-level y domain is ambiguous with independent layer scales {: #err-layers-ambiguous-y-domain }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r} sets axis_y.scale.continuous.domain={domain!r} but a layer pins its y axis to one side, so the chart has two independent y scales and one chart-level domain cannot apply to both. Remove the chart-level axis_y.scale.continuous.domain and set axis_y.scale.domain on each layer's own axis_y; the base series' domain cannot be pinned once a layer sets axis_y.position.
```

Fired when a chart sets `axis_y.scale.continuous.domain` at the chart level and any layer pins its y axis to a side with `axis_y.position`. The base chart takes the opposite side, so the chart has two independent y scales and a single chart-level domain is ambiguous. Remove the chart-level `axis_y.scale.continuous.domain` and set `axis_y.scale.domain` on each layer's own `axis_y`; the base series' domain cannot be pinned once a layer sets `axis_y.position`.

### ERR-LEGEND-ALIGN-UNSUPPORTED: A legend cannot be aligned this way on this chart {: #err-legend-align-unsupported }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r} asks for a legend `align` that cannot be honored: {reason}. Use `align: start` instead.
```

Fired when a `legend.position.align` of `center` (or a pie's `end`) cannot be honored: the chart is small multiples or has an endpoint-label rail (no single plot to align in), or its legend is larger than the plot.

### ERR-LEGEND-POSITION-UNSUPPORTED: Legend placement combination is not supported {: #err-legend-position-unsupported }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r} places its legend at `edge: {edge}`, `align: {align}`, `overlay: {overlay}`, which no placement supports. Supported placements: {supported}.
```

Fired when the resolved `legend.position` (edge, align, overlay) names a placement the renderer cannot draw.

### ERR-LINE-Y-NOT-NUMERIC: Line chart y column is not numeric {: #err-line-y-not-numeric }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r} (line): y column {y_field!r} is not numeric. Line charts always plot x as the dimension and y as the value; use a numeric column for y.
```

Fired when a line chart's `y:` column contains non-numeric data. Line charts always use y as the value axis; use a numeric column for y.

### ERR-LINK-SCHEME-UNANCHORED: Link template starts with data, so its scheme is unknown {: #err-link-scheme-unanchored }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Link {link!r} at {field_path} begins with a template. Start it with /, ?, # or https:// so data cannot choose the scheme.
```

Fired when a chart or footer link's literal text before its first `{{` template placeholder does not itself fix a safe scheme — the query row or variable value filling the template would then decide what scheme the browser navigates to. Start the link with a board path or a fixed https:// prefix instead.

### ERR-LINK-SCHEME-UNSAFE: Link uses a URL scheme dbt Charts does not allow {: #err-link-scheme-unsafe }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Link {link!r} at {field_path} uses scheme {scheme!r}. Use a board path (/, ./, ?, #) or http, https, mailto.
```

Fired when an authored link (chart link, table column link/header_link, or footer link) resolves to a URL scheme other than http, https, or mailto. A board path (starting with /, ./, ../, ?, or #) is always allowed; any other scheme — javascript:, data:, vbscript:, or an editor deeplink like vscode:// — is rejected so a link can never execute script or navigate somewhere unexpected.

### ERR-LINK-SCHEME-UNSAFE-AT-RENDER: A rendered link uses a disallowed URL scheme {: #err-link-scheme-unsafe-at-render }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Rendered link {href!r} uses scheme {scheme!r}. Allowed: board paths (/, ./, ?, #), http, https, mailto.
```

Fired when a link resolved at render time — a table cell/row link built from query row data, or a chart link whose scheme only becomes known after Vega renders it — uses a scheme other than http, https, or mailto. Compile-time validation (ERR-LINK-SCHEME-UNSAFE) cannot see this: the value only exists once the query has run, or once a chart-link sentinel prefix used to survive Vega's own sanitizer has been stripped. The affected chart renders an inline error instead of the unsafe link.

### ERR-LOG-SCALE-REQUIRES-POSITIVE-DATA: Log scale requires strictly positive data {: #err-log-scale-requires-positive-data }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r}: column {y_field!r} has a value <= 0, but axis_y.scale.type: log requires strictly positive data; a log domain is undefined at and below zero. Filter out the non-positive rows, or drop the log scale.
```

Fired when `axis_y.scale.type: log` is used but the y column contains a value ≤ 0. A log domain is undefined at and below zero. Filter out the non-positive rows, or drop the log scale.

### ERR-MAP-LOOKUP-KEY-MISMATCH: Map chart cannot join on mismatched key format {: #err-map-lookup-key-mismatch }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Map chart {chart_id!r} cannot join lookup field {lookup_field!r} to geo source {geo_source!r} on key {geo_key!r}: the geo source expects {expected_format} keys like {expected_samples}, but the query returned values like {query_samples}.
```

Fired when a map chart's lookup field values do not match the format expected by the geo source. Check that the lookup field uses the same key format (e.g. FIPS codes, ISO country codes) as the geo source.

### ERR-MIRROR-ENDPOINT-LABELS: axis_y.mirror cannot be combined with endpoint labels {: #err-mirror-endpoint-labels }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r}: axis_y.mirror is not supported together with endpoint labels; the endpoint-label rail occupies the opposite edge. Use one or the other on this chart.
```

Fired when a chart authors (or its theme sets) `style.axis_y.mirror` while its endpoint-label rail is also visible. Both want the opposite edge from the chart's primary y-axis; the mirrored scale and the label rail can't share it. Distinct from ERR-MULTIPLES-ENDPOINT-LABELS: this code fires when the chart has no `multiples:` at all, so `axis_y.mirror` is the field actually responsible for the collision; a `multiples:` grid's collision (even one that also happens to auto-derive a both-edge axis internally) is reported as ERR-MULTIPLES-ENDPOINT-LABELS instead, since `multiples:` is the field the author wrote.

### ERR-MIRROR-LAYERS: axis_y.mirror needs layers that share the base's y scale {: #err-mirror-layers }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r}: axis_y.mirror cannot reflect this chart's `layers:`. Mirror needs one shared y scale on a vertical chart: a layer that sets its own `axis_y` has a scale of its own, and a horizontal bar measures along x. Drop `style.axis_y.mirror`, the layer's `axis_y`, or the `layers:`.
```

Fired when a chart carries `layers:` while `style.axis_y.mirror` is on and the layers do not share one y scale: a layer sets its own `axis_y`, or the base is a horizontal bar, whose measure runs along x. Layers that share the base's y scale mirror normally. Silently skipping the mirror would be a wrong result that looks right, so it refuses. Reported at render rather than by `dct validate` because mirror is cascade-resolved: a theme layer can turn it on for a chart that never authored it.

### ERR-MIRROR-MULTI-SERIES: axis_y.mirror requires a single y field {: #err-mirror-multi-series }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r}: axis_y.mirror is not supported on multi-series charts (y = {y}); a mirrored axis restates one shared y-scale, and folded measures have no single scale to restate. Collapse `y:` to one field, or drop `style.axis_y.mirror`.
```

Fired when a chart carries a list-valued `y:` while `style.axis_y.mirror` is on. Mirror draws the same y-scale on both edges of a wide chart, which only means something when there is exactly one measure scale to draw. Reported at render rather than by `dct validate` because mirror is cascade-resolved: a theme layer can turn it on for a chart that never authored it, so the combination is not visible on the authored chart alone.

### ERR-MIRROR-UNMEASURABLE-ALIGN: axis_y.labels.align cannot be measured on the mirrored edge {: #err-mirror-unmeasurable-align }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r}: axis_y.labels.align: {align!r} would draw the mirrored {opposite}-edge labels across the axis into the plot, and the engine can only reserve a gutter for text it can measure. The mirrored labels come from an expression, a case transform, or have no numeric format. To right-align a percent ruler, use `axis_y.mirror.format` (for example `.0%`); otherwise omit `axis_y.labels.align`.
```

Fired when `style.axis_y.labels.align` is authored on a chart with `style.axis_y.mirror`, and the alignment would invade the plot on the mirrored edge while the label text cannot be measured to size a safe `labelPadding`. Text from `mirror.expr`, an authored `labels.expr`, an upper/lower `font.case`, or an axis without a numeric format is evaluated at paint time, so its width is unknown. `mirror.format` is measurable and supports alignment.

### ERR-MULTI-Y-COLOR-CONFLICT: Multi-y chart's color: must name a column {: #err-multi-y-color-conflict }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r} ({chart_type}): y: [...] folds measures into a color series, and color: {color_field!r} is bound to a gradient or conditional scale, which names no series to cross them with. Bind color: to a plain column (each of its values x each measure becomes a series) or drop it.
```

Fired when a bar, area, line, or scatter chart authors y: [a, b] together with a color: that is not a plain series column -- a gradient or a conditional scale. A column composes with the fold: the series become `<value> - <measure>` composites, one per dimension value per measure.

### ERR-MULTI-Y-LAYERS-CONFLICT: Multi-y chart cannot also have layers: {: #err-multi-y-layers-conflict }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r} ({chart_type}): y: [...] folds measures into a color series automatically -- overlay layers: are not supported with multi-y charts. Keep a single y field and overlay the other measures as layers: entries instead.
```

Fired when a bar, area, line, or scatter chart authors both y: [a, b] and layers: at the same time.

### ERR-MULTIPLES-ENDPOINT-LABELS: multiples cannot be combined with endpoint labels {: #err-multiples-endpoint-labels }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r}: multiples cannot be combined with endpoint labels; the endpoint-label rail names series for a single panel, and a faceted chart has no single panel for it to sit beside. Set style.endpoint_labels.visible: false on this chart to keep the small multiples, or remove multiples to keep the labels.
```

Fired when a chart authors `multiples:` while its endpoint-label rail is explicitly switched on. The rail names series for one panel; a faceted chart has no single panel for it to sit beside. The shipped default switches the rail off wherever `multiples:` is set (a legend above the panels names the series instead), so this fires only where the rail was asked for by name. Turn off `style.endpoint_labels.visible` to keep the small multiples, or remove `multiples:` to keep the labels.

### ERR-MULTIPLES-FIELD-NOT-FOUND: multiples partition field not found in the query result {: #err-multiples-field-not-found }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
multiples field(s) {fields} not found in the query result. Available columns: {available}.
```

Fired when `multiples.rows` or `multiples.columns` names a column that is not present in the chart's query result. Check for a typo, or add the column to the query.

### ERR-MULTIPLES-INDEPENDENT-SCALE-MIRROR: multiples with scale: independent cannot use a both-edge mirror axis {: #err-multiples-independent-scale-mirror }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r}: multiples with scale: independent cannot use a both-edge (mirror) y-axis: mirroring a shared scale to both edges is meaningless when each panel has its own scale. Use scale: shared, or set style.axis_y.mirror: false.
```

Fired when a chart authors `multiples: {scale: independent}` together with `style.axis_y.mirror` (bool true or an AxisMirrorStyle format/expr override). Mirroring reflects one shared scale to both edges; meaningless once every panel has its own independent scale. Use `scale: shared`, or turn mirror off.

### ERR-MULTIPLES-LAYER-PARTITION: multiples cannot be combined with an own-query layer that returns the partition field {: #err-multiples-layer-partition }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r}: multiples cannot be combined with an own-query overlay layer whose query returns the partition field(s) {fields}; Vega-Lite cannot split one inline layer dataset per panel. Remove the partition column(s) from the layer's query to repeat the layer in every panel, or drop multiples.
```

Fired when a chart authors both `multiples:` and a `layers:` entry with its own `query:` whose result includes the partition column(s). Vega-Lite's facet operator only partitions the root dataset, never a layer's own inline dataset, so per-panel layer data cannot be represented. A layer whose query does not return the partition column is unaffected; it repeats identically in every panel, which is correct for a global reference line.

### ERR-MULTIPLES-RESOLVED-WITHOUT-DATA: a faceted chart resolved without data is being rendered with real rows {: #err-multiples-resolved-without-data }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r}: multiples is set but this chart was resolved against no data (panel_axes is empty) and is now being rendered against real rows. Re-resolve the chart against its actual data before rendering.
```

Fired when a chart authors `multiples:`, was resolved with an empty query result (baking `panel_axes == ()`, the same N=1 state a non-faceted chart gets), and is then rendered against non-empty rows. Silently falling through would render the chart unfaceted instead of raising on data resolve never saw. Re-resolve the chart against its actual data before rendering.

### ERR-MULTIPLES-ROW-MISSING-PARTITION-FIELD: row is missing a multiples partition field entirely {: #err-multiples-row-missing-partition-field }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Row is missing the multiples partition field {field!r} entirely (it carries: {available}); every row must carry every partition field, even one whose value is null.
```

Fired when a chart is rendered against a row that does not carry a partition column at all, as distinct from carrying it with a null value (a legitimate panel `resolve()` may have baked). A ragged row silently defaulting the missing field to `None` could misroute into that legitimate null panel by accident, so this is checked and raised separately.

### ERR-MULTIPLES-ROW-OUTSIDE-PANEL-AXES: row's multiples value is not among the resolved panel_axes {: #err-multiples-row-outside-panel-axes }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Row's {field!r} value {value!r} is not among the resolved panel_axes values {allowed} for this chart's multiples partition.
```

Fired when a chart is rendered against rows whose partition column carries a value `resolve()` never saw: the row-truncated render path can only ever hold a subset of the axis values baked at resolve, never one the axes lack, so this firing means the chart is being rendered against data resolve never saw. Re-resolve the chart against its actual data before rendering.

### ERR-MULTIPLES-SELF-CROSSED: multiples.rows and multiples.columns name the same field {: #err-multiples-self-crossed }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
multiples.rows and multiples.columns both name {field!r}. Only the diagonal of the resulting grid can ever hold a row; the rest are structurally empty, whatever the data says.
```

Fired when `multiples.rows` and `multiples.columns` name the same column. Crossing a field with itself builds a panel grid where a row of data can only ever land on the diagonal (the row's value matches itself); every other cell in the grid is guaranteed empty. Name a different column for `rows` or `columns`, or drop one of them and keep a single-direction partition.

### ERR-MULTIPLES-SUPPORT-TABLE: multiples cannot be combined with a chart support_table {: #err-multiples-support-table }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r}: multiples is not supported together with a chart support_table; the attached table has no meaning per panel. Use one or the other on this chart.
```

Fired when a chart authors both `multiples:` and a `support_table:`. The attached table is a single per-chart element; once the chart is faceted into a small-multiples grid it has no per-panel meaning. Remove one or the other.

### ERR-MULTIPLES-VALUE-COLLISION: two distinct multiples values stringify to the same panel key {: #err-multiples-value-collision }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
multiples field {field!r}: values {previous!r} and {value!r} both stringify to {canonical!r}; rename one to disambiguate.
```

Fired when `multiples.rows` or `multiples.columns` names a column whose distinct values collide once canonicalized to a string panel key (e.g. the string `'1'` and the integer `1`). Merging them into one panel would silently combine two genuinely distinct groups. Rename one value so the two panel keys stay distinct.

### ERR-PALETTE-UNKNOWN: Palette name is not a theme palette role or a shipped palette {: #err-palette-unknown }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Unknown palette {name!r} (authored as {authored!r}) at {field_path}. Palette roles are theme-scoped, resolved only from a theme's `palettes:` block; this name is not a role the active theme binds, and not a shipped dbt charts palette.
```

Fired when an authored `palette:` string names neither a role in the theme's `palettes:` block (`category`, `sequence`) nor a shipped dbt charts palette (`editorial-10`). Roles are theme-scoped; board- and chart-level `style:` cannot author one, only a palette name. Checked in two places: once the theme cascade is complete (a theme's own `palettes:` binding), and once each board/chart is normalized (every other palette field); both are the first point a role name can be told apart from a typo at that scope.

### ERR-PERCENT-RANGE: Percent format received a 0-100-shaped value instead of a ratio {: #err-percent-range }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Value {value!r} passed to percent format {format_spec!r} looks 0-100-shaped, but percent formats expect a 0-1 ratio (0.182, not 18.2). To fix: divide by 100 in SQL so the value is a ratio, or switch to the `percent_number`/`percent_number_delta` formats if the value is already in the 0-100 scale (e.g. 18.2 means 18.2%).
```

Fired when a percent format receives a value that looks like it is already in the 0-100 scale rather than the 0-1 ratio scale that percent formats expect. Divide by 100 in SQL so the value is a ratio, or switch to a `percent_number` format.

### ERR-PIE-NEGATIVE-THETA: Pie chart theta column contains a negative value {: #err-pie-negative-theta }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Pie chart {chart_id!r} has {negative_rows} row(s) with a negative value in its theta column {theta_field!r}. A pie slice can't represent a negative share of the whole. Filter or transform the value in the query.
```

Fired when the column bound to a pie or donut chart's `theta` channel contains a negative value. A pie's slices are angles summing to a full circle; a negative theta has no geometric meaning, so it must be filtered or transformed in the query.

### ERR-PIE-NULL-THETA: Pie chart theta column contains NULL values {: #err-pie-null-theta }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Pie chart {chart_id!r} has {null_rows} row(s) with a NULL value in its theta column {theta_field!r}. A pie slice can't represent a missing value. Filter the null rows or give them a real number in the query (e.g. COALESCE({theta_field}, 0)).
```

Fired when the column bound to a pie or donut chart's `theta` channel contains NULL values. A pie slice's angle comes directly from theta, so a NULL cannot be drawn or labeled; fix the grain in the query instead of letting the renderer guess a value.

### ERR-PIE-TOTAL-WITHOUT-HOLE: A pie total needs a donut hole to sit in {: #err-pie-total-without-hole }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
{field_path} is set, but this pie has no hole, so the total would print over the wedges. Set `style.inner_radius` above 0 to make it a donut, or remove `total:`.
```

`total:` draws the sum of the slice values at the center of the chart, which is the hole of a donut. A solid pie has no hole, so the text would overlap the wedges. Set `style.inner_radius` above 0, use `type: donut`, or remove `total:` (`total.visible: false` is accepted on a solid pie).

### ERR-REGIONAL-NESTED-MISMATCH: A nested board's regional differs from its root board's {: #err-regional-nested-mismatch }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
{board} sets regional {authored}, but the board it is nested in uses {root}. A board and everything nested in it write numbers and dates one way; remove the nested `regional:` or make it match.
```

Fired when a nested board (inline or imported) authors a `regional:` number locale, time locale or currency that differs from the root board's. One page reads numbers and dates in one locale and one currency, so nested boards take the root's `regional:`. Set it on the root board or in `charts/meta.yml`.

### ERR-RESOLVED-PIE-DATA-MISMATCH: Resolved pie rows do not match its recording {: #err-resolved-pie-data-mismatch }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Resolved pie {chart_id!r} was finalized from different query rows. Resolve the chart and record its data in the same emission.
```

Fired when replay data differs from the rows used to finalize pie label and attached-table policy. Resolved board artifacts and recordings must come from the same emission.

### ERR-RESOLVED-PIE-WIDTH-MISMATCH: Resolved pie width does not match its render slot {: #err-resolved-pie-width-mismatch }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Resolved pie {chart_id!r} was finalized at width {resolved_width}, not {render_width}. Resolve the chart again for the target slot.
```

Fired when a resolved pie is rendered at a different width from the one used to finalize its label and attached-table layout. Resolve the chart again with the actual target width before rendering.

### ERR-SCALE-DOMAIN-REQUIRES-CONTINUOUS-X: axis_x.scale.domain requires a continuous x-axis scale {: #err-scale-domain-requires-continuous-x }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r}: axis_x.scale.domain is set, but the x-axis resolved to a {vl_type!r} (categorical) scale, not a continuous one. An explicit [low, high] domain only extends a continuous scale: on a categorical scale Vega-Lite reads it as exactly two category values, collapsing every mark onto the first one. If the x field is a date, add `axis_x.scale.type: temporal` to force a continuous temporal scale.
```

Fired when `axis_x.scale.domain` is set but the x-axis resolves to a categorical (ordinal/nominal) scale rather than a continuous one. An explicit [low, high] domain only extends a continuous scale; on a categorical scale Vega-Lite reads it as exactly two category values. Add `axis_x.scale.type: temporal` to force a continuous temporal scale if needed.

### ERR-SCATTER-MULTI-Y-NOT-NUMERIC: Scatter chart multi-metric y column is not numeric {: #err-scatter-multi-y-not-numeric }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r} (scatter): y: [...] column {y_field!r} is not numeric. A single y: column may be categorical (a dot plot), but every measure in a y: [...] list is folded onto one numeric axis; use numeric columns.
```

Fired when a scatter chart's y: [a, b] list contains a non-numeric column. A single y: column may be categorical (a dot plot), but a list y: folds every measure onto one shared numeric axis, so each measure must be numeric.

### ERR-SORT-FIELD-NOT-FOUND: sort.by column not found in the query result {: #err-sort-field-not-found }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
sort.by column {field!r} not found in the query result. Available columns: {available}.
```

Fired when `sort.by` names a column that is not present on every row of the chart's query result. Without it the chart would render in natural order while claiming to be sorted. Check for a typo, or add the column to the query.

### ERR-SPAN-MIDDLE-ALIGNED-LABELS: labels.position: middle_aligned is not meaningful on a bar with y_start {: #err-span-middle-aligned-labels }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
labels.position 'middle_aligned' lines every label up at one height measured from zero, which a bar with y_start does not start from. Use 'middle' to center each label between its bar's two ends.
```

Fired when `labels.position: middle_aligned` is set on a bar with `y_start`. That position places every label at one common height measured from zero; a bar that starts elsewhere has no such height. Use `middle`.

### ERR-SPARK-BAR-VALUE-FIELD-NOT-FOUND: spark_bar x names a column not in the query result {: #err-spark-bar-value-field-not-found }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
spark_bar chart {chart_id!r}: x field {field!r} names a column not present in its data. Available columns: {available}. On spark_bar, x is the bar magnitude and must name a numeric column from the query.
```

Fired when a spark_bar chart's `x` names a column that is not in the query result at all; usually a typo or a column renamed in the query. Distinct from ERR-SPARK-BAR-VALUE-NOT-NUMERIC, which fires when the column exists but holds no usable numbers: that one's fix is to swap `x` and `y`, which would be the wrong advice for a name that simply isn't there.

### ERR-SPARK-BAR-VALUE-NOT-NUMERIC: spark_bar value field is not numeric {: #err-spark-bar-value-not-numeric }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
spark_bar chart {chart_id!r}: x field {field!r} is not usable as the magnitude: {reason}. spark_bar reverses the usual convention: x is the magnitude (the number) and y is the label (the text), the opposite of every other chart family. Set x to a numeric column and y to the text column.
```

Fired when a spark_bar chart's x field (the magnitude channel) is missing, holds no numeric values, or holds a non-numeric value in one of the rows being rendered. spark_bar reverses the x/y convention used by every other chart family: x is the magnitude, y is the label. This usually means x and y were authored in the cartesian order (swap them), or that x was left unset with no numeric column to auto-detect.

### ERR-STACKED-MIDDLE-ALIGNED-LABELS: labels.position: middle_aligned is not meaningful on a stacked bar {: #err-stacked-middle-aligned-labels }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
labels.position 'middle_aligned' aligns every bar's label to one shared height, which has no meaning for the segments of a stacked bar. Use 'middle' to center each label in its own segment, or 'top'/'bottom' to pin it to a segment edge.
```

Fired when `labels.position: middle_aligned` is set on a stacked bar. `middle_aligned` places every label at a single common height (the mean bar height, halved) so a row of labels reads as one line, a whole-bar idea with no per-segment reading. Stacked segments each need their own center: use `middle`.

### ERR-STEP-BAND-MULTI-SERIES: Step curve with a multi-series color split on a band x-axis {: #err-step-band-multi-series }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
curve: step does not support a multi-series color encoding on a band x-axis (chart '{chart_id}'). It is a single-series target-overlay idiom; drop the color split or pick a different curve.
```

Fired when `curve: step` on a band x-axis is combined with a data-driven color split. Step is a single-series target-overlay idiom there; drop the color split or choose another curve.

### ERR-STYLE-CSS-VALUE-INVALID: A style value for markdown text is not valid CSS {: #err-style-css-value-invalid }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Invalid style value for markdown text: {detail}.
```

Fired when a font color, weight, style or decoration that styles markdown text (prose, callouts, table cells) contains a character that could close the CSS declaration or open a new rule: one of `<>;{}"'\*` or a control character. Use a plain CSS value such as a hex color, `oklch(...)`, `var(--x)`, or `bold`.

### ERR-SUPPORT-TABLE-INDEPENDENT-X: support_table strip on layers with independent x scales {: #err-support-table-independent-x }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
support_table strip cannot anchor to a layer spec with resolve.scale.x == 'independent'; the layers have per-dataset x scales and the strip cannot anchor coherently.
```

Fired when a support_table strip is attached to layers with independent x scales.

### ERR-SUPPORT-TABLE-LABEL-IGNORED: support_table per_series label: names nothing in this layout {: #err-support-table-label-ignored }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
{message}
```

Fired when a `per_series:` entry without `by_measure: true` sets `label:` on a chart whose strip rows (vertical bar, line, area) or per-series columns (stacked horizontal bar) are named by the color field's series values, so the label would be silently dropped. A horizontal grouped bar's single per_series column still takes its header from `label:`. Remove the label; series names come from the color field and legend.

### ERR-SUPPORT-TABLE-NO-X-ENCODING: support_table attachment has no x-encoding {: #err-support-table-no-x-encoding }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
support_table attachment requires an x-encoding on the chart spec or its layers; none found.
```

Fired when a support_table strip cannot find an x-encoding on the chart or any layer.

### ERR-SUPPORT-TABLE-NO-Y-ENCODING: support_table column attachment has no category y-encoding {: #err-support-table-no-y-encoding }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
support_table column attachment requires a category y-encoding on the chart spec; none found.
```

Fired when a support_table column block cannot find a category y-encoding.

### ERR-SUPPORT-TABLE-POSITION-INVALID: style.support_table.position is invalid for the chart's orientation {: #err-support-table-position-invalid }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
{message}
```

Fired when `style.support_table.position` names a side the chart's own category-axis orientation can't place. A horizontal category axis (vertical bar, line, area) only accepts `top`/`bottom`; a vertical one (a horizontal bar) only accepts `left`/`right`. The message carries the specific value and orientation.

### ERR-SUPPORT-TABLE-X-FIELD-DISAGREE: support_table strip on layers with disagreeing x fields {: #err-support-table-x-field-disagree }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
support_table strip cannot anchor to a layer spec whose per-layer x-encodings disagree on field; lift x to chart level or remove support_table.
```

Fired when layers carry different x fields under a support_table strip.

### ERR-TABLE-FORMAT-KIND-MISMATCH: a table column's format spec does not match its cell values {: #err-table-format-kind-mismatch }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
table column format {fmt!r} does not match its cell values. {remedy}
```

Fired when a table column's `format:` spec is the wrong kind for the values it formats: a strftime-style time spec (a predefined name like `time_short`, or an explicit string containing a `%`-prefixed directive such as `%B` or `%W`) applied to a numeric value, or a d3 numeric spec applied to a date/datetime value. `format:` is kind-agnostic at compile time, so `dct validate` accepts either mismatch; this is caught per cell at render time instead, once the actual value kind is known.

### ERR-TABLE-LINK-FILTER-UNKNOWN: a table link template uses an unknown filter {: #err-table-link-filter-unknown }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Unknown link template filter: {filter_name!r}. Only 'urlencode' is supported.
```

Fired when a table column's `link:` template pipes a value through a filter other than `urlencode`, e.g. `{{ id | shout }}`.

### ERR-TABLE-PIVOT-DIMENSIONS-AMBIGUOUS: a pivot declares neither rows nor values {: #err-table-pivot-dimensions-ambiguous }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
pivot: declare at least one of `rows` or `values`; with both omitted the row and measure dimensions are ambiguous.
```

Fired when a table pivot gives only `columns`. The remaining fields cannot be split into row dimensions and measures without guessing, so one of `rows` or `values` is required.

### ERR-TABLE-PIVOT-DUPLICATE-CELL: a pivot cell receives more than one value {: #err-table-pivot-duplicate-cell }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
pivot_table_data: duplicate value for row ({row}) and column {pivot_column}, measure {measure!r}; move the extra field onto rows or columns.
```

Fired when more than one query row maps to the same pivot cell (same row key, column key, and measure). The pivot never aggregates, so the query must return one row per cell or the extra field must move onto `rows` or `columns`.

### ERR-TABLE-PIVOT-FIELD-NOT-FOUND: a pivot field is not a column of the query result {: #err-table-pivot-field-not-found }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
{channel} {field!r} not in data rows; observed keys: {observed}
```

Fired when a table pivot's `columns`, `values`, or `rows` names a field that the query does not return. `channel` says which channel: pivot.column, pivot.value, or pivot.row.

### ERR-TABLE-PIVOT-NO-MEASURES: a pivot has no measure columns {: #err-table-pivot-no-measures }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
pivot: no measure columns; `values` resolved to empty. Declare at least one measure field. Observed keys: {observed}
```

Fired when a table pivot ends up with no measure to place in the cells, for example an explicit `values: []`.

### ERR-TABLE-PIVOT-ROW-ROLE-CONFLICT: pivoted rows merge with conflicting roles {: #err-table-pivot-row-role-conflict }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
pivot_table_data: conflicting row roles for row ({row}): {stored_role!r} vs {this_role!r}. A merged pivot row must resolve to a single role.
```

Fired when query rows that pivot into the same wide row resolve to different `row.role` values. Keeping the first would hide the disagreement.

### ERR-TABLE-PIVOT-ROW-ROLE-LITERAL: a pivot row.role is a role name, not a column {: #err-table-pivot-row-role-literal }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
pivot.row_role {row_role!r} is a literal role, not a query column; under a pivot row.role must name the query column that carries the per-row role. Observed keys: {observed}
```

Fired when a pivoted table's `row.role` is a literal role such as `total` instead of the name of the column that carries each row's role. A literal would give every row the same role and silently drop the reshape.

### ERR-TABLE-SPANNER-NOT-ADJACENT: a table spanner's columns are not adjacent {: #err-table-spanner-not-adjacent }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
table {chart_id!r}: spanner {label!r} columns {spanner_columns} are not adjacent among the visible columns {visible_columns}. Reorder the query's SELECT; spanners never reorder columns.
```

Fired when the columns of a table spanner are not next to each other in the visible column order. Column order belongs to the query, so a spanner never reorders anything; reorder the SELECT or hide the columns between them.

### ERR-TABLE-SPANNER-UNKNOWN-COLUMN: a table spanner names a column not in the query result {: #err-table-spanner-unknown-column }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
table {chart_id!r}: spanner {label!r} names {unknown}, which are not query columns (columns: {columns}).
```

Fired when a table `spanners:` entry lists a column that the query does not return; usually a typo or a column renamed in the query.

### ERR-TABLE-SWATCH-NOT-COLOR: a swatch column holds a value that is not a color {: #err-table-swatch-not-color }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
table {chart_id!r}: column {swatch_column!r} declares swatch: true but row {row_index} value {value!r} is not a CSS color. Swatch cells must be hex (e.g. '#3164a3') or 'transparent'. Either point swatch: true at a different column, or fix the data.
```

Fired when a table column declared `swatch: true` has a cell that is empty or not a CSS color. The author either pointed `swatch` at the wrong column or the query carries the wrong content; rendering it as text would hide the mistake.

### ERR-TABLE-TEMPORAL-FORMAT-INVALID: a table cell's date or time could not be formatted {: #err-table-temporal-format-invalid }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
table cell {cell!r} could not be formatted with spec {spec!r}: {reason}
```

Fired when a table cell holds a date or time that cannot be parsed (for example an out-of-range hour in an ISO timestamp), or when the column's resolved date/time format spec is itself invalid.

### ERR-TABLE-TRANSPOSE-ROW-COUNT: a transposed table needs exactly one row {: #err-table-transpose-row-count }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
style.table.transpose requires exactly one data row; got {row_count}. Remove transpose: true or change the query.
```

Fired when `style.table.transpose` is set and the query returns zero or several rows. Transposing turns the single result row into a column of label and value pairs.

### ERR-TABLE-TRANSPOSE-VISIBLE-UNKNOWN-COLUMN: a transposed table hides a column the query does not return {: #err-table-transpose-visible-unknown-column }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
style.table.transpose: style.columns sets `visible:` on {unaddressed}, which match no query column. The transposable columns are {available}. Check for a typo.
```

Fired when a transposed table's `style.columns` sets `visible:` on a name that is not a query column. Hiding it would silently do nothing.

### ERR-TABLE-VISIBLE-UNKNOWN-COLUMN: a table hides a column that is not rendered {: #err-table-visible-unknown-column }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
table {chart_id!r}: style.columns sets `visible:` on {unaddressed}, which match no rendered column. This table's addressable columns are {addressable}. Check for a typo, or key the entry by the name the rendered column actually carries (a pivot's measure name, or a bare pivoted value).
```

Fired when a table's `style.columns` sets `visible: false` on a name that is not a rendered column, so the entry could never take effect. Under a pivot the rendered names are the pivot's measure names or bare pivoted values.

### ERR-TICKS-COUNT-REQUIRES-NON-LOG-SCALE: ticks.count is not supported with log scale {: #err-ticks-count-requires-non-log-scale }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Chart {chart_id!r}: axis_y.ticks.count is not supported with scale.type: log: a target tick count on a log axis is nonsense; Vega-Lite computes log-decade ticks natively. Remove ticks.count.
```

Fired when `axis_y.ticks.count` is combined with `axis_y.scale.type: log`. A target tick count on a log axis is meaningless because Vega-Lite computes log-decade ticks natively. Remove `ticks.count`.

### ERR-TICKS-INTERVAL-MEASURE-AXIS: ticks.time_unit is not supported on the measure axis {: #err-ticks-interval-measure-axis }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
style.axis_y.ticks.time_unit/step is not supported: the measure axis (axis_y) is never temporal in dbt charts' cartesian model, and its tick ladder is computed from ticks.count. Use axis_y.ticks.count here; ticks.time_unit/step apply to axis_x.
```

Fired when `style.axis_y.ticks.time_unit` or `step` is set. The measure axis (axis_y) is never temporal in dbt charts' cartesian model, and its tick ladder is computed from `ticks.count`. Use `axis_y.ticks.count` here; `ticks.time_unit/step` apply to `axis_x`.

### ERR-TICKS-INTERVAL-NOT-TEMPORAL: ticks.time_unit requires a continuous temporal x-axis {: #err-ticks-interval-not-temporal }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
style.axis_x.ticks.time_unit requires a continuous temporal x-axis, but {field!r} resolved to a {vl_type!r} scale. Force a continuous scale with axis_x.type: temporal (or axis_x.time_unit: none), or remove ticks.time_unit.
```

Fired when `style.axis_x.ticks.time_unit` is set but the x-axis does not resolve to a continuous temporal scale. Force a continuous scale with `axis_x.type: temporal` (or `axis_x.time_unit: none`), or remove `ticks.time_unit`.

### ERR-TICKS-STEP-NOT-QUANTITATIVE: a bare ticks.step requires a quantitative x-axis {: #err-ticks-step-not-quantitative }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
style.axis_x.ticks.step without ticks.time_unit is a numeric tick interval, but {field!r} resolved to a {vl_type!r} scale. {remedy}
```

Fired when `style.axis_x.ticks.step` is set without `ticks.time_unit` on an x-axis that does not resolve to a quantitative scale. A bare `step` is the numeric cadence lever (it emits Vega-Lite's `tickMinStep`) and only a quantitative scale has a numeric tick interval. On a temporal axis, author `ticks.time_unit` alongside `step` to name a calendar cadence. On a discrete axis (ordinal or nominal) there is no tick interval to set; remove `ticks.step`. A horizontal bar is the case worth calling out: its `axis_x` is the categorical axis and its measure is `axis_y`, so `orientation: vertical` is usually what the author wanted.

### ERR-TICKS-TIME-UNIT-NO-CADENCE: Tick time unit without a step-anchored cadence {: #err-ticks-time-unit-no-cadence }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
ticks.time_unit: {time_unit!r} has no step-anchored cadence -- only a calendar-bucketing grain ({grains}) names a VL tick interval.
```

Fired when `ticks.time_unit` names a grain that cannot anchor a temporal tick interval.

### ERR-TIME-FORMAT-NOT-TEMPORAL: a time format needs date values {: #err-time-format-not-temporal }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
style.{setting} ({fmt!r}) is a date pattern, but {field!r} holds {found}, not dates. {remedy}
```

Fired when a d3 time format (`%b %Y`) is authored on an axis whose field holds values that are not ISO dates (`2024-01`, `2024-01-31`) or date objects: category names, numbers, or non-ISO bucket labels such as `Q1 2024`. Vega would paint `Invalid Date` on every tick. A chart written with the retired `style.time_format` migrates onto `style.axis_x.labels.format` whatever x holds, so this is where a board whose x was never a date is told.

### ERR-UNKNOWN-CHART: Chart id is not on the board {: #err-unknown-chart }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
No chart {chart!r} on this board. Available charts: {available}.
```

Fired when a caller addresses one chart by board path + chart id (`dct render BOARD --chart ID`, `dct describe BOARD --chart ID`) and the board declares no chart with that id.

### ERR-URL-VALUE-NOT-ABSOLUTE: a `url` column holds a value that is not an absolute http(s) URL {: #err-url-value-not-absolute }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
{where} is formatted `url`, but row value {value!r} is not an absolute http(s) URL.
```

Fired when a column formatted `url` holds a value without an `http://` or `https://` scheme, such as `www.example.com`. A scheme-less value would link to a board-relative path and land on the wrong page, so the render stops instead. Fix the value in the query (for example `'https://' || host`), or drop `format: url`.

### ERR-VEGA-LITE-UNSUPPORTED-TYPE: Chart type does not render to a Vega-Lite spec {: #err-vega-lite-unsupported-type }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Chart type {chart_type!r} does not render to a Vega-Lite spec.
```

Fired when a chart type is asked to render a Vega-Lite spec but does not support that output format. Use a Vega-Lite-compatible chart type or choose a different output format.

### ERR-WIDE-MEASURE-NAME-CONTAINS-SEPARATOR: Wide measure name contains the dimension composite separator {: #err-wide-measure-name-contains-separator }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Chart authors y: [...] with color: as a dimension, and measure column {measure!r} contains the {separator!r} composite separator, so the composite series name cannot be split back into a dimension value and a measure. Rename the measure column, or alias it in the query.
```

A wide chart authoring a list of y: measures can also author color: as a dimension the measures cross with. Fires when one of the measure column names itself contains the separator the `<dimension value> - <measure>` composite string uses. The composite cannot be split back apart unambiguously in that case, so the measure column must be renamed, or aliased in the query, to avoid the separator.

## errors


### ERR-BOARD-ARTIFACT-INVALID: Resolved-board artifact does not match the expected schema {: #err-board-artifact-invalid }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Board artifact is invalid: {detail}. It may have been produced by an incompatible dct version, hand-edited, or truncated. Re-emit it with `dct artifact emit`.
```

Fired when a resolved-board artifact fails to validate against `ResolvedBoard` while loading it for replay. The artifact is the published, versioned contract a resolved board serializes to; this means the file is not a valid instance of that contract.

### ERR-BOARD-RECORDING-INVALID: Board recording sidecar does not match the expected schema {: #err-board-recording-invalid }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Board recording is invalid: {detail}. It may have been produced by an incompatible dct version, hand-edited, or truncated. Re-emit it with `dct artifact emit`.
```

Fired when a board recording sidecar fails to validate against `BoardRecording` while loading it for replay.

### ERR-BOARD-RECORDING-MISMATCH: Board recording does not match the artifact it was replayed against {: #err-board-recording-mismatch }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Board recording does not match this artifact: {detail} The artifact and its recording must come from the same `dct artifact emit` run.
```

Fired when replaying a resolved-board artifact against a recording that either lacks rows for one of the artifact's queries, or recorded them under different variable values. Both mean the artifact and recording came from different emits (or a truncated one); replaying anyway would render an empty or wrong chart that looks like real data.

### ERR-DUPLICATE-CHART-ID: Two charts share an id across nested boards {: #err-duplicate-chart-id }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Two charts share the id {chart_id!r} across nested boards, which the flat {format!r} format cannot represent without dropping one. Rename one of them, or use --format json, which keeps the layout nesting.
```

Chart ids are unique within a board but not across a board tree: two imported partials, including the same partial imported twice, can declare the same id. The flat output formats key charts by id, so a collision would silently drop every chart but the last. Rename the colliding chart, or render with a format that preserves the layout.

### ERR-EMITTER-NOT-FOUND: No emitter registered for the resolved chart type {: #err-emitter-not-found }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
No emitter registered for resolved chart type {resolved_type!r}. This indicates an engine bug; the normalizer should have rejected this chart before it reached render.
```

Fired when the render engine cannot find an emitter for the resolved chart type. This indicates an engine bug; the normalizer should have rejected this chart before it reached render.

### ERR-EMPTY-YAML-DOCUMENT: YAML document is empty {: #err-empty-yaml-document }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Empty YAML document: {path}.
```

Fired when a board file's content is empty, contains only comments, or parses to a null/blank YAML document. A genuinely empty board file needs at least a minimal board mapping, or should be removed. A `dct init` scaffold's `meta.yml`/`meta.yaml` given directly to a verb that expects a board is a different case: don't add a mapping or delete it. The defaults file is meant to stay empty or comment-only. Pass a real board file to the verb instead.

### ERR-FILE-NOT-FOUND: File not found {: #err-file-not-found }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
File not found: {path}
```

Fired when a file path given to a dbt charts verb does not exist on the filesystem. Check for typos in the path and ensure the file exists.

### ERR-FORMAT-CONVERSION-FAILED: Format conversion failed {: #err-format-conversion-failed }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
{format!r} export failed while converting the rendered board ({detail}). Try exporting {alt_formats} instead, or split the board into smaller boards.
```

Fired when the vl-convert-python converter raises while turning a rendered board into PNG or PDF bytes. On PDF exports, the most common permanent cause is the PDF format's own 28-level graphics-state nesting limit: a sufficiently large or deeply nested board can exceed it. Try a different export format, or split the board into smaller boards. The underlying converter message is preserved in the diagnostic detail.

### ERR-FORMAT-CONVERTER-UNAVAILABLE: Format conversion library is not installed {: #err-format-converter-unavailable }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
{format!r} rendering requires vl-convert-python. Install it with: pip install vl-convert-python
```

Fired when a PNG or PDF export (or any render path that needs vl-convert-python to turn a Vega-Lite spec into SVG/PNG/PDF) runs in an environment where vl-convert-python is not installed. Install it: `pip install vl-convert-python`.

### ERR-FORMAT-UNSUPPORTED: Unknown render format {: #err-format-unsupported }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Unknown format: {format!r}
```

Fired when a render verb is called with an output format that is not supported. Check the supported formats in the CLI reference.

### ERR-IGNORE-ERROR-CODE: --ignore-warning names an error code {: #err-ignore-error-code }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
cannot ignore {code!r}: it is an error code, not a warning code
```

Fired when `dct render --ignore-warning` names an error code. Only warnings can be suppressed; fix the board to clear an error.

### ERR-INTERNAL: Internal error {: #err-internal }

- **Level:** error
- **Domain:** unknown
- **Suppressible:** no

**Message template:**

```
{message}
```

Fired when an unclassified internal failure occurs that does not map to a more specific error code. Check the full traceback for details. If this appears in normal usage, file a bug report.

### ERR-NUMERAL-EXPR-EMPTY-SPEC: Empty format spec cannot build a numeral Vega expression {: #err-numeral-expr-empty-spec }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
numeral_vega_expr() requires a non-empty format_spec. format_d3 treats an empty spec as a distinct 'no d3 formatting' path (the bare Python value) that a Vega expression cannot reproduce byte-for-byte.
```

Fired when numeral_vega_expr() is called with an empty format_spec. format_d3 short-circuits an empty spec to the bare Python value, bypassing d3 entirely: a Vega expression cannot reproduce that byte-for-byte (Python and JS do not stringify numbers identically), so building the expression is rejected rather than silently diverging. This indicates an engine bug: callers should always resolve a concrete d3 spec before reaching this emitter.

### ERR-PATH-OUTSIDE-PROJECT: Board path is outside the project {: #err-path-outside-project }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Board path {path} is outside the project root.
```

Fired when a board path given to a dbt charts verb resolves outside the project root. Pass a path to a board inside the project, or run the verb from the project that owns the board.

### ERR-STARTUP-FAILED: Server failed to start {: #err-startup-failed }

- **Level:** error
- **Domain:** serve
- **Suppressible:** no

**Message template:**

```
Server failed to start: {detail}.
```

Fired when the uvicorn server process fails to start. The detail carries the inner error message from uvicorn.

### ERR-UNKNOWN-WARNING-CODE: --ignore-warning names an unregistered code {: #err-unknown-warning-code }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
unknown warning code: {code!r}
```

Fired when `dct render --ignore-warning` names a code that is not a registered warning code: usually a typo or a stale suppression. Check the code against the warning reference.

### ERR-YAML-SYNTAX: YAML syntax error {: #err-yaml-syntax }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Invalid YAML syntax in {source}{where}: {problem}{quoted_line}
```

**Fix:** Fix the line quoted above. The usual cause is a string that contains a colon followed by a space, or starts with a special character (`*`, `&`, `!`, `%`, `@`, `[`, `{`): wrap the whole value in quotes, for example `title: "Ten largest occupations in 1950: rank and workers"`.

Fired when a board file, or a file it `extends:`, is not valid YAML. The message names the file, the line and column, and the offending line. The common authored mistake is an unquoted colon inside a title or note, such as `title: Largest in 1950: rank`, which YAML reads as a nested mapping; another is a flow sequence holding an unquoted `[` (`palette: [category[2]]`; quote it as `palette: ["category[2]"]`). For the colon the rest of the report comes from a copy of the file with the line quoted (the file is not changed and the board still does not render), so the schema and query errors appear in the same pass; any other syntax error is the only one reported until it is fixed.

## layout


### ERR-NO-LAYOUT: Board defines charts but has no layout {: #err-no-layout }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Board defines charts ({charts}) but no layout: would render with no visible charts. Add a `rows:`/`cols:`/`grid:`/`tabs:` block that references them.
```

Fired when a board defines charts but no layout block (rows/cols/grid/tabs). Without a layout, the board would render with no visible charts. Add a layout block that references the charts.

### ERR-TAB-DEFAULT-UNKNOWN: tabs.default names no tab {: #err-tab-default-unknown }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
`tabs.default: {default}` slugs to {slug!r}, which is not a tab on this board (tabs: {slugs}).
```

Fired when the `default:` of a `tabs:` layout matches no tab title. It is compared by slug: the title lowercased with spaces replaced by underscores.

### ERR-TAB-UNKNOWN: Unknown tab selected {: #err-tab-unknown }

- **Level:** error
- **Domain:** render
- **Suppressible:** no

**Message template:**

```
Tab variable {variable!r} is {value!r}, which is not a tab on this board (tabs: {slugs}).
```

Fired when a render selects a tab that is not on the board, through a `--var`, a URL parameter, or an API variable named by the tabs `id:`. A tab is selected by slug: its title lowercased with spaces replaced by underscores.

## queries


### ERR-ADAPTER-DUCKDB-CONFIG-APPLY-FAILED: DuckDB source config could not be applied to the connection {: #err-adapter-duckdb-config-apply-failed }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
DuckDB source config's {field!r} could not be applied: {reason}.
```

Fired when the physical DuckDB connection opened successfully but a post-connect step for the source's `extensions`, `settings`, `secrets`, or `attach` config failed: a missing extension, an unrecognized setting, a malformed secret, or an attach target that cannot be opened. Unlike ERR-WAREHOUSE-CONNECTION, the connection is live and SQL has already been sent. `{field}` names which config section raised it, and `{reason}` is DuckDB's own error text unchanged (not a classified summary), so an actionable hint like "Did you mean: "threads"" reaches the author.

### ERR-ADAPTER-DUCKDB-CONFIG-INVALID: DuckDB source config could not be turned into SQL {: #err-adapter-duckdb-config-invalid }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
DuckDB source config's {field!r} is invalid: {reason}. Fix this in the source config before it can connect.
```

Fired before any SQL is sent, while turning a DuckDB source's `extensions`/`settings`/`secrets`/`attach` config into the SQL statements that apply it: a bad identifier (a key or name that is not a bare `[A-Za-z_][A-Za-z0-9_]*` token, so it cannot be safely spliced into SET/ATTACH/CREATE SECRET), a secret missing its required `type`, or an `attach` entry that sets the same option through both a direct field (`type`/`secret`/`read_only`) and `options`. `{field}` names the config key that failed; fix it in the source config.

### ERR-ADAPTER-NOT-INSTALLED: Warehouse adapter is not installed {: #err-adapter-not-installed }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
dbt Charts needs the {package} adapter to query {adapter_type!r} sources, and it is not installed in this Python environment. Install it with: {install}
```

Fired when a source needs a dbt adapter package that is not installed. It applies to a direct warehouse source in `dbt_charts.yml` and to a `type: dbt_profile` source whose profiles.yml target names the warehouse. Each warehouse adapter ships as a dbt Charts extra, so the fix is to install the extra into the same environment `dct` runs from, e.g. `uv tool install "dbt-charts[snowflake]"` for a uv tool install, or `pip install "dbt-charts[snowflake]"` for a pip/venv install. The message names the command that matches how this dbt Charts was installed. Raised before any connection is attempted.

### ERR-ADAPTER-RELATIVE-PATH-NO-DATA-DIR: Relative source path needs a data directory to resolve against {: #err-adapter-relative-path-no-data-dir }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
Relative {adapter} path {path!r} requires a data_dir to resolve against; none was configured for this adapter. Use an absolute path or configure a data directory.
```

Fired when a file-backed source (DuckDB, SQLite) declares a relative `path:` but the adapter has no data directory to resolve it against. Resolving against the process working directory would make the source depend on where `dct` was invoked from, so dbt charts refuses. Use an absolute path or configure a data directory for the project.

### ERR-ADAPTER-UNSUPPORTED-DUCKDB-FIELD: DuckDB source field is not supported by the in-process adapter {: #err-adapter-unsupported-duckdb-field }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
DuckDB source config sets {field!r}. The in-process DuckDB adapter does not support this field; remove it from the source config.
```

Fired when a `dbt_profile` source expands to a duckdb target carrying `plugins`, `filesystems`, `remote`, or `use_credential_provider` and the in-process DuckDBAdapter executes it. A directly authored duckdb source is rejected at parse time instead. These fields need dbt-duckdb's own connection lifecycle (plugin hooks, fsspec registration, remote transport) that the in-process adapter does not implement; silently ignoring them would connect with different semantics than authored. There is no supported way to run this field through dbt charts today. Remove it from the source config or `profiles.yml` target.

### ERR-BINDER-TYPE-MISMATCH: Warehouse rejected the query due to a type mismatch {: #err-binder-type-mismatch }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
Warehouse rejected the query due to a type mismatch: {detail}. Add explicit type casts to resolve ambiguity.
```

Fired when the warehouse reports a type mismatch during query binding. Add explicit type casts to resolve the ambiguity.

### ERR-BINDER-UNKNOWN-COLUMN: Warehouse rejected an unknown column reference {: #err-binder-unknown-column }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
Warehouse could not resolve a column reference: {detail}. Check that all referenced columns exist in the source.
```

Fired when the warehouse reports that a column reference could not be resolved during query binding. Check that all referenced columns exist in the source.

### ERR-BINDER-UNKNOWN-RELATION: Warehouse reports a table or view does not exist {: #err-binder-unknown-relation }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
Warehouse could not find a table or view: {detail}. Check that the relation exists and the connection can read it.
```

Fired when the warehouse reports that a table, view or schema the query names does not exist or is not visible to the connection. For a ref() or source() the relation may have moved since the dbt manifest was built.

### ERR-CACHE-FILE-UNAVAILABLE: The query-result cache file could not be opened {: #err-cache-file-unavailable }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
Could not open the query-result cache at {path} after retrying for {seconds}s: {detail} If another process is holding the file open, close it; otherwise check that the file is readable and writable and the disk has space. To go on without it, pass --cache PATH for another file, or --no-cache.
```

Fired when the query-result cache file cannot be opened for the whole retry window. The message carries DuckDB's own description of why. One cause is another process holding the file: it is a DuckDB database, which one process at a time may open for writing. dbt Charts opens it only for the length of each read or write, so several `dct` processes normally share it, but a process that keeps it open, such as a DuckDB shell or a release that held the cache for the life of the process, locks the others out. The other causes are a file that is damaged, not readable or writable by this user, or on a full disk. Results are never served from a substitute in-memory cache, because that would silently re-run every query against the warehouse.

### ERR-CHART-COLUMN-NOT-IN-RESULT: Chart channel references a column absent from the query result {: #err-chart-column-not-in-result }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
Chart '{chart}' channel '{channel}' references column '{column}' which is not in the result of query '{name}'. Available columns: {columns}
```

Fired during `dct validate --warehouse` when a chart's channel (x, y, color, value, etc.) names a column that the backing query does not return. Rename the channel to match a returned column, or update the query to return the expected column.

### ERR-DBT-CALL-UNSUPPORTED: dbt call form this engine cannot resolve {: #err-dbt-call-unsupported }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
Could not resolve {call!r} against the dbt manifest: dbt charts reads the relation name from the call itself, so each argument must be a plain quoted string: {{{{ ref('model') }}}} or {{{{ source('source', 'table') }}}}.
```

**Fix:** Package-qualified `ref('package', 'model')`, versioned `ref('model', v=2)`, and macro-computed arguments are not supported: each needs information the manifest lookup does not use, so resolving one would mean guessing which relation you meant. Name the model directly, or write the relation out.

Fired when a query's SQL calls dbt's `ref()` or `source()` in a form dbt charts cannot resolve to a single relation. dbt charts rewrites these calls textually against the manifest rather than executing dbt's Jinja, so it reads the names straight out of the call and every argument must be a plain quoted string. Rather than let an unrecognized call through to the warehouse (where it fails as a SQL syntax error naming `{{`, far from the cause), dbt charts reports it here.

### ERR-DBT-COLUMN-FORMAT-UNKNOWN: A dbt column's meta.format names a format the board does not have {: #err-dbt-column-format-unknown }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
dbt {kind} {model!r} column {column!r} has meta.format {spec!r}, which is neither an engine format nor defined in this board's style.formats.
```

Fired when a board query reads a dbt column whose `config.meta.format` is not an engine format name and not a key in the rendering board's merged `style.formats`. Fix the value in the model's YAML, or define the name under the board's `style.formats`. A column the board never reads is never checked.

### ERR-DBT-MANIFEST-MISSING: SQL uses a dbt macro but no manifest is available {: #err-dbt-manifest-missing }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
SQL uses {kind} but no dbt manifest was found (looked for {paths}). Build one with `dbt parse` (`dbt parse --target <target> --target-path <dir>` for a source that sets `target_path:`).
```

Fired when a query's SQL calls `ref()` or `source()` but the project has no dbt manifest to resolve the call against. The manifest is what maps a model name to its warehouse relation, so without it dbt charts cannot know which table the query means. Run `dbt parse` (or any command that writes `target/manifest.json`) in the dbt project. A `dbt_profile` source that sets `target_path:` resolves against `<target_path>/manifest.json` instead: build it with `dbt parse --target <target> --target-path <target_path>`.

### ERR-DBT-MANIFEST-UNREADABLE: dbt manifest could not be read {: #err-dbt-manifest-unreadable }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
The dbt manifest at {relpath!r} could not be read: {detail}. Rebuild it with `dbt parse`.
```

Fired when the manifest exists but cannot be read: the file is unreadable (OSError) or the JSON is malformed: usually a truncated write from an interrupted dbt run. Rebuild with `dbt parse`. The manifest's schema version is not checked: dbt charts reads the manifest as plain JSON rather than through dbt's typed contract, so a manifest written by a different dbt version still resolves refs normally.

### ERR-DBT-MODEL-COLUMN-MISSING: Query references a column the dbt model no longer produces {: #err-dbt-model-column-missing }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
Query {query_name!r} references column {column_name!r} of dbt model {model!r}, but the model's SQL does not produce it. Model columns: {available}.
```

Fired when a board query references a column of a dbt model whose output columns, derived statically from the model's SQL in `target/manifest.json`, do not include it. This catches a column renamed or dropped in the model *before* `dbt run` rebuilds the warehouse, when `--warehouse` validation still passes against the old table. If the model was just changed on purpose, update the board; if the manifest is stale, re-run `dbt parse`.

### ERR-DBT-PROJECT-NO-LOCAL-WAREHOUSE: dbt project has no local DuckDB warehouse to query {: #err-dbt-project-no-local-warehouse }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
The query's source did not resolve to a configured source, and the dbt project at {dbt_project_path!r} has no local DuckDB file under data/ (looked for {candidates}). Configure the source in dbt_charts.yml `sources:` or create the local warehouse file.
```

Fired when a SQL query names a source in a dbt project with no `sources:` configured, so it falls through to the project's local DuckDB warehouse, but no such file exists under `data/`. Running against an empty in-memory database would return a result that looks right but is not, so dbt charts refuses. For warehouse-free SQL, declare a `type: duckdb` source with `path: ':memory:'`.

### ERR-DBT-REF-UNKNOWN-NODE: ref() names a node that isn't in the dbt manifest {: #err-dbt-ref-unknown-node }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
SQL references {{{{ ref({ref_name!r}) }}}}, but no model, seed, or snapshot named {ref_name!r} exists in the dbt manifest. Available: {available}.
```

Fired when a query's SQL calls the dbt `ref()` Jinja function with a name that is not present in the loaded manifest. `ref()` addresses models, seeds, and snapshots, not data tests or sources (use `source()` for those). Check for a typo, or refresh the manifest (`dbt parse`) if the node was added recently.

### ERR-DBT-SOURCE-UNKNOWN-TABLE: source() names a table that isn't in the dbt manifest {: #err-dbt-source-unknown-table }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
SQL references {{{{ source({source_name!r}, {table_name!r}) }}}}, but no matching source table exists in the dbt manifest. Available sources: {available}.
```

Fired when a query's SQL calls the dbt `source()` Jinja function with a source/table pair that is not present in the loaded manifest. Check for a typo, or refresh the manifest (`dbt parse`) if the source was added recently.

### ERR-DBT-TARGET-NEEDS-SOURCE: This dbt target is reachable only through a declared source {: #err-dbt-target-needs-source }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
This dbt project's target {target!r} is {warehouse}, which dbt Charts reaches only through a declared source. Add a source with `dbt_profile: {profile}` and `target: {target}`, and set `source:` on the query.
```

Fired when a query uses dbt Jinja such as `{{ ref() }}` with no `source:`, and the dbt project's own target is lake compute or Trino. Such a query would run through dbt Core against that target, and dbt Charts connects to those warehouses through a driver rather than a dbt Core adapter. Declare a source that names the profile and target, and set `source:` on the query.

### ERR-DBT-TARGET-PATH-INVALID: dbt target path is not usable {: #err-dbt-target-path-invalid }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
The dbt target path from {origin} is not usable: {detail}. Use a relative directory inside the dbt project, e.g. `target_path: target/prod` on the source.
```

Fired when the directory the manifest is read from (the source's `target_path:`, `DBT_TARGET_PATH`, or `target-path:` in `dbt_project.yml`) is absolute, climbs out of the dbt project, contains an unrendered Jinja template, or sits in a `dbt_project.yml` that is not valid YAML. Manifests are read through the project, so the directory must be relative to the dbt project root. Fix it where the message says it came from, or set a relative `target_path:` on the `dbt_profile` source, which wins over `DBT_TARGET_PATH` and `target-path:`. Only checked where a manifest is needed: a query calling `ref()` or `source()`.

### ERR-DRIVER-CHECKSUM-MISMATCH: The warehouse driver is not the pinned build {: #err-driver-checksum-mismatch }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
{subject} hashes to {actual}, not the pinned {expected}. {outcome}
```

Fired when a warehouse driver does not match the SHA-256 pinned for its version and platform, either as downloaded or as already cached on disk. A downloaded file is discarded and no library is loaded. A cached file is never overwritten, because the cache is shared with dbt: delete the named file and retry. A download that repeats the mismatch is usually a truncated or proxy-rewritten response; a cached file that fails is truncated, corrupted or replaced.

### ERR-DRIVER-PLATFORM-UNSUPPORTED: No warehouse driver is published for this machine {: #err-driver-platform-unsupported }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
No {driver} driver is published for {arch} {os}. Published platforms: {available}.
```

Lake compute has no ADBC driver on PyPI, so dbt Charts downloads dbt's own build for this machine's OS and CPU. Fired when no build exists for that combination. The download is refused rather than attempted, because dbt Charts will only run a binary whose SHA-256 it pinned in advance. Run dbt Charts on one of the platforms named in the message.

### ERR-DRIVER-TOO-LARGE: The downloaded warehouse driver expanded past its size ceiling {: #err-driver-too-large }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
{url} expanded past {ceiling} bytes and was discarded before it could fill the disk.
```

A pinned SHA-256 says nothing about how far the bytes expand, and the expansion necessarily happens before the hash can be compared, so dbt Charts also caps the unpacked size. Nothing is written to the driver cache. A published driver is far below the cap, so this means the response was not the artifact dbt published.

### ERR-FILE-SOURCE-AMBIGUOUS: Inline file source path exists at both candidate locations {: #err-file-source-ambiguous }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Query {query_name!r}: inline file source {ref!r} exists at both {candidates}. Rename or remove one so only a single candidate exists.
```

Fired when a query's inline `source: <path>` ref resolves to a real file at both of its two candidate locations, the board's own directory and the project root (a bare path is tried against both anchors so it works from any board depth). dbt charts never silently prefers one anchor; move or rename one of the two files so only a single candidate remains.

### ERR-FILE-SOURCE-DECIMAL-TOO-WIDE: File source decimal column exceeds precision 38 {: #err-file-source-decimal-too-wide }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
File source {source_name!r}, table {table_name!r}: column {column!r} in {relpath!r} is {column_type}, wider than the 38 significant digits the query engine's DECIMAL can hold. Re-export the column at precision 38 or less (BigQuery: CAST(col AS NUMERIC) instead of BIGNUMERIC), or split the digits across columns.
```

Fired when a decimal column in a file source is declared with more than 38 significant digits, whatever its values. Parquet's decimal type allows more precision than the query engine's DECIMAL, and BigQuery BIGNUMERIC exports routinely use it. Re-export the column at precision 38 or less, or split the digits across columns.

### ERR-FILE-SOURCE-DUPLICATE-COLUMN: File source repeats a column name {: #err-file-source-duplicate-column }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
File source {source_name!r}, table {table_name!r}: {relpath!r} names column {column!r} more than once. Column names are case-insensitive in SQL; rename one of the columns in the file.
```

Fired when a file's header (CSV) or schema (Parquet) names the same column twice, ignoring case. SQL could not tell the two apart, so the file is refused rather than one column being renamed. Rename one of the columns in the file.

### ERR-FILE-SOURCE-NOT-FOUND: File source path could not be read from disk {: #err-file-source-not-found }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
File source {source_name!r}: {relpath!r} could not be read ({detail}). Restore the missing file, fix the path, or fix its permissions.
```

Fired when a `type: csv`/`json`/`parquet` source's `files:` mapping, or a query's inline `source: <path>` ref, names a literal (non-glob) path that cannot be opened on disk: the leaf is missing, a path component traverses through an existing file instead of a directory, or the OS denies read access. `{detail}` carries the OS error string (e.g. "No such file or directory", "Not a directory", "Permission denied") so the message doesn't call a permissions problem a missing file. Unlike an empty glob match (`ERR-GLOB-EMPTY`), a literal path is never expanded, so this is the only place these failures surface. Compile probes an inline ref's two candidate locations (board directory, project root) only to choose between them; a path that exists at neither, like a `files:` path, fails here at query-execution time (`dct render`/`dct serve`), one chart at a time. Fix the path, add the missing file, or fix its permissions.

### ERR-FILE-SOURCE-TOO-LARGE: File source relation exceeded the uncompressed-size cap {: #err-file-source-too-large }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
File source {source_name!r}, table {table_name!r}: reading {relpath!r} ({raw_mb:.1f} MB on disk) took this table to {size_mb:.1f} MB uncompressed, exceeding the {cap_mb:.1f} MB cap. Load less into this table — fewer files, fewer columns, or a pre-aggregated extract — or use a database connection for data this size.
```

Fired when the uncompressed size of a file-source relation (the file(s) backing one `files:` table entry) exceeds the effective `execution.file_source_max_bytes` limit. Every format is measured on the same basis: the file's own bytes for CSV and JSON, and for Parquet the uncompressed total its footer records, so choosing the compact format is never what gets a relation rejected. The message names no config key deliberately — the effective limit is the lower of the project's own `execution.file_source_max_bytes` and any deployment ceiling (`DCT_FILE_SOURCE_MAX_BYTES_CEILING`), so where a ceiling is what fired, raising the project setting does nothing. Lower the data volume, or use a database connection for data this size.

### ERR-FILE-SOURCE-TOO-MANY-TABLES: File source exceeded the table-count cap {: #err-file-source-too-many-tables }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
File source {source_name!r}: `files:` has {count} tables, exceeding the {cap}-table cap. Split the source, raise execution.file_source_max_tables in dbt_charts.yml, or use a database connection for large-scale data.
```

Fired when a file source's `files:` mapping declares more table entries than the configured `execution.file_source_max_tables` limit. A wide `files:` map can quietly fill the shared cache disk, split the source into multiple sources, raise the cap in `dbt_charts.yml` under `execution: file_source_max_tables: <N>`, or use a database connection for large-scale data.

### ERR-FILE-SOURCE-UNSUPPORTED-TYPE: File source column type is not supported by the query engine {: #err-file-source-unsupported-type }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
File table {table_name!r}: the query engine cannot load one of its column types. {detail} Re-export the file with the column cast to a standard SQL type.
```

Fired when a file carries a column type the query engine cannot represent. Re-export the file with the column cast to a standard SQL type.

### ERR-GLOB-EMPTY: Glob pattern in file source matched no files {: #err-glob-empty }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
File source {source_name!r}, table {table_name!r}: glob pattern {pattern!r} matched no files. Provide at least one matching file or fix the pattern.
```

Fired when a glob pattern in a file source's `files:` mapping expands to zero files. Every glob must match at least one file; an empty match is always a configuration error. Check the pattern for typos, verify the files exist at the expected paths, and confirm the path is relative to the project root.

### ERR-GLOB-SCHEMA-MISMATCH: Glob-matched files have inconsistent column schemas {: #err-glob-schema-mismatch }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
File source {source_name!r}, table {table_name!r}: {path!r} disagrees with {first_path!r} on column names or types. {detail}All files matched by a glob must share the same column names and types.
```

Fired when a glob pattern in a file source's `files:` mapping expands to files whose column schemas disagree — either a differing set of column names, or the same column carrying a different type in one file than another. Align the schemas across all matched files, or split the source into separate entries with non-overlapping patterns.

### ERR-GLOB-TOO-MANY: Glob pattern in file source exceeded the file-count cap {: #err-glob-too-many }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
File source {source_name!r}, table {table_name!r}: glob pattern {pattern!r} matched {count} files, exceeding the {cap}-file cap. Increase execution.max_glob_file_count in dbt_charts.yml if needed.
```

Fired when a glob pattern in a file source's `files:` mapping matches more files than the configured `execution.max_glob_file_count` limit. Narrow the pattern, or raise the cap in `dbt_charts.yml` under `execution: max_glob_file_count: <N>`.

### ERR-JINJA-ERROR: Jinja template in a query failed to render {: #err-jinja-error }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Jinja template error: {message}
```

Fired when a Jinja template in a query or pre-query raises a rendering error. Check the template syntax and ensure all referenced values and filters are available.

### ERR-MUTATING-SQL: Non-read-only SQL is not allowed {: #err-mutating-sql }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
dct refuses to execute non-read-only SQL. Statement: {rejected_node_kind}. Preview: {fragment_preview}.
```

Fired when dbt charts detects a non-SELECT statement (INSERT, UPDATE, DELETE, DROP, etc.) in a query. dbt charts only executes read-only SQL to prevent accidental data modification.

### ERR-QUERY-DIALECT-MIXED: Composed queries declare different dialects {: #err-query-dialect-mixed }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Query {query_name!r} (dialect: {dialect}) embeds {{{{ queries.{dep_name} }}}} (dialect: {dep_dialect}). Queries composed with {{{{ queries.X }}}} become one statement, so they must all declare the same `dialect:`.
```

**Fix:** Set the same `dialect:` on both queries, or on neither. A query that sets none is written in its source's own dialect.

Fired when a query embeds another with `{{ queries.X }}` and the two declare different `dialect:` values, counting an unset `dialect:` as a value.

### ERR-QUERY-DURATION-EXCEEDED: Query exceeded the maximum allowed duration {: #err-query-duration-exceeded }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
Query exceeded max_query_duration_seconds={seconds}s on source {source!r}.
```

Fired when a query runs longer than the configured `max_query_duration_seconds` limit on a source. Optimize the query, raise the limit, or add a WHERE clause to reduce the result set.

### ERR-QUERY-FORMAT-COLUMN-MISSING: A query's formats: names a column the query did not return {: #err-query-format-column-missing }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
Query '{query}' formats names column '{column}', which the query did not return. Returned columns: {columns}
```

Fired when a query's `formats:` key is not among the columns the query returns. Checked at compile for `values` queries, by `dct validate --warehouse` for SQL queries, and when rows come back at execution. A zero-row result carries no column names, so an empty result passes; `dct validate --warehouse` still checks the query's columns.

### ERR-QUERY-FORMAT-SPEC: A query's formats: value is a format spec, not a format name {: #err-query-format-spec }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Query {query!r} formats.{column} is a format spec ({spec!r}), not a format name. Name it in style.formats (for example `{column}_format: {spec!r}`) and use the name here.
```

Fired when a query's `formats:` value is a d3 or strftime spec (`$,.0f`, `%b %Y`) instead of a name. A query says what a column means by naming a format: an engine format (`currency`, `percent`, `year`, ...) or one the board defines in `style.formats`. The spec itself belongs in `style.formats`, where one definition restyles every column that names it.

### ERR-QUERY-FORMAT-UNKNOWN: A query's formats: value names a format the board does not have {: #err-query-format-unknown }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Query {query!r} formats.{column} names {spec!r}, which is neither an engine format nor defined in style.formats. Available: {available}
```

Fired when a query's `formats:` value is not an engine format name and not a key in the rendering board's merged `style.formats`. A query imported into another board is checked against that board's names, so a shared query naming a format of your own needs it defined in every board that imports it.

### ERR-QUERY-INTERRUPTED: Query interrupted by server shutdown {: #err-query-interrupted }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
Query interrupted: the server is shutting down.
```

Fired when `dct serve` stops while a query runs or waits to run. It says nothing about the query and is never cached; reload the board once the server is back.

### ERR-REPO-FILE-TOO-LARGE: Repository file exceeds the per-file size limit {: #err-repo-file-too-large }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
Repo file too large: {file_path} is at or over the {limit_mb:.0f} MB per-file limit in a connected repo. Use a database connection for data this size.
```

Fired when a file in a connected repository is at or over the deployment's per-file size limit. dbt charts imposes this limit because large files are better served by a direct database connection rather than loading the entire file into memory.

### ERR-RESULT-DUPLICATE-COLUMN: A query returned two columns with the same name {: #err-result-duplicate-column }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
The query returned more than one column named {columns}. Rows are keyed by column name, so one would silently replace the other. Alias each column to a distinct name in the query.
```

Fired when a query result has two or more columns with the same name, for example `select 1 as a, 2 as a` or a join that selects `id` from both sides. Names are compared after the adapter's own case normalization.

### ERR-RESULT-NUMERIC-OVERFLOW: A returned number is too large to represent {: #err-result-numeric-overflow }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
Column {column!r} holds a whole number too large for a 64-bit integer. Cast it in the query (e.g. to VARCHAR or FLOAT) to choose how it should be read.
```

Fired when a warehouse returns an integer wider than 64 bits. dbt Charts refuses to narrow it, because a driver's own narrowing can wrap silently and produce a plausible wrong number. Cast the column in the query to state what you want instead.

### ERR-SOURCE-CONFIG-INVALID: Source configuration fails validation {: #err-source-config-invalid }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Source {source_name!r} in {filename}: {detail}
```

Fired when a `sources:` entry in dbt_charts.yml fails typed SourceConfig validation. Check the source definition for missing required fields or invalid values, and refer to the sources reference for the expected schema.

### ERR-SOURCE-CREDENTIAL-LITERAL: Source contains a raw credential literal {: #err-source-credential-literal }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Source {source_name!r}: field {field!r} holds a raw credential literal. dbt_charts.yml is committed to git, so inline secrets leak on push. Reference the secret instead (e.g. {field}: {{{{ env_var('SECRET_NAME') }}}}), or use a `type: dbt_profile` source that delegates to an out-of-repo profiles.yml.
```

Fired when a `sources:` entry in the committed dbt_charts.yml contains a raw secret literal (password, API key, etc.). Since dbt_charts.yml is committed to git, inline secrets would be leaked on push. Reference the secret via `env_var()` or use a `dbt_profile` source type that delegates to an out-of-repo profiles.yml.

### ERR-SOURCE-CROSS-FILE-FORBIDDEN: Cross-file source reference is not allowed {: #err-source-cross-file-forbidden }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
Cross-file source reference (`#` anchor form) is not allowed: {offending_value!r}.
```

Fired when a source reference uses the YAML anchor cross-file form (`#`). Cross-file source references are not allowed; use a named source from the project allowlist instead.

### ERR-SOURCE-INLINE-FORBIDDEN: Inline source definition is not allowed {: #err-source-inline-forbidden }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Query {query_name!r}: inline source definitions are not allowed. Reference a source by name (`source: my_db`) instead. Got: {offending_value}
```

**Fix:** Use a named source declared under `sources:` in your dbt_charts.yml instead of inline connection parameters.

Fired when a query's `source:` is set to an inline dictionary instead of a named source reference. Inline source definitions are forbidden for security reasons: connection parameters in the committed YAML would leak credentials. Use a named source declared under `sources:`.

### ERR-SOURCE-INVALID-TYPE: Unknown source type {: #err-source-invalid-type }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
Unknown source type {offending_value!r}. Valid types: {available}.
```

Fired when a source's `type:` field names a source type that is not registered. Check for typos and refer to the documentation for the supported source types.

### ERR-SOURCE-MISSING-TYPE: Source is missing the required type field {: #err-source-missing-type }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
Source is missing the required `type` field: {offending_value!r}.
```

Fired when a source definition omits the required `type:` field. Add a `type:` field naming the source adapter to use.

### ERR-SOURCE-NOT-FOUND: Query references an unknown source {: #err-source-not-found }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Query {query_name!r} references unknown source {source!r}. Available sources: {available}. dct sources are declared under `sources:` in your dbt_charts.yml; the source name is not the dbt project name.
```

Fired when a query's `source:` names a source that is not declared in the sources registry. Check for typos and ensure the source is declared under `sources:` in your dbt_charts.yml. Also includes the execute-side failure of the same name (source lookup at query time).

### ERR-SOURCE-NOT-FOUND-EMPTY: No source profiles are configured {: #err-source-not-found-empty }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
Source {source!r} not found. No source profiles are configured. Declare sources under `sources:` in your dbt_charts.yml.
```

Fired when a query references a source but no source profiles are configured at all. Declare sources under `sources:` in your dbt_charts.yml.

### ERR-SOURCE-NOT-NAMED: Query names no source {: #err-source-not-named }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
Query names no source. Available: {available}. Set `source:` on the query or at the board root.
```

Fired when a SQL query reaches execution without naming a source. Set `source:` on the query, or once at the board root so every query inherits it, to one of the available sources. The only fallback is a dbt project that declares no `sources:`, whose implicit source is named after its dbt profile.

### ERR-SOURCE-REQUIRED: Query has no source configured {: #err-source-required }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Query {query_name!r}: SQL queries must have a source. Set it on the query (`source: my_db`), or at the board or folder meta.yml level (`source: my_db`).
```

Fired when a SQL query has no `source:` set at the query, board, or folder meta.yml level and no default source is configured. Set `source: my_db` on the query or as a default at a higher level.

### ERR-SQL-DATE-LITERAL-VARIABLE: Variable quoted as a date/time/timestamp literal will not compile {: #err-sql-date-literal-variable }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Query {query_name!r} {field_label} casts a variable with {keyword} '{{{{ {variable} }}}}'. This source binds the variable as a query parameter, so its quotes are stripped and this compiles to {keyword} $N, which the warehouse does not parse. Use cast('{{{{ {variable} }}}}' as {keyword}) instead.
```

Fired when a query casts a Jinja variable to a date/time/timestamp using the SQL literal syntax (`date '{{{{ var }}}}'`) on a source whose adapter binds variables as real query parameters (duckdb, sqlite). The parameterizer strips the quotes around every placeholder, so `date '{{{{ var }}}}'` compiles to `date $1` -- syntax the warehouse does not accept. Other sources (postgres, snowflake, bigquery, dbt_profile, etc.) render variables as inline literal text instead, so the same SQL is valid there and this check does not fire. Use `cast('{{{{ var }}}}' as date)` (or `time`/`timestamp`) instead, which keeps the variable an ordinary string parameter and works on every source.

### ERR-SQL-DIALECT-UNSUPPORTED: SQL cannot be translated to the warehouse dialect {: #err-sql-dialect-unsupported }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
Cannot translate this {read} SQL to {write}: {reason}
```

**Fix:** Rewrite the statement with constructs both dialects share, or remove `dialect:` from the query and write it in the warehouse's own SQL.

Fired when a query sets `dialect:` to something other than its source's warehouse and its SQL cannot be translated safely: it calls a function the translator does not know, uses a construct with no equivalent in the warehouse, holds more than one statement, or does not parse. It also covers paths that do not translate at all (file sources, `{{ queries.X.cache }}` references, incremental queries) when `dialect:` differs from the warehouse.

### ERR-SQL-LITERAL-NEWLINES: SQL contains literal backslash-n from single-quoted YAML {: #err-sql-literal-newlines }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Query {query_name!r} {field_label} contains literal \n (backslash + n). Use YAML block scalar `{field_label}: |` to write multiline SQL:

  queries:
    my_query:
      {field_label}: |
        SELECT
          col
        FROM t
```

Fired when a query's SQL or pre-query string contains a literal backslash followed by 'n', which typically means YAML single-quote escaping swallowed an intended newline. Use a YAML block scalar (`field: |`) for multiline SQL to avoid this.

### ERR-TEMPLATE-OUTPUT-TOO-LARGE: Board render's cumulative template output exceeded the cap {: #err-template-output-too-large }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
This board render's templated fields (queries, titles, markdown, …) emitted more than {ceiling} bytes combined, stopping after {emitted_bytes} bytes. This is a render-wide cumulative cap, not a per-field one — a nested loop, a runaway variable expansion, or genuinely oversized content anywhere in the board can trip it. Reduce the amount of text a templated field (or their combination) produces.
```

Fired when the cumulative bytes emitted by every templated field (queries, titles, markdown, chart labels) in one board render exceed the effective `execution.max_template_output_bytes` limit — a hard error, not a truncation-with-warning like `WARN-QUERY-RESULT-TRUNCATED`: a truncated SVG or SQL string is a corrupt document, never a usable-with-a-caveat result. The message names no config key deliberately: the effective limit is the lower of the project's own config value and any deployment ceiling (`DCT_MAX_TEMPLATE_OUTPUT_BYTES_CEILING`), so it cannot be raised past the ceiling.

### ERR-UNKNOWN-QUERY: Chart references an unknown query {: #err-unknown-query }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Chart {chart_name!r} references unknown query {query_name!r}. Declare the query under `queries:` or fix the typo in `query:`.
```

Fired when a chart's `query:` names a query that is not declared under `queries:` in the board or any included meta.yml. Check for typos and ensure the query is declared.

### ERR-UNPARSEABLE-SQL: SQL could not be parsed for static checks {: #err-unparseable-sql }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
Could not parse this SQL: {cause}
```

**Fix:** If the warehouse accepts this query, the SQL is fine; the parser just does not model that dialect or macro yet, and only dbt charts' static checks (read-only enforcement, reaggregation and join lint) are skipped for it. If the warehouse rejects it too, fix the syntax at the reported position.

Fired when dbt charts' static SQL parser cannot parse a query. The query is still sent to the warehouse; what is lost is the static read-only check and the semantic lint that run on parseable SQL. It is not necessarily an error in the SQL itself; unmodeled dialect syntax and dbt macros land here too.

### ERR-UNRESOLVED-REFERENCE: Reference points to an unknown name {: #err-unresolved-reference }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Reference {ref!r} not found{context}.
```

Fired when a chart or layout reference names a target that cannot be found in the current board or any included files. Check for typos and ensure the referenced chart, query, or layout item is declared.

### ERR-WAREHOUSE-CONNECTION: Could not open the warehouse {: #err-warehouse-connection }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
Could not open the warehouse: {reason}
```

Fired when opening the connection fails, before any SQL is sent: a database file that is missing, unreadable, or lock-held by another process (DuckDB, SQLite), or bad credentials, an unreachable host, or a missing database/role on a network warehouse (Postgres, Snowflake, BigQuery, Databricks, …). Distinct from ERR-WAREHOUSE-RUNTIME because nothing ever read the SQL: the query may be perfectly good, so callers that judge queries (`dct validate --warehouse`) must not report it as a query defect. `{reason}` names the classified cause; the driver's own text (which may carry hostnames, PIDs, or usernames) is not shown here but is available in `dct`'s diagnostics output and server logs. Check the source's credentials, host, and network reachability in `dbt_charts.yml` or `profiles.yml`.

### ERR-WAREHOUSE-QUERY-INVALID: Query failed warehouse validation {: #err-warehouse-query-invalid }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
Query '{name}' failed warehouse validation ({mechanism}): {warehouse_message}
```

Fired when a query's SQL is rejected by the warehouse during `dct validate --warehouse`. The warehouse message carries the specific failure reason (unknown column, syntax error, etc.). Fix the SQL or re-run `dbt parse` if a referenced model was recently renamed.

### ERR-WAREHOUSE-RESULT-WARNING: The warehouse reported a warning about this result {: #err-warehouse-result-warning }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
The warehouse reported a warning about this result: {warnings}
```

Fired when the warehouse answered a query and attached a warning, such as an export limit that truncated the rows. A result the warehouse itself flagged as incomplete is a wrong answer that looks right, so dbt Charts raises rather than rendering it. Change the query so the warning no longer applies, for example by selecting fewer rows.

### ERR-WAREHOUSE-RUNTIME: Warehouse rejected the query at runtime {: #err-warehouse-runtime }

- **Level:** error
- **Domain:** execute
- **Suppressible:** no

**Message template:**

```
Warehouse rejected the query: {detail}.
```

Fired when the warehouse rejects a query for an unclassified runtime error. The detail carries the warehouse's original error message.

## variables


### ERR-UNKNOWN-VARIABLE: Unknown variable referenced in template {: #err-unknown-variable }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
{surface} {owner_name!r} references unknown variable {var_name!r}. Declare it under `variables:` or fix the typo.
```

Fired when a Jinja template references a variable name that is not declared under `variables:`. Check for typos and ensure the variable is declared before the template that uses it.

### ERR-VARIABLE-NAME-INVALID: Variable name is not an identifier {: #err-variable-name-invalid }

- **Level:** error
- **Domain:** compile
- **Suppressible:** no

**Message template:**

```
Variable {name!r} must be a valid identifier: letters, digits and underscores, not starting with a digit.
```

Fired when a name under `variables:` is not a valid identifier. Variables are referenced as bare Jinja names in queries and templates, so a name with a space, hyphen, or leading digit never actually worked — this catches it at compile instead of a confusing render-time failure.

# Telemetry (https://docs.dbtcharts.com/reference/telemetry/)

# Telemetry

`dct` sends anonymous usage statistics to dbt Labs so the team can count how many people run it and which commands they use. Events travel through the same pipeline as dbt's own usage stats, and `dct` shares dbt's anonymous user id (`.user.yml`), so one person running both tools counts as one user.

## What is sent

Two events per command: one when it starts and one when it ends.

| Field | Meaning |
|---|---|
| `event_id` | Random UUID, unique per event |
| `invocation_id` | Random UUID shared by the start and end event of one command |
| `progress` | `start` or `end` |
| `command` | The command path, such as `render` or `cloud connect`. Only command names are sent, never arguments or option values |
| `version` | The installed `dbt-charts` version |
| `python_version` | The Python version |
| `os_name` | The operating system name, such as `Darwin` or `Linux` |
| `project_id` | MD5 hash of the `name` in your `dbt_project.yml`; empty outside a dbt project. The name itself is never sent |
| `dbt_local_cookie_user_id` | The anonymous id stored in `.user.yml` |
| `result_type` | `ok` or `error`; end event only |
| `duration_ms` | Command run time in milliseconds; end event only |

Fields that do not apply to an event are sent empty (`project_id` outside a dbt project, `result_type` and `duration_ms` on the start event). Requests carry no credentials. Events are sent in the background, and `dct` waits at most one second on exit for delivery; a failed or slow send is dropped silently and never changes a command's result.

Board contents, queries, file paths, warehouse credentials, and query results are never sent. The payload carries no IP address, but the receiving pipeline adds IP-derived geolocation to each event on the server.

## Where the id lives

The anonymous id is a random UUID in `~/.dbt/.user.yml`, or in `$DBT_PROFILES_DIR/.user.yml` when that variable is set. It is shared with dbt when dbt uses the default `~/.dbt` or the same `DBT_PROFILES_DIR`; dbt's `--profiles-dir` option and a `profiles.yml` in the current directory are not consulted, so in those setups the two tools keep separate ids. `dct` creates the file on the first run that sends an event, prints a one-line notice to stderr when it does, and never creates it while usage stats are disabled.

## Opting out

Any one of these turns usage stats off. They are listed in precedence order.

1. `DO_NOT_TRACK=1` in the environment. Any non-empty value other than a false spelling (`0`, `f`, `false`, `n`, `no`, `off`) opts out, so `DO_NOT_TRACK=anything` does too.
2. The `--no-send-anonymous-usage-stats` flag, placed before the command: `dct --no-send-anonymous-usage-stats render board.yml`.
3. `DBT_SEND_ANONYMOUS_USAGE_STATS=false` in the environment (also `0`, `f`, `n`, `no`, `off`; `true`, `1`, `t`, `y`, `yes`, `on` turn it on).
4. `send_anonymous_usage_stats: false` under `flags:` in `dbt_project.yml`.

Settings 3 and 4 and the project's `project_id` come from the project a command targets: `--project-dir` / `DCT_PROJECT_DIR` and `--dbt-project-dir` / `DBT_PROJECT_DIR`, not the current directory.

A value that is not a boolean, such as `DBT_SEND_ANONYMOUS_USAGE_STATS=maybe`, prints a warning to stderr and disables usage stats for that run.

## More information

- [dbt usage stats](https://docs.getdbt.com/reference/global-configs/usage-stats)
- [dbt Labs privacy policy](https://www.getdbt.com/cloud/privacy-policy)

# dbt Charts Warning Reference (https://docs.dbtcharts.com/reference/warnings/)

# dbt Charts Warning Reference


Auto-generated from `dbt_charts.core.diagnostics.REGISTRY`. Every `WARN-*` code dbt charts can emit, grouped by docs topic. All warnings are suppressible via a query's `ignore:` or a chart's `warnings_ignore:` field.


## board


### WARN-DEFAULTS-FILE-GIVEN-AS-BOARD: A defaults file was given to dct render {: #warn-defaults-file-given-as-board }

- **Level:** warning
- **Domain:** compile
- **Suppressible:** yes

**Message template:**

```
{path} holds defaults for the boards beside it; skipped.
```

**Fix:** Nothing to fix when a glob picked it up. To see its effect, render a board in the same directory.

Fired when a path given to `dct render` is a meta.yml or meta.yaml file. That file holds defaults the boards in its directory inherit, and has nothing of its own to draw. A glob like `charts/*.yml` picks it up alongside the boards, so it is skipped and the boards render.

### WARN-DOUBLE-HEADER: Board title is repeated by a heading at the top of the body {: #warn-double-header }

- **Level:** warning
- **Domain:** compile
- **Suppressible:** yes

**Message template:**

```
Board title {title!r} is followed immediately by a level-{level} markdown heading {heading!r}; the board renders both, so the dashboard headers itself twice.
```

**Fix:** Delete the heading line from the body; `title:` already renders as the board header. If you would rather keep the heading, drop `title:` instead and let it be the header.

Fires when a board sets `title:` and the first block of its body markdown is a heading that either is level 1 (a document has one document title) or repeats the board title. The board prints the board title as its header and the markdown heading directly beneath it. A heading further down the body, or a lower-level heading with different text (`## Overview` under `title: Sales`), is ordinary section structure and does not fire. Heading detection uses the same markdown parser that renders the text, so a fenced code block opening with a `#` comment is not mistaken for a heading. Checked on the board itself, not on nested boards; a section card pairing its title with a styled body heading is a deliberate pattern. Emitted by `compile/validate/board_warnings.py`.

### WARN-H1-BODY-NO-TITLE: Body opens with a level-1 heading but the board has no title {: #warn-h1-body-no-title }

- **Level:** warning
- **Domain:** compile
- **Suppressible:** yes

**Message template:**

```
Body opens with a level-1 markdown heading {heading!r} and the board has no `title:` set; the heading renders as plain body text instead of the styled board header.
```

**Fix:** Set `title: {heading}` and delete the `# {heading}` line from the body text.

Fires when a board has no `title:` and the first block of its body markdown is a level-1 heading; the author likely reached for a markdown heading instead of the purpose-built `title:` field, so the board renders as unstyled prose with no header. Only a literal level-1 heading counts; a lower-level heading (`## Overview`) with no title is ordinary section structure and does not fire, since there is no title text to compare it against. Heading detection uses the same markdown parser that renders the text, so a fenced code block opening with a `#` comment is not mistaken for a heading. Checked on the board itself, not on nested boards; a section card's own opening heading is not inspected. Emitted by `compile/validate/board_warnings.py`.

### WARN-HTML-POLICY-CAPPED: Board html_policy downgraded by deployment ceiling {: #warn-html-policy-capped }

- **Level:** warning
- **Domain:** compile
- **Suppressible:** yes

**Message template:**

```
Board requested html_policy={requested!r} but the {ceiling_source} ceiling is {ceiling!r}; effective policy is {effective!r}. Raw HTML in this board will be treated as {effective!r}.
```

**Fix:** Either lower the board's `html_policy:` to {effective!r} to match what is actually rendered, or raise the deployment ceiling (DCT_HTML_POLICY_CEILING or markdown.html_policy_ceiling in dbt_charts.yml) if the deployment operator permits it.

Fires when a board's authored `html_policy` is above the effective deployment ceiling (set by DCT_HTML_POLICY_CEILING env var or `markdown.html_policy_ceiling` in dbt_charts.yml). The board compiles successfully but the policy is downgraded at normalize time; this warning makes the downgrade visible so the author knows their html_policy setting is not being honored. Emitted by `compile/compiler.py`.

### WARN-LOW-TEXT-CONTRAST: Text ink has too little contrast against its background {: #warn-low-text-contrast }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
{element} is painted {ink} on {background} -- {ratio:.1f}:1 contrast, below the {floor:.1f}:1 floor for {size} text.
```

**Fix:** Set {key} to a color with more contrast against {background}.

Fires when a text block's heading or body ink clears less than the WCAG 2.1 AA contrast ratio (4.5:1, or 3:1 under WCAG's own large-text exception) against the opaque background it paints on. The common case is a row's own default ink left unchanged after authoring a `style.background` on that row; the fix names the key that governs that element's ink today (`style.title.font.color` for a heading, `style.font.color` for body text). The engine never repaints -- the color pair is still painted exactly as written.

### WARN-RETIRED-IGNORE-CODE: --ignore-warning names a retired warning code {: #warn-retired-ignore-code }

- **Level:** warning
- **Domain:** compile
- **Suppressible:** yes

**Message template:**

```
--ignore-warning: {code} no longer exists and suppresses nothing
```

**Fix:** Remove it from the ignore list.

Fired when `dct render --ignore-warning` names a warning code an earlier release shipped and a later one removed. The code can no longer fire, so the flag is dead weight rather than a typo, and the render proceeds.

### WARN-SCHEMA-MIGRATED: Board YAML uses retired syntax {: #warn-schema-migrated }

- **Level:** warning
- **Domain:** compile
- **Suppressible:** yes

**Message template:**

```
{message}
```

**Fix:** Run `dct migrate` to rewrite the file, or update the YAML by hand where the message says `dct migrate` cannot.

Fired when a board, meta.yml, or `extends:` file uses syntax from an older dbt charts release. The board is migrated in memory and still renders, but the file on disk is stale. When migration could not finish, the message says so, and errors reported alongside it may name retired syntax.

### WARN-SINGLE-CHART-REDUNDANT-TITLE: Single-chart dashboard has both a board title and a chart title {: #warn-single-chart-redundant-title }

- **Level:** warning
- **Domain:** compile
- **Suppressible:** yes

**Message template:**

```
Board title {title!r} sits above a single chart that carries its own title {chart_title!r}; two headers for one chart.
```

**Fix:** Give the board one header: drop the chart's `title:` (the board title already heads the board, and it is what listings, search, and nav show), or drop the board `title:` and let the chart title stand.

Fires when a board's whole content is one chart and both the board and the chart carry a title, so the board stacks two headers over a single piece of content. A single-chart dashboard does not need a separate dashboard title. Does not fire when only one of the two is titled, when the board holds more than one chart, or when body prose sits between the two titles. KPI and callout charts are excluded: a KPI labels itself with `label:` and a callout's title is a prose lead-in, so neither stacks a chart header under the board's. Checked on the board itself, not on nested section boards. Emitted by `compile/validate/board_warnings.py`.

## charts


### WARN-AREA-UNSTACKED-READS-AS-STACKED: Unstacked area is hard to tell apart from a stacked one {: #warn-area-unstacked-reads-as-stacked }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r}: hard to tell this area chart apart from a stacked one. Its {count} series from {field!r} overlap, so the outer edge represents an individual series value, not the total.
```

**Fix:** Set `style.stack: "zero"` if the series compose a total, or use `type: line` if they are independent trends. Which one this occurrence recommends leading with depends on how much of the real total the chart's outer edge is hiding.

Fires when an area chart resolves to an unstacked mode (`stack: none`), paints two or more series (from a `color:` column or a wide `y: [a, b, c]` measure list), and no pair of those series visibly trades places anywhere on the axis. A pair is compared at the x values they share, on values coercible to a number, and only where both sit on one side of the zero baseline: a series painting above the baseline and one painting below it never warn about each other, since their bands occupy disjoint regions rather than nesting. A log y axis is not judged, since position there is logarithmic and no single ratio converts a gap at every magnitude. dbt charts already signals stacking through fill weight: an unstacked area's fill is translucent, a stacked one's is solid. A series that visibly trades places with another declares itself an overlap; the reader sees two bands swap and reads them as independent. Where that never visibly happens, each band looks nested inside the next at every x, indistinguishable from a real stack whatever the fill opacity says. A reader takes the outer edge for the total; it instead represents an individual series value, and the real total's magnitude may be several times larger. The render is unchanged by this warning; it reports a chart that is very likely either a stacked area missing its `stack:` key or a line chart drawn with the wrong mark. Small multiples split by the series column itself give each series its own panel, so no panel holds a pair to compare and nothing is reported. A chart with overlay layers is never judged: a layer can paint the very total the base series' outer edge only looks like, and judging the base alone would fire on a chart that already resolves the ambiguity. A series that repeats the same x value on two or more rows within one panel abstains the whole panel, since there is no principled way to pick which of the repeated values the chart actually paints.

### WARN-AREA-ZERO-BASELINE-CROPPED: An area chart's zero baseline is cropped {: #warn-area-zero-baseline-cropped }

- **Level:** warning
- **Domain:** compile
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r} sets axis_y.scale.continuous.zero to false, so the area's fill starts above zero and overstates the change.
```

**Fix:** Remove axis_y.scale.continuous.zero to keep the zero baseline, or use `type: line` to zoom into a range. If the crop is deliberate, add WARN-AREA-ZERO-BASELINE-CROPPED to the chart's warnings_ignore.

An area's fill encodes magnitude from the zero baseline, so `style.axis_y.scale.continuous.zero: false` shows a cropped fill that overstates change. A zoomed area is sometimes deliberate, so this warns instead of failing and can be suppressed with `warnings_ignore`.

### WARN-AXIS-ALIGN-DISCARDED: Authored axis_y.labels.align has no effect on a house-format quantitative axis {: #warn-axis-align-discarded }

- **Level:** warning
- **Domain:** compile
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r}: axis_y.labels.align = {authored_align!r} has no effect: the format alias {format_alias!r} forces label.align = 'right' on right-edge quantitative axes for correct digit alignment.
```

**Fix:** Remove axis_y.labels.align from this chart. To opt out of forced alignment, use a literal d3 format spec (e.g. '.1%') instead of the alias.

Fired when a chart authors axis_y.labels.align alongside a house-rule format alias (percent, currency, etc.) on a right-edge quantitative axis. The alias forces label.align = 'right' for place-value alignment; the authored align value is silently discarded.

### WARN-AXIS-LABEL-COLLISION: X-axis tick labels overlap with no room left to fix it {: #warn-axis-label-collision }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r}: x field {field!r} has {label_count} tick labels that overlap even after skipping and tilting labels — they will render on top of each other.
```

**Fix:** Widen the chart, reduce the number of x categories (roll up to a coarser time grain, filter the data), or shorten the labels.

Fires on a line/area/scatter chart whose x-axis tick labels still overlap after the render tried every enabled overlap strategy (`style.axis_x.labels.overlap.skip`/`.tilt`, both on by default) — the same collision a table's cramped-columns warning reports for width, applied to axis tick text. Unlike `WARN-TOO-MANY-X-CATEGORIES` (a fixed category-count ceiling on a categorical band axis), this fires on any x-axis shape, including a continuous temporal axis whose auto-picked ticks simply don't fit the chart's width.

### WARN-AXIS-TITLE-TRUNCATED: Axis title was too long and was truncated with an ellipsis {: #warn-axis-title-truncated }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r}: {authored_field!r} was truncated: the authored text {authored_text!r} did not fit within two lines at the available extent.
```

**Fix:** Shorten the axis title, or widen the chart so the title has more room.

Fires when an axis title is pre-wrapped to at most two lines (to prevent Vega-Lite's autosize from collapsing the plot) and the authored text is still too long: the last line is cut with a Unicode ellipsis (…) and the remainder of the title is lost. The title text in the message is the full authored text before truncation, so you can see exactly what was cut.

### WARN-BAR-BAND-WIDTH-TOO-NARROW: Bar chart bands are too narrow to read {: #warn-bar-band-width-too-narrow }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r} has {distinct} bands x {series} series across {render_width:.0f}px (~{bar_width:.2f}px per bar); {min_band_width:.0f}px is the threshold this configuration crosses, so bars will read as a merged block instead of separate marks.
```

**Fix:** Widen the chart (or, for a horizontal bar, make it taller), reduce the number of categories, or (for time series) roll up to a coarser grain (e.g. day -> week or month).

Fires on bar (vertical + horizontal) charts that pack so many bands into the plot's bounding dimension (width for vertical, height for horizontal) that each band's fill drops below a readability floor: the fill disappears and the bar's own border stroke merges neighbors into a "ghost band" smear. Classic trigger: daily-granularity data (hundreds of distinct days) rendered as bars at a normal chart size, or a grouped/wide bar whose per-series sub-band is too thin even though the outer band is not. Also fires on a numeric x (no band scale, vertical bars only) when the bar's width, authored or computed from gap/min_size/max_size, exceeds the gap between the closest two x values, so adjacent bars visually overlap.

### WARN-BAR-GROUPED-SERIES-COINCIDE: Grouped bar series paint on top of each other {: #warn-bar-grouped-series-coincide }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r}: {field!r} is quantitative (or a wide temporal range), so its color-grouped bars have no band scale to offset series within: every series paints at the same position, hiding all but the last one drawn.
```

**Fix:** Switch the x field to a categorical or bucketed-time column (so bars group side by side), or use a line/area/scatter mark, which already draw overlapping series legibly on a continuous x.

Fires when a color-grouped bar (color + stack: none) sits on a quantitative x, or a temporal x wide enough to promote to Vega-Lite's continuous temporal type. Vega-Lite's xOffset/yOffset sub-scale needs a discrete band to divide bars within; a continuous position has none, so every series paints at the identical position and width, each one occluding the series drawn before it. The render is unchanged by this warning: bar renders the same overlapping marks a line/area/scatter chart already draws on the same data, just without a legible way to tell the series apart.

### WARN-CALLOUT-TEXT-TRUNCATED: Callout text was truncated {: #warn-callout-text-truncated }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r}: callout {authored_field!r} was truncated: the authored text {authored_text!r} exceeded the maximum lines.
```

**Fix:** Shorten the callout text, or increase the chart height/width.

Fires when a callout chart's title, message, or hint text is wrapped and the last line is cut with a Unicode ellipsis because the text exceeds the maximum line count.

### WARN-CATEGORY-COLOR-PIN-UNSEEN: A category_colors pin names a value this render never draws {: #warn-category-color-pin-unseen }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
`style.charts.category_colors.{field}` pins {values}, which this render does not draw; the pin was skipped.
```

**Fix:** Check the value's spelling against the data. A pinned value can also be missing because a variable filter or a narrowed layout excluded it, not necessarily a typo.

Fires when a value pinned under `style.charts.category_colors.<field>` names something none of the charts on this render actually draw for that field. The pin is skipped rather than seated — seating it would claim a palette slot for a category nothing draws and push every real value along one — but a misspelled pin would otherwise do nothing with no signal at all. The value can be genuinely absent for reasons other than a typo: a variable filter, a narrowed `dct render --chart` layout, or a sibling chart whose query failed.

### WARN-CHART-TITLE-TRUNCATED: Chart title or subtitle was truncated with an ellipsis {: #warn-chart-title-truncated }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r}: {authored_field!r} was truncated: the authored text {authored_text!r} did not fit within the available width.
```

**Fix:** Shorten the title or subtitle, or widen the chart.

Fires when a chart title or subtitle is wrapped and the last line is cut with a Unicode ellipsis (…) because the authored text exceeds the available width. The message shows the full authored text before truncation.

### WARN-DUAL-AXIS-COMPETING-SCALES: Dual-axis chart plots two measures on independent scales {: #warn-dual-axis-competing-scales }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r}: {layer_col!r} is drawn against its own y-axis, separate from {base_col}. The two scales are set independently, so where the marks cross, which one sits higher, and how closely they track are artifacts of the axis ranges, not the data: readers will see a relationship that may not exist.
```

**Fix:** Show each measure in its own chart, stacked so they share the x-axis. To compare trends in one chart, index both series to a common start (e.g. 100) in the query so they share one axis; to show how one measure moves with the other, plot them as a scatter. If the second series is the same quantity in another unit (°F/°C, $/€), remove the layer and relabel the chart's opposite edge with `style.axis_y.mirror` and an `expr` that converts the value (for example `format(datum.value * 1.8 + 32, '.0f')`): one scale, two unit labels. Where the audience expects this form, list the code in the chart's `warnings_ignore:`. Both scales draw full-width gridlines, which interleave into an uneven ladder; set `axis_y.grid.visible: false` on the pinned layer to keep one set.

Fires on a layered chart where a layer is pinned to its own y-axis side, which gives it an independent y scale. A layer opts in by setting `axis_y.position`. The marks on the two scales are not comparable: crossings, relative height, and apparent correlation come from the axis ranges, not the data. Classic example: revenue bars with a headcount line on the right axis. A layer that sets only `axis_y.title` shares the base scale and never fires.

### WARN-ENDPOINT-LABEL-GAP-OVERFLOW: Endpoint-label rail is too cramped for its intended spacing {: #warn-endpoint-label-gap-overflow }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r} packs {series_count} endpoint labels needing {gap_px:.0f}px apart into a plot shorter than that: labels are distributed evenly across the plot instead of at their intended spacing.
```

**Fix:** Give the chart more height, reduce the number of series, or switch to a color legend instead of an endpoint-label rail.

Fires when an endpoint-label rail's intended gap (`font_size * constants.marks.ENDPOINT_LABEL_LINE_HEIGHT_MULTIPLIER`) cannot fit between the rail's series count and the plot's actual height. This is advisory, not a floor: the rail still renders, with labels distributed evenly across the available plot rather than piled onto the domain edges.

### WARN-ENDPOINT-LABEL-RAIL-OVERFLOW: Endpoint-label rail dropped series that had no room, despite fitting overall {: #warn-endpoint-label-rail-overflow }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r}: {dropped_count} of {series_count} endpoint labels could not be placed {gap_px:.0f}px apart and were dropped from the rail rather than piled onto the same spot.
```

**Fix:** Unlike a rail that is cramped everywhere, more height reliably helps here: it gives the clustered anchors room to spread apart from whichever series they crowded against. Reducing the series count or switching to a color legend also works.

Fires when an endpoint-label rail's real anchors are clustered such that some labels cannot be placed at the intended gap, even though `(n - 1) * gap` fits the plot height in the best case: that global check only proves the *block* of labels fits somewhere in the domain, not that the anchors' own positions leave room for all of them. Distinct from `WARN-ENDPOINT-LABEL-GAP-OVERFLOW`, which keeps every label and compresses the spacing instead: this fires only when some labels are dropped from the rail entirely.

### WARN-ENDPOINT-LABEL-RAIL-TIED: Endpoint-label rail has no spread to place labels along {: #warn-endpoint-label-rail-tied }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r}: all {series_count} series end on the same value, so the rail has no vertical spread to space labels by: they are distributed evenly across the plot instead of stacking on one point.
```

**Fix:** This is a property of the data, not the layout; more height will not change it. Check whether the trailing rows are null or zero for every series; if that is expected, a color legend names the series without implying distinct endpoints.

Fires when an endpoint-label rail's labels cannot be spaced because no pixels-per-data-unit could be measured from them: every series ends on the same value (a trailing all-null or all-zero column is the usual cause), or the y scale collapsed them onto a single pixel. Distinct from `WARN-ENDPOINT-LABEL-GAP-OVERFLOW`, which is a height problem: this one is a data property and adding height cannot clear it. Advisory, not a floor: the rail still renders.

### WARN-FACET-PANEL-WIDTH-BELOW-MINIMUM: Small-multiples panel width shrank below the legibility floor {: #warn-facet-panel-width-below-minimum }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r} facets into {panel_cols} column panel(s) at {panel_width:.0f}px each, below the {min_panel_px:.0f}px floor small multiples need to stay legible.
```

**Fix:** Widen the chart, reduce the column-facet's cardinality, or move part of the split from `multiples.columns` to `multiples.rows` (rows stack vertically instead of dividing the card's width).

Fires when a small-multiples chart's column-facet cardinality leaves each panel narrower than the configured legibility floor. The floor is `constants.layout.FACET_MIN_PANEL_PX`. The card's declared width is never negotiable, panels shrink below the floor rather than push painted content past the card's edge, so this is the author's only signal that the panel count has outgrown the card.

### WARN-FORMAT-UNUSED-NAME: style.formats name is defined but nothing uses it {: #warn-format-unused-name }

- **Level:** warning
- **Domain:** compile
- **Suppressible:** yes

**Message template:**

```
`style.formats.{name}` is defined but nothing uses it.{did_you_mean} To restyle an engine format, redefine its name (`number`, `currency`, `date_short`, ...).
```

**Fix:** Name it in a `format:` slot, redefine an engine name instead, or delete it.

Fires at compile time for a name this board file's own `style.formats` defines that no format slot on the board references and that is not an engine format name. The engine's names are the keys that restyle every chart (`number`, `currency`, `percent`, `date_short`, ...). A name inherited from `meta.yml` or `extends` never warns here, since a sibling board may use it. Emitted by `compile/validate/board_warnings.py`.

### WARN-KPI-ALIGN-OVERFLOW: KPI align was ignored because a text run overflowed the card {: #warn-kpi-align-overflow }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r}: a text run is wider than the card, so align: center/right was not applied; every run on the card stays left-aligned and the overflowing one spills past the right edge.
```

**Fix:** Widen the card, shorten the value with a more compact format, or drop align: so the left-aligned overflow is expected.

Fires when a KPI authors align: center or align: right and any of its text runs (value, label, or support) is wider than the available content width. Alignment is a whole-card choice, so it is dropped for every run rather than applied to the ones that fit: clamping per run would leave the card with two different alignments. Shifting the run would give it a negative x, and the card's SVG viewport clips at x=0; destroying the value's LEADING characters, so a right-aligned 1,234,567,890 would read as a well-formed but wrong 234,567,890. The renderer keeps the run at the left edge instead, where overflow spills right and reads as visibly truncated, and reports that the authored align did not take effect.

### WARN-KPI-INLINE-VARIANT-FALLBACK-TO-STACKED: KPI inline variant fell back to stacked {: #warn-kpi-inline-variant-fallback-to-stacked }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r}: style.variant: {authored_text!r} did not fit the card at the available width: value, label, and support fell back to the stacked arrangement instead of painting past the card edge.
```

**Fix:** Widen the card, shorten the label or support text, or author style.variant: stacked directly.

Fires when an inline KPI's assembled value + label + support run does not fit the card at its available width. The renderer falls back to the stacked arrangement for that card rather than paint past the card edge, so the card's actual layout no longer matches the authored style.variant: inline.

### WARN-KPI-LABEL-TRUNCATED: KPI card label was truncated {: #warn-kpi-label-truncated }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r}: KPI label was truncated: the authored text {authored_text!r} did not fit within the card at the available width.
```

**Fix:** Shorten the KPI label, widen the card, or use a smaller font size.

Fires when the KPI card label text is clipped or wrapped with an ellipsis because it exceeds the card width. The message shows the full authored label before truncation.

### WARN-KPI-SUPPORT-TRUNCATED: KPI card support line was truncated {: #warn-kpi-support-truncated }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r}: KPI support line was truncated: the authored text {authored_text!r} did not fit within the card at the available width.
```

**Fix:** Shorten the support label, widen the card, or use a smaller font size.

Fires when the KPI support explainer is cut with an ellipsis because the support row is wider than the card. The glyph and value stay whole; the message shows the full authored explainer.

### WARN-LAYER-DATA-OUTSIDE-DOMAIN: Layer data falls outside its authored y domain {: #warn-layer-data-outside-domain }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r}: layer {layer_col!r} has values from {data_min} to {data_max}, but its `axis_y.scale.domain` is [{lo}, {hi}], so the marks outside the domain are cut off at the plot edge.
```

**Fix:** Widen `axis_y.scale.domain` to cover the data, or filter the rows in the query. To let the marks run past the plot deliberately, set `axis_y.scale.clip: false` on the layer.

Fires on a layer whose authored y domain excludes some of the layer's own values while its clip is on, which is the default. Those marks are clipped at the plot edge, so the data they carry is not visible. Set `axis_y.scale.clip: false` on the layer to let them run past the plot.

### WARN-LAYER-X-DOMAIN-PAINT-ORDER: Layered chart x-axis is ordered by paint order, not by the data {: #warn-layer-x-domain-paint-order }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r}: layer queries contribute {n_new} x categor{plural} ({sample}) that the base query never returns on {x_field!r}, and there is no order the base states to place them into, so the axis is drawn base-query rows first, then each layer's, and the left-to-right reading order is paint order rather than an ordering the data states.
```

**Fix:** Return every x category from one query: join the layers onto a shared spine so the axis order is that query's. An authored `sort:` is not a fix: it orders only the categories the base query returns and leaves the layer's appended in paint order.

Fires on a layered chart whose typed layers contribute x categories the base query does not, either from their own `query:`, or from their own `x:` column on the shared one, when the engine cannot place them into an order the base states. Two shapes reach that: the categories have no derivable order at all (not dates, not numbers), or they do but the base query's own rows are not in it, so there is no direction to extend. Date-like buckets and numeric categories over a base already in that order are placed into it instead, and never warn. Plain labels (month abbreviations, region names) cannot be: the union is base-query order followed by each layer's own, which is the order the layers happened to be painted in. On the migrated shape this reads as a chronology it is not: `Jan, Mar, May, Feb, Apr, Jun`. Sorting them lexically would be worse than paint order, so the engine leaves the order alone and says so rather than guessing.

### WARN-LAYERED-CHART-SHARED-Y-AXIS-SCALE-MISMATCH: Layered chart y series have a large scale mismatch {: #warn-layered-chart-shared-y-axis-scale-mismatch }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r}: y columns {col_a!r} and {col_b!r} share a y-axis but their value ranges differ by {ratio:.0f}×: the smaller series will be visually crushed to a flat line.
```

**Fix:** Index the series to a common scale in the query (e.g. percent change, or 100 = first period), or show them as two charts stacked so they share the x-axis.

Fires on a layered chart where the base chart's own y series and/or its layers share the y-axis but their value ranges differ by ≥100×: the smaller series is visually crushed to a flat line. Classic example: revenue (millions) overlaid with conversion rate ([0, 1]).

### WARN-LAYOUT-MIN-EXCEEDS-HEIGHT: Chart's category count needs more height than its row allows {: #warn-layout-min-exceeds-height }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r} has {n_categories} category bands, which need at least {min_height:.0f}px to stay readable, but its row/tile height caps it at {authored_height:.0f}px. The chart rendered at {min_height:.0f}px anyway: the row's authored height was not honored, and any sibling charts sharing the row grew to match.
```

**Fix:** Raise the row's height to fit the category count, or reduce the categories (filter, paginate, or roll up to a coarser grain) so the readable minimum fits inside the authored height.

Fires when a horizontal bar chart's category count forces a minimum height (one readable band per category) that exceeds the row/tile height its author assigned. The engine expands the chart to the computed minimum regardless (squashing labels past legibility to honor an impossible authored height would be worse), so the row's authored height silently loses; any sibling chart in the same row inherits the expansion. This warns so the author learns why the row grew, instead of measuring it by hand.

### WARN-LEGEND-POSITION-WIDTH-FALLBACK: A narrow card overrode an authored legend edge {: #warn-legend-position-width-fallback }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r} authored `legend.position.edge: {authored_edge}`, but a card this narrow cannot hold a side legend, so it was placed on the `{resolved_edge}` edge instead.
```

**Fix:** Widen the chart, or drop `legend.position.edge` and accept the automatic placement.

Fires when a chart authors a `legend.position.edge` its card is too narrow to honor and the engine places the legend elsewhere. A cartesian chart (bar, line, area, scatter, heatmap) authoring a non-top edge on a card in the tiny width tier gets a compact top strip; a pie or donut authoring a side edge (`left` or `right`) gets its attached table below the wheel when the wheel region beside it would be too narrow. The fallback itself is not a defect (the card physically cannot fit a side legend); this warning exists only because the override was otherwise silent: the resolved chart renders a different legend position than the one the author wrote, with no signal that happened.

### WARN-LEGEND-VALUES-UNRESOLVED: style.legend.values entry does not resolve against the legend domain {: #warn-legend-values-unresolved }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r} authored `legend.values` entries {values} that did not resolve to exactly one legend entry. Legend domain: {domain}.
```

**Fix:** Check the spelling against the legend domain, or remove the entry if it's expected to be legitimately absent sometimes.

Fires when `style.legend.values` names an entry that matches none of the chart's legend entries, or matches more than one. The entry is dropped rather than shown or causing a render failure. If every authored entry misses, the legend falls back to its default order. Covers every nominal/ordinal `color:` field on bar, area, line, scatter, heatmap, and pie, a wide `y: [...]` chart, an overlay's `layers:` labels, and a geoshape choropleth. Not checked: `point_map`/`bubble_map` (no legend resolution there), a quantitative, temporal, or boolean `color:` column (`legend.values` is used exactly as authored, with no diagnostic on a miss), and an overlay whose base `y` is non-quantitative (its shared color scale is never built, so `legend.values` passes through verbatim).

### WARN-LIKELY-CURRENCY-OR-PERCENT-MISSING-FORMATTER: Field looks like money, a percentage or a fraction but has no fitting format {: #warn-likely-currency-or-percent-missing-formatter }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r}: field {field!r} looks like {kind} but the {surface} {format_state}.
```

**Fix:** Set `{format_key}` to {suggestion} to match the field's meaning.

Fires when a chart's y-encoding field, a KPI's headline or support value, or a table column looks like money or a percentage but its resolved format is unfit to render that kind (a KPI or table column warns only when its values are numbers). Detection is name-based: fields ending in _usd, _revenue, _amount, _pct, _rate, etc. (or bare names like `share`, `mrr`) trigger when the resolved y-axis format is unfit for that kind. A percent-classified field needs a `%` in the resolved format or in an authored FormatConfig prefix/suffix (a column already in percent points, `suffix: '%'`, is labeled); any other affix does not satisfy it. A currency-classified field is satisfied either by a `$` in the resolved format OR by an authored FormatConfig prefix/suffix (e.g. `€`, `EUR `) with no `$` anywhere: d3's grammar admits only `$`/`#` as a spec's own symbol character, so a non-dollar currency can only ever reach the axis through that authored affix. The fix suggests the dollar spec (`$,.2f`), except for a currency-classified field whose trailing `_<code>` names a currency dbt Charts recognizes (`_eur`, `_gbp`): it suggests `,.2f` with `prefix: '€'` (that currency's own symbol). A visible table column warns when it has no number format and its name looks like money or a percentage, or, whatever its name, its non-null values are all numbers between 0 and 1 and not all exactly 0 or 1 (a flag): left unformatted it renders as a bare fraction (0.4367 shows as `0.4367`, not a percentage). The fix is to set `style.columns.<name>.format`, e.g. `.1%`; a KPI takes `style.value.format` or `style.support.format`. Pivot measure columns are not checked.

### WARN-LOCAL-TIME-LABEL-EXPR-ON-BUCKETED-AXIS: Authored axis label expression uses local time on a bucketed axis {: #warn-local-time-label-expr-on-bucketed-axis }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r}: axis_x.labels.expr calls {accessor}(), which reads datum.value in the render process's time zone. Static rendering pins that to UTC, so the {time_unit!r} bucketing's UTC-midnight tick values resolve in UTC today, not necessarily the zone you or the chart's viewers are actually in, and dbt charts has no way to render this in a different zone.
```

**Fix:** Replace local-time accessors with their utc-prefixed equivalents (utcFormat()/utcyear()/utcmonth()/...), e.g. utcFormat(toDate(datum.value), '%b %Y'), to make the UTC result explicit instead of implying a local-time read that never happens.

Fires on bar (vertical + horizontal, single-metric + multi-metric), line, and area charts when axis_x.labels.expr contains a local-time accessor (timeFormat(), year(), month(), date(), quarter(), ...) while the chart's x-axis buckets to a UTC-midnight calendar grain (yearmonth, yearquarter, year, ...), whether authored via axis_x.time_unit or auto-detected from the query data. Vega-Lite's bucketed timeUnit transform produces UTC-midnight Date values, and dbt charts always renders statically in UTC, so a local-time accessor reads them as UTC today, the same result its utc-prefixed equivalent would give, and no longer dependent on which machine renders the chart. It still cannot be made to read in a different zone: there is no per-board or per-viewer timezone setting today, in any dbt charts surface. Heatmap and scatter are not yet covered. dbt charts never rewrites an authored label expression, so this only warns; switch to utcFormat() or utcmonth()/utcyear()/... to say what actually happens.

### WARN-NORMALIZE-PERCENT-FORMAT-READS-RAW-VALUE: Percent format on a 100% stack formats the raw value, not the share {: #warn-normalize-percent-format-reads-raw-value }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r}: percent format {format!r} formats the raw {field!r} value, not the share the normalized stack paints: one stack group's values sum to {total}, not 1, so the hover rows and the value labels multiply a raw number by 100 and print it as a percentage.
```

**Fix:** Drop the percent format (a normalized stack already labels its axis 0-100%, so the format never reaches that axis), or make the measure a real 0..1 share in SQL by dividing each value by its group's total, so the raw value and the painted share are the same number.

Fires when a bar or area chart resolves to `style.stack: normalize`, its measure carries a percent format, and the raw y values in some stack group do not already sum to about 1. The normalized stack pins the measure axis to 0-100% itself, so an authored format never reaches that axis; it reaches the hover rows, the printed value labels, and the stack-total label, and every one of those reads the RAW column value. A count of 20 under a percent format therefore prints as `2000%`. Both authoring doors reach the same baked format and both fire: the query's `formats:` and an authored `style.axis_y.labels.format`. A chart whose measure is already a 0..1 share, every group summing to about 1, is the honest case and never fires: there the raw value and the painted share are the same number. A non-percent format (currency, plain digits) never fires either: it prints the true raw number, and only its unit differs from the axis. A stack group summing to 0 is not judged at all, since a share is undefined at a zero total. `stack: zero` and `stack: center` are not judged either: an absolute stack labels its axis with that same authored format, so the chart is self-consistent. Small multiples are judged one panel at a time, since a normalized stack normalizes within a panel. The render is unchanged by this warning.

### WARN-PALETTE-UNSUPPORTED: Palette name is a known anti-pattern {: #warn-palette-unsupported }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r}: palette {requested!r} is a known anti-pattern; resolved to {resolved} instead.
```

**Fix:** Author a supported palette name; see the anti-patterns table in docs/guides/palette-resolver.md#anti-patterns.

Fires when a chart authors a palette name on the known anti-pattern list (e.g. 'RdYlGn', 'parula'); these are CVD-hostile or superseded by a dbt-charts-native palette. palette() resolves the substitute silently at compile time; this detector is the only place the nudge surfaces.

### WARN-PIE-DOMINANT-SEGMENT: Pie chart is dominated by a single segment {: #warn-pie-dominant-segment }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Pie chart {chart_id!r}: {dominant_field!r} holds {dominant_share:.0%} of the total; the chart conveys a single value.
```

**Fix:** Use a KPI chart for the dominant share and a bar or table for the breakdown, rather than a pie dominated by one slice.

Fires on pie/donut charts where one slice is so large that the chart conveys a single value; the other slices are visually negligible. A near-single-value pie should be a KPI (the dominant share) plus a breakdown elsewhere.

### WARN-PIE-TOTAL-EXCEEDS-INNER-RADIUS: Donut center total is too wide for the hole {: #warn-pie-total-exceeds-inner-radius }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Donut chart {chart_id!r}: center total {formatted_value!r} is {text_width:.1f}px wide but the hole is only {hole_diameter:.1f}px across (slot {slot_width:.0f}×{slot_height:.0f}px).
```

**Fix:** Use a compacting number format (e.g. `format: number`) to shorten the total, or enlarge whichever slot dimension is smaller so the hole diameter increases.

Fires on donut charts whose formatted center total is wider than the hole it sits in, measured with the engine's font measurer. The hole diameter is `min(slot_width, slot_height) * outer_fraction * inner_radius`, where the slot is the plot box the wheel draws in, after the slice labels' reach and any legend.

### WARN-PLOT-HEIGHT-BELOW-MINIMUM: Chart chrome squeezes the plot below its readability floor {: #warn-plot-height-below-minimum }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r} squeezes its plot to an estimated {plot_height:.0f}px on a {card_height:.0f}px card, below the {floor_px:.0f}px floor it needs to stay readable.
```

**Fix:** Give the chart more height, drop authored chrome that is not earning its space here (subtitle, axis titles, a high-cardinality legend), or accept the smaller size deliberately and suppress this warning per-chart with `warnings_ignore`.

Fires when a bar chart's estimated plot height falls below its calibrated readability floor. The floor is `constants.layout.PLOT_HEIGHT_FLOOR_RATIO` of the card's own height, checked at every width: a short, wide card carrying heavy chrome starves its plot the same way a narrow one does. ERR-CHART-PAINTED-NO-MARKS already hard-fails around 247px, where marks paint with zero extent; this covers the band above it where the chart still renders but its plot has shrunk to a squashed sliver. No chrome is removed automatically to fix this: the author decides whether to widen the card, trim what they authored, or keep the chart small on purpose.

### WARN-PLOT-WIDTH-BELOW-MINIMUM: A support_table column block claims most of the card's width {: #warn-plot-width-below-minimum }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r}: the support_table column block ({block_width:.0f}px) already claims most of the {card_width:.0f}px card, leaving the plot an estimated {plot_width:.0f}px.
```

**Fix:** Drop a support_table column, widen the card, or move the block to `position: right` — or accept it deliberately and suppress this warning per-chart with `warnings_ignore`.

Fires when a horizontal bar's support_table column block already claims more than `constants.layout.SUPPORT_TABLE_COLUMN_BLOCK_SHARE_WARN_RATIO` of the width it shares with the plot, measured from the column block's own font-measured reservation before any further axis-label or legend chrome is subtracted. The missing twin of WARN-PLOT-HEIGHT-BELOW-MINIMUM: no chrome is removed automatically — the author decides whether to widen the card, drop a column, or move the block. A plot that would fall below its readability floor once the remaining axis chrome is accounted for raises ERR-INPUT-INVALID instead of warning: a zero-width plot is a missing chart, not a squeezed one.

### WARN-POINT-MAP-NEGATIVE-SIZE-VALUES: Point map size measure has negative values {: #warn-point-map-negative-size-values }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Point map {chart_id!r}: {dropped_count} of {total_count} points have a negative {size_field!r} value and were not drawn; mark area cannot be negative.
```

**Fix:** Size by a magnitude instead of a signed value (e.g. `size: abs({size_field})` in the query) and encode direction with a diverging `color:` instead.

Fires when a bubble_map's `size:` measure contains negative values. Mark area cannot be negative, so rows with a negative size value are dropped before Vega-Lite sees them rather than drawn at the smallest visible size; a negative value clamped to the scale's zero floor would read as "nearly zero", misrepresenting a large-magnitude negative measurement. Size by a magnitude (e.g. `abs(...)` in the query) and encode direction with a diverging `color:` instead. A zero-valued row is legitimate data with a legitimate area of nothing and is never dropped or counted here.

### WARN-POINT-MAP-OUT-OF-PROJECTION: Point map has data outside the projection boundary {: #warn-point-map-out-of-projection }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Point map {chart_id!r}: {dropped_count} of {total_count} points are outside the {projection!r} projection boundary and were dropped.
```

**Fix:** Filter the data to the projection's region, or switch to a projection that covers the full data extent.

Fires when a point_map chart uses a bounded projection (e.g. albersUsa) and some data points fall outside its mapped region. The emitter drops those rows from spec.data before Vega-Lite sees them; this warning reports how many points were dropped and why.

### WARN-QUERY-RESULT-TRUNCATED: Chart query result truncated {: #warn-query-result-truncated }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
{subject}: query result exceeded the {reason} limit; truncated to {kept_row_count} rows.
```

**Fix:** Add a LIMIT to the query, narrow its filters, or raise execution.max_rows/max_result_bytes in dbt_charts.yml if the full result is genuinely needed.

Fires when a query's result exceeded the execution.max_rows or max_result_bytes safety ceiling and was truncated before it ever reached the result cache. The chart still renders with the truncated data; this is a safety net against an unbounded query exhausting memory or bloating the cache, not a hard error.

### WARN-QUERY-RETURNED-ZERO-ROWS: Chart query returned zero rows {: #warn-query-returned-zero-rows }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r}: query returned zero rows.
```

**Fix:** Check the WHERE clause or date filter: it may be excluding all data for the current filter values.

Fires on any chart whose query returned zero rows. An empty chart renders as a blank panel with axes; no signal to the viewer that the query returned nothing. Most common cause: a WHERE clause or date filter that excludes all data.

### WARN-REDUNDANT-ENCODING: Same column bound to two visual channels {: #warn-redundant-encoding }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r}: field {field!r} is bound to channels {channels}: binding the same field twice adds no information.
```

**Fix:** Remove one of the channel bindings, or use different fields for each channel to encode distinct dimensions.

Fires when one query column is bound to two or more visual channels of the same chart (e.g. `y` and `color` both set to the same field), or when a `multiples.rows`/`multiples.columns` facet field is also bound to `x` or `y`. Binding the same field twice adds no information; the second channel is redundant, and for a facet collision, the axis repeats what the panel's own header already says. The bar `x==color` case is excluded: it renders full-width category-colored bars, a useful pattern. Faceting by a field also bound to `color`/`size`/`shape` is excluded too: those legends are drawn once, board-wide, never duplicated per panel, so pairing one with the facet gives every panel a consistent identifying color at no extra cost.

### WARN-SERIES-LABEL-TRUNCATED: Series label was too long for the endpoint-label rail and was truncated {: #warn-series-label-truncated }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r}: {count} series {labels_noun} from {authored_field!r} {were} truncated in the endpoint-label rail, which is capped at a fraction of the chart's width: {labels}.
```

**Fix:** Shorten the {authored_field} values, widen the chart, or set style.endpoint_labels.visible: false to keep the series names in the legend.

Fires when a chart's series labels are drawn in the right-hand endpoint-label rail and do not fit. The rail may claim only a fraction of the chart's width, so longer names are cut with an ellipsis (…). The labels are the values of the column bound to `color:`; for a wide-form chart authored `y: [a, b, …]`, the measure names themselves, prefixed by the `color:` column's value (`<value> - <measure>`) when one is authored; the warning names whichever key holds the long part. The label text in the message is the full value before truncation, so you can see exactly what was cut. Only the drawn label is shortened: the underlying values, the color scale, and tooltips still carry the full text.

### WARN-SERIES-LABELS-REPEAT-WORD: Every series label repeats the same word {: #warn-series-labels-repeat-word }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r}: every {authored_key!r} series label repeats {repeated}: {labels}.
```

**Fix:** {once} Tighter labels: {shortened}. Alias the query column for a wide `y: [...]` chart (`SELECT ... AS created`), or shorten the `color:` column's own values for a long-form chart. Keep the repeat only when a label would be unclear without it.

Fires when every series label of a multi-series chart shares a leading or trailing word: 'Documents Created' / 'Documents Completed' makes the reader parse 'Documents' once per label to learn nothing, and widens the label rail. A word every series shares describes the chart, not a series, so it belongs in the title or y_label. The fix text adapts: when the title or y_label already says the word it advises dropping it, otherwise moving it there. `color:` values only fire when the title or y_label already says the word, since a shared word in a data value is often part of the name ('North America' / 'South America'). Words under three characters or without a letter (the year of a date-valued column) are ignored, and nothing fires when a tightened label would be under three characters ('Region A' -> 'A') or no longer distinct. Labels are the humanized measure names for a wide `y: [a, b]` chart, or the distinct `color:` column values for a long-form chart; a wide chart also authoring `color:` is skipped, since its labels are '<value> - <measure>' composites. The detector only reports -- it never rewrites a label itself.

### WARN-SPARK-LABEL-TRUNCATED: Spark-bar row label was truncated {: #warn-spark-label-truncated }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r}: {truncation_count} spark-bar label(s) were truncated; the label column is too narrow to show the full text.
```

**Fix:** Widen the chart or increase the label column width in the chart style.

Fires when one or more spark-bar row labels are truncated because the label column is too narrow to fit the full text. One warning fires per chart with any truncated labels.

### WARN-STATIC-PAGINATION-CAPPED: Static export stopped short of every table page {: #warn-static-pagination-capped }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Table {chart_id!r}: static export pre-rendered {rendered_pages} of {total_pages} pages ({page_rows} rows each, {total_rows} rows total); rows past page {rendered_pages} are not in this file.
```

**Fix:** Reduce the row count, raise style.pagination.page_rows so fewer pages are needed, give the table a taller slot, or view it on an interactive host (dct serve, Cloud) instead of a static export.

Fires when a static export (dct render --format html/svg/png) has a table with more pages than the renderer will pre-draw AND its slot is too short for the note that says so inside the file. A static export ships no JS runtime that can ask a server for another page, so every page's rows are pre-rendered into the artifact as toggle groups; left uncapped, that makes file size scale with total row count instead of page size. Past the cap the artifact shows only the first N pages. When the slot has room, the file states the cap itself and nothing fires; the text format states the page counts and never fires.

### WARN-SUPPORT-TABLE-CELL-OVERFLOW: Support table cells are wider than their band {: #warn-support-table-cell-overflow }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r}: support_table cells ({detail}) are wider than the space between neighboring categories, so adjacent values run together.
```

**Fix:** Widen the chart, show fewer categories, or shorten the values with a more compact format.

Fires when the widest formatted cell in a support_table row, plus the row's horizontal padding, is wider than one category band. Every cell is drawn at its own band, so neighbors collide and read as one number (6.7, 19.2, 20.4 becoming 6.719.220.4). The render is unchanged by this warning. It is skipped when the strip is already thinned to the axis's label periods.

### WARN-TABLE-COLUMNS-OVERFLOW: Table is wider than its dashboard slot {: #warn-table-columns-overflow }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Table {chart_id!r} overflows its slot: needed {needed_width:.0f}px but only {available_width:.0f}px available.
```

**Fix:** Widen the table's dashboard slot, reduce the number of columns, or add explicit column widths to control how the table distributes its available space.

Fires when a table needs more width than the slot it was given. A table sizes each column to its minimum readable width; when those widths sum past the available width, the renderer clips the table at its slot's edge, so the columns past it are not shown.

### WARN-TABLE-CRAMPED: Table columns were cramped under their width demand {: #warn-table-cramped }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Table {chart_id!r} is cramped: {wrapped_headers} of {column_count} column headers wrapped onto a second line. Columns need {needed_width:.0f}px but have {available_width:.0f}px.
```

**Fix:** Set the board's style.frame.width to about {suggested_width:.0f}px, widen the table's slot, drop columns, or set explicit pixel column widths.

Fires when a table still fits its box widthwise but only because the renderer degraded it: the columns were divided into less than their content demanded and headers were forced onto a second line. Distinct from WARN-TABLE-COLUMNS-OVERFLOW, which is the physical case where columns cannot fit at all and the table paints past its slot; from WARN-TABLE-TEXT-TRUNCATED, which fires only once text is actually cut with an ellipsis; the last rung of the same ladder; and from WARN-TABLE-PAGE-SQUEEZED, the height axis, where the slot cuts the rows-per-page down and the fix is to grow the slot rather than the width.

### WARN-TABLE-PAGE-SQUEEZED: Layout slot forced a smaller table page than the table asked for {: #warn-table-page-squeezed }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Table {chart_id!r}: the layout slot fits {drawn_rows} of the {page_rows} rows a page holds ({total_rows} rows total); the rest moved onto later pages.
```

**Fix:** Give the tile more height (layout height:, a taller row, or fewer siblings sharing the row), or set `style.pagination.page_rows: {drawn_rows}` to page at what the slot fits. page_rows is a ceiling: raising it does not make the slot taller.

Fires when a pinned layout slot (explicit height, grid row, equalized siblings) fits fewer rows than the table's page_rows, so the paginator draws fewer rows per page and the export photographs as a faithful table showing a fraction of its rows. An auto-sized tile is measured by the renderer and always fits its page; page_rows: null never warns. Paginating because the data is longer than the page is not this warning.

### WARN-TABLE-TEXT-TRUNCATED: Table column header or cell text was truncated {: #warn-table-text-truncated }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r}: truncated text in column(s) {authored_field}: {truncation_count} value(s) were cut with an ellipsis.
```

**Fix:** Widen the column, shorten the values, or increase the chart width.

Fires when a table column header or one or more cell values are clipped with an ellipsis because they exceed the column width. One warning fires per table; each truncated column is a related location.

### WARN-TEMPORAL-SINGLE-POINT: Temporal line or area chart has only one data point {: #warn-temporal-single-point }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r} ({chart_type}): temporal x-axis has exactly one data point; a one-point line/area conveys no trend.
```

**Fix:** Widen the date filter to include more time periods, or switch to a KPI or stat tile if a single-point value is intentional.

Fires on line and area charts where the x-axis is temporal and the query result has exactly one row. A one-point line is rendered as a single dot; a one-point area is a vertical line. Both render but convey nothing about a trend; this almost always means the date filter is too narrow.

### WARN-TOO-MANY-COLOR-CATEGORIES: Color encoding has more categories than a reader can tell apart {: #warn-too-many-color-categories }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r}: color encoding on {field!r} yields {count} distinct series, more than the {max_categories} a reader can tell apart.
```

**Fix:** Reduce the number of color categories by grouping small values into 'Other', or filter the data to the most significant categories.

Fires when a categorical color encoding has more distinct values than the larger of the chart's palette length and eight; past that a reader cannot match legend entries to marks, and a short palette recycles colors. A handful of series on a short palette stays quiet. The message states the series count and the threshold. Gated on the Vega-Lite color encoding type so a continuous (quantitative) color gradient never trips it. A wide chart (y: [a, b]) is counted by the series its fold renders -- the measures, crossed with the color: dimension's values when one is authored.

### WARN-TOO-MANY-X-CATEGORIES: x-axis has too many distinct values to read {: #warn-too-many-x-categories }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r}: x field {field!r} has {count} distinct values; labels collide and marks are too thin to read (limit: {max_categories}).
```

**Fix:** Filter to the top N categories by value, roll up to a coarser grouping, or switch to a scrollable table for wide categorical data.

Fires when a categorical (nominal/ordinal) x-axis has more distinct values than fit legibly; labels collide and the marks are too thin to read. For a bar chart, also fires on a temporal x-axis: bars still draw one band per distinct x value even where the density gate has moved bucketed temporal data off the ordinal scale. On that axis the warning is about band width only: a temporal axis thins its own tick labels, so nothing is claimed about label collision, and the fix is to widen the chart, roll up to a coarser time grain, or switch to a line chart. Never fires on a quantitative axis, or on a temporal axis for line/area/scatter charts, where a dense axis is a continuous draw, not a crowded band.

### WARN-UNREFERENCED-CHART: Chart is defined but not placed in any layout {: #warn-unreferenced-chart }

- **Level:** warning
- **Domain:** compile
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r} is defined but not referenced in any layout (rows/cols/grid/tabs). It will not appear in the rendered dashboard.
```

**Fix:** Add the chart to a layout block, or delete it if it is no longer needed.

Fires at compile time for charts that are defined somewhere in the board tree but never placed in any layout (rows/cols/grid/tabs). The board still compiles because content-only boards are valid; this warning surfaces lazy authoring: an author defined a chart and forgot to display it. Emitted by `compile/validate/board_warnings.py`.

### WARN-VALUE-LABELS-CROWD-WIDTH: Value labels are wider than their per-mark slot {: #warn-value-labels-crowd-width }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r}: widest value label is {label_width:.0f}px but each mark only has {slot_width:.0f}px; labels will overflow and collide with neighbors.
```

**Fix:** Shorten the number format (e.g. use SI suffix `.2~s` instead of full precision), reduce the number of labeled marks, or widen the chart.

Fires when a chart's value labels are wider than the horizontal room each one gets. Value labels are drawn at the mark, fixed size, with no adaptive avoidance, so they are the label kind that genuinely overflows. The check uses the panel's real rendered width and font metrics; it fires exactly when the widest label is wider than its slot.

### WARN-WIDE-MEASURE-LABEL-COLLISION: Two wide y: measures humanize to the same legend label {: #warn-wide-measure-label-collision }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r} authors y: measures {measures}, which all show the label {label!r}. Each is now shown under its own column name instead.
```

**Fix:** Author distinct `y:` column names, or rename one of them in the query so they no longer produce the same label.

Fires when two or more measures in a wide chart's y: list produce the same legend and axis label. For example, `churn_pct` and `churn_percent` both read `churn (%)`. Each colliding measure is shown under its own column name instead, keeping them as separate series. Other measures in the list are unaffected.

### WARN-Y-ENCODING-MOSTLY-NULL: Y-encoding field is mostly NULL in the query result {: #warn-y-encoding-mostly-null }

- **Level:** warning
- **Domain:** render
- **Suppressible:** yes

**Message template:**

```
Chart {chart_id!r}: y field {field!r} is {null_pct:.0%} NULL across {row_count} rows.
```

**Fix:** Check for a broken join or a nullable source column. A COALESCE or WHERE clause may be needed to filter the empty rows.

Fires on any chart where the y-encoding field is more than 50% NULL in the query result rows. Mostly-empty visual marks with no explanation usually indicate a broken join or a nullable source column. NULL-only differs from NULL+zero: zero is a valid measurement.

## layout


### WARN-FLAT-COLS-UNSIZED-OVERFLOW: Flat cols: row has too many unsized non-KPI cells {: #warn-flat-cols-unsized-overflow }

- **Level:** warning
- **Domain:** compile
- **Suppressible:** yes

**Message template:**

```
cols: has {growable_count} unsized non-KPI cells (max recommended {max_unsized}). Each inherits the row's full vertical budget, so a wide flat row makes row height unpredictable. KPI cards are height-stable and don't count.
```

**Fix:** Nest cells into sized rows-in-cols groups instead, e.g.:
  cols:
  - width: "17%"
    rows:
      - kpi_a
      - kpi_b
  - width: "55%"
    rows:
      - hero

Fires when a flat `cols:` row has more unsized non-KPI cells than the recommended limit. Each unsized cell inherits the row's full vertical budget, making row height unpredictable with many columns. KPI cards are carved out because they are height-stable. Emitted by `compile/validate/authoring_warnings.py`.

### WARN-INHERITED-LAYOUT-REPLACED: A board's own layout or tags replace the inherited ones {: #warn-inherited-layout-replaced }

- **Level:** warning
- **Domain:** compile
- **Suppressible:** yes

**Message template:**

```
`{field}:` {replacer} replaces {inherited} inherited from {source}.
```

**Fix:** To keep the inherited items, move the shared parts into a partial and import it from both boards.

Fired when a `meta.yml`, an extended board or the board itself sets `rows:`, `cols:`, `grid:`, `tabs:` or `tags:` over a non-empty value a lower layer set. The closer value replaces it; nothing is appended.

## queries


### WARN-COLUMN-CHECK-UNAVAILABLE: Column check unavailable on this adapter {: #warn-column-check-unavailable }

- **Level:** warning
- **Domain:** execute
- **Suppressible:** yes

**Message template:**

```
Column check unavailable on {adapter_type} ({mechanism} validates the query but returns no result schema).
```

**Fix:** Chart column checks need a schema-bearing mechanism (DuckDB, BigQuery dry run). Verify chart columns against a sample run, e.g. dct query <board> <name>.

Fired during `dct validate --warehouse` when the adapter can validate that the query is accepted by the warehouse but cannot return a result schema, so chart channel column checks are skipped. Use a DuckDB or BigQuery source for full column verification.

### WARN-DATE-AS-TEXT: A charted x column is a date the query turned into text {: #warn-date-as-text }

- **Level:** warning
- **Domain:** query
- **Suppressible:** yes

**Message template:**

```
Query {query_name!r}: {message}
```

**Fix:** Return the date itself (with date_trunc for a grain) instead of formatting it; the axis labels dates by grain. For a month-of-year or day-of-week category, return the month or weekday name.

Fires when a column some chart uses as its x is a date or timestamp wrapped in a formatting call (`strftime`, `to_char`, `to_varchar`, `format_date`, `format_timestamp`, `format_datetime`, `date_format`, SQL Server `FORMAT`) or cast to a text type. Text has no time scale, label thinning, or gaps for missing periods, so the chart draws it as categories.

The warning needs evidence that the input is temporal. Functions that take only dates (`strftime`, `format_date`, `format_timestamp`, `format_datetime`, `date_format`) count on the format alone. Functions that also format numbers (`to_char`, `to_varchar`, SQL Server `FORMAT`) and casts to text count only when the value is evidently a date: a `date_trunc`/date function, a date literal, a cast to a date type, or a column named like a date (`created_at`, `order_date`, `ts`).

A month or weekday name alone stays quiet (`%b`, `%A`, `Mon`, `FMDay`, `DATENAME(month, d)`, `monthname(d)`): that is a deliberate seasonality category. Any other format warns, including a month or hour number alone.

When the format or the `date_trunc` unit is not a literal, the warning still fires but leaves the format and grain out of the message.

The detector reads the query's own SELECT list, for columns charted as x by a chart or one of its layers. A date made text in a CTE, view, or dbt model is not seen.

### WARN-DBT-MANIFEST-MISSING: Queries use dbt macros but no manifest was found {: #warn-dbt-manifest-missing }

- **Level:** warning
- **Domain:** execute
- **Suppressible:** yes

**Message template:**

```
Queries use {kind} but no dbt manifest was found (looked for {paths}); refs were not validated.
```

**Fix:** Run 'dbt parse' in the dbt project.

Fired once per manifest path, per validate run and per board render, when one or more queries call ref() or source() but no manifest is present at that path. The refs were not checked against the manifest. Run 'dbt parse' to generate target/manifest.json; a source that sets `target_path:` is looked up at `<target_path>/manifest.json`.

### WARN-DBT-MODEL-COLUMNS-UNRESOLVED: A dbt model's output columns could not be derived statically {: #warn-dbt-model-columns-unresolved }

- **Level:** warning
- **Domain:** execute
- **Suppressible:** yes

**Message template:**

```
Query {query_name!r} reads dbt model {model!r}, whose output columns could not be derived from its SQL ({reason}); column references against it were not checked.
```

**Fix:** The reason names what blocks static derivation (a `SELECT *` wants explicit projections; an unaliased cast or expression wants an alias; seeds and snapshots are never derivable); the columns can always be verified with `dct validate --warehouse` after `dbt run`.

Fired when a board query reads a dbt model whose output columns cannot be derived statically from its manifest SQL: a `SELECT *`, a macro in projection position, a snapshot (dbt injects meta columns at build time), or SQL that does not parse. Reported rather than silently skipped: an unchecked column reference is not a verified one.

### WARN-DBT-QUERY-COLUMNS-INDETERMINATE: A query's dbt column references could not be determined {: #warn-dbt-query-columns-indeterminate }

- **Level:** warning
- **Domain:** execute
- **Suppressible:** yes

**Message template:**

```
Query {query_name!r} uses dbt ref()/source() but the columns it reads could not be determined ({reason}); they were not checked against the dbt models.
```

**Fix:** The reason names what blocks the analysis (a `SELECT *` wants explicit columns; a templated identifier is decided at render time); the query can always be verified with `dct validate --warehouse` after `dbt run`.

Fired when a board query that calls ref()/source() cannot be statically analyzed for the (table, column) pairs it consumes: a `SELECT *`, a templated identifier, an ambiguous unqualified column, or SQL that does not parse. The model-column drift check makes no claim either way for such a query; this warning keeps that gap visible instead of passing it in silence. Queries with no dbt calls are out of scope; the SQL lint tiers own those.

### WARN-MISSING-JOIN-PREDICATE: Join is missing a predicate and may produce a cross join {: #warn-missing-join-predicate }

- **Level:** warning
- **Domain:** query
- **Suppressible:** yes

**Message template:**

```
Query {query_name!r}: {message}
```

**Fix:** Add an ON clause that relates the tables, or join a source that returns one row (an aggregate with no GROUP BY, or LIMIT 1).

Fires when query validation detects a CROSS JOIN, a comma join, or a join on a constant (`ON TRUE`, `ON 1 = 1`) between two sources that can each return many rows. That multiplies every row of one by every row of the other; it almost always means a missing ON clause.

A source that returns one row by construction never multiplies rows, so a join against it stays quiet: a subquery or CTE that aggregates with no `GROUP BY`, a `SELECT` with no `FROM`, or a `LIMIT 1`. So does a table function such as `generate_series`. A filter that merely happens to match one row does not count. Emitted by `validate_compiled_queries` via the query validator.

### WARN-PARSE-ERROR: SQL query could not be parsed for semantic validation {: #warn-parse-error }

- **Level:** warning
- **Domain:** query
- **Suppressible:** yes

**Message template:**

```
Query {query_name!r}: {message}
```

**Fix:** Check the SQL syntax. The query may still execute, but semantic validation (reaggregation, missing join predicates) cannot run on unparseable SQL.

Fires when a SQL query cannot be parsed as a structured AST. The query may still execute against the warehouse; this warning surfaces that semantic validation (reaggregation, missing join predicates) cannot run on unparseable SQL. Emitted by `compile()` for authored queries whose dialect resolves and whose failure carries a specific position.

### WARN-REAGGREGATION: Grouping-dependent aggregate applied on top of an aggregated input {: #warn-reaggregation }

- **Level:** warning
- **Domain:** query
- **Suppressible:** yes

**Message template:**

```
Query {query_name!r}: {message}
```

**Fix:** Compute the aggregate once over the underlying rows, or carry the SUM and COUNT up and divide them in the outer query.

Fires when an outer query applies an aggregate whose result depends on how rows were grouped to a column that a CTE or subquery already aggregated: `AVG`, `MEDIAN`, or a percentile over any aggregate, and `SUM` over an `AVG`, `MEDIAN`, or percentile, and any `DISTINCT` aggregate, which collapses equal pre-aggregated values. An average of averages weights every group equally, so it differs from the average of the underlying rows. The message names both functions, for example `AVG over AVG`. Emitted by `validate_compiled_queries` via the query validator.

Pairs that compose exactly stay quiet: `SUM` or `COUNT` over `SUM` or `COUNT`, `MAX` over `MAX`, and `MIN` over `MIN`. So do window functions (`LAG`, a running `SUM(...) OVER`), which run per row, and aggregates with a `FILTER (WHERE ...)` clause, which pick a subset of rows.

### WARN-WAREHOUSE-CHECK-UNAVAILABLE: Warehouse check unavailable on this adapter {: #warn-warehouse-check-unavailable }

- **Level:** warning
- **Domain:** execute
- **Suppressible:** yes

**Message template:**

```
Query '{name}' was not checked: {reason}.
```

**Fix:** The query is unverified, not verified. Check it against a source with a check mechanism (DuckDB, BigQuery, Postgres, Redshift, Snowflake), or run it directly, e.g. dct query <board> <name>.

Fired during `dct validate --warehouse` when a query could not be checked without running it at full cost: the adapter offers no mechanism (DESCRIBE, EXPLAIN, or a dry run), the query composes another query's cached result, or the warehouse was never reached. The query is reported as unchecked rather than valid: nothing inspected the SQL. `--warehouse` will never run the query itself to find out.

## variables


### WARN-REDUNDANT-AUTHORED-DEFAULT: Variable field is explicitly set to its default value {: #warn-redundant-authored-default }

- **Level:** warning
- **Domain:** compile
- **Suppressible:** yes

**Message template:**

```
Variable {var_name!r} explicitly sets {field_name} to the default value {default_value!r}.
```

**Fix:** Omit `{field_name}:` when the default is intended.

Fires when a variable explicitly sets a field to its default value. The explicit setting is redundant and adds noise without changing behavior. Emitted by `compile/validate/authoring_warnings.py`.

### WARN-REDUNDANT-AUTHORED-LABEL: Variable label is the same as the inferred display name {: #warn-redundant-authored-label }

- **Level:** warning
- **Domain:** compile
- **Suppressible:** yes

**Message template:**

```
Variable {var_name!r} sets label to {authored_label!r}, which is already inferred from the variable name.
```

**Fix:** Omit `label:` unless the display label should differ from the inferred name.

Fires when a variable's authored `label:` is exactly the same as the label dbt charts would infer from the variable name (title-cased, underscores to spaces). The explicit label is redundant and can be omitted. Emitted by `compile/validate/authoring_warnings.py`.

# Editor Keybindings (https://docs.dbtcharts.com/reference/editor-keybindings/)

# Editor Keybindings

The YAML editor (Dashboard editor and Playground) offers a VSCode-parity keymap: standard
editing, multi-cursor selection, and undo/redo bindings on top of the YAML+SQL syntax
highlighting and completions.

Bindings below use `Mod`, which resolves to `Cmd` on macOS and `Ctrl` on Windows/Linux.

## Editing

| Binding | Action |
|---|---|
| `Mod-/` | Toggle line comment |
| `Mod-]` / `Mod-[` | Indent / dedent selection |
| `Shift-Alt-f` | Tidy the document's indentation |
| `Tab` | Indent (or insert a tab if the selection is empty), or accept the open completion |
| `Shift-Alt-Up` / `Shift-Alt-Down` | Copy line up / down |
| `Shift-Mod-k` | Delete line |

`Mod-/` inserts `#` in ordinary YAML. Inside a `query:` or `sql:` block-scalar body it inserts
`--` instead, since the block scalar holds SQL text where `#` isn't a comment - it's part of
the query string.

`Enter` on a sequence item that already has content starts the next item for you, dash and
all: press it after `- charts.revenue` and the new line opens at `- `.

## Formatting

`Shift-Alt-f` straightens the document's indentation, and pasted YAML is re-indented to fit
where it lands. Both move leading whitespace only - your comments, quoting, key order, blank
lines, and the contents of `sql:` / `query:` block scalars are left exactly as written, so a
file that is already correctly indented comes back byte-for-byte identical. A wrapped value
and a multi-line `[flow, collection]` move with the key they belong to rather than being
snapped to the indent grid, and a comment keeps whatever indent you gave it.

## Selection and multiple cursors

| Binding | Action |
|---|---|
| `Mod-d` | Select the next occurrence of the current selection (or the word under the cursor) |
| `Mod-Alt-Up` / `Mod-Alt-Down` | Add a cursor on the line above / below |

## Navigation

| Binding | Action |
|---|---|
| `Alt-Up` / `Alt-Down` | Move the current line up / down |
| `Mod-Alt-g` | Go to line |

## Search

| Binding | Action |
|---|---|
| `Mod-f` | Open the search panel |
| `F3` / `Mod-g` | Find next match |
| `Shift-F3` / `Shift-Mod-g` | Find previous match |
| `Mod-Shift-l` | Select all occurrences of the current selection |

Search opens in the editor's top-right corner. Use the arrow beside the search field to
show or hide the replace controls.

## History

| Binding | Action |
|---|---|
| `Mod-z` | Undo |
| `Mod-Shift-z` / `Mod-y` | Redo |

## Completions

| Binding | Action |
|---|---|
| `Mod-Shift-Space` | Open completions (`Cmd-Shift-Space` on macOS, `Ctrl-Shift-Space` elsewhere) |
| `Tab` | Accept the highlighted completion |
| `Enter` | Accept the highlighted completion, except on a line that is still only indentation - there it inserts a new line |

The editor also suggests dbt Charts keys, chart types, and other schema-driven values as you
type - `Mod-Shift-Space` opens the list explicitly if it hasn't appeared on its own. `Ctrl-Space`
also works wherever the operating system hasn't already claimed it, but on macOS it is usually
unavailable: it is the input-source switcher, and toggles between input sources instead of
reaching the editor whenever two or more are installed. macOS additionally offers `Alt-\`` /
`Alt-i`.

Pressing `Enter` to open a new indented line lists everything valid at that level before you
type anything, so you can read the options rather than guess at them - if `orientation` is not
in the list under a chart, it belongs to one of the nested keys that is (`style:`). Because
nothing has been typed to choose with, `Enter` on such a line still means "new line"; use `Tab`
(or click) to accept from that list. Type any character and the list narrows to it, and `Enter`
accepts again as usual.

Accepting a key completion inserts a shape appropriate to what that key expects: a scalar value
stays on the same line after `key: `, an object value moves to an indented new line and reopens
the list with that object's keys, and a list value moves to an indented new line with `- ` ready
for the first item.

# Layout Types Reference (https://docs.dbtcharts.com/reference/layout-types/)

# Layout Types Reference

Detailed reference for all layout types available in dbt Charts boards.

**Note:** This page provides detailed reference material. For conceptual overview and common patterns, see the [Boards Guide](../boards/index.md).

---

## Layout Types Overview

dbt Charts supports four primary layout types for organizing content:

- **[Rows](#rows-layout)** (`rows`): Vertical stack (default for top-level boards)
- **[Cols](#cols-layout)** (`cols`): Horizontal stack
- **[Grid](#grid-layout)** (`grid`): Two-dimensional positioning
- **[Tabs](#tabs-layout)** (`tabs`): Tabbed content organization

Any item within these layouts can be a **Chart**, **Content Block**, or a **Nested Board**, allowing for infinite recursion.

A `rows`/`cols` section or a grid item can also be made **collapsible** with the **[Details](#details-collapsible-sections)** modifier.

---

## Rows Layout

### Description

Arranges items sequentially, one after another (vertically). This is the standard "document flow" layout.

### Configuration

```yaml {contract=board-fragment}
rows:
  - item_1
  - item_2
  - item_3
```

### Behavior

- Items stack vertically.
- Each item takes the full width of the container (unless restricted by a parent).
- Height is determined by the item's content or explicit `height` property.

### Example

```yaml {contract=unverified}
title: "Monthly Report"
rows:
  - title: "KPIs"
    cols: [...]  # Nested horizontal layout

  - title: "Revenue Trend"
    type: line
    query: queries.revenue

  - title: "Detailed Table"
    type: table
    query: queries.details
```

---

## Cols Layout

### Description

Arranges items side-by-side (horizontally).

### Configuration

```yaml {contract=board-fragment}
cols:
  - item_1
  - item_2
```

### Behavior

- Items are placed horizontally.
- Width is divided equally among items by default (for example, 3 items = 33% each).
- You can override widths using the `width` property on individual items.
- `cols` never stacks: the board is a fixed-width frame that the page scales, so every item keeps its share of the width. See [Sizing](../boards/sizing.md).

### Item Options

| Field | Type | Description |
|-------|------|-------------|
| `width` | string/number | Explicit width: `"50%"`, `"300px"`, or a bare number meaning **pixels** (not a relative weight) |

### Example

```yaml {contract=unverified}
# 50/50 Split
cols:
  - title: "Revenue"
    type: bar
    query: queries.revenue

  - title: "Orders"
    type: line
    query: queries.orders

# 70/30 Split
cols:
  - width: "70%"
    title: "Main Chart"
    # ...
  - width: "30%"
    title: "Sidebar"
    # ...
```

---

## Grid Layout

### Description

Arranges items in a precise 2D grid. Items can flow naturally into the next available space or be pinned to specific coordinates.

### Configuration

```yaml {contract=board-fragment}
grid:
  columns: 24           # Number of vertical columns
  items:
    - item: item_1
    - item: item_2
```

### Grid Options

| Field | Type | Description |
|-------|------|-------------|
| `columns` | number | Number of vertical columns (default: 24) |
| `items` | list | The items to place in the grid |

Grid rows size to their content, and every item spans one column and one row unless it says otherwise. Spacing between cells is set by `style.layout.grid.gap`, in pixels.

### Item Options

Grid items support specific positioning properties:

| Field | Type | Description |
|-------|------|-------------|
| `col` | number | Starting column index (0-based) |
| `row` | number | Starting row index (0-based) |
| `col_span` | number | Number of columns to span (default: 1) |
| `row_span` | number | Number of rows to span (default: 1) |

!!! tip "Clear naming"
    We use `col_span` and `row_span` instead of `width` and `height` to avoid confusion with pixel dimensions.

### Behavior

- **Auto-Flow**: Items without `col` and `row` are placed automatically in the next available space.
- **Pinned**: Items with `col` and `row` are fixed to that position.
- **Overlap**: Pinned items can overlap other items.

### Example

```yaml {contract=board-fragment}
grid:
  columns: 24
  items:
    # Top Row: 3 KPIs (8 columns each)
    - col_span: 8
      item: kpi_1
    - col_span: 8
      item: kpi_2
    - col_span: 8
      item: kpi_3

    # Middle: Main Chart (16 cols) + List (8 cols)
    - col_span: 16
      row_span: 4
      item: main_chart
    - col_span: 8
      row_span: 4
      item: recent_activity_list
```

---

## Tabs Layout

### Description

Organizes content into switchable tabs. Useful for grouping related but distinct views without cluttering the screen.

### Configuration

```yaml {contract=unverified}
tabs:
  position: top       # Tab bar position (top, left)
  items:
    - title: "Tab 1"
      rows: [...]     # Content for Tab 1
    - title: "Tab 2"
      cols: [...]     # Content for Tab 2
```

### Tab Item Options

| Field | Type | Description |
|-------|------|-------------|
| `title` | string | **Required**: Label text |
| `icon` | string | Optional icon name |

Tab content is placed via direct `rows:`, `cols:`, `grid:`, or `tabs:` keys on the tab item itself; there is no separate `layout:` field.

### Example

```yaml {contract=board-fragment}
tabs:
  items:
    - title: "Overview"
      rows:
        - kpi_row
        - trend_chart

    - title: "Regional"
      cols:
        - map_view
        - regional_table
```

---

## Details (Collapsible Sections)

### Description

A `rows`/`cols` section or a grid item's `item:` board can be made collapsible by adding a `details` property. This renders a clickable summary bar with a disclosure triangle (▶/▼) that expands or collapses the content. Works like HTML `<details>/<summary>`.

The expanded/collapsed state is controlled by an auto-generated hidden variable and toggled via URL parameters; no JavaScript required.

### Configuration

Add `details` to a section within a layout. Tab items, grid item wrappers and bare chart references reject it:

```yaml {contract=board-root}
rows:
  - details:
      summary: "Show More"      # Summary text (clickable header)
      expanded_title: "Hide"    # Optional: different text when expanded
      expanded: false          # Optional: default state (default: false)
    id: breakdown               # Optional: URL param name (auto-generated if omitted)
    rows:                       # Content (any layout type)
      - text: Breakdown
      - text: Detail
```

### Item Options

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `details.summary` | string | *(required)* | Summary text shown in the clickable header |
| `details.expanded_title` | string | same as `details.summary` | Different text shown when expanded |
| `details.expanded` | boolean | `false` | Whether the section starts expanded |
| `id` | string | auto-generated | URL parameter name for the toggle variable |

### Behavior

- **Collapsed**: Only the summary bar is rendered (36px). Content is not rendered at all.
- **Expanded**: Summary bar + full content below it.
- **Toggle**: Clicking the summary bar navigates to a URL that flips the variable, triggering a server re-render.
- **URL state**: The toggle variable appears in the URL as `?breakdown=true` or `?breakdown=false`, preserving all other parameters.
- **Sizing**: Height adjusts automatically; collapsed sections take minimal space.

### Example

```yaml {contract=board-root}
title: "Sales Dashboard"
rows:
  - text: Summary

  - details:
      summary: "Revenue Breakdown"
      expanded_title: "Hide Breakdown"
    rows:
      - text: By region
      - text: By product

  - details:
      summary: "Raw Data"
      expanded: true
    id: raw_data
    rows:
      - text: Raw data
```

This renders:
```text
┌──────────────────────────────────┐
│  [summary_kpis]                  │
├──────────────────────────────────┤
│ ▶ Revenue Breakdown              │  ← click to expand
├──────────────────────────────────┤
│ ▼ Raw Data                       │  ← starts expanded
│  [raw_data_table]                │
└──────────────────────────────────┘
```

---

## Comparison Table

| Layout Type | Best For | Responsive Behavior | Complexity |
|-------------|----------|---------------------|------------|
| **Rows** | Standard reports, mobile-first | Stacks vertically (naturally) | Low |
| **Cols** | Side-by-side comparisons, sidebars | Fixed frame; never stacks | Low |
| **Grid** | Dense dashboards, precise control | Reflows or scales based on config | High |
| **Tabs** | Reducing clutter, categorization | Tab bar adapts (scrolls or menu) | Medium |
| **Details** | Collapsible sections, progressive disclosure | Collapses to single row | Low |

---

## Best Practices

1.  **Start with Rows**: Most dashboards are effectively a stack of sections. Start with a `rows` layout and nest other layouts inside.
2.  **Use Cols for comparisons**: Place related metrics side-by-side for easy comparison.
3.  **Limit Nesting**: While dbt Charts supports infinite nesting, sticking to 2-3 levels usually produces the most maintainable and readable boards.
4.  **Narrow targets**: `cols` never stacks, so five charts across a 700px frame get about 115px each, too narrow for a bar chart's axis labels. For a narrow target, set `style.frame.width` and size the rows for it (see [Sizing](../boards/sizing.md)).

---

## Related

- [Boards Guide](../boards/index.md) - Conceptual overview and patterns
- [YAML Schema Reference](yaml-reference.md) - Complete field reference

# Support Table (`chart.support_table`) (https://docs.dbtcharts.com/reference/chart-support-table/)

# Support Table (`chart.support_table`)

An optional mini data-grid attached to a chart, with columns
pixel-aligned to the chart's x-axis ticks. The strip position is
controlled by `style.charts.support_table.position` (`top` or `bottom`);
the default is `top` (strip above the plot, Excel-style). Direct Excel
analog: "Chart Element → Data Table."

```yaml {contract=unverified}
chart:
  type: bar
  x: month
  y: revenue
  support_table:
    - source: sample_size
      format: ",d"
      label: "n"
    - aggregate: sum
      source: revenue
      format: currency
      label: "Total"
```

Each list entry is a row. Columns align to the chart's x-axis ticks.
When `label:` is omitted on a source or aggregate row, the row stub is derived
from `source:` (`successful_launches` renders as `Successful Launches`).
Missing, non-finite, or invalid cell values render as a regular dash (`-`), not as
JavaScript sentinel text such as `NaN` or `null`.
When `format:` is omitted on a row that reads the chart's primary measure column,
the strip inherits `chart.format` so the chart and strip do not show the same
measure with different number formatting.

## The unit is stated once, not on every cell

When a row's `format:` is a predefined name that carries a unit (such as
`currency` or `percent`) the strip
states that unit on its **leftmost cell** and leaves the rest bare, so the row
reads as one measurement instead of repeating itself:

```text
$441mn   448   456   464   473   483   493   505   516            Goal
5.5%     6.2   6.4   7.1   7.8   8.5   9.3   11.2  13.4           Goal
```

The whole row shares one magnitude, chosen from its own values, so cells never
disagree about scale the way per-cell formatting can (`993k` beside `1.0M`).
A row whose values outgrow that magnitude repeats the **suffix** on every cell;
a currency symbol is still stated once, since repeating it disambiguates
nothing.
A vertical block (beside a horizontal bar) reads like a table column: a unit
stated once takes the analytic form (`$2.35M`), a repeated one the narrative
form (`2.35mn`).

Nothing is authored for this: the unit comes from the `format:` you already
write, and a format naming no unit is untouched. A sorted category axis
(an authored `sort:`, or a horizontal bar's largest-first default) states the
unit on the first cell in its sorted order. Three shapes keep the older
per-cell spelling, because the leftmost painted cell either cannot be
identified or should not carry the extra glyph:

| Shape | Why |
|---|---|
| a raw d3 format literal (for example, `"$.2s"`), or a `style.formats` alias to one | only engine-predefined format names engage the anchor |
| a quantitative x axis | continuous, so the leftmost band is not the first row |
| a currency format without a magnitude on a left-oriented y-axis | a leading symbol on the anchor would push its digits off the shared edge |

**Orientation determines which side the affix hangs.**
For a right-oriented y-axis the affix leads the digits and hangs into the
y-axis gutter. For a left-oriented y-axis, suffix-only formats (SI without a
currency prefix, percent) hang the suffix into the anchor cell's own band so
every other cell's left digit edge stays in one lane. A currency symbol that
leads the digits repeats on every cell on a left-oriented axis, while a
magnitude suffix is still stated once (`$441mn  $448  $456`). Set
`repeat: anchor` on the format to state the symbol once anyway.
`axis_y.position` defaults to `auto` and resolves
to left whenever a chart draws endpoint labels, which multi-series line, area,
and bar charts do by default.

## Entry shapes

Two shapes, one of each per list entry:

| Shape | Keys | When to use |
|---|---|---|
| Source row | `source:` (required), `format:`, `label:` | Read a raw per-x value from a query column. `label:` defaults from `source:` when omitted. |
| Aggregate row | `aggregate:` + `source:` (both required), `format:`, `label:` | Compute a per-x aggregate across other dimensions (for example, segment-stacked bars). `label:` defaults from `source:` when omitted. |

A source row with no `format:`/`label:` override may be written as a bare
column name; `- revenue` is shorthand for `- {source: revenue}`, the same
scalar-listable spelling `y:` uses:

```yaml {contract=board-fragment}
rows:
  - type: bar
    query: q
    x: month
    y: revenue
    support_table:
      - revenue
      - cost
```

### Supported aggregate operations

`sum`, `avg`, `min`, `max`, `median`, `count`, `count_distinct`. Exact
names: no aliases.

## Supported chart types (v1)

`bar`, `line`, `area`.

Every other chart type (`pie`, `donut`, `scatter`, `kpi`, `table`,
`arc`, `waterfall`, etc.) rejects the `support_table:` block with a
compile error. Layered charts and charts with a multi-field `y:` list
are also rejected: the attached strip needs a single unambiguous
x-encoding.

## Rules

- `source:` alone is valid only when the query returns at most one row
  per x-value. On stacked/grouped charts, use `aggregate:` to resolve:
  the renderer errors with a pointer at `aggregate:` if a bare `source:`
  is ambiguous.
- `aggregate:` always requires `source:`.
- `source:` must reference a column present in the chart's query output.
- Maximum **40 x-axis ticks** (the chart's x-cardinality, not the
  number of `support_table` rows). Aggregate or filter in the query
  before rendering.
- Duplicate entries (same `source:` + `aggregate:` combination) reject
  at compile time.
- On dense time-like ordinal axes, strip cells thin to the same visible tick
  cadence as the axis. This covers both authored coarser label cadences
  (for example monthly bars with quarterly labels) and runtime
  `labelOverlap: parity` culling on narrow bucketed-time bar charts.
- Entries render in list order from the row adjacent to the plot outward:
  top-to-bottom for `position: bottom`, bottom-to-top for `position: top`
  (the default). The row closest to the plot always corresponds to the first
  entry in the authored list.

## Styling

Themeable at three tiers, each merging into the next:

1. `style.charts.support_table.*`: universal defaults.
2. `style.charts.<chart_type>.support_table.*`: per-chart-type override.
3. `chart.style.support_table.*`: per-chart authored override.

Styleable leaves: `font`, `divider`, `row`, `label`,
`padding_top`, `padding_bottom`, `position`.

Value cells align toward their row labels automatically: a left-side y-axis
(labels on the left) left-aligns the values, a right-side axis right-aligns
them. There is no separate alignment knob.

**`position`** accepts `"top"` (strip above the plot, default) or
`"bottom"` (strip below the plot, legacy layout). Override at any
tier to keep below-plot placement:

```yaml {contract=unverified}
chart:
  style:
    support_table:
      position: bottom  # legacy below-plot layout for this chart
```

**No column-header row** exists on `support_table`. The `divider:` block
styles a single line drawn between the plot and the strip (off by default;
set `visible: true`), not a header row.

```yaml {contract=unverified}
style:
  charts:
    support_table:
      font:
        size: 11
      divider:
        visible: true
        width: 1
      label:
        align: left
      position: top   # default; set bottom for below-plot legacy layout
    bar:
      support_table:
        font:
          size: 10     # tighter for dense bar charts
```

# Quick Reference Cheat Sheet (https://docs.dbtcharts.com/reference/quick-reference/)

# Quick Reference Cheat Sheet

Quick reference for dbt Charts board structure and common patterns.

---

## Board Structure

`notes:` is available on boards, charts, queries, variables, and layout items
(rows/cols/grid/tab entries) for AI search and maintainer context. It never
appears in the rendered board; the one exception is board-level `notes:`,
which dbtcharts.com shows in the dashboard-card hover overlay on the project
and home listings.

```yaml {contract=unverified}
title: "Board Title"
tags: [marketing, q1]

theme: clarity

# Layout (Use exactly one: rows, cols, grid, tabs)
rows:
  - _header_partial.yml   # Include other files (path relative to this file)
  - title: "KPIs"
    cols:                 # Nested layout
      - kpi_revenue
      - kpi_orders

# Definitions (Scoped to this board)
variables:
  priority:
    input: select
    column: dundersign.tickets.priority

queries:
  revenue:
    notes: "What this query powers"
    sql: SELECT month, SUM(revenue) AS revenue FROM dundersign.orders GROUP BY 1
    source: my_postgres

charts:
  kpi_revenue:
    type: kpi
    query: queries.revenue
    value: revenue
```

---

## Query Templates

### dbt Model

Query a dbt model with plain SQL: `ref()` resolves through the dbt profile source:

```yaml {contract=board-root}
queries:
  raw_data:
    notes: "Base order rows for detailed analysis"
    sql: SELECT order_id, amount, status FROM {{ ref('fct_orders') }}
    source: my_dbt_source
```

### Raw SQL


```yaml {contract=board-fragment}
queries:
  custom:
    notes: "Tickets filtered to the selected priority"
    sql: |
      SELECT * FROM dundersign.tickets
      WHERE {{ filter('priority', priority) }}
    source: my_postgres
```


---

## Chart Template

```yaml {contract=board-fragment}
charts:
  revenue_trend:
    title: "Revenue Trend"
    notes: "Tracks monthly revenue by region"
    query: queries.sales
    type: line                  # bar, line, area, scatter, kpi, table...
    x: month
    y: revenue
    color: region
    style:
      legend:
        visible: true
```

---

## Variable Template

```yaml {contract=board-root}
variables:
  # Column-bound (Automatic options)
  priority:
    input: select               # select, multiselect, text, number...
    notes: "Priority filter applied to all charts"
    column: dundersign.tickets.priority

  # Date Range
  date_range:
    input: daterange
    notes: "Date range for report period"
    default: ["2024-01-01", "2024-01-31"]

  # Custom Options
  status:
    input: select
    notes: "Lifecycle status filter"
    options:
      static: [Draft, Active, Archived]
      # OR dynamic
      query: queries.statuses
      column: status_id
      label_column: status_name
```

---

## Layout Templates

### Rows (Vertical)

```yaml {contract=unverified}
rows:
  - title: "Top Section"
    notes: "Primary KPI context"
    cols: [...]
  - trend_chart
```

### Cols (Horizontal)

```yaml {contract=board-fragment}
cols:
  - width: "30%"
    rows:
      - sidebar_nav
  - width: "70%"
    rows:
      - main_content
```

### Grid

```yaml {contract=board-fragment}
grid:
  columns: 24
  items:
    - item: kpi_1
      notes: "Revenue KPI card"
      col_span: 6
    - item: kpi_2
      col_span: 6
    - item: main_chart
      col: 0
      row: 1
      col_span: 24
      row_span: 4
```

### Tabs

```yaml {contract=unverified}
tabs:
  position: top
  items:
    - title: "Overview"
      notes: "Executive summary tab"
      rows: [...]
    - title: "Details"
      grid: {...}
```

---

## Common Patterns

### Filtered Query


```yaml {contract=board-root}
variables:
  status:
    input: select
    options:
      static: ["new", "solved"]

queries:
  filtered:
    sql: |
      SELECT status, COUNT(*) AS ticket_count FROM dundersign.tickets
      WHERE {{ filter('status', status) }}
      GROUP BY status
    source: warehouse
```


### KPI Row

```yaml {contract=board-fragment}
rows:
  - height: "120px"
    cols:
      - type: kpi
        query: queries.kpis
        value: revenue
      - type: kpi
        query: queries.kpis
        value: orders
```

### Variable-Filtered Chart

```yaml {contract=board-root}
variables:
  selected_category:
    input: select
    column: products.category

queries:
  sales:
    sql: |
      SELECT product, revenue FROM sales
      WHERE {{ filter('category', selected_category) }}
    source: warehouse

charts:
  filtered_bar:
    type: bar
    query: queries.sales
    x: product
    y: revenue
```

---

## Field Quick Reference

### Common Chart Types
- `bar` - Bar chart
- `line` - Line chart
- `area` - Area chart
- `scatter` - Scatter plot
- `table` - Data table
- `kpi` - Single number
- `heatmap` - Heatmap

### Common Inputs
- `select` - Single dropdown
- `multiselect` - Multiple dropdown
- `daterange` - Date range picker
- `text` - Text input
- `number` - Number input
- `checkbox` - Toggle

### Layout Keys
- `rows` - Vertical stack
- `cols` - Horizontal stack
- `grid` - 2D Grid
- `tabs` - Tabbed view

---

## Expression Quick Reference

### References

```sql
WHERE region = '{{ region }}'                  -- direct reference
  AND backup = '{{ region or 'All' }}'         -- with default
  AND {{ filter('region', region) }}           -- helper: unset → unfiltered
```


### Formatting

```sql
WHERE order_date >= '{{ date_range | date('%Y-%m-%d') }}'
  AND amount_label = '{{ amount | number('0.00') }}'
```


### Logic

```sql
WHERE {% if show_all %} 1=1 {% else %} id = {{ id }} {% endif %}
```


---

## Related

- [YAML Schema Reference](yaml-reference.md) - Complete field definitions
- [Boards Guide](../boards/index.md) - Layout concepts
- [Chart Types](../charts/types.md) - Visualizations