Report Definition

Reports define analytics, visualizations, and data exports for business intelligence and decision-making. They provide aggregated views, charts, and formatted output of your data.

File Naming Convention: <report_name>.report.yml

The filename (without the .report.yml extension) automatically becomes the report's identifier. This eliminates the need for a redundant name property inside the file.

Examples:

sales_summary.report.yml → Report identifier: sales_summary
revenue_forecast.report.yml → Report identifier: revenue_forecast
inventory_status.report.yml → Report identifier: inventory_status

Files should use snake_case for multi-word names.

1. Root Properties

Property	Type	Required	Description
`label`	`string`	Required	Human-readable report title.
`description`	`string`	Optional	Internal description of report purpose.
`type`	`string`	Required	Report type: `tabular`, `summary`, `matrix`, `chart`, `dashboard`.
`object`	`string`	Conditional	Primary object for the report. Required for most types.
`data_source`	`object`	Required	Query configuration for report data.
`columns`	`array`	Conditional	Columns to display (for tabular reports).
`grouping`	`object`	Optional	Grouping configuration.
`aggregations`	`object`	Optional	Aggregate calculations.
`filters`	`array`	Optional	Default filters for the report.
`parameters`	`object`	Optional	User-configurable parameters.
`sorting`	`array`	Optional	Default sort order.
`visualization`	`object`	Optional	Chart/graph configuration.
`format`	`object`	Optional	Formatting and styling options.
`schedule`	`object`	Optional	Automated report generation schedule.
`export`	`object`	Optional	Export configuration (PDF, Excel, CSV).
`permissions`	`object`	Optional	Access control for the report.
`ai_context`	`object`	Optional	AI-friendly context.

2. Report Types

2.1 Tabular Report

Simple list of records with columns.

# File: customer_list.report.yml

label: Customer List Report
type: tabular
object: customer
description: Complete list of all customers with contact details

# Data source
data_source:
  object: customer
  fields:
    - name
    - email
    - phone
    - industry
    - status
    - created_at

# Columns
columns:
  - field: name
    label: Customer Name
    width: 200
  
  - field: email
    label: Email Address
    width: 250
  
  - field: phone
    label: Phone
    width: 150
    format: phone
  
  - field: industry
    label: Industry
    width: 150
  
  - field: status
    label: Status
    width: 100
  
  - field: created_at
    label: Created Date
    width: 150
    format: date

# Default filters
filters:
  - field: status
    operator: "="
    value: active

# Sorting
sorting:
  - field: name
    direction: asc

# Export options
export:
  formats: [pdf, excel, csv]

ai_context:
  intent: "Complete customer list for marketing and outreach"
  domain: crm

2.2 Summary Report

Aggregated data grouped by dimensions.

# File: sales_by_region.report.yml

label: Sales by Region
type: summary
object: order
description: Total sales aggregated by region and sales rep

# Data source
data_source:
  object: order
  fields:
    - region
    - sales_rep.name
    - amount
    - status
  filters:
    - field: status
      operator: "="
      value: completed

# Grouping
grouping:
  # Primary grouping
  - field: region
    label: Region
    sort: asc
  
  # Secondary grouping
  - field: sales_rep.name
    label: Sales Representative
    sort: asc

# Aggregations
aggregations:
  # Count orders
  order_count:
    function: count
    label: Number of Orders
  
  # Sum amount
  total_sales:
    field: amount
    function: sum
    label: Total Sales
    format: currency
  
  # Average order value
  avg_order_value:
    field: amount
    function: avg
    label: Average Order Value
    format: currency
  
  # Min/Max
  smallest_order:
    field: amount
    function: min
    format: currency
  
  largest_order:
    field: amount
    function: max
    format: currency

# Parameters
parameters:
  date_range:
    type: date_range
    label: Date Range
    default: this_quarter
    filter:
      field: order_date
      operator: between

# Visualization
visualization:
  type: bar_chart
  x_axis: region
  y_axis: total_sales
  series: sales_rep.name

ai_context:
  intent: "Analyze sales performance by geographic region and rep"
  domain: sales

2.3 Matrix Report

Two-dimensional grouped data.

# File: product_sales_matrix.report.yml

label: Product Sales Matrix
type: matrix
object: order_item
description: Sales by product and quarter

# Data source
data_source:
  object: order_item
  fields:
    - product.name
    - order.order_date
    - quantity
    - total_amount

# Matrix configuration
matrix:
  # Rows
  rows:
    - field: product.name
      label: Product
      sort: asc
  
  # Columns (time periods)
  columns:
    - field: order.order_date
      label: Quarter
      group_by: quarter
      format: Q# YYYY
  
  # Values (aggregations)
  values:
    - field: quantity
      function: sum
      label: Units Sold
    
    - field: total_amount
      function: sum
      label: Revenue
      format: currency

