Skip to main content

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:

  1. The name of the source system (defined in your sources.yml)
  2. 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 .sql model or a .csv seed) → 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 FROM clauses; always use one of these two functions.