rill-canvas

# Instructions for developing a canvas dashboard in Rill ## Introduction Canvas dashboards are free-form dashboard resources that display custom chart and table components laid out in a grid. They enable building overview and report-style dashboards with multiple visualizations, similar to traditional business intelligence tools. Canvas dashboards differ from explore dashboards in important ways: - **Explore dashboards:** Best for explorative analysis, drill-down investigations, and letting users freely slice data by any dimension. - **Canvas dashboards:** Best for fixed reports, executive summaries, or combining multiple metrics views into a single view. Canvas dashboards are lightweight resources found downstream of metrics views in the project DAG. Each component within a canvas fetches data individually, typically from a metrics view resource. **When to use canvas dashboards:** - Building executive summaries with KPIs and multiple visualizations - Creating report-style dashboards with markdown explanations - Comparing metrics across different metrics views - Designing custom layouts not possible with explore dashboards ## Canvas Structure A canvas dashboard is defined in a YAML file with `type: canvas`. Here is the basic structure (most canvas dashboards work great without any of the optional properties here): ```yaml type: canvas display_name: "Sales Overview Dashboard" # Optional filter settings filters: enable: true pinned: - region - product_category required: - customer_id # Dashboard refuses to render until this filter has a value # Optional time range presets time_ranges: - P7D - P30D - P90D - inf # Optional maximum dashboard width max_width: 1400 # Optional theme reference theme: my_theme # Default time settings for all components defaults: time_range: P7D comparison_mode: time # Optional default filters, keyed by metrics view name filters: sales_metrics: "region IN ('US', 'CA')" # Optional security access control security: access: "'{{ .user.domain }}' == 'company.com'" # Required dashboard content organized in rows rows: - height: 240px items: - width: 12 kpi_grid: metrics_view: sales_metrics measures: - total_revenue - order_count - height: 400px items: - width: 6 line_chart: metrics_view: sales_metrics title: "Revenue Trend" x: type: temporal field: event_time y: type: quantitative field: total_revenue - width: 6 bar_chart: metrics_view: sales_metrics title: "Revenue by Region" color: primary x: type: nominal field: region limit: 10 sort: -y y: type: quantitative field: total_revenue ``` ### Filter settings `filters.pinned` and `filters.required` both reference dimensions or measures by name (they must exist on at least one referenced metrics view). They control different things: - **`pinned`**: keeps a filter pill visible at the top of the dashboard so users can change it without opening the filter menu. The dashboard renders normally whether or not the user has set a value. - **`required`**: the dashboard refuses to render until every required filter has a value. Set a default value in `defaults.filters` to satisfy a required filter automatically; otherwise the user is prompted to pick one. Required filters are implicitly pinned — do not also list them under `pinned`. Use `required` for filters that are unsafe or meaningless to omit (e.g. tenant ID, customer scope, region when results would otherwise mix incompatible data). #### Default filters `defaults.filters` is a **map keyed by metrics view name**, where each value is a **Metrics SQL `WHERE` expression** applied when the dashboard first loads. ```yaml defaults: time_range: P7D filters: sales_metrics: "region IN ('US', 'CA') AND total_revenue > 1000" support_metrics: "ticket_status != 'closed'" ``` Rules for writing `defaults.filters`: - Each key must be the name of a metrics view that is referenced by at least one component on the canvas. - A filter only applies to the components backed by its metrics view. To filter several metrics views, add one entry per metrics view, including duplicating shared dimension/measure names. - Expressions reference dimension and measure **names as defined on that metrics view**, not the underlying table columns. Table prefixes, aliases, and subqueries are not supported. - Write only the expression itself; do not include the `WHERE` keyword. - Supported syntax: `=`, `!=`, `<`, `<=`, `>`, `>=`, `IN`, `NOT IN`, `LIKE`, `ILIKE`, `IS NULL`, `IS NOT NULL`, `BETWEEN`, combined with `AND`, `OR`, and parentheses. String literals use single quotes. ## Layout System Canvas dashboards use a 12-unit grid system for layout. ### Row Configuration Each row defines a horizontal section with a specific height: ```yaml rows: - height: 240px # Row height in pixels items: # Components go here ``` **Recommended row heights:** - Markdown headers: 40px - 80px - KPI grids: 128px - 240px (depending on number of measures) - Charts and visualizations: 300px - 500px - Leaderboards: 300px - 450px - Tables: 300px - 500px ### Item Widths Items within a row share the 12-unit width: ```yaml rows: # Full width (1 component per row) - items: - width: 12 markdown: content: "# Dashboard Title" # Half width (2 components per row) - items: - width: 6 line_chart: # ... - width: 6 bar_chart: # ... # Third width (3 components per row) - items: - width: 4 donut_chart: # ... - width: 4 bar_chart: # ... - width: 4 area_chart: # ... ``` **Width guidelines:** - `width: 12` - Full width; use for KPI grids, markdown headers, wide charts - `width: 6` - Half width; use for side-by-side comparisons - `width: 4` - Third width; use for three equal charts - `width: 3` - Quarter width; use for four small components (minimum practical width) ### Tab groups A row entry can be a tab group instead of a plain row. A tab group has a `name` (URL key) and a list of `tabs`, each with a `label`, optional `name`, and its own `rows`. Only the active tab loads data. Allowed only at the top level, not nested inside a tab. ```yaml rows: - name: by_region tabs: - label: North America rows: - items: - width: 6 bar_chart: # ... - label: EMEA rows: - items: - width: 6 bar_chart: # ... ``` ## Dashboard Composition Best Practices When building a new canvas dashboard, follow this recommended structure: 1. **Row 1 - Context**: Start with a markdown component providing dashboard title and overview 2. **Row 2 - Key Metrics**: Add a KPI grid with 2-4 of the most business-relevant measures 3. **Row 3 - Primary Analysis**: Split into two halves: - Left (width 6): A leaderboard showing top entities by a key dimension - Right (width 6): A time-series chart (line_chart or stacked_bar) showing trends 4. **Additional Rows**: Add 1-2 more rows with relevant charts based on the data **Choosing chart types:** - **Time-series analysis**: Use `line_chart` or `area_chart` with temporal x-axis - **Categorical comparisons**: Use `bar_chart` or `stacked_bar` with nominal x-axis - **Part-to-whole**: Use `donut_chart` or `stacked_bar_normalized` - **Two-dimensional patterns**: Use `heatmap` - **Dual-metric comparison**: Use `combo_chart` for two measures with different scales - **Funnel analysis**: Use `funnel_chart` to visualize sequential stage drop-offs - **Two-measure relationships**: Use `scatter_plot` to explore correlation, clusters, or outliers between two numeric measures # Field guidelines The field names are case sensitive and should match exactly to the fields present in the metrics view. **Time dimension restrictions:** The time dimension (timeseries field from the metrics view) is special and can ONLY be used in the x-axis field for temporal charts. Never use the time dimension in: - Leaderboard dimensions - Color fields - Any other dimension configuration ## Component Types ### Markdown Add text content, headers, and documentation: ```yaml markdown: content: | ## Dashboard Overview This dashboard tracks key sales metrics across all regions. --- alignment: horizontal: left # left, center, right vertical: middle # top, middle, bottom ``` **Best practices:** - Use markdown for dashboard titles, section headers, and explanatory text - Add blank lines between markdown elements for proper rendering - Use `---` for horizontal rules to separate sections ### KPI Grid Display key metrics with comparison values and sparklines: ```yaml kpi_grid: metrics_view: sales_metrics measures: - total_revenue - order_count - average_order_value - customer_count comparison: - delta # Absolute change - percent_change # Percentage change - previous # Previous period value sparkline: right # right, bottom, none ``` **With dimension filters:** ```yaml kpi_grid: metrics_view: sales_metrics measures: - total_revenue - order_count dimension_filters: region IN ('North America', 'Europe') comparison: - percent_change sparkline: bottom hide_time_range: true ``` ### Leaderboard Display ranked dimension values by measures: ```yaml leaderboard: metrics_view: sales_metrics title: "Top Products" description: "Products ranked by total revenue" dimensions: - product_category measures: - total_revenue - order_count num_rows: 10 ``` **With multiple dimensions:** ```yaml leaderboard: metrics_view: sales_metrics dimensions: - region - product_category measures: - total_revenue - average_order_value - order_count num_rows: 7 ``` **Important:** Never use time dimensions in leaderboard dimensions. Leaderboards are for categorical ranking, not time-series analysis. ### Line Chart Show trends over time: ```yaml line_chart: metrics_view: sales_metrics title: "Revenue Trend" color: primary x: field: order_date type: temporal limit: 30 y: field: total_revenue type: quantitative zeroBasedOrigin: true ``` **With color dimension breakdown:** ```yaml line_chart: metrics_view: sales_metrics title: "Revenue by Region" color: field: region type: nominal limit: 5 legendOrientation: top x: field: order_date type: temporal y: field: total_revenue type: quantitative zeroBasedOrigin: true ``` **With custom color mapping:** ```yaml line_chart: metrics_view: sales_metrics title: "Performance Comparison" color: field: status type: nominal colorMapping: - value: "active" color: hsl(120, 70%, 45%) - value: "inactive" color: hsl(0, 70%, 50%) x: field: event_date type: temporal y: field: event_count type: quantitative ``` ### Bar Chart Compare values across categories: ```yaml bar_chart: metrics_view: sales_metrics title: "Revenue by Product Category" color: hsl(210, 70%, 50%) x: field: product_category type: nominal limit: 10 sort: -y y: field: total_revenue type: quantitative zeroBasedOrigin: true ``` **With color dimension:** ```yaml bar_chart: metrics_view: sales_metrics title: "Revenue by Category and Region" color: field: region type: nominal limit: 5 x: field: product_category type: nominal limit: 8 sort: -y y: field: total_revenue type: quantitative ``` **Horizontal bars** (bars run left to right; useful for long category labels or many categories). `x` and `y` always name the field drawn on that axis, so put the measure on `x` and the dimension on `y`: ```yaml bar_chart: metrics_view: sales_metrics title: "Revenue by Product Category" color: primary x: field: total_revenue type: quantitative zeroBasedOrigin: true y: field: product_category type: nominal limit: 15 sort: -x ``` Sort values refer to axes, so `sort: -x` on `y` orders the categories by the measure. The same layout works for `stacked_bar` and `stacked_bar_normalized`; `line_chart` and `area_chart` always keep the dimension on `x`. ### Stacked Bar Show cumulative values across categories or time: ```yaml stacked_bar: metrics_view: sales_metrics title: "Revenue Over Time by Region" color: field: region type: nominal limit: 5 x: field: order_date type: temporal limit: 20 y: field: total_revenue type: quantitative zeroBasedOrigin: true ``` **With multiple measures:** ```yaml stacked_bar: metrics_view: sales_metrics title: "Cost Breakdown Over Time" color: field: rill_measures type: value legendOrientation: top x: field: order_date type: temporal limit: 20 y: field: cost_of_goods fields: - cost_of_goods - shipping_cost - marketing_cost type: quantitative zeroBasedOrigin: true ``` ### Stacked Bar Normalized Show proportional distribution (100% stacked): ```yaml stacked_bar_normalized: metrics_view: sales_metrics title: "Revenue Share by Region" color: field: region type: nominal limit: 5 x: field: order_date type: temporal limit: 20 y: field: total_revenue type: quantitative zeroBasedOrigin: true ``` **With custom color mapping for measures:** ```yaml stacked_bar_normalized: metrics_view: inventory_metrics title: "Inventory Status Distribution" color: field: rill_measures type: value legendOrientation: top colorMapping: - value: "in_stock" color: hsl(120, 60%, 50%) - value: "low_stock" color: hsl(45, 90%, 50%) - value: "out_of_stock" color: hsl(0, 70%, 50%) x: field: report_date type: temporal limit: 20 y: field: in_stock fields: - in_stock - low_stock - out_of_stock type: quantitative ``` ### Area Chart Show magnitude over time with optional stacking: ```yaml area_chart: metrics_view: sales_metrics title: "Order Volume Over Time" color: primary x: field: order_date type: temporal limit: 30 y: field: order_count type: quantitative zeroBasedOrigin: true ``` **With color dimension:** ```yaml area_chart: metrics_view: sales_metrics title: "Revenue by Channel" color: field: sales_channel type: nominal limit: 4 x: field: order_date