Metadata-Version: 2.5
Name: dbt-charts
Version: 0.5.0
Summary: Dataface - 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.0.0
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>=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: metricflow
Requires-Dist: metricflow<0.212.0,>=0.211.0; extra == 'metricflow'
Provides-Extra: mkdocs-plugin
Requires-Dist: mkdocs>=1.4.0; extra == 'mkdocs-plugin'
Provides-Extra: playground
Requires-Dist: dbt-charts-playground; extra == 'playground'
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

# Dataface

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

Dataface (package `dbt-charts`, CLI `dct`) is a Python-based board framework that
compiles YAML board definitions into interactive visualizations. Queries run as plain
SQL against your warehouse by default — no dbt project required — with an optional,
deeper integration into dbt's Semantic Layer (MetricFlow) when you have metrics and
dimensions already defined there.

---

## Why Dataface?

### The Problem

If you're a data analyst, you've probably experienced this:
- You have data in a warehouse (with or without dbt models on top of it)
- You want to build dashboards to share insights with your team
- But building dashboards requires learning complex BI tools, writing app code, or
  paying for a hosted platform

### The Solution

Dataface lets you:
- **Write boards in YAML** — simple, human-readable format
- **Query with plain SQL** — or reference existing dbt Semantic Layer metrics, if you
  have them
- **Create interactive visualizations** — filters, drill-downs, and click actions
- **Share and collaborate** — boards are version-controlled YAML files
- **Stay in sync with dbt** — when you do use dbt, boards and models deploy together
  through Git branches, eliminating broken dashboards after data migrations

### How It Works

1. **You write a YAML file** describing what data to show and how to visualize it
2. **Dataface compiles it** into an interactive board
3. **The board queries your warehouse** — plain SQL by default, or your dbt Semantic
   Layer (MetricFlow) if you reference metrics/dimensions instead
4. **Users interact** with filters, click charts, and explore the data

---

## Getting Started

### Prerequisites

- **Python 3.10-3.13**
- **dbt** project (optional but highly recommended)

### Install

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

Verify:

```bash
dct --version
```

### Without dbt (optional)

If you don't already have a dbt project, install Dataface with the warehouse adapter you need:

```bash
pip install "dbt-charts[bigquery]"
pip install "dbt-charts[databricks]"
pip install "dbt-charts[postgresql]"
pip install "dbt-charts[redshift]"
pip install "dbt-charts[snowflake]"
pip install "dbt-charts[spark]"
```

### MCP (optional)

Dataface ships an MCP server for use with any compatible AI agent:

```bash
pip install "dbt-charts[mcp]"
dct init mcp
```

### Quick Start

```bash
# Bootstrap a new project
dct init

# Validate a board for errors
dct validate charts/guide.yaml

# Start a live preview server
dct serve
```

### Environment variables

