Skip to main content

Alert YAML

Along with dashboard-level alerts that can be created via the UI, you can develop more extensive alerting in an alert YAML file. When creating an alert via a YAML file, you'll see this denoted in the UI as Created through code.

Properties​

type​

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

refresh​

[object] - Refresh schedule for the alert

refresh:
  cron: "* * * * *"
  #every: "24h"

(required)

  • cron - [string] - A cron expression that defines the execution schedule

  • time_zone - [string] - Time zone to interpret the schedule in (e.g., 'UTC', 'America/Los_Angeles').

  • disable - [boolean] - If true, disables the resource without deleting it.

  • ref_update - [boolean] - If true, allows the resource to run when a dependency updates.

  • run_in_dev - [boolean] - If true, allows the schedule to run in development mode.

display_name​

[string] - Display name for the alert

description​

[string] - Description for the alert

intervals​

[object] - Defines the alert interval to check.

  • duration - [string] - An ISO 8601 duration to define the interval duration.

  • limit - [integer] - Maximum number of intervals to check on invocation.

  • check_unclosed - [boolean] - Whether unclosed intervals should be checked.

watermark​

[string] - Specifies how the watermark is determined for incremental processing. Use 'trigger_time' to set it at runtime or 'inherit' to use the upstream model's watermark.

timeout​

[string] - Defines the timeout of the alert in seconds. (optional)

data​

[oneOf] - Data source for the alert (required)

  • option 1 - [object] - Executes a raw SQL query against the project's data models.

    • sql - [string] - Raw SQL query to run against existing models in the project. (required)

    • connector - [string] - Specifies the connector to use when running SQL or glob queries.

  • option 2 - [object] - Executes a SQL query that targets a defined metrics view.

    • metrics_sql - [string] - SQL query that targets a metrics view in the project (required)

  • option 3 - [object] - Calls a custom API defined in the project to compute data.

    • api - [string] - Name of a custom API defined in the project. (required)

    • args - [object] - Arguments to pass to the custom API.

  • option 4 - [object] - Uses a file-matching pattern (glob) to query data from a connector.

    • glob - [oneOf] - Simple path/glob pattern or path/glob pattern with advanced options. (required)

      • option 1 - [string] - Glob pattern used to match files or directories in the object store.

      • option 2 - [object] - Configuration for specifying a file path/glob pattern with advanced options.

        • connector - [string] - Specifies the object store connector to use (e.g. "s3", "gcs"). If not provided, it is inferred from the scheme of the path.

        • path - [string] - Glob pattern used to match files or directories in the object store. (required)

        • start - [string] - Defines the lower bound (inclusive) for partition filtering. Only partitions with paths greater than or equal to this value are considered.

        • end - [string] - Defines the upper bound (exclusive) for partition filtering. Only partitions with paths less than this value are considered.

        • last - [integer] - Limits the result to the last N partitions (the N highest paths in lexicographic order). This hard limit always applies, including on the first run when there is no existing data. Additionally, when previously processed partitions exist, it raises the lower bound to the Nth partition from the end of those successfully processed partitions, forming a rolling window that prevents full re-listings each time.

        • partition - [string] - Controls how matched files are grouped: - "file" (default) : Each matched path is returned as a row. Use the glob pattern to match files or directories at the level you want (for example, file-level or directory-level). - "directory": This mode is deprecated. Instead, use "file" with a glob that directly matches the directory level you want. - "hive": groups files by directory and extracts Hive-style partition values from the path as columns.

        • rollup_files - [boolean] - If true, includes a "files" array listing all files in each partition. Only applicable when using "directory" or "hive" partitioning.

        • transform_sql - [string] - Optional DuckDB SQL query used to transform the results. The resolved data is available as a table referenced using {{ .table }}.

  • option 5 - [object] - Uses the status of a resource as data.

    • resource_status - [object] - Based on resource status (required)

      • where_error - [boolean] - Indicates whether the condition should trigger when the resource is in an error state.

  • option 6 - [object] - Invokes multiple resolvers and returns the union of their results. Each entry in the list is a resolver definition (e.g. sql, glob, metrics_sql, api).

    • union - [array of object] - List of resolver definitions whose results are combined into a single result set. (required)

  • option 7 - [object] - Uses AI to generate insights and analysis from metrics data. Only available for reports.

    • ai - [object] - AI resolver configuration for generating automated insights (required)

      • prompt - [string] - Custom prompt to guide the AI analysis. If not provided, a default analysis prompt is used.

      • time_range - [object] - Time range for the analysis period. Use either a Rill time expression or fixed start and end timestamps.

        • expression - [string] - Rill time expression. Note that snapping excludes the period containing the reference point, so '1D as of latest/D' is the day before the latest data; use '1D as of latest/D+1D' for the last day with data.

        • start - [string] - Start timestamp in ISO 8601 format

        • end - [string] - End timestamp in ISO 8601 format

      • comparison_time_range - [object] - Optional comparison time range for period-over-period analysis. Use either a Rill time expression or fixed start and end timestamps.

        • expression - [string] - Rill time expression for the comparison period (e.g., '1D as of latest/D' when the time range is '1D as of latest/D+1D')

        • start - [string] - Start timestamp in ISO 8601 format

        • end - [string] - End timestamp in ISO 8601 format

      • time_zone - [string] - IANA time zone used to evaluate the time range expressions (e.g., 'America/New_York'). Defaults to UTC.

      • explore - [string] - Name of the explore dashboard to analyze. If provided, the analysis is limited to the metrics view of this dashboard. Combined with watermark: inherit on the report, time range expressions are resolved against the latest data in the metrics view instead of the report's trigger time.

      • dimensions - [array of string] - List of dimensions to include in the analysis

      • measures - [array of string] - List of measures to include in the analysis

      • where - [object] - Optional filter expression to apply to the analysis, in the same format as metrics view query filters

