dataface 0.1.5.dev237

Dataface - dbt-native dashboard and visualization layer

Dataface

Declarative, dbt-native dashboards in YAML

Dataface is a Python-based dashboard framework that compiles YAML dashboard definitions into interactive visualizations. It integrates seamlessly with dbt's Semantic Layer (MetricFlow) to provide a simple, declarative way to create dashboards.

---

Why Dataface?

Database + Interface = Dataface. Dataface is designed to be the universal language of data visualization—perfect for humans and AI alike.

The Problem

If you're a data analyst working with dbt, you've probably experienced this:

• You have great metrics and dimensions defined in dbt's Semantic Layer
• You want to create dashboards to share insights with your team
• But building dashboards requires learning complex BI tools, writing SQL queries, or coding

The Solution

Dataface lets you:

• Write dashboards in YAML — simple, human-readable format
• Reference your existing dbt metrics — no need to redefine them
• Create interactive visualizations — filters, drill-downs, and click actions
• Share and collaborate — dashboards are version-controlled YAML files
• Stay in sync with dbt — dashboards 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 dashboard
3. The dashboard queries your dbt Semantic Layer (MetricFlow) to fetch data
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

pip install "dataface"

Verify:

dft --version

Without dbt (optional)

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

pip install "dataface[bigquery]"
pip install "dataface[databricks]"
pip install "dataface[postgresql]"
pip install "dataface[redshift]"
pip install "dataface[snowflake]"
pip install "dataface[spark]"

AI chat (optional)

For the AI agent (dft chat), add the [chat] extras and set OPENAI_API_KEY in your environment:

pip install "dataface[chat]"
dft chat

MCP (optional)

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

pip install "dataface[mcp]"
dft init mcp

Quick Start

# Bootstrap a new project
dft init

# Validate a face for errors
dft validate faces/hello.yml

# Start a live preview server
dft serve

Environment variables

dft reads DFT_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 for the full list (themes, ports, dbt overrides, etc.).

Place faces in your dbt project

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

---

Key Features

dbt-Native

• Uses dbt Semantic Layer (MetricFlow) directly
• Reads your profiles.yml automatically
• Works with all dbt adapters (Snowflake, BigQuery, Postgres, etc.)
• No need to redefine metrics
• Dashboards 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.it-dataface.com

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

---

CLI Commands

The Dataface CLI is called dft (short for DataFace Tool), intentionally mirroring dbt (Data Build Tool). Just as dbt transforms your data, dft transforms your dashboards.

Validate

Validate dashboards for errors:

dft validate [PATH]

# Examples:
dft validate                        # Validate all in faces/
dft validate faces/                 # Validate all in a directory
dft validate faces/hello.yml        # Validate one file
dft validate --strict               # Fail on warnings

Serve

Start interactive preview server:

dft serve [OPTIONS]

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

Render

Render a dashboard to a self-contained file:

dft render FACE [OPTIONS]

# Examples:
dft render faces/hello.yml --format html
dft render faces/hello.yml --format pdf
dft render faces/hello.yml --format png --output hello.png
dft render faces/hello.yml --format json   # resolved layout + executed data

---

Example Dashboards

Simple KPI Dashboard

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

title: "Sales Dashboard"

variables:
  date_range:
    input: daterange
    default: "2024-01-01"

  region:
    input: multiselect
    options:
      static: ["North", "South", "East", "West"]
    default: ["North", "South"]

queries:
  q_sales:
    metrics: [total_revenue, order_count]
    dimensions: [month, region]
    filters:
      order_date: "{{ date_range }}"
      region: "{{ region }}"

charts:
  revenue_trend:
    title: "Revenue Over Time"
    query: q_sales
    type: line
    x: month
    y: total_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 Dashboard → Python Compiler → Vega-Lite Specs → Renderer
                     ↓
                 (Validation)
                     ↓
              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	Native (MetricFlow)	dbt metrics	Separate	Limited
Installation	pip install dataface	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 — Step-by-step onboarding
• YAML Style Guide — Dashboard YAML conventions
• CLI Reference — All dft commands
• Chart Types — Available chart types and configuration
• Variables & Filters — Interactive variables and UI elements

---

Contributing

Contributions welcome! See the GitHub repository for contributor setup, architecture docs, and development workflows.