Field Reference¶

Complete reference of all fields available in Dataface.

Board¶

The fundamental building block of Dataface. A Board is a container that defines content, layout, and data resources. Boards are recursive: a board can contain other boards.

# Board
title: string                   # Optional: display title
description: string             # Optional: description
tags: [string]                  # Optional: tags for organization

# Layout (Use exactly one of these keys)
# The presence of one of these keys identifies this object as a Board.
rows: [...]                     # Stack items vertically
cols: [...]                     # Stack items horizontally
grid: {...}                     # Arrange items in a grid
tabs: {...}                     # Organize items in tabs
content: string                 # Optional: markdown content (can be used with layout)

# Styling & Dimensions (When nested)
id: string                      # Optional: unique ID for referencing (e.g. "file.id")
style: {...}                    # Optional: style overrides
width: string | number          # Optional: explicit width (e.g. "50%", 6)
height: string | number         # Optional: explicit height (e.g. "400px", 4)

# Definitions (Scoped Resources)
# Variables, queries, and charts defined here are available to this board and its children.
variables: {...}                # Optional: variable definitions
queries: {...}                  # Optional: query definitions
charts: {...}                   # Optional: shared chart definitions
style: {...}                    # Optional: styling options

Layout Configuration¶

Grid Configuration¶

Used when the grid: key is present.

# Grid Layout
grid:
  columns: number                 # Required: number of columns (e.g., 12)
  row_height: string              # Optional: height of rows (e.g., "100px")
  gap: string                     # Optional: gap size (sm, md, lg, xl)
  items:                          # Required: list of grid items
    - item: string | Board | Chart # The content to place
      description: string         # Optional: metadata for AI search/tooltips
      x: number                   # Optional: column start
      y: number                   # Optional: row start
      width: number               # Optional: column span
      height: number              # Optional: row span

Tab Configuration¶

Used when the tabs: key is present.

# Tab Layout
tabs:
  position: top | left            # Optional: tab bar position
  items:                          # Required: list of tabs
    - title: string               # Required: tab label
      icon: string                # Optional: icon name
      description: string         # Optional: metadata for AI search/tooltips
      # ... plus any Board properties (rows, cols, etc.)

Chart¶

Charts visualize data. They can be defined inline within a layout or in the charts: definition block.

# Chart
title: string                   # Optional: display title
type: string                    # Required: chart type (bar, line, etc.)
query: string                   # Required: query name reference
description: string             # Optional: help text/tooltip

## Chart Data Mapping
x: string                       # Optional: x-axis field
y: string | [string]            # Optional: y-axis field(s)
color: string                   # Optional: color encoding field
size: string                    # Optional: size encoding field
shape: string                   # Optional: shape encoding field

## Chart Configuration
limit: number                   # Optional: maximum rows

## Chart Settings (display config)
settings:                       # Optional: chart-specific display settings
  orientation: horizontal | vertical  # Bar chart orientation
  stacked: boolean              # Stack grouped data (future)
  # Type-specific settings...

## Chart Formatting & Interactivity
style: {...}                    # Optional: styling options
interactions: {...}             # Optional: interaction configuration
filters: {...}                  # Optional: chart-level filters

Query¶

Queries define how to fetch data.

# Query (MetricFlow)
description: string             # Optional: metadata for AI search/tooling
metrics: [string]               # Required: list of metric names
dimensions: [string]            # Optional: list of dimension names
filters: {...}                  # Optional: filter conditions
time_grain: string              # Optional: day|week|month|quarter|year
limit: number                   # Optional: maximum rows

# Query (dbt Model)
description: string             # Optional: metadata for AI search/tooling
model: string                   # Required: dbt model reference
columns: [string]               # Required: columns to select
filters: {...}                  # Optional: filter conditions
limit: number                   # Optional: maximum rows

# Query (SQL)
type: sql                       # Required: must be "sql"
description: string             # Optional: metadata for AI search/tooling
sql: string                     # Required: SQL query (supports Jinja)

Variable¶

Variables allow for dynamic dashboard filtering and interaction.

# Variable
input: string                   # Required: select|daterange|text|number|bool
label: string                   # Optional: display label
description: string             # Optional: helper text
default: any                    # Optional: default value (undefined by default)
required: boolean               # Optional: is value required?

# Select Options
options:
  static: [string]              # List of static values
  query: string                 # Query to fetch options dynamically
  column: string                # Column name to tie the variable to
  label_column: string          # Optional other column to use for labels

Foreach¶

The foreach construct dynamically generates layout items by iterating over inline data.

# Foreach (within rows/cols)
- foreach:
    query:                          # Required: data source
      data: [...]                   # Required: inline data array
    as: string                      # Required: loop variable name
    items: [...]                    # Required: items to generate per iteration

Fields¶

Field	Type	Required	Description
`query`	object	Yes	Contains `data` array to iterate over
`as`	string	Yes	Variable name for each row (e.g., `item`)
`items`	list	Yes	Layout items to generate per iteration

Example¶

rows:
  - foreach:
      query:
        data:
          - name: "Revenue"
            type: "numeric"
          - name: "Date"
            type: "date"
      as: col
      items:
        - title: "{{ col.name }}"
          content: "Type: {{ col.type }}"

See Board Imports for more examples.

Styling¶

# Style (Board-level)
style:
  palette: string                 # Optional: color palette name
  font: string                    # Optional: font family name
  mode: light | dark              # Optional: default color mode
  density: compact | comfortable  # Optional: spacing density

# Style (Chart-level)
style:
  palette: string                 # Optional: override color palette
  color: string                   # Optional: specific color (hex/name)
  show_legend: boolean            # Optional: toggle legend
  show_grid: boolean              # Optional: toggle grid lines
  show_labels: boolean            # Optional: toggle data labels
  x_axis: {...}                   # Optional: axis config
  y_axis: {...}                   # Optional: axis config

Interaction¶

Coming Soon

Click interactions are planned but not yet implemented. Hover tooltips work automatically.

# Interaction (planned)
interactions:
  click:                          # Not yet implemented
    action: string                # filter|open_link|set_variable
    target: string                # Target variable or link pattern
  hover:
    tooltip: boolean              # Show tooltip (default: true)