Modality

Appearance

Report Block (Exposure) ​

The report block defines reports, dashboards, and visualizations within a data product. Reports group related metrics together and specify which entities they use. Reports are also called "exposures" as they expose data to end users.

Purpose ​

Reports help you document:

  • What dashboards and reports exist
  • Which metrics are tracked together
  • Which entities power each report
  • Report types and visualization styles

Syntax ​

Reports are defined within data products:

mml
data_product "ProductName" {
  report "ReportName" {
    description = "Report description"
    type = "dashboard" | "table" | "chart" | "kpi"

    # Entities used in this report
    uses "Domain.Entity"
    uses "Domain.Entity"

    # Metrics within this report
    metric "MetricName" { ... }
  }
}

Report Types ​

Reports can be categorized by their visualization type:

dashboard ​

Interactive dashboards with multiple metrics and visualizations.

mml
report "Revenue Dashboard" {
  type = "dashboard"
  description = "Executive revenue metrics"

  uses "Sales.Order"
  uses "Sales.Customer"

  metric "Total Revenue" { ... }
  metric "Average Order Value" { ... }
}

table ​

Tabular reports showing detailed data.

mml
report "Customer List" {
  type = "table"
  description = "Customer directory with key metrics"

  uses "Sales.Customer"
  uses "Sales.Order"
}

chart ​

Individual charts or visualizations.

mml
report "Revenue Trend" {
  type = "chart"
  description = "Monthly revenue trend line"

  uses "Sales.Order"

  metric "Monthly Revenue" { ... }
}

kpi ​

Key performance indicator cards.

mml
report "Top KPIs" {
  type = "kpi"
  description = "Executive KPI cards"

  metric "MRR" { ... }
  metric "Churn Rate" { ... }
}

Attributes ​

Optional Attributes ​

description ​

A clear description of what the report shows and its purpose.

  • Type: String
  • Required: No (but highly recommended)
mml
report "Revenue Dashboard" {
  description = "Daily revenue and sales performance metrics"
}

type ​

The type of report or visualization.

  • Type: String
  • Required: No
  • Valid values: "dashboard", "table", "chart", "kpi"
mml
report "Revenue Dashboard" {
  type = "dashboard"
}

Entity Usage ​

The uses keyword declares which entities the report depends on.

Syntax:

mml
uses "Domain.Entity"

Example:

mml
report "Revenue Dashboard" {
  uses "Sales.Order"
  uses "Sales.Customer"
  uses "Sales.Product"
}

Metrics ​

Reports contain metrics that define calculated business measures. Each metric specifies its calculation logic and which entities it uses.

Syntax:

mml
metric "MetricName" {
  description = "Metric description"
  calculation = "SQL or formula"
  target_value = "benchmark or goal"

  uses "Domain.Entity"
}

Example:

mml
metric "Total Revenue" {
  description = "Sum of all order values"
  calculation = "SUM(Order.amount)"
  target_value = "$1M monthly"

  uses "Sales.Order"
}

Examples ​

Basic Report ​

mml
data_product "Sales Analytics" {
  report "Revenue Dashboard" {
    description = "Daily revenue metrics"
    type = "dashboard"

    uses "Sales.Order"
    uses "Sales.Customer"
  }
}

Report with Metrics ​

mml
data_product "Sales Analytics" {
  report "Revenue Dashboard" {
    description = "Daily revenue and sales metrics"
    type = "dashboard"

    uses "Sales.Order"
    uses "Sales.Customer"

    metric "Total Revenue" {
      description = "Sum of all order values"
      calculation = "SUM(Order.amount)"
      target_value = "$1M monthly"
      uses "Sales.Order"
    }

    metric "Average Order Value" {
      description = "Average revenue per order"
      calculation = "AVG(Order.amount)"
      target_value = "$150"
      uses "Sales.Order"
    }

    metric "Customer Count" {
      description = "Number of unique customers"
      calculation = "COUNT(DISTINCT Customer.id)"
      target_value = "10,000 active customers"
      uses "Sales.Customer"
    }
  }
}

Multiple Reports in a Product ​

