Visualizations

Visualization files map query output to UI

Each visualization consumes one model query and renders one chart or table. Keep all transformation logic in model queries. The visualization YAML is only for presentation decisions: which chart type, which fields map to which axes, how numbers are formatted.

For a full catalog of all supported types with working examples, see Visualization Types.

The query reference format

Every visualization points to a model query using this format:

query: "models/ec_revenue.malloy::by_category"

The part before :: is the path to the .malloy file from the workspace root. The part after :: is the view or query name defined inside that file. Both must match exactly — this reference is validated on every looky validate run.

Working examples from ecommerce-showcase

KPI with delta

id: ec_revenue_kpi
title: Revenue
query: "models/ec_revenue.malloy::kpi"
type: kpi
mapping:
  value: revenue
  delta: return_rate_pct
format:
  revenue: "$#0,0a"
  return_rate_pct: "#0,00%"
published: true

Bar chart

id: ec_revenue_by_category_bar
title: Revenue by Category
query: "models/ec_revenue.malloy::by_category"
type: bar
mapping:
  x: category
  y: revenue
format:
  revenue: "$#0,00"
published: true

Line chart with dual axis

id: ec_revenue_over_time_line
title: Revenue Over Time
query: "models/ec_revenue.malloy::over_time"
type: line
mapping:
  x: order_month
  y: revenue
  y2: order_count
  series_label: Revenue
  series_label_2: Orders
format:
  revenue: "$#0,00"
  order_count: "#0"
published: true

Cross-filtering

In fluid_grid dashboards, bar charts, line charts, scatter plots, and heatmaps participate in cross-filtering by default. When a user clicks a data point, all other cross-filter-enabled visualizations in the dashboard filter to that selection.

To opt a visualization out of cross-filtering — for example a headline KPI that should always show the full period total — add this to the visualization YAML:

chart:
  cross_filter: false

KPIs and grids do not emit cross-filter events but can receive them.

All supported chart fields

The chart block controls rendering behavior beyond the data mapping:

chart:
  height: 420              # fixed height in pixels
  variant: donut           # for bar type: donut renders as pie/donut
  cross_filter: false      # opt out of cross-filtering
  show_value_labels: true  # show values inside the chart
  show_legend: true        # show/hide the chart legend
  legend_position: bottom  # legend position: bottom | right
  pdf_expand_all: true     # for report_matrix: expand all groups in PDF

Validation checklist

• query path and view name both exist and match exactly.
• Every field referenced in mapping exists in the query output.
• Every field referenced in format also exists in mapping.
• id is unique across all visualizations in the workspace and stable over time — changing it breaks dashboards that reference it.
• published: true is explicit for visualizations that should appear in dashboards.

looky validate
looky list visualizations