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 # 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 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 ``` ## 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) ## 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 labelAngle: 0 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 ``` ### 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 type: temporal limit: 20 y: field: total_revenue type: quantitative zeroBasedOrigin: true ``` ### Donut Chart Show proportional breakdown: ```yaml donut_chart: metrics_view: sales_metrics title: "Revenue by Region" innerRadius: 50 color: field: region type: nominal limit: 8 sort: -measure measure: field: total_revenue type: quantitative showTotal: true ``` ### Heatmap Show patterns across two dimensions: ```yaml heatmap: metrics_view: activity_metrics title: "Activity by Day and Hour" color: field: event_count type: quantitative x: field: day_of_week type: nominal limit: 7 y: field: hour_of_day type: nominal limit: 24 sort: -color ``` **With custom color range:** ```yaml heatmap: metrics_view: performance_metrics title: "Performance Score Matrix" color: field: score type: quantitative colorRange: mode: scheme scheme: sequential x: field: category type: nominal limit: 10 y: field: subcategory type: nominal limit: 15 ``` **With custom Vega-Lite config for colors:** ```yaml heatmap: metrics_view: utilization_metrics title: "Resource Utilization" vl_config: | { "range": { "heatmap": ["#F4A261", "#D63946", "#457B9D"] } } color: field: utilization_rate type: quantitative x: field: resource_name type: nominal limit: 20 y: field: time_slot type: nominal limit: 12 ``` ### Combo Chart Combine bar and line on dual axes: ```yaml combo_chart: metrics_view: sales_metrics title: "Revenue and Order Count" color: field: measures type: value legendOrientation: top x: field: order_date type: temporal limit: 20 y1: field: total_revenue type: quantitative mark: bar zeroBasedOrigin: true y2: field: order_count type: quantitative mark: line zeroBasedOrigin: true ``` **With custom color mapping:** ```yaml combo_chart: metrics_view: funnel_metrics title: "Conversions and Conversion Rate" color: field: measures type: value legendOrientation: top colorMapping: - value: "Conversions" color: hsl(210, 100%, 73%) - value: "Conversion Rate" color: hsl(280, 70%, 55%) x: field: event_date type: temporal limit: 30 y1: field: conversions type: quantitative mark: bar