Import Your dbt Schemas as Assets

What you'll do

Run bruin import database against the schemas your dbt project materializes (e.g., *_raw, *_staging, *_reports). Bruin connects to the warehouse, reads each table's column list and types, and writes one .asset.yml per table under context/assets/.

Why this step matters

This is the heavy lifting in one command. Without it, you'd be hand-writing 40 YAML files trying to remember every column, every type, every table. With it, Bruin reads the warehouse you just built with dbt and generates the skeletons for you in seconds.

What you get out of this step is structure: tables, columns, types. The next step (AI enhance) adds the meaning: descriptions, tags, quality checks. Both halves matter — but the structure has to come from the warehouse, not from a guess.

Instructions

1. Identify your dbt schemas

You need the actual warehouse schema names. If you used the reference contoso project's schema convention, they're:

contoso_dbt_raw — what dlt loads
contoso_dbt_staging — stg_* models
contoso_dbt_reports — rpt_* models

If you're not sure what your dbt project lands as, check dbt_project.yml. The full schema name is <target.schema>_<+schema> by default, or just <+schema> if you've overridden generate_schema_name (the contoso project does).

2. Run the import

From the dbt project root, point the import at your context/ pipeline folder. The --schemas flag is repeatable for BigQuery — pass it once per schema:

bruin import database \
  --config-file context/.bruin.yml \
  --connection contoso_dbt_bq \
  --schemas contoso_dbt_raw \
  --schemas contoso_dbt_staging \
  --schemas contoso_dbt_reports \
  context

For Postgres, Redshift, or ClickHouse, use --schema (singular) once per run:

bruin import database \
  --config-file context/.bruin.yml \
  --connection contoso_dbt_pg \
  --schema contoso_dbt_staging \
  context

Note: The trailing positional argument is the pipeline path, not the project root. That's context in our setup — the directory containing pipeline.yml.

3. Inspect what was generated

ls context/assets/

You should see one folder per schema, each containing one .asset.yml per table:

context/assets/
├── contoso_dbt_raw/
│   ├── customers.asset.yml
│   ├── orders.asset.yml
│   └── ...
├── contoso_dbt_staging/
│   ├── stg_customers.asset.yml
│   └── ...
└── contoso_dbt_reports/
    ├── rpt_revenue_by_segment.asset.yml
    └── ...

Open one — they look like this:

name: contoso_dbt_reports.rpt_revenue_by_segment
type: bq.source
columns:
  - name: segment_id
    type: STRING
  - name: category_name
    type: STRING
  - name: year
    type: INT64
  - name: revenue_usd
    type: NUMERIC

No descriptions, no tags, no checks yet — just structure. That's by design. The AI enhance step in the next chapter is what fills in the meaning.

4. Filter out loader-internal tables

If your raw schema was loaded by dlt, Fivetran, or Airbyte, the import will include their bookkeeping tables. They're not useful as agent context — drop them before enhancing so Claude doesn't waste time describing _dlt_pipeline_state:

# dlt
find context/assets -name "_dlt_*.asset.yml" -delete

# Airbyte
find context/assets -name "_airbyte_*.asset.yml" -delete

# Fivetran
find context/assets -name "fivetran_*.asset.yml" -delete

Run only the one(s) that match your loader. The contoso project uses dlt, so the first command applies.

5. (Optional) Validate the structure

Even before enhancement, you can sanity-check the YAMLs:

bruin validate --config-file context/.bruin.yml context

You should see one line per asset and a summary like:

✓ Successfully validated 40 assets across 1 pipeline, all good.

If you see parse errors, re-run the import for that schema — partial files can occasionally be left behind if the introspection is interrupted.

Troubleshooting

"connection not found"

You didn't pass --config-file, so Bruin loaded a different .bruin.yml from elsewhere in the repo. Always include --config-file context/.bruin.yml.

"permission denied" / "access denied" on a schema

Your connection identity is missing read access. For BigQuery, the role is BigQuery Data Viewer on the dataset; for Postgres / Redshift, it's SELECT on the schema's tables.

Some tables are missing from context/assets/

bruin import database only writes assets for tables that exist right now. If a dbt model failed to materialize, it won't be there. Re-run dbt build, then re-run the import.

Import is slow on a large schema

Each table costs one metadata round-trip. For a few hundred tables this is still a matter of seconds; if you have thousands, consider importing one schema at a time so partial progress isn't lost on Ctrl-C.

What just happened

context/assets/ now mirrors your warehouse: one YAML per table, with column names and types pulled directly from the live database. This is the skeleton — the structural truth that the rest of the module builds on. Next we'll let Claude (or your AI of choice) fill in the descriptions, tags, and quality checks.

Import Your dbt Schemas as Assets

Learn more