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 many grid columns each visualization occupies. The default grid is 3 columns. Width 1 = one column, width 2 = two columns, width 3 = full width. Optional advanced spans: width 4 = quarter row, width 6 = half row.

id: ec_sales_breakdown
title: Where Is Revenue Coming From?
layout_mode: fluid_grid
published: true
filters:
  - id: global_period
    type: cutoff_date
    granularity: year
    label: Period
    default: "{{today}}"
items:
  - visualization: ec_revenue_kpi
  - visualization: ec_orders_kpi
  - visualization: ec_revenue_by_category_bar
  - visualization: ec_revenue_by_country_bar
  - visualization: ec_top_brands_bar
  - visualization: ec_traffic_source_bar
    width: 2
  - visualization: ec_revenue_by_department_bar
    width: 1
  - visualization: ec_orders_detail_grid

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
    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. 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: each item is either {visualization: <id>} or the same plus an optional width:. There is no height, position, row, or col; the fluid grid lays out items in declaration order and the document layout is single-column.

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 — month (default) sets date_from to the first day of the chosen date's month; year sets date_from to January 1 of that year.

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

Supported granularity values for dashboard-level cutoff_date filters:

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

The granularity key is dashboard-level only; per-visualization cutoff_date filters always behave as month.

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