> ## 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.

# relationships

> Defines a list of topic-level joins.

<Note>
  Views representing a [data input table or uploaded CSV/XLSX files](/analyze-explore/data-input-csvs#limitations) can't be used in a join unless the table has been uploaded to a database.
</Note>

Defines a list of topic-level joins. Joins defined using this parameter will only be available to the topic where they are declared. This can be useful for one-off use cases, rare aliasing, or utilizing different join organization schemes. Refer to the [Relationships & Joins documentation](/modeling/relationships) for more information about top-level and global relationships.

User attributes (`{{ omni_attributes.<user_attribute> }}`) can be used in joins to create access filtered joins, which can be useful when you want to keep all rows in the dataset but limit access to the metadata.

## Syntax

```yaml theme={null}
relationships:
  - join_from_view: <view_name>
    join_to_view: <view_name>
    join_to_view_as: <alias>
    join_type: <join_type>
    on_sql: <join_condition>
    relationship_type: <relationship_type>
```

## Properties

<ParamField path="relationships" type="object[]">
  An array of relationship objects that define topic-level joins. These joins are only available within the topic where they are declared.

  <Expandable title="relationships properties" defaultOpen="true">
    <ParamField path="join_from_view" type="string" required>
      The view to join from.
    </ParamField>

    <ParamField path="join_to_view" type="string" required>
      The view to join to.
    </ParamField>

    <ParamField path="join_to_view_as" type="string">
      An alias for the joined view, useful for creating multiple joins to the same table.
    </ParamField>

    <ParamField path="join_type" type="string" required>
      The type of join (e.g., `always_left`, `always_inner`, `left`, `inner`).
    </ParamField>

    <ParamField path="on_sql" type="string" required>
      The SQL condition for the join. Can include user attributes using `{{ omni_attributes.<user_attribute> }}` syntax.
    </ParamField>

    <ParamField path="relationship_type" type="string" required>
      The relationship cardinality (e.g., `many_to_one`, `one_to_many`, `one_to_one`, `many_to_many`).
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Join order_items to buyers" theme={null}
relationships:
  - join_from_view: order_items
    join_to_view: users
    join_to_view_as: buyers
    join_type: always_left
    on_sql: ${buyers.id} = ${order_items.buyer_id}
    relationship_type: many_to_one
```

```yaml title="Filtered join using user attributes" theme={null}
relationships:
  - join_from_view: order_items
    join_to_view: users
    join_to_view_as: sellers
    join_type: always_left
    on_sql: ${sellers.id} = ${order_items.seller_id} AND ${sellers.organization_id} = {{ omni_attributes.seller_org_id }}
    relationship_type: many_to_one
```