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 (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 the constant value inf for all time (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.

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

  • column — a categorical column (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
    • 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

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)