Update docs to clarify the way aliases are used in CTEs (#5795)

## What are you changing in this pull request and why?

This PR updates the docs to reflect the bugfix made in
dbt-labs/dbt-core#10290 and
dbt-labs/dbt-adapters#236 to bring the
identifiers used for CTEs in line with the identifiers used for tables
and views.

⚠️ Note that these changes should **not** be deployed until those two
PRs have been merged and released, since these docs will not accurately
reflect the behavior of the packages until they have been patched. I've
included this prerequisite in the checklist below.

## Checklist
- [x] Review the [Content style
guide](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/content-style-guide.md)
so my content adheres to these guidelines.
- [x] For [docs
versioning](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/single-sourcing-content.md#about-versioning),
review how to [version a whole
page](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/single-sourcing-content.md#adding-a-new-version)
and [version a block of
content](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/single-sourcing-content.md#versioning-blocks-of-content).
- [x] Add a checklist item for anything that needs to happen before this
PR is merged, such as "needs technical review" or "change base branch."
- [ ] Merge and release dbt-labs/dbt-core#10290
and dbt-labs/dbt-adapters#236

---------

Co-authored-by: Matt Shaver <[email protected]>

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 <Term id="table" /> or a <Term id="view" /> ) in the database, except in the case of an [ephemeral model](/docs/build/materializations), when it will create a <Term id="cte" /> 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 <Term id="data-warehouse" />. 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 <Term id="table" /> 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 | &lt;None&gt; | "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') }} | <Term id="view" /> | "analytics"."ga_sessions" |
+| ga_sessions.sql | {{ config(materialization='view', alias='sessions') }} | <Term id="view" /> | "analytics"."sessions" |
+| ga_sessions.sql | {{ config(materialization='ephemeral') }} | <Term id="cte" /> | "\__dbt\__cte\__ga_sessions" |
+| ga_sessions.sql | {{ config(materialization='ephemeral', alias='sessions') }} | <Term id="cte" /> | "\__dbt\__cte\__sessions" |
 
 To configure an alias for a model, supply a value for the model's `alias` configuration parameter. For example:
 

website/docs/docs/build/materializations.md

@@ -94,7 +94,8 @@ When using the `table` materialization, your model is rebuilt as a <Term id="tab
     * Use incremental models when your `dbt run`s are becoming too slow (i.e. don't start with incremental models)
 
 ### Ephemeral
-`ephemeral` models are not directly built into the database. Instead, dbt will interpolate the code from this model into dependent models as a common <Term id="table" /> 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 (<Term id="cte" />). 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 <Term id="data-warehouse" /> clean by reducing clutter (also consider splitting your models across multiple schemas by [using custom schemas](/docs/build/custom-schemas)).

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 <Term id="cte" /> 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).