Create a dashboard

A dashboard chooses one workspace semantic model and composes reusable filters, visual queries, tabular queries, and report pages. Build the smallest useful page first, verify its query behavior, and add interactions only after the standalone results are correct.

[!TIP] Use this guide for the authoring workflow and representative configuration. Use Dashboard configuration and Visual types when you need the complete accepted field contract.

Before you begin

Verify the semantic model with direct queries and choose a small decision-oriented page to build first. Prepare expected values for each initial visual at an unfiltered state and at least one filtered state.

Use this sequence:

  1. Create the dashboard and one bounded, deterministically sorted visual query.
  2. Place that visual on a page with a compact-layout reading order.
  3. Add a KPI and verify both against direct semantic queries.
  4. Add filters and interactions one at a time.
  5. Validate, plan, deploy to development, and review every state.

Define the dashboard surface

Create the resource

Create dashboards/workspaces/sales/dashboards/executive-sales.yaml:

apiVersion: leapview.dev/v1
kind: Dashboard
metadata:
  workspace: sales
  name: executive-sales
  title: Executive Sales
  description: Revenue and order trends for sales leadership.
  tags: [sales, revenue]
spec:
  semanticModel: sales
  visuals:
    revenue_by_month:
      title: Revenue by month
      type: area
      query:
        dimensions:
          purchase_month: orders.purchase_month
        measures:
          revenue:
        sort:
          - field: purchase_month
            direction: asc
        limit: 30
  pages:
    - id: overview
      title: Overview
      grid:
        columns: 12
        row_height: 48
        gap: 16
        padding: 16
      components:
        - id: revenue-trend
          kind: visual
          visual: revenue_by_month
          placement: {col: 1, row: 1, col_span: 12, row_span: 8}

The visual definition owns semantic query and presentation settings. The page entry references it by stable ID and owns placement. This separation keeps layout edits from rewriting data logic.

Design the query result

Names on the left of dimensions and measures are stable field IDs compiled into the visualization specification. Values on the right refer to semantic fields. Choose clear aliases and keep them stable when typed presentation or interactions depend on them.

Every chart query should have a bounded limit and deterministic sort. For time series, sort the time field ascending. For ranked bars, sort the value descending and choose a limit that users can read. Do not rely on database default order.

Add a KPI

KPI visuals use one measure and typed KPI presentation:

visuals:
  total_revenue:
    type: kpi
    query:
      measures:
        revenue:
    presentation:
      note: Filtered order revenue
      tone: success

Place it on the page with kind: visual and visual: total_revenue. Its type: kpi selects the KPI renderer. The semantic measure supplies empty and formatting behavior; the dashboard supplies context-specific note and tone.

Add filters after the base query works

Define filters against semantic fields and place filter-card components on the page. Exercise each filter independently before combining several. Use stable URL parameters when users should share filtered links.

Validate the dashboard

Discover and validate

Ensure the workspace manifest includes dashboard files, then run:

leapview validate --project dashboards/leapview.yaml
leapview plan --project dashboards/leapview.yaml

Validation checks contract shape and references. The plan shows the resource-level candidate. Neither proves that a visual communicates the right result, so deploy to development and verify the rendered page with representative data.

Verify the rendered page

Confirm that:

  • the dashboard appears in the intended workspace;
  • titles, descriptions, and tags support discovery;
  • chart and KPI results match direct semantic queries;
  • filters change every intended component and no unintended component;
  • empty, loading, and failure states are readable;
  • component order makes sense for keyboard and compact layouts;
  • limits and sorting remain useful for high-cardinality data.

Troubleshooting

If a visual is empty, first run its semantic query without dashboard filters, then add filters one at a time. If values are correct but order changes between loads, add an explicit sort with a stable tie-breaker. If a compact layout reads poorly, fix component source order and placement together rather than using visual-only CSS reordering.

Next steps

Continue with Pages and layout, Filters and interactions, and Tables, matrices, and pivots. Use Dashboard configuration and Visual types for exact contracts.