Dataface Overview

Dataface 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 Dataface 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?

Dataface 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. Dataface compiles it into an interactive board
3. The board queries your database (via SQL) or your dbt Semantic Layer (MetricFlow) to fetch data
4. Users interact with filters, click through charts, and explore the data

Quick Start Example

Here's a compact dashboard with SQL right on each chart, against the bundled Dundersign demo database (source: dundersign_db). The face-level source applies to every chart; encodings map query columns to the visualization.

title: "Document activity"

source: dundersign_db

charts:
  status_chart:
    query: |
      SELECT status, COUNT(*) AS document_count
      FROM documents
      WHERE voided_at IS NULL
      GROUP BY 1
      ORDER BY document_count DESC
    type: bar
    title: "Documents by status"
    x: status
    y: document_count

  trend_chart:
    query: |
      SELECT CAST(date_trunc('week', created_at) AS DATE) AS week, COUNT(*) AS documents
      FROM documents
      GROUP BY 1
      ORDER BY 1
    type: line
    title: "New documents per week"
    x: week
    y: documents

rows:
  - cols:
      - status_chart
      - trend_chart

▶

That's it: YAML plus SQL on the chart, a side-by-side layout, and a live board — with named queries, filters, and richer layouts layered on as you grow.

Why Dataface

• YAML is the source of truth — Dashboards are text files. Version-controlled, diffable, reviewable in a pull request.
• SQL or dbt — Start with raw SQL for speed; move to dbt metrics for governed, reusable definitions. Dataface speaks both.
• 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 — Free to run locally, with optional Cloud features.

What You Need to Know

To use Dataface 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 — Dataface handles rendering and query generation.

Get Started

• Install Dataface — get set up in your environment
• Quick Guide — learn boards, queries, charts, and variables, and build a dashboard in a few minutes
• Examples — complete, working dashboards to copy from

Once you're building, the Charts, Variables, Styling, and YAML Reference sections cover everything the language can do.