Metadata-Version: 2.5
Name: dbt-charts
Version: 0.6.0
Summary: dbt charts - dbt-native dashboard and visualization layer
Author: Fivetran, Inc.
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: <3.14,>=3.10
Requires-Dist: dbt-adapters<2,>=1.20
Requires-Dist: dbt-common>=1.0
Requires-Dist: dbt-core<2,>=1.8
Requires-Dist: dbt-duckdb<2,>=1.10
Requires-Dist: duckdb>=1.0.0
Requires-Dist: fastapi>=0.100.0
Requires-Dist: fonttools>=4.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: importlib-resources>=6.0
Requires-Dist: jinja2>=3.1.6
Requires-Dist: jsonschema>=4.0
Requires-Dist: msgpack>=1.0.0
Requires-Dist: nh3>=0.3.3
Requires-Dist: pillow>=9.0.0
Requires-Dist: plotext<6,>=5.0.0
Requires-Dist: pyarrow>=14.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pygments>=2.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Requires-Dist: sqlglot>=28.0.0
Requires-Dist: titlecase>=2.4
Requires-Dist: tomli-w>=1.0.0
Requires-Dist: tomli>=2.0.0; python_version < '3.11'
Requires-Dist: typer<0.26,>=0.12
Requires-Dist: typing-extensions>=4.5.0
Requires-Dist: uvicorn>=0.23.0
Requires-Dist: vl-convert-python>=1.9.0
Requires-Dist: watchfiles>=1.1.1
Provides-Extra: bigquery
Requires-Dist: dbt-bigquery<2.0,>=1.10; extra == 'bigquery'
Requires-Dist: google-cloud-bigquery>=3.33.0; extra == 'bigquery'
Provides-Extra: databricks
Requires-Dist: dbt-databricks<2.0,>=1.10; extra == 'databricks'
Provides-Extra: lsp
Requires-Dist: pygls<3,>=2; extra == 'lsp'
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.0.0; extra == 'mcp'
Provides-Extra: mkdocs-plugin
Requires-Dist: mkdocs>=1.4.0; extra == 'mkdocs-plugin'
Provides-Extra: postgresql
Requires-Dist: dbt-postgres<2.0,>=1.10; extra == 'postgresql'
Provides-Extra: redshift
Requires-Dist: dbt-redshift<2.0,>=1.10; extra == 'redshift'
Provides-Extra: server
Requires-Dist: fastapi>=0.100.0; extra == 'server'
Requires-Dist: uvicorn>=0.23.0; extra == 'server'
Provides-Extra: snowflake
Requires-Dist: dbt-snowflake<2.0,>=1.10; extra == 'snowflake'
Provides-Extra: spark
Requires-Dist: dbt-spark<2.0,>=1.10; extra == 'spark'
Provides-Extra: trino
Requires-Dist: dbt-trino<2.0,>=1.9; extra == 'trino'
Description-Content-Type: text/markdown

# dbt charts

**Declarative, dbt-native boards in YAML**

dbt charts (package `dbt-charts`, CLI `dct`) compiles YAML board definitions into
interactive boards, static HTML, and PDF reports. Queries run as plain SQL against
your warehouse — no dbt project required, though dbt models are queried the same way
(via `ref()`) when you have one.

