Skip to content

Getting Started Tutorial

Step-by-step tutorial for creating your first Dataface dashboard.

Prerequisites Check

Before starting, ensure you have: - ✅ Dataface installed (face --version) - ✅ dbt project with Semantic Layer configured - ✅ At least one metric and dimension defined in your Semantic Layer

Step 1: Set Up Project Structure

Create your project structure. Dataface works best when organized in a dbt project:

my-dbt-project/
├── dbt_project.yml
├── models/
├── dashboards/              # Your dashboards here
│   └── my_first_dashboard.yml
├── assets/                  # Optional: Assets directory
│   ├── images/             # Logos, icons, images
│   ├── styles/             # CSS files (future)
│   └── data/               # CSV files for CSV queries
└── profiles.yml

Note: The assets/ directory is optional but useful for: - Storing logos and images referenced in dashboard content - CSV files for CSV data connector queries - Future: CSS stylesheets for custom styling

Step 2: Create Dashboard File

Create a new file dashboards/my_first_dashboard.yml:

title: "My First Dashboard"

Step 3: Define a Query

Add a query that fetches data from your Semantic Layer:

title: "My First Dashboard"

queries:
  sales:
    metrics: [total_revenue]
    dimensions: [month]

Replace total_revenue and month with metrics and dimensions from your Semantic Layer.

Step 4: Create a Chart

Add a chart to visualize the query data:

title: "My First Dashboard"

queries:
  sales:
    metrics: [total_revenue]
    dimensions: [month]

charts:
  revenue_chart:
    title: "Revenue by Month"
    query: sales
    type: bar
    x: month
    y: total_revenue

rows:
  - title: "Sales Overview"
    cols:
      - revenue_chart

Step 5: Organize with Layouts

Layouts organize your dashboard. You can use rows, cols, or grid:

rows:
  - title: "Sales Overview"
    cols:
      - revenue_chart
      - orders_chart

Step 6: Validate and Preview

Validate Your Dashboard

face validate dashboards/my_first_dashboard.yml

Fix any errors that appear.

Preview Your Dashboard

face serve dashboards/my_first_dashboard.yml

Open your browser to http://localhost:8080 to see your dashboard!

Step 7: Add Variables

Add interactive filters:

title: "My First Dashboard"

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

queries:
  sales:
    metrics: [total_revenue]
    dimensions: [month]
    filters:
      region: "{{ region }}"

charts:
  revenue_chart:
    title: "Revenue by Month"
    query: sales
    type: bar
    x: month
    y: total_revenue

rows:
  - title: "Sales Overview"
    cols:
      - revenue_chart

Now your dashboard has a region filter that updates the chart!

Step 8: Add More Charts

Add additional charts using grid layout:

charts:
  revenue_chart:
    title: "Revenue by Month"
    query: sales
    type: bar
    x: month
    y: total_revenue

  orders_chart:
    title: "Orders by Month"
    query: sales
    type: line
    x: month
    y: order_count

rows:
  - title: "Sales Overview"
    grid:
      columns: 12
      items:
        - item: revenue_chart
          width: 6
        - item: orders_chart
          width: 6

Complete Example

Here's your complete first dashboard:

title: "My First Dashboard"

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

queries:
  sales:
    metrics: [total_revenue, order_count]
    dimensions: [month, region]
    filters:
      region: "{{ region }}"

charts:
  revenue_chart:
    title: "Revenue by Month"
    query: sales
    type: bar
    x: month
    y: total_revenue
    color: region

  orders_chart:
    title: "Orders by Month"
    query: sales
    type: line
    x: month
    y: order_count
    color: region

rows:
  - title: "Sales Overview"
    grid:
      columns: 12
      items:
        - item: revenue_chart
          width: 6
        - item: orders_chart
          width: 6

Next Steps

Now that you've created your first dashboard:

  1. Read the Queries Guide - Learn more about queries
  2. Read the Charts Guide - Explore chart types and options
  3. Read the Variables Guide - Add more interactive filters
  4. See Examples - Explore example dashboards
  5. Best Practices - Learn dashboard design best practices

Common Questions

How do I know which metrics/dimensions are available?

Check your dbt Semantic Layer configuration in dbt_project.yml or use MetricFlow CLI: 

mf list metrics
mf list dimensions

Can I use multiple queries?

Yes! Define multiple queries and reference them in different charts.

How do I add more rows?

Add more items to the rows array. Each row can have its own layout with cols or grid.

Can I customize colors and styling?

Yes! See the Styling Guide for theme and styling options.