source() vs ref()
As you build your dbt pipelines, you will constantly write FROM clauses in your SQL models.
You must never hardcode a table name in a FROM clause (e.g., FROM BEEMS_PROD.RAW.customers). Instead, you must use one of dbt's two core Jinja functions: source() or ref().
Understanding exactly when to use which function is fundamental to mastering dbt.
Topics Covered
- The
source()Function - The
ref()Function - The Golden Rule
1. The source() Function
The source() function is used to reference data that dbt did not create.
Think of a "source" as the starting point of your pipeline. This is raw data that was loaded into your data warehouse (e.g., Snowflake) by a third-party ingestion tool like Fivetran, Airbyte, Snowpipe, or an AWS Lambda function.
dbt's job is to read this data, not to build it.
Syntax
The source() function takes two arguments:
- The name of the source system (defined in your
sources.yml) - The name of the specific table
-- Querying raw data loaded by Fivetran from Salesforce
SELECT
customer_id,
customer_name
FROM {{ source('salesforce_crm', 'customers') }}
Lineage Implications
When you use source(), the table appears as a green node at the very far left of your dbt Lineage Graph. It signifies the absolute beginning of your transformation DAG (Directed Acyclic Graph).
2. The ref() Function
The ref() function is used to reference data that dbt created.
If you ran a dbt run command to build a model, or a dbt seed command to build a seed file, you must use ref() to query it.
Syntax
The ref() function takes only one argument: the name of the model or seed file (without the .sql or .csv extension).
-- Querying a staging model that dbt built
SELECT
customer_id,
customer_name
FROM {{ ref('stg_salesforce_customers') }}
Notice that you do not specify the schema! If developer Arjun runs this code locally, dbt compiles {{ ref('stg_salesforce_customers') }} into DEV_ARJUN.STAGING.stg_salesforce_customers. If the production orchestrator runs it, dbt compiles it into BEEMS_PROD.STAGING.stg_salesforce_customers. This dynamic resolution is the entire point of ref().
Lineage Implications
When you use ref(), it creates a dependency line between two models in your DAG. If fct_orders uses ref('stg_orders'), dbt knows it must build stg_orders first.
3. The Golden Rule
To summarize, memorize this Golden Rule:
Did dbt build the table?
- NO (It was loaded by Fivetran/Snowpipe) → Use
{{ source('system', 'table') }}- YES (It's a
.sqlmodel or a.csvseed) → Use{{ ref('model_name') }}
A Complete Example
Let's look at a typical model (fct_deliveries.sql) for an Indian logistics company that uses both functions.
WITH raw_tracking_data AS (
-- This data is streamed in by Apache Kafka. dbt did not build it!
SELECT * FROM {{ source('kafka_stream', 'delivery_tracking') }}
),
pincode_mapping AS (
-- This is a CSV seed file. We ran `dbt seed` to build it.
SELECT * FROM {{ ref('indian_pincodes') }}
),
staged_orders AS (
-- This is an upstream dbt model. We ran `dbt run` to build it.
SELECT * FROM {{ ref('stg_orders') }}
)
SELECT
o.order_id,
p.state_name,
t.delivery_status
FROM staged_orders o
JOIN pincode_mapping p ON o.pincode = p.pincode
LEFT JOIN raw_tracking_data t ON o.order_id = t.order_id
Summary
source(): Used for raw data ingested by external tools. It creates the starting nodes in your DAG.ref(): Used for models and seeds managed by dbt. It establishes dependencies and handles dynamic schema resolution.- Never hardcode schemas in your
FROMclauses; always use one of these two functions.