> This repository is a read-only mirror of a private upstream. Issues are welcome;
> pull requests are not accepted. See
> [CONTRIBUTING.md](https://github.com/dbt-labs/dbt-charts/blob/main/CONTRIBUTING.md).

---

## Why

Boards are YAML files in Git, so they version, review, and deploy like the rest of your
project. No BI tool to learn, no app code to write, no hosted platform required. When
boards live inside a dbt project, they move through branches in lockstep with the models
they query: a column rename and the boards that read it ship in one PR.

YAML is also a format LLMs generate and edit reliably, which is why dbt charts ships an
MCP server and a set of board-authoring skills for agents.

---

## Getting started

Requires Python 3.10 to 3.13.

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

`dct` talks to your warehouse through dbt adapters. Inside an existing dbt project the
adapter is already installed; otherwise install the one you need as an extra:

```bash
pip install "dbt-charts[bigquery]"      # also: databricks, postgresql, redshift,
                                        # snowflake, spark, trino
```

Using a coding agent? Hand it one sentence. `dct skills intro` teaches it the tool
and which skill to read next:

```text
Make charts of this with dbt charts. Start with: uv tool install dbt-charts && dct skills intro
```

By hand:

```bash
dct init                        # bootstrap a project (creates charts/guide.yaml)
dct validate charts/guide.yaml  # check board YAML for errors, no warehouse needed
dct serve                       # live preview server
```

Try it without installing anything at **[play.dbtcharts.com](https://play.dbtcharts.com)**:
a split-pane YAML editor with live preview on sample data.

### Project layout

```
my-dbt-project/
├── dbt_project.yml
├── models/
├── charts/                  # boards live here
│   ├── sales_overview.yml
│   └── finance.yml
└── assets/                  # optional: images/, data/
```

A dbt project isn't required — `charts/` can stand alone and query your warehouse
directly. Nesting it under a dbt project is what unlocks branch-based deploys in lockstep
with your models.

### MCP and agent skills

```bash
pip install "dbt-charts[mcp]"
dct init mcp      # wire the MCP server into Cursor, VS Code, Claude Desktop, Codex, …
dct init skills   # install board-authoring skills for file-based agent discovery
```

---

## CLI

The CLI is `dct` (**d**bt **c**har**t**s), mirroring `dbt`.

```bash
dct validate [PATH]           # default: everything under charts/; --strict fails on warnings
dct serve [--port N] [--host H]
dct render BOARD... --format {html,pdf,png,svg,json}
dct query SOURCE 'SELECT …'   # run raw SQL, or a named board query
dct search <query>            # find boards by keyword
dct impact <column>           # which boards reference a column
dct docs [TOPIC]              # built-in YAML reference
dct examples [SLUG]           # bundled board specimens
```

`dct` reads `DCT_PROJECT_DIR` when `--project-dir` is not passed. The
[CLI reference](https://docs.dbtcharts.com/cli/#environment-variables) lists every
environment variable.

---

## Examples

A KPI row:

```yaml
title: "Executive KPIs"

queries:
  q_totals:
    source: warehouse
    sql: |
      SELECT SUM(revenue) AS total_revenue,
             COUNT(*) AS order_count
      FROM orders

charts:
  revenue:
    label: "Total Revenue"
    query: q_totals
    type: kpi
    value: total_revenue
  orders:
    label: "Total Orders"
    query: q_totals
    type: kpi
    value: order_count

rows:
  - title: "Key Metrics"
    cols: [revenue, orders]
```

Variables become filter UI, and macros expand them into safe SQL predicates:

```yaml
title: "Sales Dashboard"

variables:
  date_range:
    input: daterange
    default: ["2024-01-01", "2024-12-31"]
  region:
    input: multiselect
    options:
      static: ["North", "South", "East", "West"]
    default: ["North", "South"]

queries:
  q_sales:
    source: my_db
    sql: |
      SELECT month, region, SUM(revenue) AS revenue
      FROM sales
      WHERE {{ filter_date_range('order_date', date_range) }}
        AND {{ filter('region', region) }}
      GROUP BY month, region

charts:
  revenue_trend:
    title: "Revenue Over Time"
    query: q_sales
    type: line
    x: month
    y: revenue
    color: region

rows:
  - title: "Revenue Trends"
    cols: [revenue_trend]
```

---

## How it works

```
board YAML → compile (validate, resolve theme + layout)
           → execute (SQL against your warehouse via dbt adapters)
           → render  (Vega-Lite specs → live HTML, static HTML, PDF, PNG, SVG)
```

Built on Pydantic (schema validation), Jinja2 (templating, as in dbt), Vega-Lite via
`vl-convert` (charting), and FastAPI (the preview server).

---

## Documentation

- [Getting started](https://docs.dbtcharts.com/guides/getting-started/)
- [YAML style guide](https://docs.dbtcharts.com/guides/yaml-style-guide/)
- [CLI reference](https://docs.dbtcharts.com/cli/)
- [Chart types](https://docs.dbtcharts.com/charts/types/)
- [Variables and filters](https://docs.dbtcharts.com/variables/)

---

## Contributing

Development happens in a private upstream repository and is mirrored here read-only.
Pull requests opened against this repository are closed unmerged; bug reports and feature
requests are welcome via [GitHub Issues](https://github.com/dbt-labs/dbt-charts/issues).
See [CONTRIBUTING.md](https://github.com/dbt-labs/dbt-charts/blob/main/CONTRIBUTING.md)
and [SECURITY.md](https://github.com/dbt-labs/dbt-charts/blob/main/SECURITY.md).

## License

[Apache License 2.0](https://github.com/dbt-labs/dbt-charts/blob/main/LICENSE).
