Skip to main content

Explore 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 explore (required)

display_name​

[string] - Refers to the display name for the explore dashboard

description​

[string] - Refers to the description of the explore dashboard

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

metrics_view​

[string] - Refers to the metrics view resource

dimensions​

[oneOf] - List of dimension names. Use '*' to select all dimensions (default)

  • option 1 - [string] - Wildcard(*) selector that includes all available fields in the selection

  • option 2 - [array of string] - Explicit list of fields to include in the selection

  • option 3 - [object] - Advanced matching using regex, DuckDB expression, or exclusion

    • regex - [string] - Select dimensions using a regular expression

    • expr - [string] - DuckDB SQL expression to select fields based on custom logic

    • exclude - [object] - Select all dimensions except those listed here

measures​

[oneOf] - List of measure names. Use ''*'' to select all measures (default)

  • option 1 - [string] - Wildcard(*) selector that includes all available fields in the selection

  • option 2 - [array of string] - Explicit list of fields to include in the selection

  • option 3 - [object] - Advanced matching using regex, DuckDB expression, or exclusion

    • regex - [string] - Select dimensions using a regular expression

    • expr - [string] - DuckDB SQL expression to select fields based on custom logic

    • exclude - [object] - Select all dimensions except those listed here

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.

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

lock_time_zone​

[boolean] - When true, the dashboard will be locked to the first time provided in the time_zones list. When no time_zones are provided, the dashboard will be locked to UTC

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.

defaults​

[object] - defines the defaults YAML struct

  • dimensions - [oneOf] - Provides the default dimensions to load on viewing the dashboard

    • option 1 - [string] - Wildcard(*) selector that includes all available fields in the selection

    • option 2 - [array of string] - Explicit list of fields to include in the selection

    • option 3 - [object] - Advanced matching using regex, DuckDB expression, or exclusion

      • regex - [string] - Select dimensions using a regular expression

      • expr - [string] - DuckDB SQL expression to select fields based on custom logic

      • exclude - [object] - Select all dimensions except those listed here

  • measures - [oneOf] - Provides the default measures to load on viewing the dashboard

    • option 1 - [string] - Wildcard(*) selector that includes all available fields in the selection

    • option 2 - [array of string] - Explicit list of fields to include in the selection

    • option 3 - [object] - Advanced matching using regex, DuckDB expression, or exclusion

      • regex - [string] - Select dimensions using a regular expression

      • expr - [string] - DuckDB SQL expression to select fields based on custom logic

      • exclude - [object] - Select all dimensions except those listed here

  • 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

embeds​

[object] - Configuration options for embedded dashboard views

  • hide_pivot - [boolean] - When true, hides the pivot table view in embedded mode

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.