Skip to main content

Report YAML

Reports allow you to schedule and deliver data exports or AI-powered insights to recipients via email or Slack.

Properties​

type​

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

display_name​

[string] - Display name for the report shown in notifications and UI

title​

[string] - Deprecated: use display_name instead

refresh​

[object] - Refresh schedule for the report

refresh:
  cron: "0 9 * * *"

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

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.

intervals​

[object] - Defines the report 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

timeout​

[string] - Define the timeout for the report execution (e.g., '5m', '1h')

data​

[oneOf] - Data source for the report using the generic resolver pattern. Supports ai resolvers only as of now.

  • 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

query​

[object] - Legacy query-based report configuration

  • name - [string] - Name of the query to execute (e.g., MetricsViewAggregation)

  • args - [object] - Arguments to pass to the query

  • args_json - [string] - Query arguments as a JSON string (alternative to args)

export​

[object] - Export configuration for query-based reports

  • format - [string] - Export file format

  • include_header - [boolean] - Include column headers in the export

  • limit - [integer] - Maximum number of rows to export

notify​

[object] - Notification configuration for email and Slack delivery

  • 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 for report metadata (e.g., admin_owner_user_id for AI reports)

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: query-based report with CSV export
type: report
display_name: Weekly Sales Report
refresh:
    cron: "0 9 * * 1"
data:
    metrics:
        metrics_view: sales_metrics
        dimensions:
            - name: region
        measures:
            - name: total_sales
        time_range:
            expression: "7D as of latest/D"
export:
    format: csv
    limit: 1000
notify:
    email:
        recipients:
            - sales@example.com
annotations:
    admin_owner_user_id: user-123
    web_open_mode: recipient # report will use recipient's permission to run the query
# Example: AI-powered insight report
type: report
display_name: Daily AI Insights
refresh:
    cron: "0 8 * * *"
watermark: inherit # resolve "latest" against the explore's data instead of the trigger time
data:
    ai:
        prompt: "Analyze key metrics and identify significant changes"
        time_range:
            expression: "1D as of latest/D+1D" # the last day with data
        comparison_time_range:
            expression: "1D as of latest/D" # the day before it
        explore: my_explore
notify:
    email:
        recipients:
            - team@example.com
annotations:
    admin_owner_user_id: user-123 # report will be run with this user permission