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] - Define the interval of the report to check

  • duration - [string] - A valid ISO8601 duration to define the interval duration

  • limit - [integer] - Maximum number of intervals to check for 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 - [anyOf] - Defines the file path or pattern to query from the specified connector. (required)

      • option 1 - [string] - A simple file path/glob pattern as a string.

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

    • connector - [string] - Specifies the connector to use with the glob input.

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

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