for​

[oneOf] - Specifies how user identity or attributes should be evaluated for security policy enforcement.

  • option 1 - [object] - Specifies a unique user identifier for applying security policies.

    • user_id - [string] - The unique user ID used to evaluate security policies. (required)

  • option 2 - [object] - Specifies a user's email address for applying security policies.

    • user_email - [string] - The user's email address used to evaluate security policies. (required)

  • option 3 - [object] - Specifies a set of arbitrary user attributes for applying security policies.

    • attributes - [object] - A dictionary of user attributes used to evaluate security policies. (required)

on_recover​

[boolean] - Send an alert when a previously failing alert recovers. Defaults to false.

on_fail​

[boolean] - Send an alert when a failure occurs. Defaults to true.

on_error​

[boolean] - Send an alert when an error occurs during evaluation. Defaults to false.

renotify​

[boolean] - Enable repeated notifications for unresolved alerts. Defaults to false.

renotify_after​

[string] - Defines the re-notification interval for the alert (e.g., '10m','24h'), equivalent to snooze duration in UI, defaults to 'Off'

notify​

[object] - Notification configuration for email and Slack delivery (required)

  • email - [object] - Send notifications via email.

    • recipients - [array of string] - An array of email addresses to notify. (required)

  • slack - [object] - Send notifications via Slack.

    • users - [array of string] - An array of Slack user IDs to notify.

    • channels - [array of string] - An array of Slack channel names to notify.

    • webhooks - [array of string] - An array of Slack webhook URLs to send notifications to.

annotations​

[object] - Key-value pairs used for annotations.

Common Properties​

name​

[string] - Name is usually inferred from the filename, but can be specified manually.

refs​

[array of string] - List of resource references

tags​

[array of string] - Tags for organizing and filtering the resource (e.g. on the project dashboards list).

metadata​

[object] - User-defined key-value metadata attached to the resource. Rill does not read or write it; it is exposed as-is on the resource's meta over the API for external tooling. Values are strings, with numbers and booleans coerced. Not supported in rill.yaml defaults.

dev​

[object] - Overrides any properties in development environment.

prod​

[object] - Overrides any properties in production environment.

Examples​

# Example: To send alert when data lags by more than 1 day to slack channel #rill-cloud-alerts
type: alert
display_name: Data lags by more than 1 day
# Check the alert every hour.
refresh:
    cron: 0 * * * *
# Query that returns non-empty results if the measures lag by more than 1 day.
data:
    sql: |-
        SELECT  *
        FROM
        (
          SELECT  MAX(event_time) AS max_time
          FROM rill_metrics_model
        )
        WHERE max_time < NOW() - INTERVAL '1 day'
# Send notifications in Slack.
notify:
    slack:
        channels:
            - '#rill-cloud-alerts'