Semantic Layer as Code

Semantic layer as code means managing metric definitions, dimension relationships, and business logic in version-controlled files rather than in a GUI. The semantic layer lives in a Git repository alongside dbt models and infrastructure configs. Changes go through pull requests, code reviews, and CI/CD pipelines – the same workflow that governs every other piece of production software.

This approach treats the semantic layer as an engineering artifact rather than a configuration setting.

What lives in code

A code-defined semantic layer typically consists of structured files – YAML, LookML, AML, or a similar domain-specific language – that declare:

• Metrics: calculation logic, aggregation type, filters, and dimensional constraints.
• Dimensions: column mappings, display labels, descriptions, and allowed values.
• Relationships: join paths between tables, fan-out handling, and grain specifications.
• Access policies: who can query which metrics, row-level security rules, and data masking.

Each file maps to a specific domain or data model. A revenue.yml file might define all revenue-related metrics. A customers.aml file might define the customer dimension table and its relationships. The file structure mirrors the logical structure of the business.

Why code over GUI

GUI-based semantic layer management works early on. A small team clicks through a configuration interface, sets up a few metrics, and moves quickly. The problem surfaces at scale.

Audit trails. Git tracks every change – who modified the revenue definition, when, and why. GUI tools may log changes, but rarely with the granularity or searchability of a commit history.

Code review. When a junior analyst redefines "active customer" to include trial users, a reviewer catches it before the change reaches production. GUI-based changes often take effect immediately, with no approval step.

Rollback. A bad metric definition ships on Tuesday. With code, you revert the commit. With a GUI, you reconstruct the previous state from memory or hope the tool has a version history feature.

CI/CD validation. Automated tests can verify that metric definitions parse correctly, that join paths resolve without fan-out, and that new metrics don't conflict with existing ones – all before merging. GUI-based tools rarely support this level of pre-deployment validation.

Environment promotion. Code-based definitions move through dev, staging, and production environments using the same branching and merging patterns as application code. GUI changes are typically made directly in production.

Build with clicks, maintain with code

A pragmatic operating model combines both approaches. Business users and analysts prototype metrics through a visual interface – clicking through join builders, testing aggregation logic, previewing results. Once the metric is validated, the definition gets committed to code and enters the governed workflow.

This model respects two realities: exploration is faster with a GUI, and governance is stronger with code. The transition point – from prototype to production – is where discipline matters.

Tool support

Several tools support code-based semantic layer definitions:

• LookML (Looker): The original code-based semantic layer. All model definitions live in .lkml files within a Git repository. Looker's IDE provides a hybrid experience – edit in the browser, commit to Git.
• AML (Holistics): A modeling language with full Git integration, supporting metric composition, cross-model references, and reusable templates.
• dbt YAML metrics (dbt + Lightdash/MetricFlow): Metric definitions in YAML files alongside dbt model definitions. Tightly integrated with the transformation layer.
• Cube.js: JavaScript or YAML-based schema files defining measures, dimensions, and joins, version-controlled and deployable through standard CI pipelines.

Each approach has different expressiveness and ergonomics, but they share the core principle: the semantic layer is a codebase rather than a configuration panel.

The shift to code also strengthens data contracts. When metric definitions are versioned and reviewable, they function as explicit agreements between data producers and consumers – breaking changes become visible before they reach production.