Quick Guide¶

Get up and running with Dataface in 5 minutes. This guide walks you through the core concepts and builds a dashboard from scratch.

Core Elements¶

Dataface has just four core elements:

boards — containers that define layout and structure
queries — fetch data via SQL, CSV, dbt, MetricFlow, or HTTP
charts — visualize data from queries
variables — user inputs that filter and update the dashboard

We'll make combinations fo these in one YAML file to declare exactly the dashboard we'd like to be rendered. We'll start by going through each of these and build up an example dashboard.

Boards of boards: The Layout System¶

Boards are the fundamental building block of Dataface. They work recursively and by creating and nesting combinations of boards you can make incredibly complex designs. A board uses one of four layout types: rows, cols, tabs, or grid.

Here's a quick example showcasing the different types of boards:

rows:
  - title: "ROWS: Stack items vertically"
    style:
      border: "2px solid tomato"
      padding: "12px"
    rows:
      - content: "**First row item** - full width"
        style:
          background: mistyrose
          padding: "8px"
      - content: "**Second row item** - stacks below"
        style:
          background: pink
          padding: "8px"

  - title: "COLS: Place items side by side"
    style:
      border: "2px solid dodgerblue"
      padding: "12px"
    cols:
      - content: "**Left column**"
        style:
          background: aliceblue
          padding: "8px"
      - content: "**Middle column**"
        style:
          background: lightblue
          padding: "8px"
      - content: "**Right column**"
        style:
          background: lightskyblue
          padding: "8px"

  - title: "NESTED: Unequal widths"
    style:
      border: "2px solid mediumseagreen"
      padding: "12px"
    cols:
      - content: "**Wide** (2/3)"
        style:
          background: honeydew
          padding: "8px"
      - cols:
          - content: "**Narrow** (1/6)"
            style:
              background: palegreen
              padding: "8px"
          - content: "**Narrow** (1/6)"
            style:
              background: lightgreen
              padding: "8px"

  - title: "TABS: Organized views"
    style:
      border: "2px solid mediumorchid"
      padding: "12px"
    tabs:
      items:
        - title: "Tab A"
          content: "Content for **Tab A** - click the tabs above!"
          style:
            background: lavender
            padding: "12px"
        - title: "Tab B"
          content: "Content for **Tab B** - tabs hide content until needed"
          style:
            background: thistle
            padding: "12px"
        - title: "Tab C"
          content: "Content for **Tab C** - great for reducing clutter"
          style:
            background: plum
            padding: "12px"

▶

As you can see, you can nest simple boards to create complex layouts. You can even import entire files and use them as board items.

Split Screen Imports - Show two dashboards side by side:

title: "Split Screen View"
cols:
  - title: "Sales Dashboard"
    style:
      border: "2px solid tomato"
      padding: "12px"
    rows:
      - content: "## 📈 Sales Overview"
        style:
          background: mistyrose
          padding: "8px"
      - content: "Revenue metrics and trends would go here"
        style:
          background: pink
          padding: "8px"

  - title: "Marketing Dashboard"
    style:
      border: "2px solid dodgerblue"
      padding: "12px"
    rows:
      - content: "## 📊 Marketing Overview"
        style:
          background: aliceblue
          padding: "8px"
      - content: "Campaign metrics and analytics would go here"
        style:
          background: lightblue
          padding: "8px"

▶

With imports, this becomes just:

cols:
  - sales_dashboard      # Imports sales_dashboard.yml
  - marketing_dashboard  # Imports marketing_dashboard.yml

Any .yml file can be imported by name (without extension) and used as a board item.

In a nutshell, that's the layout system: boards of boards.

Queries: Getting Data¶

Queries define where your data comes from. Each query has a name and a source:

queries:
  sales:
    sql: |
      SELECT product, category, revenue, units_sold
      FROM sales
      WHERE revenue > 100
    profile: my_postgres

Dataface supports multiple types of queries: SQL, values (inline data), CSV, dbt, MetricFlow, HTTP APIs, and more. You can even reference queries from other files.

queries:
  # SQL query
  sales:
    sql: SELECT * FROM sales

  # Inline data — no database needed
  products:
    columns: [product, price, category]
    values:
      - ["Widget A", 29.99, "Electronics"]
      - ["Gadget X", 34.00, "Accessories"]

  # Import from another file
  users:
    source: shared_queries.yml#users

📖 See Queries for the full guide on all source types.

Charts: Visualizing Data¶

Charts turn query data into visualizations. Reference a query and map fields to chart properties:

charts:
  revenue_by_product:
    query: _doc_examples.yaml#sales_by_product
    type: bar
    x: product
    y: revenue

rows:
  - revenue_by_product

▶

