> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omni.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Aliasing views

> Alias views to handle database table renames or to create duplicate views for joins.

Aliasing lets you reference a view by an additional name. This is useful for handling database table renames and for creating duplicate views needed in join logic.

<Tip>
  Aliased views are best paired with [topics](/modeling/topics) and may not appear as views in **All Views and Fields** in the workbook. Additionally, aliased views can't be extended.
</Tip>

## Handling table name changes

If the name of view's base table changes in the database, it can cause content in Omni to break. Use the [`aliases`](/modeling/views/parameters/aliases) parameter to add the table's original name(s), which will allow Omni to find the correct table in the database.

## Duplicating views with aliases

In some cases, you may need to duplicate a view - for example, a `users` view that contains both **buyers** and **sellers**. Aliased views are automatically created when you define them as joins in the model's [Relationships file](/modeling/relationships).

The following example demonstrates how to alias the `users` view to create `buyers` and `sellers` views. Note that the names of the aliased views are used to declare the joins:

```yaml title="relationships.yaml" highlight={2,5,9,12} theme={null}
- join_to_view: users
  join_to_view_as: buyers
  join_type: always_left
  relationship_type: many_to_one
  on_sql: ${order_items.user_id} = ${buyers.id}
  reversible: false

- join_to_view: users
  join_to_view_as: sellers
  join_type: always_left
  relationship_type: many_to_one
  on_sql: ${order_items.user_id} = ${sellers.id}
  reversible: false
```

## Alias scope

An alias created by [`join_to_view_as`](/modeling/relationships/parameters/join-to-view-as) or [`join_from_view_as`](/modeling/relationships/parameters/join-from-view-as) only exists within:

* The `on_sql` of the relationship that creates it
* The [`joins`](/modeling/topics/parameters/joins) parameter of a topic, to bring the alias into that topic
* Custom field or dimension SQL defined in the topic's [`views`](/modeling/topics/parameters/views) parameter, since that SQL is evaluated in the context of the topic where the alias is already joined in

It isn't a full view, so it can't be referenced from a view file's own field or dimension SQL, or used as a join target in a different relationship — Omni can't resolve it as a table outside the contexts above.

### Giving an alias its own fields, label, or display order

To customize an alias further — set its `display_order` or `label` in a topic, or add fields to it that other topic-level SQL can reference — extend the original view under the alias's name instead of using `join_to_view_as`/`join_from_view_as`:

```yaml title="Topic file" highlight={2-3,11} theme={null}
views:
  buyers:
    extends: [ users ]
    dimensions:
      buyer_tier:
        sql: ${TABLE}.tier
    display_order: 2

relationships:
  - join_from_view: order_items
    join_to_view: buyers
    join_type: always_left
    on_sql: ${order_items.user_id} = ${buyers.id}
    relationship_type: many_to_one
```

The relationship now joins directly to `buyers` with [`join_to_view`](/modeling/relationships/parameters/join-to-view) rather than aliasing `users` with `join_to_view_as`. Once `buyers` is declared this way it's a real view: it can hold its own fields, take a `display_order` and `label` in the topic's `views` parameter, and be used as a join target in other relationships — none of which a `join_to_view_as`/`join_from_view_as` alias supports.

<Warning>
  Don't declare both a `join_to_view_as`/`join_from_view_as` alias and a `views` entry with the same name in the same topic. Omni will see two definitions claiming the same name and raise a `Relationship alias duplicates view name` error. Pick one: alias for `on_sql` disambiguation only, or an extended view for everything else.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Relationship alias duplicates view name / Table not found">
    This happens when a `join_to_view_as` or `join_from_view_as` alias is declared in a topic's `views` parameter without an `extends` parameter — Omni can't resolve the alias as a table on its own.

    Add `extends: [ <original_view> ]` to the `views` entry, and change the relationship to join directly to the alias's name with `join_to_view` (or `join_from_view`) instead of aliasing the original view. See [Giving an alias its own fields, label, or display order](#giving-an-alias-its-own-fields-label-or-display-order) above.
  </Accordion>

  <Accordion title="View is not joined into topic">
    This happens when a view file's own field or dimension SQL references a `join_to_view_as`/`join_from_view_as` alias (for example, `${my_alias.field}`). View files are evaluated independently of any topic, so they have no way to know the alias will exist at query time.

    Move the field definition into the topic's `views` parameter instead, under the alias's name — SQL defined there can see aliases already joined into that topic.
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.