Skip to content

Quick Reference Cheat Sheet

Quick reference for Dataface board structure and common patterns.

Board Structure

title: "Board Title"
description: "Optional description"
tags: [marketing, q1]

theme: default

# Layout (Use exactly one: rows, cols, grid, tabs)
rows:
  - _header_partial       # Include other files
  - title: "KPIs"
    cols:                 # Nested layout
      - kpi_revenue
      - kpi_orders

# Definitions (Scoped to this board)
variables:
  region:
    input: select
    column: orders.region

queries:
  revenue:
    description: "What this query powers"
    metrics: [revenue]
    dimensions: [month]

charts:
  kpi_revenue:
    type: kpi
    query: queries.revenue
    value: revenue

Query Templates

Semantic Layer (MetricFlow)

queries:
  sales:
    description: "Monthly revenue and order trends by region"
    metrics: [revenue, orders]
    dimensions: [month, region]
    time_grain: month
    limit: 100

dbt Model

Query a dbt model with plain SQL — ref() resolves through the dbt profile source:

queries:
  raw_data:
    description: "Base order rows for detailed analysis"
    sql: SELECT order_id, amount, status FROM {{ ref('fct_orders') }}
    source: my_dbt_source

Raw SQL

queries:
  custom:
    description: "Orders above the current minimum threshold"
    sql: |
      SELECT * FROM orders
      WHERE amount > {{ min_amount }}
    source: my_postgres

Chart Template

charts:
  revenue_trend:
    title: "Revenue Trend"
    description: "Tracks monthly revenue by region"
    query: queries.sales
    type: line                  # bar, line, area, scatter, kpi, table...
    x: month
    y: revenue
    color: region
    style:
      legend:
        visible: true

Variable Template

variables:
  # Column-bound (Automatic options)
  region:
    input: select               # select, multiselect, text, number...
    description: "Region filter applied to all charts"
    column: orders.region

  # Date Range
  date_range:
    input: daterange
    description: "Date range for report period"
    default: "2024-01-01 to 2024-01-31"

  # Custom Options
  status:
    input: select
    description: "Lifecycle status filter"
    options:
      static: [Draft, Active, Archived]
      # OR dynamic
      query: queries.statuses
      column: status_id
      label_column: status_name

Layout Templates

Rows (Vertical)

rows:
  - title: "Top Section"
    description: "Primary KPI context"
    cols: [...]
  - trend_chart

Cols (Horizontal)

cols:
  - width: "30%"
    chart: sidebar_nav
  - width: "70%"
    chart: main_content

Grid

grid:
  columns: 24
  row_height: "150px"
  items:
    - item: kpi_1
      description: "Revenue KPI card"
      col_span: 6
    - item: kpi_2
      col_span: 6
    - item: main_chart
      col: 0
      row: 1
      col_span: 24
      row_span: 4

Tabs

tabs:
  position: top
  items:
    - title: "Overview"
      description: "Executive summary tab"
      rows: [...]
    - title: "Details"
      grid: {...}

Foreach (Dynamic Generation)

rows:
  - foreach:
      query:
        data:
          - name: "Revenue"
            type: "numeric"
          - name: "Orders"
            type: "numeric"
      as: col
      items:
        - title: "{{ col.name }}"
          text: "Type: {{ col.type }}"

Common Patterns

Filtered Query

variables:
  region:
    input: select
    column: customers.region

queries:
  filtered:
    sql: |
      SELECT month, SUM(revenue) AS revenue FROM orders
      WHERE {{ filter('region', region) }}
      GROUP BY month
    source: warehouse

KPI Row

rows:
  - height: "120px"
    cols:
      - type: kpi
        query: queries.kpis
        value: revenue
      - type: kpi
        query: queries.kpis
        value: orders

Variable-Filtered Chart

variables:
  selected_category:
    input: select
    column: products.category

queries:
  sales:
    sql: |
      SELECT product, revenue FROM sales
      WHERE {{ filter('category', selected_category) }}
    source: warehouse

charts:
  filtered_bar:
    type: bar
    query: queries.sales
    x: product
    y: revenue

Field Quick Reference

Common Chart Types

  • bar - Bar chart
  • line - Line chart
  • area - Area chart
  • scatter - Scatter plot
  • table - Data table
  • kpi - Single number
  • heatmap - Heatmap

Common Inputs

  • select - Single dropdown
  • multiselect - Multiple dropdown
  • daterange - Date range picker
  • text - Text input
  • number - Number input
  • checkbox - Toggle

Layout Keys

  • rows - Vertical stack
  • cols - Horizontal stack
  • grid - 2D Grid
  • tabs - Tabbed view
  • foreach - Dynamic generation from data

Expression Quick Reference

References

WHERE region = '{{ region }}'                  -- direct reference
  AND backup = '{{ region or 'All' }}'         -- with default
  AND {{ filter('region', region) }}           -- helper: unset → unfiltered

Formatting

WHERE order_date >= '{{ date_range | date('%Y-%m-%d') }}'
  AND amount_label = '{{ amount | number('0.00') }}'

Logic

WHERE {% if show_all %} 1=1 {% else %} id = {{ id }} {% endif %}