How to align Looker and dbt so metric definitions are consistent across both — the LookML-on-dbt-sources pattern, using dbt documentation in Looker, the dbt Semantic Layer as an alternative to LookML, and the governance approach that prevents metric definitions from diverging between the transformation layer and the BI layer.
Looker and dbt are the two most commonly paired tools in modern analytics stacks. Looker provides the BI layer; dbt provides the transformation layer. When they work well together, metric definitions are consistent — a revenue figure in Looker matches the revenue figure in dbt documentation because both derive from the same dbt model. When they work poorly, metric definitions diverge — LookML defines revenue one way, a dbt model defines it differently, and analysts get different answers depending on which tool they use.
This guide covers the architecture that keeps Looker and dbt consistent — LookML built on dbt sources, documentation alignment, and the dbt Semantic Layer as a more explicit alternative.
LookML Built on dbt Models
The foundational integration principle: Looker's LookML should reference dbt models (the transformed, documented tables in the analytics schema) rather than raw source tables. This ensures that:
- Business logic (metric calculations, joins, filters) is applied once, in dbt, and surfaced to Looker as a clean table
- Looker views are thin — they describe dimensions and measures against an already-modelled table, not replicate transformation logic
- When business logic changes, the change is made in dbt; LookML views that reference the dbt model automatically pick up the change
A LookML view built on a dbt mart model:
view: fct_orders {
sql_table_name: analytics.fct_orders ;;
dimension: order_id {
type: string
primary_key: yes
sql: ${TABLE}.order_id ;;
}
dimension_group: order_date {
type: time
timeframes: [date, week, month, quarter, year]
sql: ${TABLE}.order_date ;;
}
measure: total_revenue {
type: sum
sql: ${TABLE}.revenue ;;
value_format: "$#,##0.00"
}
}
The sql_table_name references the dbt-managed fct_orders table in the analytics schema. The LookML view does not duplicate joins or calculations — those are already applied in the dbt model.
**Avoid raw source tables in LookML.** If a LookML view references a raw Salesforce table (e.g., salesforce.opportunity) rather than the dbt-transformed model (analytics.dim_opportunities), business logic encoded in dbt (status normalisation, deletion filtering, currency conversion) is bypassed. Any analysis built from that LookML view uses raw, ungoverned data.
**Schema reference management.** dbt can deploy models to different schemas depending on environment (development, staging, production). LookML's sql_table_name must reference the production schema. Use Looker's liquid variables or constants to manage environment differences rather than hardcoding schema names:
constant: dbt_schema {
value: "analytics"
}
sql_table_name: "@{dbt_schema}.fct_orders" ;;
Consistent Metric Definitions
The most common point of Looker-dbt divergence is metric definition. If dbt defines revenue as:
sum(case when status = 'completed' AND refund_date is null then amount else 0 end) as revenue
And a LookML measure defines it as:
measure: revenue {
type: sum
sql: ${amount} ;;
}
The two definitions produce different numbers. The dbt version excludes non-completed orders and refunded orders; the LookML version includes everything.
To prevent this divergence:
**Define measures in LookML using dbt's pre-aggregated values where possible.** If a metric is complex (requires multiple conditions, multiple joins), compute it as a column in the dbt model rather than deriving it from raw columns in LookML. The LookML measure then sums a pre-computed column:
measure: revenue {
type: sum
sql: ${TABLE}.net_revenue ;; -- pre-computed in dbt
}
**Document the definition in both places.** dbt column documentation in schema.yml and LookML field descriptions should match. A reader of the LookML description should see the same business definition as a reader of the dbt documentation. If they differ, the definitions have diverged.
**Cross-reference dbt documentation in LookML.** Link to the dbt documentation from LookML field descriptions:
measure: revenue {
description: "Net revenue excluding cancellations and refunds. See dbt docs: analytics/fct_orders/net_revenue"
...
}
Using dbt Documentation in LookML
dbt generates a JSON documentation artifact (manifest.json and catalog.json) that describes every model, column, and test in the project. Several tools use this artifact to auto-populate LookML with documentation from dbt:
**dbt-looker** (open source) reads the dbt manifest and generates LookML view files from dbt models. The generated LookML includes dimension and measure definitions from dbt column documentation. This eliminates manual duplication — the dbt column description becomes the LookML field description automatically.
**Lightdash** takes this further — it is a Looker-like BI tool that reads dbt models directly and exposes them as an analytics layer. Metrics defined in dbt YAML are automatically available as measures in Lightdash. For organisations considering a BI tool replacement alongside a dbt implementation, Lightdash is worth evaluating.
The dbt Semantic Layer
The dbt Semantic Layer (powered by MetricFlow, available in dbt Cloud) is a more explicit integration between dbt and BI tools than the LookML-on-dbt-models pattern. Rather than encoding metric definitions in both dbt and LookML, the Semantic Layer encodes them once in dbt YAML and exposes them via a consistent SQL interface that any connected BI tool can query.
A metric defined in dbt YAML:
metrics:
- name: revenue
label: Net Revenue
model: ref('fct_orders')
description: "Revenue excluding cancellations and refunds"
type: simple
type_params:
measure:
name: revenue
agg: sum
expr: net_revenue
filter: |
{{ Dimension('order__status') }} = 'completed'
AND {{ Dimension('order__refund_date') }} is null
A BI tool connected to the dbt Semantic Layer can query this metric by name without knowing the underlying SQL. Looker supports the dbt Semantic Layer as a data connection type — LookML views can reference dbt Semantic Layer metrics rather than raw SQL.
**When the Semantic Layer creates value:** When multiple BI tools (Looker, Hex, Streamlit, Tableau via JDBC) need to share the same metric definitions. Rather than encoding the definition separately in each tool, the Semantic Layer provides a single source of truth. A change to the revenue definition propagates to all connected tools.
**When the Semantic Layer adds unnecessary complexity:** When there is only one BI tool. If the entire analytics layer is Looker, LookML is already a semantic layer. Adding the dbt Semantic Layer creates an additional abstraction without the multi-tool benefit.
Governance: Preventing Divergence Over Time
The technical integration is the easier part. The governance challenge is preventing the Looker and dbt definitions from diverging as both environments evolve.
**Change management process:** When a dbt model changes (column removed, calculation modified, table renamed), the change must be reflected in the LookML views that reference it. The connection is implicit — Looker does not automatically detect that an upstream dbt model changed. Establish a process: when a dbt model is changed, the analytics engineer identifies the Looker views that reference it and updates them in the same PR.
**LookML code review that includes dbt review.** A PR that changes a LookML measure definition should require review from the analytics engineer who owns the dbt model. This catches the case where a LookML developer creates a measure definition that conflicts with the dbt documentation.
**Regular metric consistency audit.** Every quarter, run a comparison of key business metrics (revenue, orders, customer count) as defined in dbt models versus as computed from the Looker explore. Discrepancies surface definition divergence before it affects a business decision.
The Looker-dbt integration is most powerful when it is deliberately designed and consistently governed. The technical pieces — LookML on dbt models, shared documentation, optional Semantic Layer — create the foundation. Governance prevents the foundation from eroding as both systems evolve.
Our data architecture consulting and BI strategy practice designs consistent semantic layers across dbt and BI tools — contact us to discuss your analytics architecture requirements.
A former Microsoft data architect audits your data foundation, identifies your top priorities, and sends you a written plan. Free. No pitch.
Book a Call →