Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 41 ยท Sources, Seeds and Snapshots

Seeds: Version-Controlled CSV Data

Load small CSV files into your warehouse with dbt seed, reference them with ref(), set column types, quote and delimiter options, and know when seeds are the wrong tool.

Some data is small, rarely changes, and belongs to the analytics team rather than to any application: a mapping from country codes to regions, a list of test accounts to exclude, a table of marketing channel groupings. Seeds are CSV files in your project's seeds/ folder that dbt loads into the warehouse as tables. Because they live in Git, changes to them are reviewed like code.

Creating a seed

Create seeds/country_regions.csv:

TEXT
country,region,currency
Canada,North America,CAD
France,Europe,EUR
Colombia,South America,COP
Japan,Asia,JPY

Load it:

Terminal
dbt seed

dbt creates a table named after the file (country_regions), infers column types from the data, and inserts the rows. Then use it like a model, with ref():

SQL
select
    c.customer_id,
    c.full_name,
    r.region
from {{ ref('stg_shop__customers') }} c
left join {{ ref('country_regions') }} r on r.country = c.country

Seeds appear in the DAG and in the documentation, and dbt build loads them in the right order before models that depend on them. You can reproduce the effect right here by creating the table and joining it to the sample customers:

SQL A seed joined to a model ยท database: shop

Press Run (or Ctrl + Enter) to see the result here.

Customers from countries missing in the seed appear under a NULL region, which tells you the mapping file needs more rows. That is a typical use: a tiny hand-maintained lookup that enriches a model.

How dbt infers types

For each column, dbt (through the agate library) looks at the values: all integers become a number type, ISO dates become dates, true/false become booleans, anything else is text. Inference can guess wrong, for instance a ZIP code like 02134 becoming the number 2134, losing the leading zero. The fix is to declare the types explicitly:

YAML
# seeds/_seeds.yml
version: 2

seeds:
  - name: country_regions
    description: "Maps customer country to sales region and currency."
    config:
      column_types:
        country: varchar(100)
        region: varchar(50)
    columns:
      - name: country
        data_tests:
          - unique
          - not_null

Types use the warehouse's own names, so they differ by adapter (varchar, string, text...). Stand-in time: this small program (real Python, simplified) mimics the inference and shows the ZIP code problem.

Python Stand-in: type inference and the leading-zero trap

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

zip is inferred as a number and would load as 2134, so declaring zip: varchar(10) in column_types is the right fix.

Seed configuration

YAML
seeds:
  shop_analytics:
    +schema: reference          # default schema for all seeds
    country_regions:
      +column_types:
        country: varchar(100)
      +quote_columns: false     # do not quote column names
      +delimiter: ";"           # for semicolon-separated files
      +enabled: true
  • column_types sets types, as above.
  • quote_columns controls whether column names are quoted in CREATE TABLE.
  • delimiter handles CSV variants.
  • +schema puts seeds in their own schema (remember schemas are joined to the target schema by default).
  • +full_refresh: false stops --full-refresh from dropping an expensive-to-reload seed.

Running a seed

Terminal
dbt seed                              # all seeds
dbt seed --select country_regions     # one
dbt seed --full-refresh               # drop and recreate (schema changes)
dbt build --select country_regions+   # load the seed, then models that use it

When the CSV gains rows, dbt seed truncates and reloads the table. When a column is added or its type changes, use --full-refresh because the table has to be recreated.

When NOT to use a seed

Seeds are meant for small data you maintain by hand. Avoid them for:

  • Large files. Loading is done with INSERT statements, which is slow past a few thousand rows. Use your warehouse's bulk loader or a data-loading tool instead.
  • Data that changes often or comes from a system. If a person is not editing it, it is a source, not a seed.
  • Sensitive data. Everything in seeds/ goes into Git history. Never commit personal or secret data.

A decision rule: if the file is small, hand-maintained, and changes only when your team decides it should, use a seed. If it is generated by another system, load it into the warehouse and declare a source.

Seeds in tests and development

Seeds are great for test fixtures: a small CSV that holds known input rows for a model, so you can check its output against known results. Dev-only seeds can also be enabled per target using +enabled: "{{ target.name == 'dev' }}". Context functions like target are covered in the context lesson.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How do you use a seed in a model?

    Seeds are loaded as tables named after the CSV file and referenced with ref().
  2. 2. A ZIP code column loads as a number and loses its leading zero. What is the fix?

    column_types overrides type inference so the value stays text.
  3. 3. Which data is a bad fit for a seed?

    Seeds are inserted row by row and stored in Git, so they are meant for small, hand-maintained data.
  4. 4. When do you need dbt seed --full-refresh?

    Adding rows just reloads data, but structural changes require recreating the table.

Summary

  • Seeds are small CSV files in seeds/, loaded as tables by dbt seed and referenced with ref().
  • dbt infers column types; override them with column_types to avoid surprises like lost leading zeros.
  • Configure schema, delimiter and quoting in dbt_project.yml or YAML; use --full-refresh after structural changes.
  • Use seeds for small, hand-maintained lookups; use sources for system-generated or large data.

Next: Snapshots: Tracking Changing Data