Time Grains

For Data Analysts

Time grains define how metrics aggregate data over time periods. They enable consistent time-series analysis and period-based reporting.

Overview

A time grain specifies the temporal granularity for metric calculations:

Grain	Aggregation Period	Use Case
day	Daily	Operational metrics, daily KPIs
week	Weekly (ISO week)	Weekly reports, trend analysis
month	Calendar month	Monthly reports, MoM comparisons
quarter	Calendar quarter	Quarterly business reviews
year	Calendar year	Annual reports, YoY comparisons

Basic Configuration

Setting Time Grain

metrics:
  - name: daily_revenue
    type: simple
    expression: orders.total_revenue
    time_grain: day
    description: Revenue aggregated by day

All Time Grain Values

metrics:
  - name: daily_active_users
    type: simple
    expression: users.active_count
    time_grain: day

  - name: weekly_signups
    type: simple
    expression: users.signup_count
    time_grain: week

  - name: monthly_revenue
    type: simple
    expression: orders.total_revenue
    time_grain: month

  - name: quarterly_revenue
    type: simple
    expression: orders.total_revenue
    time_grain: quarter

  - name: annual_revenue
    type: simple
    expression: orders.total_revenue
    time_grain: year

Time Grain Examples

Daily Metrics

Daily metrics are useful for operational monitoring and granular trend analysis.

metrics:
  - name: daily_orders
    type: simple
    expression: orders.order_count
    time_grain: day
    description: Number of orders placed each day

  - name: daily_active_users
    type: simple
    expression: users.active_count
    time_grain: day
    description: Unique users active each day

  - name: daily_page_views
    type: simple
    expression: analytics.page_view_count
    time_grain: day
    description: Total page views per day

Weekly Metrics

Weekly metrics smooth out day-of-week variations and support weekly reporting.

metrics:
  - name: weekly_new_customers
    type: simple
    expression: customers.new_customer_count
    time_grain: week
    description: New customers acquired each week (ISO week)

  - name: weekly_support_tickets
    type: simple
    expression: support.ticket_count
    time_grain: week
    description: Support tickets opened each week

  - name: weekly_average_response_time
    type: simple
    expression: support.avg_response_time
    time_grain: week
    format: ".1f"
    description: Average support response time in hours

Monthly Metrics

Monthly metrics are the most common for business reporting and period comparisons.

metrics:
  - name: monthly_recurring_revenue
    type: simple
    expression: subscriptions.mrr
    time_grain: month
    format: "$,.0f"
    description: Monthly Recurring Revenue (MRR)

  - name: monthly_churn_rate
    type: derived
    expression: |
      subscriptions.churned_count / subscriptions.start_of_month_count
    time_grain: month
    format: ".2%"
    description: Percentage of subscriptions churned each month

  - name: monthly_net_revenue_retention
    type: derived
    expression: |
      subscriptions.end_of_month_mrr / subscriptions.start_of_month_mrr
    time_grain: month
    format: ".1%"
    description: Net revenue retention (NRR) by month

Quarterly Metrics

Quarterly metrics support business reviews and strategic planning.

metrics:
  - name: quarterly_revenue
    type: simple
    expression: orders.total_revenue
    time_grain: quarter
    format: "$,.0f"
    description: Total revenue by fiscal quarter

  - name: quarterly_customer_acquisition
    type: simple
    expression: customers.new_customer_count
    time_grain: quarter
    description: New customers acquired each quarter

  - name: quarterly_expansion_revenue
    type: derived
    expression: |
      subscriptions.expansion_mrr * 3
    time_grain: quarter
    format: "$,.0f"
    description: Revenue from existing customer expansion

Annual Metrics

Annual metrics enable year-over-year analysis and long-term trend tracking.

metrics:
  - name: annual_revenue
    type: simple
    expression: orders.total_revenue
    time_grain: year
    format: "$,.0f"
    description: Total revenue by calendar year

  - name: annual_growth_rate
    type: derived
    expression: |
      (current.annual_revenue - prior.annual_revenue)
      / prior.annual_revenue
    time_grain: year
    format: ".1%"
    description: Year-over-year revenue growth

  - name: annual_customer_lifetime_value
    type: derived
    expression: |
      orders.total_revenue / customers.unique_customer_count
    time_grain: year
    format: "$,.0f"
    description: Average customer value per year

Time Grain and Dimensions

Querying with Time Dimensions

When querying metrics with time grains, include appropriate time dimensions:

{
  "metrics": ["monthly_revenue"],
  "dimensions": ["orders.order_date.month"],
  "filters": [
    {
      "field": "orders.order_date",
      "operator": "gte",
      "value": "2024-01-01"
    }
  ]
}

Matching Grain to Dimension

The time grain should align with or be coarser than the time dimension:

# Good: Monthly metric with month dimension
metrics:
  - name: monthly_revenue
    time_grain: month
# Query: dimensions: ["orders.order_date.month"]

# Good: Daily metric with day dimension
metrics:
  - name: daily_orders
    time_grain: day
# Query: dimensions: ["orders.order_date.day"]

# Also valid: Daily metric with month dimension (aggregates up)
metrics:
  - name: daily_orders
    time_grain: day
# Query: dimensions: ["orders.order_date.month"]

Period Comparisons

Time grains enable period-over-period comparisons using the current and prior context.

Month-over-Month

metrics:
  - name: mom_revenue_growth
    type: derived
    expression: |
      (current.monthly_revenue - prior.monthly_revenue)
      / prior.monthly_revenue
    time_grain: month
    format: ".1%"
    description: Month-over-month revenue growth rate

Quarter-over-Quarter

metrics:
  - name: qoq_customer_growth
    type: derived
    expression: |
      (current.quarterly_customers - prior.quarterly_customers)
      / prior.quarterly_customers
    time_grain: quarter
    format: ".1%"
    description: Quarter-over-quarter customer growth

Year-over-Year

metrics:
  - name: yoy_revenue_growth
    type: derived
    expression: |
      (current.annual_revenue - prior.annual_revenue)
      / prior.annual_revenue
    time_grain: year
    format: ".1%"
    description: Year-over-year revenue growth

Multiple Time Grain Variants

Create multiple versions of the same metric for different analysis needs:

metrics:
  # Base measure for different time grains
  - name: revenue_daily
    type: simple
    expression: orders.total_revenue
    time_grain: day
    description: Daily revenue for operational monitoring

  - name: revenue_weekly
    type: simple
    expression: orders.total_revenue
    time_grain: week
    description: Weekly revenue for trend analysis

  - name: revenue_monthly
    type: simple
    expression: orders.total_revenue
    time_grain: month
    description: Monthly revenue for business reporting

  - name: revenue_quarterly
    type: simple
    expression: orders.total_revenue
    time_grain: quarter
    description: Quarterly revenue for executive reviews

  - name: revenue_annual
    type: simple
    expression: orders.total_revenue
    time_grain: year
    description: Annual revenue for strategic planning

Combining Time Grain with Filters

metrics:
  - name: monthly_enterprise_revenue
    type: simple
    expression: orders.total_revenue
    time_grain: month
    filters:
      - field: customer_tier
        operator: equals
        value: enterprise
    description: Monthly revenue from enterprise customers

  - name: weekly_us_signups
    type: simple
    expression: users.signup_count
    time_grain: week
    filters:
      - field: country
        operator: equals
        value: US
    description: Weekly signups from United States

Best Practices

Choose Appropriate Granularity

Match the time grain to the decision-making cadence:

Decision Type	Recommended Grain
Real-time ops	day
Weekly standup	week
Monthly review	month
Board meeting	quarter
Strategic planning	year

Document Time Boundaries

Specify how time boundaries are handled:

metrics:
  - name: weekly_active_users
    type: simple
    expression: users.active_count
    time_grain: week
    description: |
      Unique users active each ISO week.

      ## Time Boundaries
      - Week starts on Monday
      - Uses ISO 8601 week numbering
      - Partial weeks at year boundaries included

Consider Timezone Implications

Note timezone handling for time-grain metrics:

metrics:
  - name: daily_transactions
    type: simple
    expression: payments.transaction_count
    time_grain: day
    description: |
      Daily transaction count.

      ## Timezone
      All times are in UTC. Daily boundaries are midnight UTC.
    meta:
      timezone: UTC

Use Consistent Naming

Follow a naming pattern that includes the time grain:

# Good: Clear time grain in name
- name: daily_active_users
- name: weekly_signups
- name: monthly_revenue
- name: quarterly_growth

# Avoid: Ambiguous time references
- name: active_users      # Daily? Monthly?
- name: revenue_metric    # What period?

Next Steps

• Metric Types - Learn about simple, derived, and ratio metrics
• Metric Filters - Apply filters and constraints to metrics
• Time Intelligence - Advanced time-based calculations