09. Aliases in Models
Aliases in Models
When dbt builds a model, the dbt model name and the physical object name in Snowflake are normally the same.
For example, if we have:
models/bronze/stg_customers.sql
dbt will normally create:
BEEMS_TECHNE_ECOMM.BRONZE.STG_CUSTOMERS
But sometimes the name we want in Snowflake needs to be different from the name we use in our dbt project.
This is where aliases are useful.
Alias allows us to separate the dbt model name from the physical table or view name created in Snowflake.
Topics Covered
- What is an Alias?
- Why do we use Aliases?
- Configuring an Alias using
config() - Alias with
ref() - Verifying an aliased model in Snowflake
- Configuring Aliases in
dbt_project.yml - Environment-specific Aliases
- Important Alias best practices
1. What is an Alias?
An alias is the physical name that dbt uses when creating the model in the target database.
Consider our BEEMS TECHNE E-Commerce project:
models/
│
├── bronze/
│ ├── stg_customers.sql
│ ├── stg_products.sql
│ └── stg_orders.sql
│
├── silver/
└── gold/
Without an alias:
stg_customers.sql
↓
dbt model name = stg_customers
↓
Snowflake object = STG_CUSTOMERS
With an alias:
stg_customers.sql
↓
dbt model name = stg_customers
↓
alias = CUSTOMERS_STG
↓
Snowflake object = CUSTOMERS_STG
So there are two different names:
| Purpose | Name |
|---|---|
| dbt model name | stg_customers |
| Physical Snowflake object | CUSTOMERS_STG |
2. Why Would We Use an Alias?
In a well-designed dbt project, we normally want meaningful model names.
For example:
stg_customers.sql
int_order_details.sql
fct_orders.sql
dim_customers.sql
These names tell developers what the model represents and where it belongs in the transformation pipeline.
However, the physical Snowflake object may need to follow a different naming standard.
For example, an organization might require:
CUSTOMERS_STG
ORDERS_STG
ORDER_DETAILS_INT
ORDERS_FCT
CUSTOMERS_DIM
Instead of:
STG_CUSTOMERS
STG_ORDERS
INT_ORDER_DETAILS
FCT_ORDERS
DIM_CUSTOMERS
We can keep the clean dbt project structure while using the required physical names in Snowflake.
3. Configuring an Alias with config()
The simplest way to define an alias is inside the model using the config() block.
Let's use our CUSTOMERS source table.
Create:
models/bronze/stg_customers.sql
{{ config(
materialized='table',
alias='CUSTOMERS_STG'
) }}
SELECT
CUSTOMER_ID,
FIRST_NAME,
LAST_NAME,
EMAIL,
COUNTRY,
CREATED_AT,
UPDATED_AT,
CUSTOMER_STATUS
FROM {{ source('ecommerce_raw', 'customers') }}
Notice the important part:
alias='CUSTOMERS_STG'
4. What Happens When We Run dbt?
The dbt model is:
stg_customers
But the alias is:
CUSTOMERS_STG
Therefore, dbt creates:
BEEMS_TECHNE_ECOMM
│
└── BRONZE
│
└── CUSTOMERS_STG
The important point is:
The filename remains
stg_customers.sql. Only the physical database object name changes.
5. Run the Model
Run:
dbt run --select stg_customers
Expected result:
1 of 1 OK created table model bronze.CUSTOMERS_STG
The exact dbt output can vary slightly depending on the dbt version and configuration.
6. Verify the Alias in Snowflake
Now go to Snowflake and verify the physical object.
SELECT
CUSTOMER_ID,
FIRST_NAME,
LAST_NAME,
EMAIL,
CUSTOMER_STATUS
FROM BEEMS_TECHNE_ECOMM.BRONZE.CUSTOMERS_STG
ORDER BY CUSTOMER_ID;
Expected sample output
| CUSTOMER_ID | FIRST_NAME | LAST_NAME | CUSTOMER_STATUS | |
|---|---|---|---|---|
| 10001 | Asha | Sharma | asha@example.com | ACTIVE |
| 10002 | Daniel | Lee | daniel@example.com | ACTIVE |
| 10003 | Maya | Patel | maya@example.com | ACTIVE |
| 10004 | Ravi | Kumar | ravi@example.com | ACTIVE |
| 10006 | Nora | Tan | nora@example.com | ACTIVE |
Notice that Snowflake contains:
CUSTOMERS_STG
and not:
STG_CUSTOMERS
even though our dbt file is:
stg_customers.sql
7. Alias Does Not Change the dbt Model Name
This is one of the most important concepts to understand.
Our model is still called:
stg_customers
The alias only changes the physical database object name.
Therefore, if another model needs to use stg_customers, we continue to use:
{{ ref('stg_customers') }}
We do not use:
{{ ref('CUSTOMERS_STG') }}
8. Using ref() with an Aliased Model
Suppose we create:
models/silver/int_customer_orders.sql
We can write:
SELECT
o.ORDER_ID,
o.CUSTOMER_ID,
c.FIRST_NAME,
c.LAST_NAME,
o.ORDER_DATE,
o.ORDER_STATUS
FROM {{ ref('stg_orders') }} o
INNER JOIN {{ ref('stg_customers') }} c
ON o.CUSTOMER_ID = c.CUSTOMER_ID
Notice:
{{ ref('stg_customers') }}
Even though Snowflake actually contains:
BRONZE.CUSTOMERS_STG
dbt knows how to resolve the reference.
Conceptually:
{{ ref('stg_customers') }}
↓
dbt resolves model
↓
alias = CUSTOMERS_STG
↓
BEEMS_TECHNE_ECOMM.BRONZE.CUSTOMERS_STG
This is one of the major benefits of using ref().
Developers work with dbt model names, while dbt manages the physical database names.
9. What Happens If We Use the Alias in ref()?
This is incorrect:
FROM {{ ref('CUSTOMERS_STG') }}
Why?
Because CUSTOMERS_STG is the physical database name, not the dbt model name.
The dbt model is:
stg_customers
Therefore:
{{ ref('stg_customers') }}
is correct.
10. Alias and Materialization
Alias and materialization are two different concepts.
Alias
Controls:
What is the physical object called?
alias='CUSTOMERS_STG'
Materialization
Controls:
What type of database object does dbt create?
materialized='table'
For example:
{{ config(
materialized='table',
alias='CUSTOMERS_STG'
) }}
creates:
BRONZE.CUSTOMERS_STG
as a table.
Whereas:
{{ config(
materialized='view',
alias='CUSTOMERS_STG'
) }}
creates:
BRONZE.CUSTOMERS_STG
as a view.
So remember:
materialized → TABLE / VIEW / INCREMENTAL / EPHEMERAL
alias → Physical object name
11. Alias in dbt_project.yml
Aliases can also be configured through dbt_project.yml.
For example:
models:
beems_techne_ecomm_dbt:
bronze:
+schema: BRONZE
However, unlike materialization or schema configuration, aliases are usually more useful when applied to individual models, because every model generally needs a different physical name.
For example:
stg_customers.sql → CUSTOMERS_STG
stg_products.sql → PRODUCTS_STG
stg_orders.sql → ORDERS_STG
Therefore, for beginners, the model-level approach is easier to understand:
{{ config(
alias='CUSTOMERS_STG'
) }}
Later, we can introduce project-level configuration and macros for more advanced naming strategies.
12. Environment-Specific Aliases
Aliases can also be generated dynamically using Jinja.
For example:
{{ config(
materialized='table',
alias='ORDERS' if target.name == 'prod'
else 'ORDERS_DEV'
) }}
SELECT *
FROM {{ source('ecommerce_raw', 'orders') }}
Now the physical name can depend on the target environment.
Production
target.name = prod
↓
ORDERS
Development
target.name = dev
↓
ORDERS_DEV
This can be useful when different environments have different naming requirements.
However, environment-specific aliases should be introduced as an advanced technique. In most projects, environment separation is better handled through database/schema configuration rather than creating lots of environment-specific object names.
13. Alias vs ref()
This is the key concept from this lesson:
┌─────────────────────────────┐
│ dbt Project │
│ │
│ stg_customers.sql │
│ │
│ Model name: stg_customers │
└──────────────┬──────────────┘
│
│ alias
▼
┌─────────────────────────────┐
│ Snowflake │
│ │
│ BRONZE.CUSTOMERS_STG │
└─────────────────────────────┘
Downstream models use:
{{ ref('stg_customers') }}
not:
{{ ref('CUSTOMERS_STG') }}
dbt handles the translation.
14. Best Practices
1. Don't use aliases unnecessarily
If your naming convention is already good:
stg_customers.sql
↓
BRONZE.STG_CUSTOMERS
there may be no need for an alias.
2. Use aliases when there is a genuine naming requirement
For example:
Legacy system expects:
CUSTOMERS_STG
dbt developer-friendly name:
stg_customers
An alias is appropriate.
3. Keep ref() using the dbt model name
Always:
{{ ref('stg_customers') }}
Not:
{{ ref('CUSTOMERS_STG') }}
4. Don't confuse alias with schema
These are different:
{{ config(
schema='BRONZE',
alias='CUSTOMERS_STG'
) }}
Conceptually:
schema → BRONZE
alias → CUSTOMERS_STG
result → BRONZE.CUSTOMERS_STG
15. Hands-On Exercise
Modify your existing:
models/bronze/stg_customers.sql
to use:
{{ config(
materialized='table',
alias='CUSTOMERS_STG'
) }}
Then run:
dbt run --select stg_customers
Snowflake verification
SELECT *
FROM BEEMS_TECHNE_ECOMM.BRONZE.CUSTOMERS_STG
LIMIT 5;
Expected output
| CUSTOMER_ID | FIRST_NAME | LAST_NAME | COUNTRY | CUSTOMER_STATUS | |
|---|---|---|---|---|---|
| 10001 | Asha | Sharma | asha@example.com | INDIA | ACTIVE |
| 10002 | Daniel | Lee | daniel@example.com | SINGAPORE | ACTIVE |
| 10003 | Maya | Patel | maya@example.com | INDIA | ACTIVE |
| 10004 | Ravi | Kumar | ravi@example.com | INDIA | ACTIVE |
| 10006 | Nora | Tan | nora@example.com | SINGAPORE | ACTIVE |
Then create a downstream model and reference it using:
{{ ref('stg_customers') }}
This demonstrates the complete concept:
DBT
│
▼
stg_customers.sql
│
│ alias
▼
CUSTOMERS_STG
│
▼
Snowflake
│
▼
{{ ref('stg_customers') }}
Summary
| Concept | Meaning | Example |
|---|---|---|
| Model name | dbt model identifier | stg_customers |
| File name | SQL file in project | stg_customers.sql |
| Alias | Physical database object name | CUSTOMERS_STG |
| Schema | Where the object is created | BRONZE |
| Materialization | Type of object | TABLE |
ref() | References a dbt model | ref('stg_customers') |
The one line to remember
aliaschanges the physical Snowflake name; it does not change the dbt model name used byref().