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

        • iso_duration - [string] - ISO 8601 duration (e.g., P7D for 7 days, P1M for 1 month)

        • iso_offset - [string] - ISO 8601 offset from current time (e.g., P1D to start from yesterday)

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

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

        • expression - [string] - Rill time expression (e.g., 'last 7 days', 'this month')

      • comparison_time_range - [object] - Optional comparison time range for period-over-period analysis

        • iso_duration - [string] - ISO 8601 duration for comparison period

        • iso_offset - [string] - ISO 8601 offset for comparison period (e.g., P7D to compare with previous week)

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

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

        • expression - [string] - Rill time expression for comparison period

      • context - [object] - Context to constrain the AI analysis

        • explore - [string] - Name of the explore dashboard to analyze

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

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

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

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 * * *"
data:
    ai:
        prompt: "Analyze key metrics and identify significant changes"
        time_range:
            expression: "1D as of latest/D"
        comparison_time_range:
            expression: "1D as of latest/D offset -1D"
        context:
            explore: my_explore
notify:
    email:
        recipients:
            - team@example.com
annotations:
    admin_owner_user_id: user-123 # report will be run with this user permission