Dashboards

One dashboard, one question

Most BI tools push you toward one giant dashboard that tries to answer everything at once. The result is a screen full of charts that no one reads. Looky is built around the opposite principle: one focused dashboard per business question.

A dashboard that answers "Where is revenue leaking this quarter?" is useful. A dashboard that shows all metrics for all dimensions for all time periods is a loading screen with charts. Build small, sharp, and publishable.

Two layout modes support different use cases. layout_mode is required; the only allowed values are:

• fluid_grid: interactive, responsive canvas. Charts sit side by side and cross-filter each other when users click. Best for exploration and operational monitoring.
• document: fixed top-to-bottom reading order. Designed to be read, shared, and exported to PDF. Best for reports, briefings, and scheduled deliveries.

Any other value is rejected by the validator.

Fluid grid dashboard with layout control

Use width on items to control how much of the row each visualization occupies. The grid thinks in thirds: width 1 = one third, 2 = two thirds, 3 = full row. Two extra span tokens exist for KPI rows: 4 = a quarter of the row and 6 = half the row. Omit width to let the layout planner size items by type (tables span the row; a chart followed by one or two KPIs composes automatically).

An item may also set height (a minimum height in pixels) and title_override (a display title replacing the viz's own for this dashboard only).

id: ec_order_fulfillment_dashboard
title: "How Is Fulfillment Performing?"
description: "Track created orders, shipment progress, delivery completion, and where leakage happens in fulfillment."
layout_mode: fluid_grid
published: true
tags: ["ecommerce", "fulfillment", "funnel", "dashboard"]
filters:
  - id: global_period
    type: cutoff_date
    granularity: year
    label: Period
    default: "{{today}}"
items:
  - visualization: ec_fulfillment_created_kpi
    width: 6
  - visualization: ec_fulfillment_shipped_rate_kpi
    width: 6
  - visualization: ec_fulfillment_delivered_rate_kpi
    width: 6
  - visualization: ec_fulfillment_return_rate_kpi
    width: 6
  - visualization: ec_fulfillment_funnel
    width: 2
  - visualization: ec_fulfillment_leakage_grid
    width: 1

Document dashboard for reports and exports

Document mode renders in a fixed single-column layout. It is the right choice when the dashboard will be shared via PDF export or when the reading order carries meaning.

id: ec_business_overview
title: What Is Happening In The Business?
layout_mode: document
published: true
filters:
  - id: global_period
    type: cutoff_date
    granularity: year
    param: cutoff_date    # lets a scheduled export inject the date by this name
    label: Period
    default: "{{today}}"
items:
  - visualization: ec_revenue_kpi
  - visualization: ec_orders_kpi
  - visualization: ec_aov_kpi
  - visualization: ec_revenue_over_time_line
  - visualization: ec_category_brands_matrix
  - visualization: ec_orders_by_status_bar

Document dashboards can be exported to PDF on a schedule — the export's params.cutoff_date binds through the param declared above. See Scheduled Exports.

What is NOT a dashboard-YAML field

Cross-filter relationships are not declared at the dashboard level. There is no cross_filter block on the dashboard. Cross-filter is a per-viz toggle and an automatic dashboard-wide runtime behavior — see Cross-filtering.

Similarly, the items[] entry shape is small: visualization (required — a viz id, not a file path) plus the optional width, height, and title_override. There is no position, row, or col; the fluid grid lays out items in declaration order and the document layout is single-column. Prose between charts in a document dashboard is not a dashboard field either — author it as a text viz and reference it from items.

Pagination inside a dashboard

Grid and report_matrix items inside a dashboard paginate server-side; changing pages re-runs the underlying query with the new page parameters. The behavior is identical across BigQuery, Postgres, and MySQL sources. Cost characteristics differ — see Source adapter differences.

Filter types

Filters declared on a dashboard apply to every viz the dashboard contains. The full per-type reference lives at Filters; the two most common shapes for dashboards are shown below.

cutoff_date — time-period selection

The most common dashboard filter. The user picks a single date and Looky sends two parameters to every query: date_from and date_to. The lower bound depends on granularity.

filters:
  - id: global_period
    type: cutoff_date
    granularity: month     # day | month (default) | quarter | year
    label: Period
    default: "{{today}}"

Supported granularity values — honored at both dashboard and visualization level:

• day: date_from = date_to = the chosen date. A single-day window.
• month (default): date_from = first day of the chosen date's month, date_to = the chosen date. Useful for month-to-date dashboards.
• quarter: date_from = first day of the chosen date's quarter, date_to = the chosen date.
• year: date_from = January 1 of the chosen date's year, date_to = the chosen date. Useful for year-to-date dashboards.

Default tokens: {{today}}, {{yesterday}}, {{start_of_week}}, {{end_of_week}}, {{start_of_month}}, {{end_of_month}}. Anything else is treated as a literal ISO date string.

select — dimension filter from a Malloy query

Populates a dropdown from a live query. Use when users need to filter by a dimension value (region, category, brand) rather than time.

filters:
  - id: category
    type: select
    label: Category
    param: category
    options_query: "models/ec_revenue.malloy::category_options"
    default: all

options_query points to a Malloy query that returns rows with at least id and label columns (or one of the recognised aliases — see select). The model parameter declared as p_category receives the value (the p_ prefix is stripped for the external name; the filter sends category).

Cross-filtering in fluid grid

In fluid_grid dashboards, clicking a bar, point, or cell in any interactive chart filters all other charts in the dashboard to that selection. This works automatically — no configuration required.

To disable cross-filtering for a specific visualization (for example a summary KPI that should not change when other charts are filtered), set cross_filter: false in the visualization's chart block:

# in the visualization YAML, not the dashboard
chart:
  cross_filter: false

Cross-filtering is not available in document mode. Document dashboards are designed for reading, not exploration.

The full mechanism — pills, supported-params whitelist, per-viz emit/consume rules — lives at Cross-filtering.

Composition checklist

• Every items[].visualization references an existing published visualization id.
• layout_mode is chosen deliberately: fluid_grid for exploration, document for reports.
• Dashboard title is a question, not a category label.
• Filter param matches the parameter name declared in the Malloy model.
• granularity matches the time resolution of the underlying data.

looky validate
looky list dashboards