Sources and Seeds

## The line the two functions draw dbt builds a directed acyclic graph of everything in your project by parsing the Jinja function calls inside your SQL files. Two of those calls declare upstream dependencies, and choosing between them is really a question about ownership: does dbt create this table, or does dbt merely read it? - `ref('some_model')` — dbt creates it. Models, seeds and snapshots are all dbt-built nodes and all reached with `ref()`. - `source('some_source', 'some_table')` — dbt does not create it. Something else landed the data: Fivetran, Airbyte, a `COPY` command, a CDC stream, a hand-run load script. ## What source() needs before you can call it A source has to be declared before it can be referenced. In any YAML file under your models path you add a `sources:` block: ```yaml version: 2 sources: - name: jaffle_shop database: raw schema: jaffle_shop tables: - name: orders - name: customers ``` Now `{{ source('jaffle_shop', 'orders') }}` compiles to `raw.jaffle_shop.orders`. The first argument is the source name, the second is the table name. Calling `source()` with a pair that is not declared is a compilation error, not a runtime one — dbt catches it before touching the warehouse. ## What ref() needs Nothing beyond the file existing. `ref('stg_orders')` looks up the node named `stg_orders` — a `stg_orders.sql` model file, a `stg_orders.csv` seed, or a snapshot of that name — and compiles to whatever relation dbt built for it in the current target. In development that is typically your personal schema; in production it is the deployment schema. You never write the schema yourself. ## Why the indirection is worth it Three things fall out of using the functions instead of literal table names. **Ordering.** dbt does not run your files alphabetically or in the order you list them. It reads the `ref()` and `source()` calls, builds the graph, and runs each node only after its parents. Hardcode a name and dbt has no idea the dependency exists, so it will happily build a model before the table it reads. **Environment portability.** The same SQL runs against a dev schema, a CI schema and production without edits, because both functions resolve through configuration rather than literals. **Lineage and impact analysis.** Sources appear in the generated documentation and the DAG as the graph's roots. You can answer "which models break if this raw table changes?" with a selector like `dbt build --select source:jaffle_shop+`. Hardcoded names are invisible to all of that. ## Sources are declarations, not loads A common misreading is that declaring a source makes dbt fetch or create the data. It does not. dbt is a transformation tool; it issues `SELECT`-shaped SQL against tables that already exist. A source block is a promise that the table is there, plus metadata dbt can use — descriptions, tests, and freshness thresholds checked by the separate `dbt source freshness` command. ## Seeds are dbt's, so they use ref() Seeds trip people up because they feel like input data, which pattern-matches to "source". But a seed is a CSV in your repo that dbt loads with `dbt seed`; dbt creates that table, so it is a `ref()`. The rule stays clean: if `dbt build` would create the object, use `ref()`. ## The convention that follows Most teams enforce that `source()` is called exactly once per raw table, inside a thin staging model that renames and casts columns. Everything downstream uses `ref()` on that staging model. That gives you a single place to absorb a raw-schema change, and it makes a grep for `source(` a complete inventory of what the project consumes from outside. ## Failure modes to recognise Hardcoding `raw.jaffle_shop.orders` in a model compiles fine and returns rows in production, which is exactly why it survives review. It silently drops the node from the lineage graph, breaks in dev where `raw` may not be readable, and evades every `source:` selector. Calling `source()` on a table another dbt model builds is the mirror error: it splits one node into two, so dbt no longer knows the model must run first.