# Rill Rillyaml

> Detailed instructions and examples for developing the rill.yaml file

- Skill: `rilldata/rill-rillyaml` (Agent Skill)
- Install (CLI): `npx skillmds@latest add rilldata/rill-rillyaml`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rilldata/rill-rillyaml/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: rilldata (https://skillmd.com/u/rilldata)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/rilldata/rill-rillyaml

---


# Instructions for developing `rill.yaml`

## Introduction

`rill.yaml` is a required configuration file located at the root of every Rill project. It defines project-wide settings, similar to `package.json` in Node.js or `dbt_project.yml` in dbt.

## Core Concepts

### Project metadata

There are no required properties in `rill.yaml`, but it is common to configure:

- `display_name`: Human-readable name shown in the UI
- `description`: Brief description of the project's purpose
- `compiler`: Deprecated property that is commonly found in old projects

### Default OLAP connector

The `olap_connector` property sets the default OLAP database for the project. Models output to this connector by default, and metrics views query from it unless explicitly overridden.

Common values are `duckdb` or `clickhouse`. If not specified, Rill initializes a managed DuckDB database and uses it as the default OLAP connector. 

### Default AI connector

The `ai_connector` property selects the connector powering AI features (developer agent, AI charts, chat). Point it to an AI connector defined in the project, such as `openai`, `claude`, or `gemini`. Defaults to Rill's built-in AI service.

### Mock users for security testing

The `mock_users` property defines test users for validating security policies during local development. Each mock user can have:

- `email` (required): The user's email address
- `name`: Display name
- `admin`: Boolean indicating admin privileges
- `groups`: List of group memberships
- Custom attributes for use in security policy expressions

When mock users are defined and security policies exist, a "View as" dropdown appears in the dashboard preview.

### Environment variables

The `env` property sets default values for non-sensitive variables. These can be referenced in resource files using templating syntax (`{{ .env.<variable> }}`). Sensitive secrets should go in `.env` instead.

### Resource type defaults

Project-wide defaults can be set for resource types using plural keys:

- `models`: Default settings for all models (e.g., refresh schedules)
- `metrics_views`: Default settings for all metrics views (e.g., `first_day_of_week`)
- `explores`: Default settings for explore dashboards (e.g., `time_ranges`, `time_zones`)
- `canvases`: Default settings for canvas dashboards

Individual resources can override these defaults.

### Path management

- `ignore_paths`: List of paths to exclude from parsing (use leading `/`)
- `public_paths`: List of paths to expose over HTTP (defaults to `['./public']`)

### Environment overrides

The `dev` and `prod` properties allow environment-specific configuration overrides.

## Minimal Example

A minimal `rill.yaml` for a new project:

```yaml
display_name: My Analytics Project
```

## Complete Example

A comprehensive `rill.yaml` demonstrating common configurations:

```yaml
display_name: Sales Analytics
description: Sales performance dashboards with partner access controls

olap_connector: duckdb

# Use a project-defined Claude connector to power AI features
ai_connector: claude

# Non-sensitive environment variables
env:
  default_lookback: P30D
  data_bucket: gs://my-company-data

# Mock users for testing security policies locally
mock_users:
  - email: admin@mycompany.com
    name: Admin User
    admin: true
  - email: partner@external.com
    groups:
      - partners
  - email: viewer@mycompany.com
    tenant_id: xyz

# Project-wide defaults for models
models:
  refresh:
    cron: 0 0 * * *

# Project-wide defaults for metrics views
metrics_views:
  smallest_time_grain: day

# Project-wide defaults for explore dashboards
explores:
  defaults:
    time_range: P3M
  time_zones:
    - UTC
    - America/New_York
    - Europe/London
  time_ranges:
    - PT24H
    - P7D
    - P30D
    - P3M
    - P12M

# Exclude non-Rill files from parsing
ignore_paths:
  - /docs
```

## Reference documentation

Here is a full JSON schema for the `rill.yaml` syntax:

```
$schema: http://json-schema.org/draft-07/schema#
allOf:
    - properties:
        ai_connector:
            description: Specifies the default AI connector for the project. Defaults to Rill's internal AI connector if not set.
            type: string
        ai_instructions:
            description: Extra instructions for LLM/AI features. Used to guide natural language question answering and routing.
            type: string
        compiler:
            description: Specifies the parser version to use for compiling resources
            type: string
        description:
            description: A brief description of the project
            type: string
        display_name:
            description: The display name of the project, shown in the upper-left corner of the UI
            type: string
        features:
            description: Optional feature flags. Can be specified as a map of feature names to booleans.
            type: object
      title: Properties
      type: object
    - description: |
        Rill allows you to specify the default OLAP engine to use in your project via `rill.yaml`.
        :::info Curious about OLAP Engines?
        Please see our reference documentation on [OLAP Engines](/developers/build/connectors/olap).
        :::
      properties:
        olap_connector:
            description: Specifies the default OLAP engine for the project. Defaults to duckdb if not set.
            examples:
                - olap_connector: clickhouse
            type: string
      title: Configuring the default OLAP Engine
      type: object
    - description: |
        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](models.md), [metrics_view](metrics-views.md), and [explore](explore-dashboards.md)

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

        :::info Hierarchy of inheritance and property overrides
        As a general rule of thumb, properties that have been specified at a more _granular_ level will supersede 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](models.md)/[metrics_views](metrics-views.md)/[explore](explore-dashboards.md) object-level properties (e.g. `models.yaml` or `explore-dashboards.yaml`)
        2. [Environment](/developers/build/models/templating) level properties (e.g. a specific property that has been set for `dev`)
        3. [Project-wide defaults](#project-wide-defaults) for a specific property and resource type
        :::
      properties:
        canvases:
            description: Defines project-wide default settings for canvases. Unless overridden, individual canvases will inherit these defaults.
            examples:
                - canvases:
                    defaults:
                        time_range: P7D
                    time_ranges:
                        - PT24H
                        - P7D
                    time_zones:
                        - UTC
                  explores:
                    defaults:
                        time_range: P24M
                    time_ranges:
                        - PT24H
                        - P6M
                    time_zones:
                        - UTC
                  metrics_views:
                    first_day_of_week: 1
                    smallest_time_grain: month
                  models:
                    refresh:
                        cron: 0 * * * *
            type: object
        explores:
            description: Defines project-wide default settings for explores. Unless overridden, individual explores will inherit these defaults.
            type: object
        metrics_views:
            description: Defines project-wide default settings for metrics_views. Unless overridden, individual metrics_views will inherit these defaults.
            type: object
        models:
            description: Defines project-wide default settings for models. Unless overridden, individual models will inherit these defaults.
            type: object
      title: Project-wide defaults
      type: object
    - description: |
        Primarily useful for [templating](/developers/build/connectors/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.
        :::info 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:
        ```bash
        rill start --env numeric_var=100 --env string_var="different_value"
        ```
        :::
        :::tip 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:
        ```bash
        variable=xyz
        ```
        Similar to how [connector credentials can be pushed / pulled](/developers/build/connectors/credentials#pulling-credentials-and-variables-from-a-deployed-project-on-rill-cloud) 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.
        :::
      properties:
        env:
            description: |
                A map of key-value pairs for setting variables on your project. It accepts both user-defined variables (for use with templating) and reserved `rill.*` keys that configure project-wide settings. The full set of reserved keys is listed below.
            examples:
                - env:
                    foo: bar
                    rill.interactive_sql_row_limit: 5000
            properties:
                rill.ai.completion_timeout_seconds:
                    description: 'Maximum duration of a full AI completion request (which may include multiple LLM calls and tool uses), in seconds. Default: 300.'
                    type: integer
                rill.ai.default_query_limit:
                    description: 'Default row limit applied to AI tool queries when no limit is specified. Default: 25.'
                    type: integer
                rill.ai.llm_timeout_seconds:
                    description: 'Maximum duration of a single LLM completion request, in seconds. Default: 180. Note: when using Rill''s hosted AI service (i.e. not a self-configured LLM), the admin server enforces a hard upper bound of 10 minutes, so values above that have no effect.'
                    type: integer
                rill.ai.max_query_limit:
                    description: 'Maximum row limit allowed for AI tool queries. Default: 250.'
                    type: integer
                rill.ai.max_time_range_days:
                    description: 'Maximum time range allowed for AI tool queries, in days. Set to 0 for no limit. Default: 0.'
                    type: integer
                rill.ai.require_time_range:
                    description: 'Require AI tool queries to include a time range filter; reject queries without one. Default: true.'
                    type: boolean
                rill.alerts.default_streaming_refresh_cron:
                    description: 'Default cron expression for refreshing alerts that depend on streaming refs (for example, external tables in Druid where new data may arrive at any time). Default: `0 0 * * *` (every 24 hours).'
                    type: string
                rill.alerts.fast_streaming_refresh_cron:
                    description: 'Cron expression for refreshing streaming alerts on always-on OLAP connectors. Default: `*/10 * * * *` (every 10 minutes).'
                    type: string
                rill.download_limit_bytes:
                    description: 'Limit on the size of an exported file, in bytes. Default: 134217728 (128 MB).'
                    type: integer
                rill.interactive_sql_row_limit:
                    description: 'Row limit for interactive SQL queries; does not apply to SQL exports. Default: 10000.'
                    type: integer
                rill.metrics.approximate_comparisons:
                    description: 'Rewrite metrics comparison queries to use an approximate, faster form. Approximate comparisons may not return data points for all values. Default: true.'
                    type: boolean
                rill.metrics.approximate_comparisons_cte:
                    description: 'Rewrite metrics comparison queries to use a CTE for the base query. Default: false.'
                    type: boolean
                rill.metrics.approximate_comparisons_two_phase_limit:
                    description: 'Row-limit threshold under which metrics comparison queries use a two-phase strategy (base values first, comparison values second). Default: 250.'
                    type: integer
                rill.metrics.druid_mvd_filtered_group_by:
                    description: 'Narrow unnested (multi-value) dimensions to the filtered values when grouping in Druid, so results contain only the filtered values rather than every value co-occurring in matching rows. Default: false.'
                    type: boolean
                rill.metrics.druid_mvd_filtered_search:
                    description: 'Extends rill.metrics.druid_mvd_filtered_group_by to dimension search (ILIKE filters) using MV_FILTER_REGEX, so search results contain only values matching the search text. Requires Druid 35.0.0 or newer. Default: false.'
                    type: boolean
                rill.metrics.exactify_druid_topn:
                    description: 'Split Druid TopN queries into two queries to improve measure accuracy, at the cost of performance. Default: false.'
                    type: boolean
                rill.metrics.timeseries_null_filling_implementation:
                    description: 'Null-filling implementation for timeseries queries. One of `none`, `new`, or `pushdown`. Default: `pushdown`.'
                    type: string
                rill.model.partitions_warn_on_failure:
                    description: 'When true, partition execution failures are surfaced as non-blocking warnings instead of errors. Default: true in `prod`, false otherwise.'
                    type: boolean
                rill.model.tests_warn_on_failure:
                    description: 'When true, model test failures are surfaced as non-blocking warnings instead of errors. Default: true in `prod`, false otherwise.'
                    type: boolean
                rill.model.timeout_override:
                    description: 'Timeout for model reconciliation in seconds, used in validation mode. Default: 0 (no override).'
                    type: integer
                rill.models.concurrent_execution_limit:
                    description: 'Maximum number of concurrent model executions. Default: 5.'
                    type: integer
                rill.models.default_materialize:
                    description: 'Materialize models as tables by default instead of views. Default: false.'
                    type: boolean
                rill.models.disable:
                    description: 'When true, model execution is disabled. Useful for stopping any ingestion in Rill temporarily. Default: false.'
                    type: boolean
                rill.models.materialize_delay_seconds:
                    description: 'Delay before materializing models, in seconds. Default: 0.'
                    type: integer
                rill.parser.skip_updates_if_parse_errors:
                    description: 'Short-circuit project parser reconciliation when parse errors exist. Default: false.'
                    type: boolean
                rill.strict_model_properties:
                    description: 'Return an error when a model contains unmapped properties. Default: false.'
                    type: boolean
                rill.strict_resolver_properties:
                    description: 'Return an error when a resolver contains properties not recognized by its implementation. Default: false.'
                    type: boolean
            type: object
      title: Setting variables
      type: object
    - description: |
        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`. This path is relative to your project root.
        :::
      properties:
        ignore_paths:
            description: A list of file or directory paths to exclude from parsing. Useful for ignoring extraneous or non-Rill files in the project
            examples:
                - ignore_paths:
                    - /path/to/ignore
                    - /file_to_ignore.yaml
            items:
                type: string
            type: array
        public_paths:
            description: List of file or directory paths to expose over HTTP. Defaults to ['./public']
            items:
                type: string
            type: array
      title: Managing Paths in Rill
      type: object
    - description: |
        During development, it is always a good idea to check if your [access policies](/developers/build/metrics-view/security) 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.
        :::info 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 its contents are viewable by every user.
        :::
      properties:
        mock_users:
            description: A list of mock users used to test dashboard security policies within the project
            examples:
                - mock_users:
                    - admin: true
                      email: john@yourcompany.com
                      name: John Doe
                    - email: jane@partnercompany.com
                      groups:
                        - partners
                    - email: anon@unknown.com
                    - custom_variable_1: Value_1
                      custom_variable_2: Value_2
                      email: embed@rilldata.com
                      name: embed
            items:
                properties:
                    admin:
                        description: Indicates whether the mock user has administrative privileges
                        type: boolean
                    email:
                        description: The email address of the mock user. This field is required
                        type: string
                    groups:
                        description: An array of group names that the mock user is a member of
                        items:
                            type: string
                        type: array
                    name:
                        description: The name of the mock user.
                        type: string
                required:
                    - email
                type: object
            type: array
      title: Testing access policies
      type: object
    - properties:
        dev:
            description: Overrides any properties in development environment.
            type: object
        prod:
            description: Overrides any properties in production environment.
            type: object
      title: Common Properties
      type: object
description: The `rill.yaml` file contains metadata about your project.
id: rill-yaml.schema.yaml
title: Project YAML
type: object
```