Change Management

How to version your semantic layer and avoid breaking dashboards and downstream consumers.

Semantic layers break consumers when names, grains, or join paths change. Plan changes like API changes.

Breaking Change Patterns

• Renaming a model, dimension, or metric
• Changing a metric definition (filters/aggregation/grain)
• Changing relationships or keys (join paths, fan-out behavior)

Recommended Practices

• Keep a changelog for semantic layer releases.
• Add migration aliases when possible (old name → new name).
• Validate canonical queries in CI (see CI Workflow).