What to Check When Renaming Dimensions or Measures in a Cube Model

FAQs
1

:warning: Important: Prefer title property Over Renaming (Best Practice)

If your goal is only to change how a dimension or measure appears to end users, do not rename it.

Instead, use the title property.

The title property is a non-breaking way to update display names without affecting:

  • Cube model references

  • Joins and pre-aggregations

  • Embeddable dashboards

How the title Property Works

  • name → Internal, stable identifier (used in all references)

  • title → Display label shown to end users only

cubes:
  - name: orders
    sql_table: orders

    dimensions:
      - name: customer_id
        sql: customer_id
        type: number
        title: "Customer ID"

    measures:
      - name: total_revenue
        sql: amount
        type: sum
        title: "Total Sales Revenue"

:backhand_index_pointing_right: Only rename name when a true semantic change is required.

If you must rename, follow the checklist below.

1. References Within the Same Cube

Derived measures
Check measures that reference other measures or dimensions.

measures:
  - name: profit_margin
    sql: 100.0 * ({profit} / {revenue})

Computed / filtered dimensions
Look for dimensions that reference other dimensions or measures.

dimensions:
  - name: is_completed
    sql: "{CUBE}.status = 'completed'"

2. References in Joins and Across Cubes

Join conditions
Update all join SQL that references the renamed field.

joins:
  - name: customers
    sql: "{CUBE}.customer_id = {customers}.id"

Cross-cube references
Check other cubes that reference this field.

sql: "{orders}.status"

3. Pre-Aggregation References

If the renamed field is used in a pre-aggregation, update:

  • measures

  • dimensions

  • time_dimension

  • partition_dimension

pre_aggregations:
  - name: orders_by_month
    measures: total_revenue
    dimensions: status
    time_dimension: created_at

4. Embeddable Frontend Usage

If the renamed field is used as a time dimension in an Embeddable FE component:

  • Ensure the generated query in the Embeddable Builder uses the new name

  • Otherwise, the component will error due to a stale reference

5. Testing Process

After completing the rename:

  1. Global search
    Search the entire project for the old field name to catch missed references.

  2. Direct usage tests
    Run queries that reference the renamed dimension or measure directly.

  3. Indirect dependency tests
    Test queries that rely on the renamed field indirectly (joins, derived measures, filters, pre-aggregations).