Organizing Lightdash Metrics at Scale

Lightdash provides three tools for navigating large metric implementations: sidebar groups, the Metrics Catalog with Spotlight categories, and parameters for values that change across deployments.

Groups are collapsible sections in the Explore sidebar. Users see “Revenue” and “Operations” instead of a flat alphabetical list of 40 fields. Defining groups is a two-step process: declare the groups on the model, then assign fields to them.

Declaring group_details

The group_details block at the model level defines the available sections and their labels:

models:
  - name: mrt__sales__orders
    meta:
      group_details:
        revenue:
          label: "Revenue"
          description: "All revenue-related metrics and dimensions"
        operations:
          label: "Operations"
          description: "Fulfillment, shipping, and status fields"
        customer:
          label: "Customer"

The description is optional but shows as a tooltip when users hover over the group name. It’s useful when group labels are broad or when a group’s scope needs clarification.

Groups support up to two levels of nesting. A top-level group can contain sub-groups, which creates a hierarchy in the sidebar. In practice, two levels is plenty — three or more levels is a sign that the model has grown too large and should be split into separate models.

Assigning Fields to Groups

Once groups are declared, assign individual dimensions and metrics with the groups property:

    meta:
      group_details:
        revenue:
          label: "Revenue"
        operations:
          label: "Operations"
      metrics:
        average_order_value:
          type: number
          sql: "${total_revenue} / NULLIF(${total_orders}, 0)"
          groups: ["revenue"]
    columns:
      - name: order__revenue
        meta:
          dimension:
            groups: ["revenue"]
          metrics:
            total_revenue:
              type: sum
              groups: ["revenue"]
      - name: order__status
        meta:
          dimension:
            groups: ["operations"]
      - name: order__created_at
        meta:
          dimension:
            groups: ["operations"]
            time_intervals: ['DAY', 'WEEK', 'MONTH', 'QUARTER', 'YEAR']

Fields without a groups assignment appear at the top of the sidebar, ungrouped. If most fields have groups, ungrouped fields stand out as things that haven’t been organized yet — a useful signal during setup.

The groups value is a list, so a field can appear in multiple groups. Use this sparingly. A lifetime_value metric that belongs in both “Revenue” and “Customer” groups is reasonable. Over-assigning fields to multiple groups defeats the purpose of grouping.

The Metrics Catalog and Spotlight

The Metrics Catalog (shipped January 2025) provides a cross-model searchable view of all your metrics. Users browse by name, search by keyword, and see descriptions and owners without needing to know which model a metric lives on. It’s the front door for users who know what they want to measure but don’t know where to find the metric.

Spotlight categories add color-coded labels to models in the Catalog, configured in lightdash.config.yml at the project root:

spotlight:
  categories:
    - name: Revenue
      color: orange
      models: [mrt__sales__orders, mrt__sales__subscriptions]
    - name: Marketing
      color: blue
      models: [mrt__marketing__campaigns, mrt__marketing__ad_spend]
    - name: Product
      color: green
      models: [mrt__product__events, mrt__product__features]
    - name: Finance
      color: purple
      models: [mrt__finance__invoices, mrt__finance__expenses]

In the Catalog, each model gets a colored badge based on its category. Users who “work in marketing” can filter to the blue badge and immediately see their domain’s metrics without scrolling past revenue or product models.

Spotlight is configured at the project level rather than the model level because categories often cut across models. Revenue might span sales, subscriptions, and refunds models. Marketing might include campaign performance and website traffic. The project-level config lets you define these cross-model groupings without changing individual model YAML.

Naming Conventions for Discoverability

The Catalog is only as useful as the names and descriptions feeding it. Consistent naming conventions matter here for the same reason they matter in MetricFlow: users search, and search only works if names follow predictable patterns.

Keep names in snake_case: total_revenue, unique_customers, average_order_value. Use label for the human-readable display name with units and context that would be awkward in a code identifier:

metrics:
  total_revenue:
    type: sum
    label: "Total Revenue (EUR)"
    description: >
      Sum of order revenue after discounts, in euros.
      Includes completed and partially-refunded orders.
      Excludes cancelled and pending orders.

Descriptions in the Catalog are not truncated — write them to be read. Include what the metric measures, what it excludes, and any limitations or caveats. Six months from now, a new analyst will rely on that description to understand whether this metric is the right one for their analysis.

Parameters

Parameters handle values that change across environments or deployments. A development deployment might use a different currency symbol, a different date threshold for “recent” data, or a different default time zone than production. Without parameters, these values get hardcoded in YAML, and every environment change requires a find-and-replace across multiple files.

Parameters are defined in lightdash.config.yml and referenced in model YAML:

parameters:
  currency_symbol:
    default: "€"
  revenue_threshold:
    default: "500"
  fiscal_year_start:
    default: "01-01"

Reference them in metric or dimension definitions with ${ld.parameters.parameter_name}:

metrics:
  total_revenue:
    type: sum
    label: "${ld.parameters.currency_symbol} Total Revenue"
    format: '[${ld.parameters.currency_symbol}]#,##0.00'
  high_value_orders:
    type: count_distinct
    filters:
      - field: order__revenue
        operator: greater_than
        value: "${ld.parameters.revenue_threshold}"

Parameters are resolved at deploy time, not query time, so they’re appropriate for environment-specific configuration but not for user-specific or query-specific values. For row-level filtering based on the current user, Lightdash’s user attributes feature handles that separately.

Incremental Adoption

Groups, Spotlight, and parameters address distinct scaling problems and can be adopted independently:

Groups become useful around 20+ fields on a single model, when the sidebar becomes hard to navigate.
Spotlight becomes useful with more than five or six models visible in the Explore view.
Parameters are needed when multiple deployment environments require different hardcoded values across YAML files.

Sidebar Groups