Skip to content

Charts

Charts visualize your query data. Each chart references a query and defines how to display it.

Vega-Lite foundation: Charts render through Vega-Lite, but authored chart YAML is a typed Dataface surface. Use top-level Dataface fields (x, y, color, lookup, value, etc.) and the typed style object exclusively. Arbitrary Vega-Lite spec, mark, encoding, config, transform, params, and composition (hconcat/vconcat/concat/repeat/resolve) blocks are rejected on the authored surface.

A chart's control surface is the full set of authored properties available on a single chart. In Dataface, that surface is primarily top-level chart fields plus the typed style object.

Basic Chart Structure

charts:
  revenue_chart:
    title: "Revenue by Month"
    query: queries.sales          # References a query name
    type: bar                     # Chart type
    x: month                      # X-axis dimension
    y: total_revenue              # Y-axis metric

Here's a working example:

source: examples_db
charts:
  revenue_chart:
    query:
      sql: |
        SELECT product, category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY product, category ORDER BY revenue DESC
    type: bar
    title: Revenue by Product
    x: product
    y: revenue
rows:
  - revenue_chart
Dataface DF-UNKNOWN-INTERNALChart Error: revenue_chartQuery execution failed: Source 'examples_db' not found. No source profiles are configured. Declare sources under `sources:` in your dataface.yml. (query: _inline_query_revenue_chart)https://docs.it-dataface.com/guides/error-handling/?code=DF-UNKNOWN-INTERNAL 2026-07-17 15:04 UTC made with dataface
▶

Common Chart Types

Type Best For
line Time series trends
bar Comparisons across categories
area Stacked trends over time
scatter Relationships between metrics
pie / donut Part-to-whole comparisons
heatmap Two-dimensional patterns
histogram Distributions
table Detailed data view
kpi Single metric display
callout Status or warning message card
map Geographic region maps
point_map Location markers
bubble_map Sized location markers

See also: Bar Charts • Line Graphs • Sector Charts • Point Charts • Area Charts • Maps • Tables and Text

Field Reference

charts:
  <chart_id>:              # Unique identifier (must be unique within a file and across all imported files)
    title: string          # Optional
    query: string          # Required
    type: string           # Required (bar, line, area, etc.)

    # Channel fields
    x: string              # Dimension for x-axis
    y: string | [string]   # Metric(s) for y-axis
    color: string          # Field to encode as color
    size: string           # Field to encode as size
    shape: string          # Field to encode as shape

    # KPI-specific
    value: string          # KPI value binding or map fill field (column reference)
    label: string         # KPI label above the value

    # Map-specific
    geo_source: string     # Built-in geographic data source
    lookup: string         # Query field to join to geography
    latitude: string       # Point/bubble map latitude field
    longitude: string      # Point/bubble map longitude field

    # Data and links
    sort:
      by: string
      order: asc | desc
    link: string           # URL template for drill-down links ({{ x }}, {{ y }}, etc.)

    # Chart-specific presentation
    style:
      palette: string                    # Named color palette
      background: string                 # Chart SVG background fill
      legend:
        visible: boolean                 # false to hide legend
      axis:
        grid:
          visible: boolean               # false to hide grid lines
      orientation: horizontal | vertical  # Bar chart orientation
      stack: none | zero | normalize | center  # Stack mode
      columns:
        column_name: {}                   # Table column config (mapping key = column name)
      # Axis, scale, legend, mark, and other style sections...

    description: string    # Help text/tooltip

Row limiting belongs on the query (queries.<id>.limit), not on the chart.

Chart Sizing

Two fields at chart root control how tall a chart renders. They live directly under charts.<name>:, not under style:.

charts:
  revenue_trend:
    query: revenue
    type: bar
    x: month
    y: total
    height: 400          # exact pixel height; wins over aspect_ratio and theme

  wide_chart:
    query: revenue
    type: line
    x: month
    y: total
    aspect_ratio: 3.0    # wider than default; height = width / 3.0
  • height — fixes the pixel height exactly. Bypasses min_height/max_height clamps. Not supported on kpi, table, callout, or spark_bar.
  • aspect_ratio — controls shape without pinning a size. The theme default is 1.5 (3:2 landscape). Not supported on the same chart types.

Width is always owned by the layout. There is no chart-root width: field.

See Board Sizing for the full three-layer model (layout tile → chart root → theme default) and guidance on when to use each layer.

Chart Styling

Customize chart appearance:

charts:
  styled_chart:
    query: queries.sales
    type: bar
    x: month
    y: total_revenue
    style:
      palette: "category10"       # Color scheme
      legend:
        visible: true             # Show legend (default)
      axis:
        grid:
          visible: true            # Show grid lines
      background: "#f8fafc"       # Chart background fill

Style options: - palette: Color scheme (e.g., "category10", "viridis", "blues") - legend.visible: false to hide the legend - axis.grid.visible: false to hide grid lines - background: SVG/CSS-compatible background fill applied behind the chart

See the Styling guide for themes and color palettes.

Value Labels

Bar, line, and scatter charts can show the numeric value on each mark. Enable per-chart via the family marks path:

style:
  bar:           # or line: / scatter:
    marks:
      bar:       # or line: / point:
        labels:
          visible: true     # show value above each bar
          position: top     # top | inside_top | middle (bar); top | bottom | left | right | middle (line/point)

format defaults to null (inherits from axis_y format). Set a d3-format string to override. See per-chart docs for the full field list: Bar Charts · Line Graphs · Point Charts.

Best Practices

Choosing Chart Types

  • Time series: Use line or area
  • Comparisons: Use bar
  • Relationships: Use scatter
  • Single numbers: Use kpi
  • Detailed data: Use table

Effective Color Encoding

  • Use color to distinguish categories
  • Choose accessible palettes (colorblind-friendly)
  • Limit distinct colors (5-7 max)

Filtering

  • Use variables with dropdowns for cross-chart filtering
  • Tooltips appear automatically on hover

See Interactions for hover tooltips and link: drill-down links.

Previewing Charts

Preview your charts interactively:

dft serve

dft serve auto-discovers the project and prints the URL on startup. See CLI Reference.

Validate First

dft validate faces/sales.yml
  • Bar Charts - Comparison-first charts and columns
  • Line Graphs - Line-graph style, examples, Vega-Lite mapping, and gaps
  • Sector Charts - Pie, donut, and related arc-based charts
  • Point Charts - Dot plots, scatterplots, and other point-based charts
  • Area Charts - Filled trend and composition charts
  • Maps - Geographic charts and projection-aware mapping
  • Tables and Text - Exact-value tables, KPIs, and other data-powered text outputs
  • Interactions - Hover tooltips and link: drill-down links
  • Queries - Data sources for charts
  • Boards - Organizing charts in dashboards
  • Variables - Variables in query filters and inputs
  • Styling - Themes and color palettes