Migrate from dbt Semantic Layer

What to export from a dbt project, how dbt semantic models and MetricFlow metrics map to Malloy, and how to rebuild them with the modeling agent while dbt keeps building the tables, for analytics engineers who maintain a dbt project

dbt Semantic Layer definitions (semantic models and MetricFlow metrics) move into Credible through the modeling agent. The agent reads the YAML as reference material and drafts the Malloy model from it, checking its proposals against your data. Expect to review the translations more closely than for Looker or Power BI, which have dedicated skills.

You don't have to change your dbt transformations. The Malloy model reads the tables dbt builds, the same way the semantic layer does.

Comparing the two products first? See Credible vs. dbt.

What to Export

  • Semantic models and metrics: the YAML files in your dbt project that contain semantic_models:, metrics: and saved_queries:. The source YAML is the best input, because it keeps each expr, filter and agg_time_dimension.
  • Model documentation: the schema.yml files with model and column descriptions, which are useful for #(doc) tags.
  • Optional: target/semantic_manifest.json after dbt parse, if the semantic layer YAML is generated or spread across packages.

How dbt Concepts Map to Malloy

dbtMalloyNotes
Semantic model with model: ref('fct_orders')source: over the table dbt builds
Primary entityprimary_key:
Foreign entityjoin_one: to the source whose primary entity matches
Categorical dimensiondimension:
Time dimension with time_granularityA date or timestamp field, truncated with .day, .month, .year
Measure agg: sum, average, min, maxsum(), avg(), min(), max()
agg: countcount(), or count() { where: field is not null }Check which one the expr intends
agg: count_distinctcount(field)count(field) is distinct in Malloy
agg: sum_booleancount() { where: condition }
Simple metricThe measure itselfNo second field needed
Metric filter (Jinja)measure { where: condition }
Ratio metricOne measure divided by another
Derived metricAn expression over other measuresResolve the chain of metrics first
Cumulative metricA calculate: window function such as sum_cumulative() in a query, or a filtered aggregate over a date range
metric_timeA specific date field chosen per queryMalloy has no shared time dimension
Conversion metricReview by handUsually a query-based source
Saved queryA named view:
description#(doc) tag

Steps

  1. Set up a local modeling directory with cred init (Cred CLI). Copy the semantic layer YAML into a subfolder such as dbt/ and add it to .credignore.
  2. Ask the agent to build the model, naming the folder and the domain: "Build a model of our orders domain using the dbt semantic models and metrics in dbt/ as prior art."
  3. Review the proposed sources, joins and fields. Check that each metric that only renamed a measure became one field, not two.
  4. Compare the key metrics with the same grain and filters, as described in Prove Parity. MetricFlow generates the SQL on the dbt side, so its result is the number to match.
  5. Publish.

What Needs Manual Review

  • metric_time and the time spine. Choose the date field each metric should use. Metrics that relied on the time spine to fill empty periods need a deliberate approach.
  • Cumulative and conversion metrics. Check each one at the grains people query.
  • Join paths. MetricFlow builds joins from entities at query time. In Malloy the joins are declared on the source, so confirm each one and its cardinality.
  • Transformations in the semantic layer. If an expr holds substantial SQL, decide whether it belongs in a dbt model instead.
  • Access control. Re-create any restrictions with access rules.

Next Steps

On this page