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

# Creating table joins

> Create table joins in Omni workbooks or the model IDE, configure join types and conditions, and promote joins to the shared model.

## Creating joins in the workbook

<Note>
  Unless promoted to the shared model, joins created in workbooks will only be available in the workbook where they were created.

  Queriers can create joins in workbooks, but Modeler or Connection Admin permissions are required for promotion.
</Note>

In the field browser, right-click on a table and select **Joins > New join**. This opens the join builder:

<Frame>
  <img src="https://mintcdn.com/omni-e7402367/oCPXfFciZmj0I-11/modeling/images/join-modal.png?fit=max&auto=format&n=oCPXfFciZmj0I-11&q=85&s=c06df8076a57464f5b9850f37bfd07f9" style={{width: "400px", height: "auto"}} alt="Diagram showing the architecture of the system" width="1422" height="1290" data-path="modeling/images/join-modal.png" />
</Frame>

From here, you can use the **Builder** or **SQL** tabs to define the join:

<AccordionGroup>
  <Accordion title="Builder tab" icon="eye" description="Define the join with a visual editor">
    <Steps>
      <Step>
        The left and right sides of the **Builder tab** represent the views you want to join. On each side, select the fields that should be used to join the views.

        For example, selecting `orders.customer_id` and `customers.id`.
      </Step>

      <Step>
        Select a **Type** to define what type of join this is. Omni defaults to **Left** (`LEFT JOIN`), but you can change this. Refer to the [`join_type`](/modeling/relationships/parameters/join-type) reference for more information about this setting.
      </Step>

      <Step>
        Select a **Relationship** for the join. This setting is used to ensure that counts across the tables are accurate. If you're not sure what this setting should be, click the **Infer relationship** button at the bottom left corner of the modal.

        Omni will check the cardinality between the datasets and select the relationship type on your behalf. Refer to the [`relationship_type`](/modeling/relationships/parameters/relationship-type) reference for more information about this setting.
      </Step>

      <Step>
        Check the **Reversible** box allow for exploration in both directions of the join.

        <Warning>
          This setting controls how fan out is handled and thus impacts the shape of result sets. Refer to the [`reversible`](/modeling/relationships/parameters/reversible) reference for more information.
        </Warning>
      </Step>

      <Step>
        Use the **Add to topic** settings to select if the join should be added to the current topic, all possible topics, or not added.
      </Step>

      <Step>
        Click **Save** to create the join.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="SQL joins" icon="code" description="Define the join condition using SQL">
    The **SQL** tab is useful if you're creating a complex join or just prefer writing in SQL:

    <img src="https://mintcdn.com/omni-e7402367/oCPXfFciZmj0I-11/modeling/images/sql-relationship-editor.png?fit=max&auto=format&n=oCPXfFciZmj0I-11&q=85&s=b8f4d21a30d8da9f16e26b5f1c159a39" alt="SQL tab in the join modal, useful for creating complex joins" width="1420" height="922" data-path="modeling/images/sql-relationship-editor.png" />

    <Steps>
      <Step>
        Select the source and target views using the dropdowns.
      </Step>

      <Step>
        In the code block, write the join using SQL. Use `${view_name.field_name}` syntax to reference fields.
      </Step>

      <Step>
        Select a **Type** to define what type of join this is. Omni defaults to **Left** (`LEFT JOIN`), but you can change this. Refer to the [`join_type`](/modeling/relationships/parameters/join-type) reference for more information about this setting.
      </Step>

      <Step>
        Select a **Relationship** for the join. This setting is used to ensure that counts across the tables are accurate. If you're not sure what this setting should be, click the **Infer relationship** button at the bottom left corner of the modal.

        Omni will check the cardinality between the datasets and select the relationship type on your behalf. Refer to the [`relationship_type`](/modeling/relationships/parameters/relationship-type) reference for more information about this setting.
      </Step>

      <Step>
        Check the **Reversible** box allow for exploration in both directions of the join.

        <Warning>
          This setting controls how fan out is handled and thus impacts the shape of result sets. Refer to the [`reversible`](/modeling/relationships/parameters/reversible) reference for more information.
        </Warning>
      </Step>

      <Step>
        Use the **Add to topic** settings to select if the join should be added to the current topic, all possible topics, or not added.
      </Step>

      <Step>
        Click **Save** to create the join.
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

Saving the join will add a new relationship definition to the workbook model's `relationships` file, which you can view by clicking **Model > Model layers > Workbook**.

<Tip>
  [Promote the join](/modeling/develop/model-management) to the shared model to make it accessible outside the workbook.
</Tip>

## Defining relationships in the model IDE

<Note>
  Connection Admin or Modeler permissions are required to access the model IDE.
</Note>

For a code-forward approach, you can use the model IDE to create and modify joins.

<Steps>
  <Step>
    Open the model IDE by clicking **Develop** in the left navigation, then clicking the model you want to work with.
  </Step>

  <Step>
    In the **Settings** section, click **Relationships**.
  </Step>

  <Step>
    The `relationships` file will open in the editor panel. Add a relationship definition, which will look similar to the following example:

    <CodeGroup>
      ```yaml Example definition theme={null}
      - join_from_view: main__orders
        join_to_view: main__customers
        join_type: always_left
        on_sql: ${main__orders.customer_id} = ${main__customers.id}
        relationship_type: assumed_many_to_one
      ```

      ```yaml Template theme={null}
      - join_from_view:
        join_to_view:
        join_type:
        on_sql: 
        relationship_type:
      ```
    </CodeGroup>

    <Tip>
      Click the **Template** tab in the above code block for a copy + pasteable relationship definition!
    </Tip>
  </Step>

  <Step>
    Define the parameters to complete the join. In addition to the parameters in the above example and template, you can add parameters like  [`where_sql`](/modeling/relationships/parameters/where-sql) or [`reversible`](/modeling/relationships/parameters/reversible) to further customize the relationship. Refer to the [Relationship parameters reference](/modeling/relationships/parameters/parameters) for more information and examples.
  </Step>

  <Step>
    Click **Save changes**.

    <Note>
      If the model is currently configured to require branches, merge the branch to apply the changes to the shared model.

      If the model also uses the git integration, you may need to create a pull request to accomplish this.
    </Note>
  </Step>
</Steps>