Skip to main content

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​

type​

[string] - Refers to the resource type and must be metrics_view (required)

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)

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

  • display_name - [string] - the display name of your measure.

  • description - [string] - a freeform text description of the dimension

  • 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

  • window - [anyOf] - A measure window can be defined as a keyword string (e.g. 'time' or 'all') or an object with detailed window configuration.

    • 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 - [anyOf] - 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 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.

      • frame - [string] - Defines the window frame boundaries for calculations, specifying which rows are included in the window relative to the current row.

  • per - [anyOf] - for per dimensions

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

  • requires - [anyOf] - using an available measure or dimension in your metrics view to set a required parameter, cannot be used with simple measures

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

  • 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

  • valid_percent_of_total - [boolean] - a boolean indicating whether percent-of-total values should be rendered for this measure

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

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.