Dataface Overview¶

Dataface makes it easy to make any Interface for your Database. You, or AI write straight forward YAML language declaring what you want to see, and then render it out in a variety of different formats.

What and who is it for?¶

Built on top of dbt, Dataface empowers data analysts and engineers with visual workflows in three key areas:

1. Data Understanding & Governance¶

Diagnose and model with confidence. Use the built-in Diagnostics tool to visually profile data, spot quality issues, and understand distributions before you build.

2. Data Exploration¶

Go from query to visual instantly. A fast, iterative interface for exploring data and finding insights without the overhead of building complex reports.

3. Reporting & Dashboarding¶

Build and share polished narratives. Create extensive, interactive dashboards with rich formatting options and share them in multiple formats.

How It Works¶

You write a YAML file describing what data to show and how to visualize it
Dataface compiles it into an interactive board
The board queries your database (via SQL) or your dbt Semantic Layer (MetricFlow) to fetch data
Users interact with filters, click charts, and explore the data

Key Benefits¶

No coding required — YAML is easy to learn and write
SQL or dbt — Dataface speaks both. Start with raw SQL for speed, upgrade to dbt metrics for governance
Version control friendly — Boards are text files, perfect for Git
Fast iteration — Change YAML, preview instantly, deploy easily
Extensible — Add custom chart types via plugins
Seamless branching & deployment — Boards sync with dbt models through Git branches. When you deploy model changes, boards update automatically. No more broken dashboards after data migrations (unlike Tableau and other BI tools where you have to manually fix broken references)
Open source — Free to use locally, with optional Cloud features
AI-friendly — YAML is the perfect format for AI to generate boards and analysis results

Built for humans and AI: The Language of Data Visualization¶

Dataface isn't just for humans—it's designed to be the language of data visualization that AI can speak fluently.

Why YAML for AI? - Structured and predictable — AI models excel at generating well-structured YAML - Self-documenting — The format itself communicates intent clearly - No ambiguity — Clear schema means AI can generate valid boards consistently - Composable — AI can build complex boards by combining simple patterns

AI Use Cases: - Natural language to board — "Show me sales by region" → instant YAML board - Analysis results visualization — AI analyzes data and creates boards to show findings - Iterative refinement — AI can modify existing boards based on feedback - Automated reporting — AI generates boards from data analysis workflows

When AI needs to visualize data or show analysis results, YAML is the ideal interface. It's much easier for AI to write clean, valid YAML than to generate complex JavaScript, SQL, or configure proprietary BI tools. Dataface makes AI's work easier, enabling AI assistants to create, modify, and iterate on boards as naturally as they write code or documentation.

The future of data visualization is declarative, text-based, and AI-native. Dataface is that future.

Quick Start Example¶

Here's a simple board that shows sales data:

title: "Sales Overview"

charts:
  revenue_chart:
    query: _doc_examples.yaml#sales
    type: bar
    title: "Revenue by Category"
    x: category
    y: revenue
    color: category

  trend_chart:
    query: _doc_examples.yaml#sales
    type: line
    title: "Revenue Over Time"
    x: date
    y: revenue

rows:
  - revenue_chart
  - trend_chart

▶

That's it! A few lines of YAML creates a fully interactive dashboard.

📖 See the Quick Guide for a step-by-step walkthrough of boards, queries, charts, variables, and styling.

Getting Started¶

Ready to build your first board?

📖 Quick Guide — Learn the core concepts and build a dashboard in 5 minutes

Or follow these steps:

Install Dataface — Get Dataface set up in your environment
Quick Guide — Learn boards, queries, charts, and variables
Explore Examples — See complete working boards

Documentation Structure¶

This documentation covers the Dataface Markup Language (DSL) — the YAML-based language for creating boards.

Core Concepts¶

Quick Guide — Learn all the basics in 5 minutes
Boards — Organize dashboards with layouts
Queries — Define what data to fetch
Charts — Create visualizations of your data
Variables — Add interactive filters and inputs
Expressions — Reference variables and use Jinja expressions
UI Elements — All input types and options
Advanced — Dependent variables and conditional layouts
Styling — Customize board appearance

Examples¶

Quick Start — Minimal "hello world" board
KPI Board — Simple board with multiple KPIs
Interactive Board — Board with variables and filters
Nested Layouts — Complex board layouts
Drill-Down — Click interactions and drill-downs

Guides¶

Installation — Installation and setup
Getting Started — First board tutorial
CLI Reference — Complete CLI command reference (validate, compile, serve)
Best Practices — Board design best practices
Troubleshooting — Common issues and solutions
Data Diagnostics — Profile and understand your data

Reference¶

Field Reference — Complete field reference
Chart Types — All supported chart types (Vega-Lite)
Layout Types — All layout types
Quick Reference — Cheat sheet

What You Need to Know¶

To use Dataface effectively, you should be familiar with: - SQL or dbt — A basic understanding of data models (metrics and dimensions) - YAML — Basic YAML syntax (it's simple!) - Data visualization concepts — Charts, filters, dimensions, metrics - git - basic version control understanding

You don't need to know: - JavaScript, React, or any programming language - Complex SQL (Dataface handles query generation) - Web development or deployment (handled by Dataface)

Next Steps¶

Quick Guide → Learn core concepts in 5 minutes
Install Dataface → Get set up
Try an Example → See complete boards

Happy Board Building! 🎉