Skip to main content

Project YAML

The rill.yaml file contains metadata about your project.

Properties​

compiler​

[string] - Specifies the parser version to use for compiling resources

display_name​

[string] - The display name of the project, shown in the upper-left corner of the UI

description​

[string] - A brief description of the project

features​

[object] - Optional feature flags. Can be specified as a map of feature names to booleans.

ai_instructions​

[string] - Extra instructions for LLM/AI features. Used to guide natural language question answering and routing.

Configuring the default OLAP Engine​

Rill allows you to specify the default OLAP engine to use in your project via rill.yaml.

Curious about OLAP Engines?

Please see our reference documentation on OLAP Engines.

olap_connector​

[string] - Specifies the default OLAP engine for the project. Defaults to duckdb if not set.

olap_connector: clickhouse

Project-wide defaults​

In rill.yaml, project-wide defaults can be specified for a resource type within a project. Unless otherwise specified, individual resources will inherit any defaults that have been specified in rill.yaml. For available properties that can be configured, please refer to the YAML specification for each individual resource type - model, metrics_view, and explore

Use plurals when specifying project-wide defaults

In your rill.yaml, the top level property for the resource type needs to be plural, such as models, metrics_views and explores.

Hierarchy of inheritance and property overrides

As a general rule of thumb, properties that have been specified at a more granular level will supercede or override higher level properties that have been inherited. Therefore, in order of inheritance, Rill will prioritize properties in the following order:

  1. Individual models/metrics_views/explore object level properties (e.g. model.yaml or explore.yaml)
  2. Environment level properties (e.g. a specific property that have been set for dev)
  3. Project-wide defaults for a specific property and resource type

models​

[object] - Defines project-wide default settings for models. Unless overridden, individual models will inherit these defaults.

metrics_views​

[object] - Defines project-wide default settings for metrics_views. Unless overridden, individual metrics_views will inherit these defaults.

explores​

[object] - Defines project-wide default settings for explores. Unless overridden, individual explores will inherit these defaults.

# For example, the following YAML configuration below will set a project-wide default for:
# Models - Configure a [source refresh](/build/connect/source-refresh.md).
# Metrics View - Set the [first day of the week](metrics-view.md) for timeseries aggregations to be Sunday along with setting the smallest_time_grain.
# Explore Dashboards - Set the [default](explore-dashboards.md) values when a user opens a dashboard, and available time zones and/or time ranges.
models:
    refresh:
        cron: '0 * * * *'
metrics_views:
    first_day_of_week: 1
    smallest_time_grain: month
explores:
    defaults:
        time_range: P24M
    time_zones:
        - America/Denver
        - UTC
        - America/Los_Angeles
        - America/Chicago
        - America/New_York
        - Europe/London
        - Europe/Paris
        - Asia/Jerusalem
        - Europe/Moscow
        - Asia/Kolkata
        - Asia/Shanghai
        - Asia/Tokyo
        - Australia/Sydney
    time_ranges:
        - PT24H
        - P7D
        - P14D
        - P30D
        - P3M
        - P6M
        - P12M

Setting variables​

Primarily useful for templating, variables can be set in the rill.yaml file directly. This allows variables to be set for your projects deployed to Rill Cloud while still being able to use different variable values locally if you prefer.

Overriding variables locally

Variables also follow an order of precedence and can be overridden locally. By default, any variables defined will be inherited from rill.yaml. However, if you manually pass in a variable when starting Rill Developer locally via the CLI, this value will be used instead for the current instance of your running project:

rill start --env numeric_var=100 --env string_var="different_value"
Setting variables through .env

Variables can also be set through your project's <RILL_PROJECT_HOME>/.env file (or using the rill env set CLI command), such as:

variable=xyz

Similar to how connector credentials can be pushed / pulled from local to cloud or vice versa, project variables set locally in Rill Developer can be pushed to Rill Cloud and/or pulled back to your local instance from your deployed project by using the rill env push and rill env pull commands respectively.

env​

[object] - To define a variable in rill.yaml, pass in the appropriate key-value pair for the variable under the env key

env:
    numeric_var: 10
    string_var: "string_value"

Managing Paths in Rill​

The public_paths and ignore_paths properties in the rill.yaml file provide control over which files and directories are processed or exposed by Rill. The public_paths property defines a list of file or directory paths to expose over HTTP. By default, it includes ['./public']. The ignore_paths property specifies a list of files or directories that Rill excludes during ingestion and parsing. This prevents unnecessary or incompatible content from affecting the project.

tip

Don't forget the leading / when specifying the path for ignore_paths and this path is also assuming the relative path from your project root.

public_paths​

[array of string] - List of file or directory paths to expose over HTTP. Defaults to ['./public']

ignore_paths​

[array of string] - A list of file or directory paths to exclude from parsing. Useful for ignoring extraneous or non-Rill files in the project

ignore_paths:
    - /path/to/ignore
    - /file_to_ignore.yaml

Testing access policies​

During development, it is always a good idea to check if your access policies are behaving the way you designed them to before pushing these changes into production. You can set mock users which enables a drop down in the dashboard preview to view as a specific user.

The View as selector is not visible in my dashboard, why?

This feature is only enabled when you have set a security policy on the dashboard. By default, the dashboard and it's contents is viewable by every user.

mock_users​

[array of object] - A list of mock users used to test dashboard security policies within the project

  • email - [string] - The email address of the mock user. This field is required (required)

  • name - [string] - The name of the mock user.

  • admin - [boolean] - Indicates whether the mock user has administrative privileges

  • groups - [array of string] - An array of group names that the mock user is a member of

mock_users:
    - email: john@yourcompany.com
      name: John Doe
      admin: true
    - email: jane@partnercompany.com
      groups:
        - partners
    - email: anon@unknown.com

Common Properties​

dev​

[object] - Overrides any properties in development environment.

prod​

[object] - Overrides any properties in production environment.