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:

charts:
  revenue_chart:
    query: _doc_examples.yaml#sales_by_product
    type: bar
    title: Revenue by Product
    x: product
    y: revenue
rows:
  - revenue_chart
Gadget XGadget YTool ZWidget AWidget BProduct$0$5,000$10,000$15,000$20,000$25,000$30,000$35,000$40,000$45,000$50,000$55,000$60,000$65,000$70,000$75,000$80,000$85,000RevenueRevenue by Product 2026-05-12 12:34
▶

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
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 | number # KPI value binding, or map fill field
    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
    href: string           # URL field/template for point clicks
    filters:
      <field>: <expression>

    # Chart-specific presentation
    style:
      palette: string                    # Named color palette
      background: string                 # Chart SVG background fill
      legend:
        disable: boolean                 # true to hide legend
      axis:
        grid:
          hidden: boolean                # true to hide grid lines
      orientation: horizontal | vertical  # Bar chart orientation
      stack: boolean                      # Stack grouped data
      columns:
        - column: string                  # Table column config
      # 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 Styling

Customize chart appearance:

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

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

See the Styling guide for themes and color palettes.

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 href: click-through links. Structured click handlers are planned for a future release but are not part of the current chart schema.

Previewing Charts

Preview your charts interactively:

dft serve faces/sales.yml --reload

The --reload flag auto-refreshes on save. 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 href: click-through links
  • Queries - Data sources for charts
  • Boards - Organizing charts in dashboards
  • Variables - Variables in query and chart filters
  • Styling - Themes and color palettes