The chart references query: _doc_examples.yaml#sales_by_product to pull product-level totals, then maps product to the x-axis and revenue to the y-axis.

Multiple Charts¶

Add more charts and arrange them with layouts:

charts:
  revenue_bar:
    query: _doc_examples.yaml#sales_by_product
    type: bar
    x: product
    y: revenue

  category_donut:
    query: _doc_examples.yaml#sales_by_category
    type: donut
    theta: revenue
    color: category

  trend_line:
    query: _doc_examples.yaml#sales_by_date
    type: line
    x: date
    y: revenue

rows:
  - cols:
      - revenue_bar
      - category_donut
  - trend_line

▶

Dataface supports all Vega-Lite chart types: bar, line, area, pie, donut, scatter, heatmap, table, kpi, and more.

Variables: Making It Interactive¶

Variables add user inputs that dynamically update your dashboard. Let's start with a simple example:

variables:
  name:
    input: input
    default: World

rows:
  - content: "# Hello, ${ name }! 👋"
    style:
      background: honeydew
      padding: "20px"
      text-align: center

▶

Type in the input above and watch the greeting change! The ${ name } syntax inserts the variable value.

Variables in Dashboards¶

Variables can appear anywhere — in text, titles, and even query filters. Here's a dashboard with a category selector:

variables:
  category:
    input: select
    options:
      static: [Electronics, Furniture, Clothing]
    default: Electronics

charts:
  revenue_kpi:
    query: _doc_examples.yaml#sales_summary
    type: kpi
    metric: revenue

  revenue_chart:
    query: _doc_examples.yaml#sales_by_product
    type: bar
    x: product
    y: revenue

rows:
  - content: "### Showing: ${ category }"
    style:
      background: azure
      padding: "12px"
  - revenue_kpi
  - revenue_chart

▶

The selected category appears in the header. For actual data filtering, variables connect to query filters — see Queries for details.

📖 See Variables for all input types: select, text, number, date, date range, and more. For a complete reference, see UI Elements.

Styling: Making It Beautiful¶

Boards support title, content (markdown), and style properties to customize appearance:

variables:
  category:
    input: select
    options:
      static: [Electronics, Furniture, Clothing]
    default: Electronics

charts:
  total_revenue:
    query: _doc_examples.yaml#sales_summary
    type: kpi
    metric: revenue

  units_sold:
    query: _doc_examples.yaml#sales_summary
    type: kpi
    metric: units_sold

  revenue_chart:
    query: _doc_examples.yaml#sales_by_product
    type: bar
    x: product
    y: revenue
    color: category

  trend_chart:
    query: _doc_examples.yaml#sales_by_date
    type: area
    x: date
    y: revenue

rows:
  - content: |
      # 📊 Sales Dashboard

      Real-time insights into **${ category }** performance and revenue trends.
    style:
      background: "linear-gradient(135deg, #1e3a5f 0%, #2d5a87 100%)"
      color: white
      padding: "24px"
      border-radius: "8px"

  - cols:
      - total_revenue
      - units_sold
    style:
      gap: "16px"

  - cols:
      - revenue_chart
      - trend_chart
    style:
      gap: "16px"

  - content: |
      ---
      💡 **Tip:** Use the category filter above to drill down into specific segments.
    style:
      background: ghostwhite
      padding: "12px 16px"
      border-left: "4px solid dodgerblue"
      margin-top: "8px"

▶

Style properties accept any CSS: background, padding, border, color, border-radius, and more. Use content for markdown text, headers, and even images.

📖 See Styling for theming, custom CSS, and design patterns.

Getting Started¶

Installation¶

Install Dataface with pip:

pip install dataface

📖 See Installation Guide for detailed setup instructions.

CLI Commands¶

Once installed, use the dft command:

dft validate my-board.yml                    # Check for errors
dft render my-board.yml -o out.html          # Export to HTML
dft render my-board.yml --format terminal    # Preview in terminal
dft serve my-board.yml                       # Live preview with hot reload
dft play my-board.yml                        # Open the visual playground

The Playground¶

The playground is an interactive editor where you can build and preview dashboards in real-time:

dft play my-board.yml

Every rendered example in these docs has a "Open in Playground" link — click it to experiment with the code yourself! The playground also includes a library of example dashboards to explore.

Quick Reference¶

# Complete dashboard structure
title: My Dashboard

variables:
  filter:
    input: select
    options:
      static: [A, B, C]

queries:
  my_data:
    sql: SELECT * FROM table

charts:
  my_chart:
    query: my_data
    type: bar
    x: dimension
    y: metric

rows:
  - content: "# Welcome!"
  - my_chart

That's it — boards, queries, charts, and variables. Start simple, add complexity as needed. Happy building! 🚀