Skip to main content

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:

PurposeName
dbt model namestg_customers
Physical Snowflake objectCUSTOMERS_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_IDFIRST_NAMELAST_NAMEEMAILCUSTOMER_STATUS
10001AshaSharmaasha@example.comACTIVE
10002DanielLeedaniel@example.comACTIVE
10003MayaPatelmaya@example.comACTIVE
10004RaviKumarravi@example.comACTIVE
10006NoraTannora@example.comACTIVE

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_IDFIRST_NAMELAST_NAMEEMAILCOUNTRYCUSTOMER_STATUS
10001AshaSharmaasha@example.comINDIAACTIVE
10002DanielLeedaniel@example.comSINGAPOREACTIVE
10003MayaPatelmaya@example.comINDIAACTIVE
10004RaviKumarravi@example.comINDIAACTIVE
10006NoraTannora@example.comSINGAPOREACTIVE

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​

ConceptMeaningExample
Model namedbt model identifierstg_customers
File nameSQL file in projectstg_customers.sql
AliasPhysical database object nameCUSTOMERS_STG
SchemaWhere the object is createdBRONZE
MaterializationType of objectTABLE
ref()References a dbt modelref('stg_customers')

The one line to remember​

alias changes the physical Snowflake name; it does not change the dbt model name used by ref().