Managing Seeds

Seeds are CSV files that live in your dbt project, typically containing static data that doesn't change frequently. They provide a convenient way to incorporate reference data, mapping tables, or small datasets directly into your dbt workflow.


What Are Seeds?

Seeds are CSV files stored in your dbt project's seeds/ directory that dbt loads into your data warehouse. They become part of your version-controlled project and are accessible in models via the ref() function, just like any other model.

Seeds work best for data that changes infrequently, is relatively small in size, benefits from version control, and doesn't require complex transformations before use.


Common Use Cases for Seeds

Reference and Mapping Tables

Seeds are ideal for relatively static reference data such as country codes, currency conversion rates, product categorizations, department hierarchies, and calendar dimensions like fiscal years or holidays.

Configuration Tables

Use seeds as configuration tables for your transformations, including parameter tables, inclusion/exclusion lists, feature toggles, metric definitions, and valid value lists.

Test Data

Seeds provide a convenient way to manage test datasets, including sample customer profiles, test transactions, and expected results for complex calculations.


Creating and Using Seeds

Adding a Seed to Your Project

To add a seed to your project:

  1. Create a CSV file with headers in the first row

  2. Save it in your project's seeds/ directory

  3. Ensure the file uses proper CSV formatting (commas as delimiters, proper escaping)

Example seeds/country_codes.csv:

country_code,country_name
US,United States
CA,Canada
MX,Mexico
UK,United Kingdom
DE,Germany

Loading Seeds into Your Warehouse

Run the seed command to load all seeds into your data warehouse:

dbt seed

Or load a specific seed:

dbt seed --select country_codes

Referencing Seeds in Models

Reference seeds in your models using the ref() function, just like you would with models:

select
  customer_id,
  customer_country_code,
  cc.country_name
from {{ ref('customers') }}
left join {{ ref('country_codes') }} as cc
  on customers.country_code = cc.country_code

Configuring Seeds

Basic Configuration

Configure seeds in your dbt_project.yml file:

seeds:
  my_project:
    country_codes:
      +column_types:
        country_code: varchar(2)
        country_name: varchar(100)
    +schema: reference_data

Advanced Configuration Options

Configuration
Purpose
Example

Column Types

Explicitly define data types for columns

+column_types: amount: float transaction_date: date

Schema Placement

Control which schema seeds are loaded into

+schema: reference_data

Quote Policies

Manage identifier quoting for columns and seed names

+quote_columns: true


Best Practices for Using Seeds

When to Use Seeds (and When Not To)

Use seeds when
Consider alternatives when

The dataset is small (generally <10,000 rows)

The dataset is large

Data changes infrequently

Data requires frequent updates

Version control is beneficial

Complex transformations are needed

The team needs to collaborate on reference data

External systems manage the authoritative version


Performance Considerations

Keep seeds small to avoid version control and build time issues. Use appropriate column types to optimize storage and be mindful of dependencies on seeds throughout your project. For larger datasets or frequently changing data, consider alternatives to seeds.

Seed File Size Limits

While there's no hard limit on seed file size, large CSV files (>1MB) can cause performance issues and version control challenges. For larger datasets, consider using external data loading tools, creating a source table instead, or splitting the data into multiple smaller seed files.

Maintenance Strategies

Document the purpose of each seed and establish clear ownership for seed maintenance. Create processes for updating seeds and consider automation for seeds that change more frequently but still warrant being included in your project.


Seeds in Paradime

Paradime enhances the seed experience with visual CSV editing, data previews, version history tracking, and simplified update workflows.

Rainbow CSV Integration

Paradime integrates Rainbow CSV, which makes seed file management more efficient through:

  • Color-coded columns for easier reading

  • Visual alignment of CSV data

  • Multi-cursor column editing

  • Automatic CSV format validation

For more details, see our Rainbow CSV documentation.

Last updated

Was this helpful?