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 withformat_preset: humanize
(described below). Measures cannot have bothformat_preset
andformat_d3
entries. (optional; if neitherformat_preset
norformat_d3
is supplied, measures will be formatted with thehumanize
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"
.
- Example: to show a measure using fixed point formatting with 2 digits after the decimal point, your measure specification would include:
format_preset
— controls the formatting of this measure in the dashboard according to option specified below. Measures cannot have bothformat_preset
andformat_d3
entries. (optional; if neitherformat_preset
norformat_d3
is supplied, measures will be formatted with thehumanize
preset)humanize
— round off numbers in an opinionated way to thousands (K), millions (M), billions (B), etcnone
— raw outputcurrency_usd
— output rounded to 2 decimal points prepended with a dollar signpercentage
— output transformed from a rate to a percentage appended with a percentage signinterval_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 tofalse
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 aWHERE
clause. (optional)exclude
- List of dimension or measure names to exclude from the dashboard. Ifexclude
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 thename
of one of the dashboard's dimensions or measures. (required)
include
- List of dimension or measure names to include in the dashboard. Ifinclude
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 thename
of one of the dashboard's dimensions or measures. (required)