# Row subtotals
row_totals: true

# Column subtotals
column_totals: true

# Grand total
grand_total: true

ai_context:
  intent: "Cross-tabulation of product sales by time period"
  domain: sales

2.4 Chart Report

Visual data representation.

# File: revenue_trend.report.yml

label: Revenue Trend
type: chart
object: order
description: Monthly revenue trend with year-over-year comparison

# Data source
data_source:
  object: order
  fields:
    - order_date
    - amount
    - status
  filters:
    - field: status
      operator: "="
      value: completed
    - and
    - field: order_date
      operator: ">="
      value: $start_of_last_year

# Chart configuration
visualization:
  chart_type: line # line, bar, pie, donut, area, scatter
  
  # X-axis (time)
  x_axis:
    field: order_date
    group_by: month
    label: Month
    format: MMM YYYY
  
  # Y-axis (metric)
  y_axis:
    field: amount
    function: sum
    label: Revenue
    format: currency
  
  # Series (for comparison)
  series:
    field: order_date
    group_by: year
    label: Year
  
  # Chart options
  options:
    show_legend: true
    show_grid: true
    show_data_labels: false
    smooth: true
    fill: true
    colors: [#3498db, #2ecc71, #f39c12]

# Parameters
parameters:
  time_period:
    type: select
    label: Time Period
    options:
      - value: last_6_months
        label: Last 6 Months
      - value: last_12_months
        label: Last 12 Months
      - value: last_2_years
        label: Last 2 Years
    default: last_12_months

ai_context:
  intent: "Visualize revenue trends and identify patterns"
  domain: sales

2.5 Dashboard Report

Multiple visualizations and metrics.

# File: executive_dashboard.report.yml

label: Executive Dashboard
type: dashboard
description: High-level business metrics and KPIs

# Dashboard layout
layout:
  columns: 12
  gap: 16

# Widgets
widgets:
  # KPI: Total Revenue
  - type: metric
    title: Total Revenue
    position: { row: 0, col: 0, width: 3, height: 2 }
    data_source:
      object: order
      aggregation:
        field: amount
        function: sum
      filters:
        - field: status
          operator: "="
          value: completed
        - and
        - field: order_date
          operator: ">="
          value: $start_of_quarter
    format: currency
    comparison:
      previous_period: true
      show_trend: true
  
  # KPI: New Customers
  - type: metric
    title: New Customers
    position: { row: 0, col: 3, width: 3, height: 2 }
    data_source:
      object: customer
      aggregation:
        function: count
      filters:
        - field: created_at
          operator: ">="
          value: $start_of_month
    comparison:
      previous_period: true
  
  # Chart: Revenue by Region
  - type: chart
    title: Revenue by Region
    position: { row: 2, col: 0, width: 6, height: 4 }
    data_source:
      object: order
      fields: [region, amount]
      filters:
        - field: status
          operator: "="
          value: completed
    visualization:
      chart_type: pie
      dimension: region
      metric:
        field: amount
        function: sum
  
  # Chart: Sales Trend
  - type: chart
    title: Sales Trend
    position: { row: 2, col: 6, width: 6, height: 4 }
    data_source:
      object: order
      fields: [order_date, amount]
    visualization:
      chart_type: line
      x_axis:
        field: order_date
        group_by: month
      y_axis:
        field: amount
        function: sum
  
  # Table: Top Products
  - type: table
    title: Top 10 Products
    position: { row: 6, col: 0, width: 6, height: 4 }
    data_source:
      object: order_item
      fields:
        - product.name
        - quantity
        - total_amount
      limit: 10
      sort:
        - field: total_amount
          direction: desc
  
  # Table: Pipeline
  - type: table
    title: Sales Pipeline
    position: { row: 6, col: 6, width: 6, height: 4 }
    data_source:
      object: opportunity
      fields:
        - name
        - stage
        - amount
        - close_date
      filters:
        - field: is_closed
          operator: "="
          value: false

# Refresh interval (seconds)
refresh_interval: 300

# Parameters
parameters:
  region_filter:
    type: multiselect
    label: Regions
    options_from: regions
    default: all

ai_context:
  intent: "Executive dashboard showing key business metrics"
  domain: business_intelligence

3. Data Source Configuration

3.1 Single Object

data_source:
  object: customer
  fields:
    - name
    - email
    - status
  filters:
    - field: status
      operator: "="
      value: active

3.2 Joined Objects

data_source:
  object: order
  fields:
    - order_number
    - amount
    - customer.name
    - customer.industry
    - sales_rep.name
  joins:
    - object: customer
      type: left
      on:
        local: customer_id
        foreign: id
    
    - object: user
      alias: sales_rep
      type: left
      on:
        local: sales_rep_id
        foreign: id

3.3 Custom Query

data_source:
  type: custom_query
  query: |
    SELECT 
      c.name,
      COUNT(o.id) as order_count,
      SUM(o.amount) as total_spent
    FROM customers c
    LEFT JOIN orders o ON c.id = o.customer_id
    WHERE c.status = 'active'
    GROUP BY c.id, c.name

4. Filters and Parameters

4.1 Static Filters

filters:
  - field: status
    operator: "="
    value: completed
  
  - and
  
  - field: amount
    operator: ">"
    value: 1000

4.2 User Parameters

parameters:
  # Date range parameter
  date_range:
    type: date_range
    label: Report Period
    default: this_month
    filter:
      field: order_date
      operator: between
  
  # Select parameter
  region:
    type: select
    label: Region
    options:
      - All Regions
      - North
      - South
      - East
      - West
    default: All Regions
    filter:
      field: region
      operator: "="
      skip_if: All Regions
  
  # Multi-select parameter
  product_categories:
    type: multiselect
    label: Product Categories
    options_from:
      object: product
      field: category
      distinct: true
    filter:
      field: product.category
      operator: in
  
  # Number parameter
  min_amount:
    type: number
    label: Minimum Amount
    default: 0
    filter:
      field: amount
      operator: ">="

5. Formatting

5.1 Column Formatting

columns:
  - field: amount
    label: Revenue
    format: currency
    alignment: right
  
  - field: conversion_rate
    label: Conversion %
    format: percent
    decimals: 2
  
  - field: order_date
    label: Date
    format: date
    pattern: MM/DD/YYYY
  
  - field: status
    label: Status
    format: badge
    color_map:
      active: green
      pending: yellow
      cancelled: red

5.2 Conditional Formatting

columns:
  - field: revenue
    label: Revenue
    format: currency
    conditional_format:
      # Highlight high revenue
      - condition:
          operator: ">"
          value: 100000
        style:
          background: green
          color: white
          bold: true
      
      # Highlight low revenue
      - condition:
          operator: "<"
          value: 10000
        style:
          background: red
          color: white

6. Export Configuration

export:
  # Supported formats
  formats:
    - pdf
    - excel
    - csv
    - json
  
  # PDF options
  pdf:
    page_size: letter # letter, legal, a4
    orientation: portrait # portrait, landscape
    header: Company Name - {report_title}
    footer: Page {page} of {total_pages}
    include_logo: true
  
  # Excel options
  excel:
    sheet_name: Report Data
    include_filters: true
    freeze_header: true
    auto_filter: true
  
  # CSV options
  csv:
    delimiter: ","
    encoding: utf-8
    include_headers: true

7. Scheduling

schedule:
  # Enable scheduled generation
  enabled: true
  
  # Frequency
  frequency: daily # daily, weekly, monthly, quarterly
  
  # Time
  time: "08:00"
  timezone: America/New_York
  
  # Days (for weekly)
  days: [monday, friday]
  
  # Day of month (for monthly)
  day_of_month: 1 # 1-31, or 'last'
  
  # Recipients
  recipients:
    - email: manager@company.com
      format: pdf
    
    - email: analyst@company.com
      format: excel
  
  # Subject
  email_subject: "{report_title} - {date}"
  
  # Message
  email_body: |
    Please find attached the {report_title} for {date}.

8. Complete Examples

Example 1: Sales Performance Report

# File: sales_performance.report.yml

label: Sales Performance Report
type: summary
object: order
description: Comprehensive sales analysis by rep and product

data_source:
  object: order
  fields:
    - sales_rep.name
    - product.category
    - amount
    - quantity
    - order_date
  filters:
    - field: status
      operator: "="
      value: completed

grouping:
  - field: sales_rep.name
    label: Sales Representative
  
  - field: product.category
    label: Product Category

aggregations:
  order_count:
    function: count
    label: Orders
  
  units_sold:
    field: quantity
    function: sum
    label: Units
  
  total_revenue:
    field: amount
    function: sum
    label: Revenue
    format: currency
  
  avg_order_value:
    field: amount
    function: avg
    label: Avg Order
    format: currency

parameters:
  quarter:
    type: select
    label: Quarter
    options:
      - Q1 2026
      - Q2 2026
      - Q3 2026
      - Q4 2026
    default: Q1 2026

sorting:
  - field: total_revenue
    direction: desc

export:
  formats: [pdf, excel]

schedule:
  enabled: true
  frequency: monthly
  day_of_month: 1
  recipients:
    - email: sales@company.com

ai_context:
  intent: "Monthly sales performance analysis by rep and product"
  domain: sales

Example 2: Inventory Status Report

# File: inventory_status.report.yml

label: Inventory Status Report
type: tabular
object: product
description: Current inventory levels with reorder alerts

data_source:
  object: product
  fields:
    - sku
    - name
    - category
    - quantity_on_hand
    - quantity_committed
    - quantity_available
    - reorder_point
    - reorder_quantity
    - unit_cost
    - total_value

columns:
  - field: sku
    label: SKU
    width: 100
  
  - field: name
    label: Product
    width: 250
  
  - field: category
    label: Category
    width: 150
  
  - field: quantity_available
    label: Available
    width: 100
    alignment: right
    conditional_format:
      - condition:
          field: quantity_available
          operator: "<="
          compare_to: reorder_point
        style:
          background: red
          color: white
          bold: true
  
  - field: reorder_point
    label: Reorder Point
    width: 100
    alignment: right
  
  - field: total_value
    label: Total Value
    width: 150
    format: currency
    alignment: right

filters:
  - field: is_active
    operator: "="
    value: true

sorting:
  - field: quantity_available
    direction: asc

export:
  formats: [excel, pdf]

ai_context:
  intent: "Monitor inventory levels and identify reorder needs"
  domain: inventory_management

Example 3: Customer Lifetime Value

# File: customer_ltv.report.yml

label: Customer Lifetime Value Report
type: summary
object: customer
description: Customer value analysis with segmentation

data_source:
  object: customer
  fields:
    - name
    - industry
    - tier
    - created_at
    - orders.count
    - orders.amount_sum
    - orders.last_order_date

grouping:
  - field: tier
    label: Customer Tier
  
  - field: industry
    label: Industry

aggregations:
  customer_count:
    function: count
    label: Customers
  
  total_revenue:
    field: orders.amount_sum
    function: sum
    label: Total Revenue
    format: currency
  
  avg_customer_value:
    field: orders.amount_sum
    function: avg
    label: Avg Customer Value
    format: currency
  
  avg_order_count:
    field: orders.count
    function: avg
    label: Avg Orders per Customer
    decimals: 1

# Visualization
visualization:
  type: bar_chart
  x_axis: tier
  y_axis: avg_customer_value
  series: industry

parameters:
  cohort_year:
    type: select
    label: Customer Cohort
    options:
      - 2024
      - 2025
      - 2026
    filter:
      field: created_at
      operator: ">="
      value: ${value}-01-01

ai_context:
  intent: "Analyze customer lifetime value by tier and industry"
  domain: analytics

9. Best Practices

9.1 Performance

Limit data: Use filters to reduce dataset size
Index fields: Ensure filtered/grouped fields have indexes
Aggregate at database: Use database aggregations, not application-level
Cache results: Cache frequently run reports

9.2 Usability

Clear naming: Use descriptive report and column names
Appropriate format: Choose the right report type for the data
Default filters: Set sensible default filters
Visual hierarchy: Use grouping and formatting effectively

9.3 Accuracy

Validate logic: Test calculations and aggregations
Document assumptions: Explain any business logic
Handle nulls: Account for missing data
Date boundaries: Be clear about date range inclusivity

9.4 Security

Row-level security: Respect object permissions
Field-level security: Honor field permissions
Parameter validation: Validate user input
Audit access: Log report access for sensitive data

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Report Definition

1. Root Properties

2. Report Types

2.1 Tabular Report

2.2 Summary Report

2.3 Matrix Report

2.4 Chart Report

2.5 Dashboard Report

3. Data Source Configuration

3.1 Single Object

3.2 Joined Objects

3.3 Custom Query

4. Filters and Parameters

4.1 Static Filters

4.2 User Parameters

5. Formatting

5.1 Column Formatting

5.2 Conditional Formatting

6. Export Configuration

7. Scheduling

8. Complete Examples

Example 1: Sales Performance Report

Example 2: Inventory Status Report

Example 3: Customer Lifetime Value

9. Best Practices

9.1 Performance

9.2 Usability

9.3 Accuracy

9.4 Security

See Also

FilesExpand file tree

report.md

Latest commit

History

report.md

File metadata and controls

Report Definition

1. Root Properties

2. Report Types

2.1 Tabular Report

2.2 Summary Report

2.3 Matrix Report

2.4 Chart Report

2.5 Dashboard Report

3. Data Source Configuration

3.1 Single Object

3.2 Joined Objects

3.3 Custom Query

4. Filters and Parameters

4.1 Static Filters

4.2 User Parameters

5. Formatting

5.1 Column Formatting

5.2 Conditional Formatting

6. Export Configuration

7. Scheduling

8. Complete Examples

Example 1: Sales Performance Report

Example 2: Inventory Status Report

Example 3: Customer Lifetime Value

9. Best Practices

9.1 Performance

9.2 Usability

9.3 Accuracy

9.4 Security

See Also