mml
data_product "Sales Analytics" {
  description = "Sales performance metrics"
  owner = "sales-team"

  report "Revenue Dashboard" {
    type = "dashboard"
    description = "Daily revenue tracking"

    uses "Sales.Order"
    uses "Sales.Customer"

    metric "Total Revenue" {
      description = "Sum of all orders"
      calculation = "SUM(Order.amount)"
      target_value = "$1M monthly"
      uses "Sales.Order"
    }

    metric "Average Order Value" {
      description = "Average order amount"
      calculation = "AVG(Order.amount)"
      target_value = "$150"
      uses "Sales.Order"
    }
  }

  report "Customer Insights" {
    type = "dashboard"
    description = "Customer behavior analysis"

    uses "Sales.Customer"
    uses "Sales.Order"

    metric "Customer Lifetime Value" {
      description = "Average revenue per customer"
      calculation = "SUM(Order.amount) / COUNT(DISTINCT Customer.id)"
      target_value = "$500"
      uses "Sales.Customer"
      uses "Sales.Order"
    }

    metric "Repeat Customer Rate" {
      description = "Percentage of customers with multiple orders"
      calculation = "COUNT(DISTINCT Customer WHERE order_count > 1) / COUNT(DISTINCT Customer) * 100"
      target_value = "40%"
      uses "Sales.Customer"
      uses "Sales.Order"
    }
  }

  report "Product Performance" {
    type = "table"
    description = "Product-level sales metrics"

    uses "Sales.Product"
    uses "Sales.Order"

    metric "Top Products" {
      description = "Products by revenue"
      calculation = "SUM(Order.amount) GROUP BY Product.name ORDER BY revenue DESC"
      uses "Sales.Product"
      uses "Sales.Order"
    }
  }
}

Complete Example ​

mml
# Define domain and entities
domain "Sales" {
  color = "#e74c3c"
  description = "Customer sales and orders"

  entity "Customer" {
    type = "entity"
    description = "A customer who can place orders"

    attribute "email" {
      type = "string"
      required = true
    }

    has-many "Sales.Order"
  }

  entity "Order" {
    type = "entity"
    description = "A customer order"

    attribute "amount" {
      type = "number"
      required = true
    }

    attribute "placed_at" {
      type = "date"
      required = true
    }

    belongs-to "Sales.Customer"
  }
}

# Define data product with reports
data_product "Sales Analytics" {
  description = "Sales performance metrics"
  owner = "sales-team"
  refresh_schedule = "0 * * * *"  # Hourly

  consumer "sales-team"
  consumer "executives"

  report "Revenue Dashboard" {
    type = "dashboard"
    description = "Real-time revenue tracking"

    uses "Sales.Order"
    uses "Sales.Customer"

    metric "Total Revenue" {
      description = "Sum of all orders"
      calculation = "SUM(Order.amount)"
      target_value = "$1M monthly"
      uses "Sales.Order"
    }

    metric "Average Order Value" {
      description = "Average order amount"
      calculation = "AVG(Order.amount)"
      target_value = "$150"
      uses "Sales.Order"
    }

    metric "Customer Count" {
      description = "Number of unique customers"
      calculation = "COUNT(DISTINCT Customer.id)"
      target_value = "10,000 active customers"
      uses "Sales.Customer"
    }
  }

  report "Customer Insights" {
    type = "dashboard"
    description = "Customer behavior analysis"

    uses "Sales.Customer"
    uses "Sales.Order"

    metric "Customer Lifetime Value" {
      description = "Average revenue per customer"
      calculation = "SUM(Order.amount) / COUNT(DISTINCT Customer.id)"
      target_value = "$500"
      uses "Sales.Customer"
      uses "Sales.Order"
    }

    metric "Repeat Customer Rate" {
      description = "Percentage of customers with multiple orders"
      calculation = "COUNT(DISTINCT Customer WHERE order_count > 1) / COUNT(DISTINCT Customer) * 100"
      target_value = "40%"
      uses "Sales.Customer"
      uses "Sales.Order"
    }
  }
}

Best Practices ​

  1. Group related metrics: Keep related metrics together in the same report

    mml
    report "Revenue Dashboard" {
  metric "Total Revenue" { ... }
  metric "Average Order Value" { ... }
  metric "Revenue Growth Rate" { ... }
}

  2. Declare entity dependencies: Always specify which entities the report uses

    mml
    report "Revenue Dashboard" {
  uses "Sales.Order"
  uses "Sales.Customer"
}

  3. Provide clear descriptions: Help users understand what each report shows

    mml
    report "Revenue Dashboard" {
  description = "Daily revenue and sales performance metrics for executives"
}

  4. Set target values for metrics: Define benchmarks and goals

    mml
    metric "Total Revenue" {
  calculation = "SUM(Order.amount)"
  target_value = "$1M monthly"
}

  5. Use appropriate report types: Choose the type that matches the visualization

    mml
    // Use dashboard for multi-metric views
report "Executive Dashboard" { type = "dashboard" }

// Use table for detailed listings
report "Customer List" { type = "table" }

// Use chart for single visualizations
report "Revenue Trend" { type = "chart" }

// Use kpi for metric cards
report "Top KPIs" { type = "kpi" }

  6. Name reports descriptively: Use clear names that indicate purpose

    mml
    // Good
report "Monthly Revenue by Region"

// Avoid
report "Report 1"

Released under the MIT License.

Copyright © 2025 Modality