diff --git a/website/docs/docs/build/custom-aliases.md b/website/docs/docs/build/custom-aliases.md index ee56480dc5c..4f22de63e3f 100644 --- a/website/docs/docs/build/custom-aliases.md +++ b/website/docs/docs/build/custom-aliases.md @@ -6,18 +6,22 @@ id: "custom-aliases" ## Overview -When dbt runs a model, it will generally create a relation (either a `table` or a `view`) in the database. By default, dbt uses the filename of the model as the identifier for this relation in the database. This identifier can optionally be overridden using the [`alias`](/reference/resource-configs/alias) model configuration. +When dbt runs a model, it will generally create a relation (either a or a ) in the database, except in the case of an [ephemeral model](/docs/build/materializations), when it will create a for use in another model. By default, dbt uses the model's filename as the identifier for the relation or CTE it creates. This identifier can be overridden using the [`alias`](/reference/resource-configs/alias) model configuration. ### Why alias model names? The names of schemas and tables are effectively the "user interface" of your . Well-named schemas and tables can help provide clarity and direction for consumers of this data. In combination with [custom schemas](/docs/build/custom-schemas), model aliasing is a powerful mechanism for designing your warehouse. -### Usage -The `alias` config can be used to change the name of a model's identifier in the database. The following shows examples of database identifiers for models both with, and without, a supplied `alias`. +The file naming scheme that you use to organize your models may also interfere with your data platform's requirements for identifiers. For example, you might wish to namespace your files using a period (`.`), but your data platform's SQL dialect may interpret periods to indicate a separation between schema names and table names in identifiers, or it may forbid periods from being used at all in CTE identifiers. In cases like these, model aliasing can allow you to retain flexibility in the way you name your model files without violating your data platform's identifier requirements. -| Model | Config | Database Identifier | -| ----- | ------ | ------------------- | -| ga_sessions.sql | <None> | "analytics"."ga_sessions" | -| ga_sessions.sql | {{ config(alias='sessions') }} | "analytics"."sessions" | +### Usage +The `alias` config can be used to change the name of a model's identifier in the database. The following table shows examples of database identifiers for models both with and without a supplied `alias`, and with different materializations. + +| Model | Config | Relation Type | Database Identifier | +| ----- | ------ | --------------| ------------------- | +| ga_sessions.sql | {{ config(materialization='view') }} | | "analytics"."ga_sessions" | +| ga_sessions.sql | {{ config(materialization='view', alias='sessions') }} | | "analytics"."sessions" | +| ga_sessions.sql | {{ config(materialization='ephemeral') }} | | "\__dbt\__cte\__ga_sessions" | +| ga_sessions.sql | {{ config(materialization='ephemeral', alias='sessions') }} | | "\__dbt\__cte\__sessions" | To configure an alias for a model, supply a value for the model's `alias` configuration parameter. For example: diff --git a/website/docs/docs/build/materializations.md b/website/docs/docs/build/materializations.md index eb150a2b20c..5deb1e7ce92 100644 --- a/website/docs/docs/build/materializations.md +++ b/website/docs/docs/build/materializations.md @@ -94,7 +94,8 @@ When using the `table` materialization, your model is rebuilt as a expression. +`ephemeral` models are not directly built into the database. Instead, dbt will interpolate the code from an ephemeral model into its dependent models using a common table expression (). You can control the identifier for this CTE using a [model alias](/docs/build/custom-aliases), but dbt will always prefix the model identifier with `__dbt__cte__`. + * **Pros:** * You can still write reusable logic - Ephemeral models can help keep your clean by reducing clutter (also consider splitting your models across multiple schemas by [using custom schemas](/docs/build/custom-schemas)). diff --git a/website/docs/reference/resource-configs/alias.md b/website/docs/reference/resource-configs/alias.md index 6cb14371dfa..3f36bbd0d8f 100644 --- a/website/docs/reference/resource-configs/alias.md +++ b/website/docs/reference/resource-configs/alias.md @@ -116,5 +116,7 @@ The standard behavior of dbt is: * If a custom alias is _not_ specified, the identifier of the relation is the resource name (i.e. the filename). * If a custom alias is specified, the identifier of the relation is the `{{ alias }}` value. +**Note** With an [ephemeral model](/docs/build/materializations), dbt will always apply the prefix `__dbt__cte__` to the identifier. This means that if an alias is set on an ephemeral model, then its CTE identifier will be `__dbt__cte__{{ alias }}`, but if no alias is set then its identifier will be `__dbt__cte__{{ filename }}`. + To learn more about changing the way that dbt generates a relation's `identifier`, read [Using Aliases](/docs/build/custom-aliases).