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 or true 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 both format_preset and format_d3. If neither is supplied, the measure will be formatted using the humanize 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 to format_preset: humanize. A measure cannot have both format_preset and format_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.

`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.

Properties​

version​

type​

connector​

display_name​

description​

ai_instructions​

model​

database​

database_schema​

table​

timeseries​

watermark​

smallest_time_grain​

first_day_of_week​

first_month_of_year​

dimensions​

measures​

annotations​

security​

Common Properties​

name​

refs​

dev​

prod​