Skip to main content

Dashboard YAML

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

Properties

model — the model name powering the dashboard with no path specified; should only be used for Rill models (either model or table is required)

table - the table name powering the dashboard with no path specified; should be used instead of model for dashboards created directly from sources and/or from external OLAP tables (either table or model is required)

title — the display name for the dashboard (required)

timeseries — the timestamp column from your model that will underlie x-axis data in the line charts (optional). If not specified, the line charts will not appear.

default_time_range — the default time range shown when a user initially loads the dashboard (optional). 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 (default). If not specified, defaults to the full time range of the timeseries column.

smallest_time_grain — the smallest time granularity the user is allowed to view in the dashboard (optional). The valid values are: millisecond, second, minute, hour, day, week, month, quarter, year.

first_day_of_week — the first day of the week for time grain aggregation (for example, Sunday instead of Monday). The valid values are 1 through 7 where Monday=1 and Sunday=7 (optional)

first_month_of_year — the first month of the year for time grain aggregation. The valid values are 1 through 12 where January=1 and December=12 (optional)

available_time_zones — time zones that should be pinned to the top of the time zone selector (optional). It should be a list of IANA time zone identifiers. By adding one or more time zones will make the dashboard time zone aware and allow users to change current time zone within the dashboard.

default_theme — default theme to apply to the dashboard (optional). A valid theme must be defined in the project. Read this page for more detailed information about themes.

default_comparison - defines which should be the default comparison mode. Default: none (optional)

  • mode - comparison mode
    • none - no comparison
    • time - time, will pick the comparison period depending on default_time_range
    • dimension - dimension comparison mode
  • dimension - for dimension mode, specify the comparison dimension by name

dimensions — for exploring segments and filtering the dashboard (required)

  • column — a categorical column (required)
  • expression a non-aggregate expression such as string_split(domain, '.'). One of column and expression is required but cannot have both at the same time (required)
  • name — a stable identifier for the dimension (optional)
  • label — a label for your dashboard dimension (optional)
  • description — a freeform text description of the dimension for your dashboard (optional)
  • unnest - if true, allows multi-valued dimension to be unnested (such as lists) and filters will automatically switch to "contains" instead of exact match (optional)
  • ignore — hides the dimension (optional)

measures — numeric aggregates of columns from your data model (required)

  • expression — a combination of operators and functions for aggregations (required)
  • name — a stable identifier for the measure (required)
  • label — a label for your dashboard measure (optional)
  • description — a freeform text description of the dimension for your dashboard (optional)
  • ignore — hides the measure (optional)
  • valid_percent_of_total — a boolean indicating whether percent-of-total values should be rendered for this measure (optional)
  • format_d3 — controls the formatting of this measure in the dashboard using a d3-format string. If an invalid format string is supplied, measures will be formatted with format_preset: humanize (described below). Measures cannot have both format_preset and format_d3 entries. (optional; if neither format_preset nor format_d3 is supplied, measures will be formatted with the humanize preset)
    • Example: to show a measure using fixed point formatting with 2 digits after the decimal point, your measure specification would include: format_d3: ".2f".
    • Example: to show a measure using grouped thousands with two significant digits, your measure specification would include: format_d3: ",.2r".
  • format_preset — controls the formatting of this measure in the dashboard according to option specified below. Measures cannot have both format_preset and format_d3 entries. (optional; if neither format_preset nor format_d3 is supplied, measures will be formatted with the humanize preset)
    • humanize — round off numbers in an opinionated way to thousands (K), millions (M), billions (B), etc
    • none — raw output
    • currency_usd — output rounded to 2 decimal points prepended with a dollar sign: $
    • currency_eur — output rounded to 2 decimal points prepended with a euro symbol:
    • percentage — output transformed from a rate to a percentage appended with a percentage sign
    • interval_ms — time intervals given in milliseconds are transformed into human readable time units like hours (h), days (d), years (y), etc

available_time_ranges — Override the list of default time range selections available in the dropdown (optional). Note that All Time and Custom selections are always available.

  • range — a valid ISO 8601 duration or one of the Rill ISO 8601 extensions for the selection (required)
  • comparison_offsets — list of time comparison options for this time range selection (optional). Must be one of the Rill ISO 8601 extensions.
  • Example:
    available_time_ranges:
    - PT15M // Simplified syntax to specify only the range
    - PT1H
    - PT6H
    - P7D
    - range: P5D // Advanced syntax to specify comparison_offsets as well
    comparison_offsets:
    - rill-PP
    - rill-PW
    - P4W
    - rill-TD // Today
    - rill-WTD // Week-To-date

default_dimensions - A list of dimensions that should be visible by default.

default_measures - A list of measures that should be visible by default.

security - define a security policy for the dashboard (optional)

  • access - 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. (optional)
  • row_filter - 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. (optional)
  • exclude - List of dimension or measure names to exclude from the dashboard. If exclude is defined all other dimensions and measures are included. (optional)
    • if - 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 - List of fields to exclude. Should match the name of one of the dashboard's dimensions or measures. (required)
  • include - List of dimension or measure names to include in the dashboard. If include is defined all other dimensions and measures are excluded. (optional)
    • if - 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 - List of fields to include. Should match the name of one of the dashboard's dimensions or measures. (required)