Skip to main content

Canvas Dashboard YAML

Canvas dashboards provide a flexible way to create custom dashboards with drag-and-drop components.

Properties​

type​

[string] - Refers to the resource type and must be canvas (required)

display_name​

[string] - Refers to the display name for the canvas (required)

title​

[string] - Deprecated: use display_name instead. Refers to the display name for the canvas

description​

[string] - Description for the canvas dashboard

[string] - Refers to the custom banner displayed at the header of an Canvas dashboard

rows​

[array of object] - Refers to all of the rows displayed on the Canvas

  • height - [string] - Height of the row in px

  • items - [array of object] - List of components to display in the row

    • component - [string] - Name of the component to display. Each component type has its own set of properties. Available component types:

      • markdown - Text component, uses markdown formatting
      • kpi_grid - KPI component, similar to TDD in Rill Explore, display quick KPI charts
      • stacked_bar_normalized - Bar chart normalized to 100% values
      • line_chart - Normal Line chart
      • bar_chart - Normal Bar chart
      • stacked_bar - Stacked Bar chart
      • area_chart - Line chart with area
      • image - Provide a URL to embed into canvas dashboard
      • table - Similar to Pivot table, add dimensions and measures to visualize your data
      • heatmap - Heat Map chart to visualize distribution of data
      • donut_chart - Donut or Pie chart to display sums of total

    • width - [string, integer] - Width of the component (can be a number or string with unit)

max_width​

[integer] - Max width in pixels of the canvas

gap_x​

[integer] - Horizontal gap in pixels of the canvas

gap_y​

[integer] - Vertical gap in pixels of the canvas

filters​

[object] - Indicates if filters should be enabled for the canvas.

  • enable - [boolean] - Toggles filtering functionality for the canvas dashboard.

allow_custom_time_range​

[boolean] - Defaults to true, when set to false it will hide the ability to set a custom time range for the user.

allow_filter_add​

[boolean] - Whether users can add new filters to the canvas dashboard.

time_ranges​

[array of oneOf] - Overrides the list of default time range selections available in the dropdown. It can be string or an object with a 'range' and optional 'comparison_offsets'

time_ranges:
  - PT15M // Simplified syntax to specify only the range
  - PT1H
  - PT6H
  - P7D
  - range: P5D // Advanced syntax to specify comparison_offsets as well
  - P4W
  - rill-TD // Today
  - rill-WTD // Week-To-date

  • option 1 - [string] - a valid ISO 8601 duration or one of the Rill ISO 8601 extensions extensions for the selection

  • option 2 - [object] - Object containing time range and comparison configuration

    • range - [string] - a valid ISO 8601 duration or one of the Rill ISO 8601 extensions extensions for the selection (required)

    • comparison_offsets - [array of oneOf] - list of time comparison options for this time range selection (optional). Must be one of the Rill ISO 8601 extensions

      • option 1 - [string] - Offset string only (range is inferred)

      • option 2 - [object] - Object containing offset and range configuration for time comparison

        • offset - [string] - Time offset for comparison (e.g., 'P1D' for one day ago)

        • range - [string] - Custom time range for comparison period

time_zones​

[array of string] - Refers to the time zones that should be pinned to the top of the time zone selector. It should be a list of IANA time zone identifiers

defaults​

[object] - defines the defaults YAML struct

defaults: #define all the defaults within here
  time_range: P1M
  comparison_mode: dimension #time, none
  comparison_dimension: filename
  filters:
    dimensions:
      - dimension: country
        values: ["US", "CA"]
        mode: in_list
    measures:
      - measure: revenue
        operator: gt
        values: ["1000"]

  • time_range - [string] - Refers to the default time range shown when a user initially loads the dashboard. The value must be either a valid ISO 8601 duration (for example, PT12H for 12 hours, P1M for 1 month, or P26W for 26 weeks) or one of the Rill ISO 8601 extensions

  • comparison_mode - [string] - Controls how to compare current data with historical or categorical baselines. Options: none (no comparison), time (compares with past based on default_time_range), dimension (compares based on comparison_dimension values)

  • comparison_dimension - [string] - for dimension mode, specify the comparison dimension by name

  • filters - [object] - Default filter configuration

    • dimensions - [array of object] - List of default dimension filters

      • dimension - [string] - Name of the dimension to filter on

      • values - [array of string] - List of values to filter by

      • limit - [integer] - Maximum number of values to show in the filter

      • removable - [boolean] - Whether the filter can be removed by the user

      • locked - [boolean] - Whether the filter is locked and cannot be modified

      • hidden - [boolean] - Whether the filter is hidden from the UI

      • mode - [string] - Filter mode - select for dropdown, in_list for multi-select, contains for text search

      • exclude - [boolean] - Whether to exclude the specified values instead of including them

    • measures - [array of object] - List of default measure filters

      • measure - [string] - Name of the measure to filter on

      • by_dimension - [string] - Dimension to group the measure filter by

      • operator - [string] - Operator for the measure filter (e.g., eq, gt, lt, gte, lte)

      • values - [array of string] - List of values to filter by

      • removable - [boolean] - Whether the filter can be removed by the user

      • locked - [boolean] - Whether the filter is locked and cannot be modified

      • hidden - [boolean] - Whether the filter is hidden from the UI

theme​

[oneOf] - Name of the theme to use. Only one of theme and embedded_theme can be set.

  • option 1 - [string] - Name of an existing theme to apply to the dashboard

  • option 2 - [object] - Inline theme configuration.

    • colors - [object] - Used to override the dashboard colors. Either primary or secondary color must be provided.

      • primary - [string] - Overrides the primary blue color in the dashboard. Can have any hex (without the '#' character), named colors or hsl() formats. Note that the hue of the input colors is used for variants but the saturation and lightness is copied over from the blue color palette.

      • secondary - [string] - Overrides the secondary color in the dashboard. Applies to the loading spinner only as of now. Can have any hex (without the '#' character), named colors or hsl() formats.

security​

[object] - Defines security rules and access control policies for dashboards (without row filtering)

  • access - [oneOf] - Expression indicating if the user should be granted access to the dashboard. If not defined, it will resolve to false and the dashboard won't be accessible to anyone. Needs to be a valid SQL expression that evaluates to a boolean.

    • option 1 - [string] - SQL expression that evaluates to a boolean to determine access

    • option 2 - [boolean] - Direct boolean value to allow or deny access

Common Properties​

name​

[string] - Name is usually inferred from the filename, but can be specified manually.

refs​

[array of string] - List of resource references

dev​

[object] - Overrides any properties in development environment.

prod​

[object] - Overrides any properties in production environment.