Import from dbt
Start from an existing dbt project instead of a blank page, and stay in step with it afterwards.
What you need#
dbt's compiled artifacts:
target/manifest.json: rundbt parsein the dbt project. It needs no warehouse connection.target/catalog.json(optional): rundbt docs generate. It adds the real column types and needs the warehouse.
Without a catalog, Strata SQL still fills in columns by reading your models' SQL; the catalog only adds the types. Manifests from dbt 0.19 up to current dbt Core and dbt Fusion are read. Strata SQL does not read dbt_project.yml or model YAML on their own, because the schema and database a model builds into come from your profile and macros. A folder without target/manifest.json is told to run dbt parse.
How to import#
- New project: Strata SQL: New Project → From a dbt project…, then the dbt folder or its
manifest.json. The platform comes from the dbt adapter. - Into the open model: Strata SQL: Import from dbt… shows a preview and writes only when you confirm.
- Re-sync later: Strata SQL: Re-sync from dbt.
- Terminal:
strata-sql import-dbt --from ./analytics --name "Jaffle Shop". Add--dry-runto list what would change and write nothing.
What is imported#
| From dbt | In Strata SQL |
|---|---|
| Models, seeds, snapshots and sources | Tables in catalogs and schemas. A view or materialized_view becomes a view with its SQL. |
| Columns | Columns with types from the catalog, descriptions, and (with no catalog) the columns your SQL selects. select * is followed through. |
| Tables read by plain name that dbt does not declare | Tables marked undeclared, so the physical tables under your raw models are in the model. |
| What each model reads | Lineage on the table. |
unique and not_null tests, contract primary keys | Primary keys and flags. |
relationships tests, contract foreign keys | Foreign-key relationships with 1..M cardinality. |
| Joins in model SQL, semantic-model entities | Relationships marked inferred in their description. |
semantic_models and metrics | Metrics on the Semantic level. |
| Aggregates in model SQL and numeric columns of tables with a foreign key | Starter metrics tagged dbt-derived, for you to review. |
tags, meta | Tags, and owner, steward, classification, criticality and lifecycle where they match. |
Re-sync: what dbt owns#
A re-sync adds what is new and updates what dbt owns (descriptions, types, view SQL, dbt_* properties, the tags it brought). It never deletes or overwrites your own modelling: keys, relationships and governance you added stay. A starter metric is made once per table, so one you edited or deleted is never touched or recreated. Every re-sync is one version per changed stream, named Sync from dbt: ..., so undo works as usual.
Strata SQL refuses a re-sync when the model differs from its version log (record the change first), when the log has an unresolved fork, and for a project split into domains.
Limits, honestly#
- Strata SQL is a reader, not dbt. SQL that macros generate can give fewer columns, never invented ones.
- Without a catalog, most column types are the generic
STRING. - Ephemeral models, installed packages, exposures, conversion metrics and saved queries are skipped and reported.
- Every import lists what it could not read as notes, never silently.
- It cannot import into a project already split by domain.