Metrics View YAML
In your Rill project directory, create a metrics view, <metrics_view>.yaml
, file in the metrics
directory. Rill will ingest the metric view definition next time you run rill start
.
Properties
version
[string] - The version of the metrics view schema
type
[string] - Refers to the resource type and must be metrics_view
(required)
connector
[string] - Refers to the connector type for the metrics view, see OLAP engines for more information
display_name
[string] - Refers to the display name for the metrics view
description
[string] - Refers to the description for the metrics view
ai_instructions
[string] - Extra instructions for AI agents. Used to guide natural language question answering and routing.
model
[string] - Refers to the model powering the dashboard (either model or table is required) (required)
database
[string] - Refers to the database to use in the OLAP engine (to be used in conjunction with table). Otherwise, will use the default database or schema if not specified
database_schema
[string] - Refers to the schema to use in the OLAP engine (to be used in conjunction with table). Otherwise, will use the default database or schema if not specified
table
[string] - Refers to the table powering the dashboard, should be used instead of model for dashboards create from external OLAP tables (either table or model is required)
timeseries
[string] - Refers to the timestamp column from your model that will underlie x-axis data in the line charts. If not specified, the line charts will not appear
watermark
[string] - A SQL expression that tells us the max timestamp that the metrics are considered valid for. Usually does not need to be overwritten
smallest_time_grain
[string] - Refers to the smallest time granularity the user is allowed to view. The valid values are: millisecond, second, minute, hour, day, week, month, quarter, year
first_day_of_week
[integer] - Refers to 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
first_month_of_year
[integer] - Refers to the first month of the year for time grain aggregation. The valid values are 1 through 12 where January=1 and December=12
dimensions
[array of object] - Relates to exploring segments or dimensions of your data and filtering the dashboard
-
name
- [string] - a stable identifier for the dimension -
display_name
- [string] - a display name for your dimension -
description
- [string] - a freeform text description of the dimension -
column
- [string] - a categorical column -
expression
- [string] - a non-aggregate expression such as string_split(domain, '.'). One of column and expression is required but cannot have both at the same time -
unnest
- [boolean] - if true, allows multi-valued dimension to be unnested (such as lists) and filters will automatically switch to "contains" instead of exact match -
uri
- [string, boolean] - enable if your dimension is a clickable URL to enable single click navigation (boolean or valid SQL expression)
measures
[array of object] - Used to define the numeric aggregates of columns from your data model
-
name
- [string] - a stable identifier for the measure (required) -
display_name
- [string] - the display name of your measure. (required) -
label
- [string] - a label for your measure, deprecated use display_name -
description
- [string] - a freeform text description of the measure -
type
- [string] - Measure calculation type: "simple" for basic aggregations, "derived" for calculations using other measures, or "time_comparison" for period-over-period analysis. Defaults to "simple" unless dependencies exist. -
expression
- [string] - a combination of operators and functions for aggregations (required) -
window
- [anyOf] - A measure window can be defined as a keyword string (e.g. 'time' or 'all') or an object with detailed window configuration. For more information, see the window functions documentation.-
option 1 - [string] - Shorthand:
time
ortrue
means time-partitioned,all
means non-partitioned. -
option 2 - [object] - Detailed window configuration for measure calculations, allowing control over partitioning, ordering, and frame definition.
-
partition
- [boolean] - Controls whether the window is partitioned. When true, calculations are performed within each partition separately. -
order
- [string] - Specifies the fields to order the window by, determining the sequence of rows within each partition.-
option 1 - [string] - Simple field name as a string.
-
option 2 - [array of oneOf] - List of field selectors, each can be a string or an object with detailed configuration.
-
option 1 - [string] - Shorthand field selector, interpreted as the name.
-
option 2 - [object] - Detailed field selector configuration with name and optional time grain.
-
name
- [string] - Name of the field to select. (required) -
time_grain
- [string] - Time grain for time-based dimensions.
-
-
-
-
frame
- [string] - Defines the window frame boundaries for calculations, specifying which rows are included in the window relative to the current row.
-
-
-
per
- [oneOf] - for per dimensions-
option 1 - [string] - Simple field name as a string.
-
option 2 - [array of oneOf] - List of field selectors, each can be a string or an object with detailed configuration.
-
option 1 - [string] - Shorthand field selector, interpreted as the name.
-
option 2 - [object] - Detailed field selector configuration with name and optional time grain.
-
name
- [string] - Name of the field to select. (required) -
time_grain
- [string] - Time grain for time-based dimensions.
-
-
-
-
requires
- [oneOf] - using an available measure or dimension in your metrics view to set a required parameter, cannot be used with simple measures. See referencing measures for more information.-
option 1 - [string] - Simple field name as a string.
-
option 2 - [array of oneOf] - List of field selectors, each can be a string or an object with detailed configuration.
-
option 1 - [string] - Shorthand field selector, interpreted as the name.
-
option 2 - [object] - Detailed field selector configuration with name and optional time grain.
-
name
- [string] - Name of the field to select. (required) -
time_grain
- [string] - Time grain for time-based dimensions.
-
-
-
-
valid_percent_of_total
- [boolean] - a boolean indicating whether percent-of-total values should be rendered for this measure -
format_preset
- [string] - Controls the formatting of this measure using a predefined preset. Measures cannot have bothformat_preset
andformat_d3
. If neither is supplied, the measure will be formatted using thehumanize
preset by default.Available options:
humanize
: Round numbers into thousands (K), millions(M), billions (B), etc.none
: Raw output.currency_usd
: Round to 2 decimal points with a dollar sign ($).currency_eur
: Round to 2 decimal points with a euro sign (€).percentage
: Convert a rate into a percentage with a % sign.interval_ms
: Convert milliseconds into human-readable durations like hours (h), days (d), years (y), etc. (optional)
-
format_d3
- [string] - Controls the formatting of this measure using a d3-format string. If an invalid format string is supplied, the measure will fall back toformat_preset: humanize
. A measure cannot have bothformat_preset
andformat_d3
. If neither is provided, the humanize preset is used by default. Example:format_d3: ".2f"
formats using fixed-point notation with two decimal places. Example:format_d3: ",.2r"
formats using grouped thousands with two significant digits. (optional) -
format_d3_locale
- [object] - locale configuration passed through to D3, enabling changing the currency symbol among other things. For details, see the docs for D3's formatLocale.format_d3: "$,"
format_d3_locale:
grouping: [3, 2]
currency: ["₹", ""]-
grouping
- [array] - the grouping of the currency symbol -
currency
- [array] - the currency symbol
-
-
treat_nulls_as
- [string] - used to configure what value to fill in for missing time buckets. This also works generally as COALESCING over non empty time buckets.
annotations
[array of object] - Used to define annotations that can be displayed on charts
-
name
- [string] - A stable identifier for the annotation. Defaults to model or table names when not specified -
model
- [string] - Refers to the model powering the annotation (either table or model is required). The model must have 'time' and 'description' columns. Optional columns include 'time_end' for range annotations and 'grain' to specify when the annotation should appear based on dashboard grain level. -
database
- [string] - Refers to the database to use in the OLAP engine (to be used in conjunction with table). Otherwise, will use the default database or schema if not specified -
database_schema
- [string] - Refers to the schema to use in the OLAP engine (to be used in conjunction with table). Otherwise, will use the default database or schema if not specified -
table
- [string] - Refers to the table powering the annotation, should be used instead of model for annotations from external OLAP tables (either table or model is required) -
connector
- [string] - Refers to the connector to use for the annotation -
measures
- [anyOf] - Specifies which measures to apply the annotation to. Applies to all measures if not specified-
option 1 - [string] - Simple field name as a string.
-
option 2 - [array of anyOf] - List of field selectors, each can be a string or an object with detailed configuration.
-
option 1 - [string] - Shorthand field selector, interpreted as the name.
-
option 2 - [object] - Detailed field selector configuration with name and optional time grain.
-
name
- [string] - Name of the field to select. (required) -
time_grain
- [string] - Time grain for time-based dimensions.
-
-
-