Skip to content

Commit

Permalink
Update custom-aliases: usage methods, File formatting, and version nu…
Browse files Browse the repository at this point in the history
…mbers (#4119)

## What are you changing in this pull request and why?
* Updated first version for Dispatch to 1.0. I'm using it in 1.4 so it
had to be introduced before what was stated. The `dispatch` doc page
says 1.0. I also updated the link to have the in-page reference it
seemed to want. I re-titled the section header so it would stand out in
the right navigation and be more descriptive.
* I added the File macro around two files that were missing it.
* I added an example of configuring an alias in YAML instead of Jinja.

## Checklist
- [x] Review the [Content style
guide](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/content-style-guide.md)
and [About
versioning](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/single-sourcing-content.md#adding-a-new-version)
so my content adheres to these guidelines.
- [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."
  • Loading branch information
mirnawong1 authored Oct 31, 2023
2 parents 2a31c2f + 0dc3933 commit 7560640
Showing 1 changed file with 22 additions and 8 deletions.
30 changes: 22 additions & 8 deletions website/docs/docs/build/custom-aliases.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,19 @@ select * from ...

</File>

Or in a `schema.yml` file.

<File name='models/google_analytics/schema.yml'>

```yaml
- models:
- name: ga_sessions
config:
alias: sessions
```
</File>
When referencing the `ga_sessions` model above from a different model, use the `ref()` function with the model's _filename_ as usual. For example:

<File name='models/combined_sessions.sql'>
Expand Down Expand Up @@ -114,34 +127,35 @@ The default implementation of `generate_alias_name` simply uses the supplied `al

</VersionBlock>

<VersionBlock firstVersion="1.6">

### Managing different behaviors across packages
### Dispatch macro - SQL alias management for databases and dbt packages

See docs on macro `dispatch`: ["Managing different global overrides across packages"](/reference/dbt-jinja-functions/dispatch)
See docs on macro `dispatch`: ["Managing different global overrides across packages"](/reference/dbt-jinja-functions/dispatch#managing-different-global-overrides-across-packages)

</VersionBlock>

### Caveats

#### Ambiguous database identifiers

Using aliases, it's possible to accidentally create models with ambiguous identifiers. Given the following two models, dbt would attempt to create two <Term id="view">views</Term> with _exactly_ the same names in the database (ie. `sessions`):

```sql
-- models/snowplow_sessions.sql
<File name='models/snowplow_sessions.sql'>

```sql
{{ config(alias='sessions') }}
select * from ...
```
</File>

```sql
-- models/sessions.sql
<File name='models/sessions.sql'>

```sql
select * from ...
```

</File>

Whichever one of these models runs second would "win", and generally, the output of dbt would not be what you would expect. To avoid this failure mode, dbt will check if your model names and aliases are ambiguous in nature. If they are, you will be presented with an error message like this:

```
Expand Down

0 comments on commit 7560640

Please sign in to comment.