Skip to main content

Canvas YAML

In your Rill project directory, create a explore dashboard, <dashboard_name>.yaml, file in the dashboards directory. Rill will ingest the dashboard definition next time you run rill start.

Properties​

type​

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

display_name​

[string] - Refers to the display name for the canvas

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

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

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.

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.

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'

  • 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

filters​

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

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

defaults​

[object] - Preset UI state to show by default

  • time_range - [string] - Default time range to display when the dashboard loads

  • comparison_mode - [string] - Default comparison mode for metrics (none, time, or dimension)

  • comparison_dimension - [string] - Default dimension to use for comparison when comparison_mode is 'dimension'

variables​

[array of object] - Variables that can be used in the canvas

  • name - [string] - Unique identifier for the variable (required)

  • type - [string] - Data type of the variable (e.g., string, number, boolean) (required)

  • value - [string, number, boolean, object, array] - Default value for the variable. Can be any valid JSON value type

rows​

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

  • 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

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

security​

[object] - Defines security rules and access control policies for resources

  • 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

  • row_filter - [string] - SQL expression to filter the underlying model by. Can leverage templated user attributes to customize the filter for the requesting user. Needs to be a valid SQL expression that can be injected into a WHERE clause

  • include - [array of object] - List of dimension or measure names to include in the dashboard. If include is defined all other dimensions and measures are excluded

    • if - [string] - Expression to decide if the column should be included or not. It can leverage templated user attributes. Needs to be a valid SQL expression that evaluates to a boolean (required)

    • names - [anyOf] - List of fields to include. Should match the name of one of the dashboard's dimensions or measures (required)

      • option 1 - [array of string] - List of specific field names to include

      • option 2 - [string] - Wildcard '*' to include all fields

  • exclude - [array of object] - List of dimension or measure names to exclude from the dashboard. If exclude is defined all other dimensions and measures are included

    • if - [string] - Expression to decide if the column should be excluded or not. It can leverage templated user attributes. Needs to be a valid SQL expression that evaluates to a boolean (required)

    • names - [anyOf] - List of fields to exclude. Should match the name of one of the dashboard's dimensions or measures (required)

      • option 1 - [array of string] - List of specific field names to exclude

      • option 2 - [string] - Wildcard '*' to exclude all fields

  • rules - [array of object] - List of detailed security rules that can be used to define complex access control policies

    • type - [string] - Type of security rule - access (overall access), field_access (field-level access), or row_filter (row-level filtering) (required)

    • action - [string] - Whether to allow or deny access for this rule

    • if - [string] - Conditional expression that determines when this rule applies. Must be a valid SQL expression that evaluates to a boolean

    • names - [array of string] - List of field names this rule applies to (for field_access type rules)

    • all - [boolean] - When true, applies the rule to all fields (for field_access type rules)

    • sql - [string] - SQL expression for row filtering (for row_filter type rules)

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.