`dct` reads `DCT_PROJECT_DIR` when no `--project-dir` is passed — handy in CI or when working in multiple project trees from one shell. The flag wins if both are set. See the [CLI environment variables reference](https://docs.dataface.com/cli/#environment-variables) for the full list (themes, ports, dbt overrides, etc.).

### Place boards in your dbt project (optional)

```
my-dbt-project/
├── dbt_project.yml
├── models/
├── charts/                  # Your boards here
│   ├── sales_overview.yml
│   ├── marketing.yml
│   └── finance.yml
└── assets/                  # Assets directory (optional)
    ├── images/             # Logos, icons, images
    └── data/               # CSV files and other data
```

A dbt project isn't required — `charts/` can live on its own, querying your warehouse
directly with plain SQL. Nesting it under a dbt project is what unlocks Semantic Layer
queries and Git-branch deploys in lockstep with your models.

---

## Key Features

### dbt-Native
- Queries run as plain SQL against your warehouse by default
- Optionally query dbt's Semantic Layer (MetricFlow) directly — no need to redefine metrics
- Reads your `profiles.yml` automatically
- Works with all dbt adapters (Snowflake, BigQuery, Postgres, etc.)
- Boards sync with dbt models through Git branches — no broken dashboards after data migrations

### Declarative YAML
- Human-readable, version-control friendly
- No code required
- AI-friendly format (perfect for LLMs to generate)

### Interactive Visualizations
- Variables/filters that update in real-time
- Click interactions (drill-down, set variables, filter)
- Built on Vega-Lite (declarative charting)

### Multiple Output Modes
- **Live mode:** Interactive web dashboard (FastAPI server)
- **Static mode:** Shareable HTML snapshot (data baked in)
- **PDF mode:** Printable/shareable PDF reports

### AI-First
- YAML is perfect for AI generation
- MCP server for any compatible AI agent (Cursor, VS Code, Claude Desktop, Codex)
- AI can create, modify, and iterate on dashboards

---

## Interactive Playground

Try Dataface online without installing anything:

**[play.dataface.com](https://play.dataface.com)**

A split-pane YAML editor with live preview. No dbt project needed (uses sample data).

---

## CLI Commands

The Dataface CLI is called `dct` (short for **D**ata**F**ace **T**ool), intentionally mirroring `dbt` (Data Build Tool). Just as dbt transforms your data, dct transforms your boards.

### Validate

Validate boards for errors:

```bash
dct validate [PATH]

# Examples:
dct validate                        # Validate all in charts/
dct validate charts/                # Validate all in a directory
dct validate charts/guide.yaml       # Validate one file
dct validate --strict               # Fail on warnings
```

### Serve

Start interactive preview server:

```bash
dct serve [OPTIONS]

# Examples:
dct serve
dct serve --port 3000
dct serve --host 0.0.0.0  # bind on the LAN, not just localhost
```

### Render

Render one or more boards to a self-contained file:

```bash
dct render BOARDS... [OPTIONS]

# Examples:
dct render charts/guide.yaml --format html
dct render charts/guide.yaml --format pdf
dct render charts/guide.yaml --format png --output guide.png
dct render charts/guide.yaml --format json   # resolved layout + executed data
```

---

## Example Dashboards

### Simple KPI Dashboard

```yaml
title: "Executive KPIs"

queries:
  q_totals:
    metrics: [total_revenue, order_count, customer_count]

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
  customers:
    label: "Total Customers"
    query: q_totals
    type: kpi
    value: customer_count

rows:
  - title: "Key Metrics"
    cols:
      - revenue
      - orders
      - customers
```

### Interactive Dashboard with Filters

```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:
    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
```

---

## Architecture

Dataface is built on:

- **Python 3.10+** - Core language
- **Pydantic** - Schema validation and data models
- **Jinja2** - Template engine (same as dbt!)
- **Vega-Lite** - Declarative charting via `vl-convert`
- **FastAPI** - Web server for live mode
- **dbt adapters** - Direct database access

### How It Works

```
YAML Board → Python Compiler → Vega-Lite Specs → Renderer
                  ↓
              (Validation)
                  ↓
    Warehouse (SQL or dbt MetricFlow) → Query Data → Charts
                  ↓
           Live HTML or Static PDF
```

---

## Comparison to Other Tools

| Feature | Dataface | Lightdash | Looker | Superset |
|---------|----------|-----------|--------|----------|
| **Format** | YAML | UI + YAML | LookML | UI |
| **dbt Integration** | SQL, or native (MetricFlow) | dbt metrics | Separate | Limited |
| **Installation** | `pip install dbt-charts` | Self-host + PostgreSQL | Enterprise license | Self-host + database |
| **Version Control** | Native (Git) | Export/Import | Native (Git) | Limited |
| **AI-Friendly** | YAML | UI-first | LookML | No |
| **Static Export** | PDF, HTML | No | Enterprise only | No |

---

## Documentation

- [Getting Started Guide](https://docs.dataface.com/guides/getting-started/) — Step-by-step onboarding
- [YAML Style Guide](https://docs.dataface.com/guides/yaml-style-guide/) — Board YAML conventions
- [CLI Reference](https://docs.dataface.com/cli/) — All `dct` commands
- [Chart Types](https://docs.dataface.com/charts/types/) — Available chart types and configuration
- [Variables & Filters](https://docs.dataface.com/variables/) — Interactive variables and UI elements

---

## Contributing

This project is developed in a private upstream repository and mirrored here read-only
— pull requests against this repository are not accepted and will be closed (see
[CONTRIBUTING.md](https://github.com/dbt-labs/dbt-charts/blob/main/CONTRIBUTING.md)). Bug reports and feature requests are welcome via
[GitHub Issues](https://github.com/dbt-labs/dbt-charts/issues).
