# Add an Upstream Connection

Source: https://userguide.qualytics.io/lineage/how-tos/connections/add-upstream-connection/

Record that another container, or one of its fields, feeds the one you are looking at. The connection you add this way is manual, so no data catalog sync and no Qualytics process will ever change or remove it.

> **Note: Permission Required**
>
> You need **Editor** permission on every datastore associated with the connection, or the **Admin** role, to add a lineage connection. See [Lineage Permissions](https://userguide.qualytics.io/lineage/deep-dive/permissions/) for details.

## Field reference

The **Add upstream** panel has two sections, one for each end of the connection. The node you started from is locked into the downstream section, so the upstream section is the one you fill in.

Three tabs at the top decide what you are connecting, and which fields the panel shows. The first is named after what the datastore holds, so it reads **Table** on a database and **File** on a file store.

**Tab: Table**

Connects whole containers.

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| **Datastore** | Yes | Select | The datastore holding the upstream container. Only datastores where you have Editor permission, including the one you started from. Unrestricted Admins can select any datastore. |
| **Container** | Yes | Select | The upstream container itself. Selectable only after a datastore is chosen. |

**Tab: Field**

Connects one column to another. Both ends need a field, so the locked section gains a field selector of its own.

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| **Datastore** | Yes | Select | The datastore holding the upstream container. Only datastores where you have Editor permission, including the one you started from. Unrestricted Admins can select any datastore. |
| **Container** | Yes | Select | The upstream container itself. Selectable only after a datastore is chosen. |
| **Field** (upstream) | Yes | Select | The upstream column. Selectable after the container is chosen. |
| **Field** (downstream) | Yes | Select | The column on the locked container. |

**Tab: External**

Connects the locked container to a dataset that is not registered in Qualytics, such as a file in object storage, a SaaS application, or a dashboard. You name the dataset the way OpenLineage names it, so lineage your OpenLineage producers later report for the same dataset joins the same node instead of drawing a second one.

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| **Namespace** | Yes | Text | The system the upstream dataset lives in, for example `s3://landing` or `snowflake://my-account`. |
| **Name** | Yes | Text | The dataset's name within its namespace, for example `exports/orders.parquet`. |

A dataset that is already registered in Qualytics is refused, with a message to connect its table instead. So is one whose namespace and name point into a datastore where you do not have Editor permission.

## Steps

**Step 1**: Open the container and go to its **Lineage** tab. From a datastore's **Lineage** tab, click **Open this table's lineage**  on the container's card instead.

**Step 2**: Hover the left edge of the node you want to extend, then click **Add upstream** . You can also right-click the node and choose **Add upstream** .

**Step 3**: The **Add upstream** panel opens. The node you started from is shown locked, with a lock icon, in the downstream section.

**Step 4**: Choose the mode. Stay on the container tab to connect whole containers, switch to **Field** to connect one column to another, or switch to **External** to connect a dataset that is not in Qualytics.

**Step 5**: In the upstream section, select the **Datastore**, then the **Container**. On **External**, enter the dataset's **Namespace** and **Name** instead. See the [Field reference](https://userguide.qualytics.io/lineage/how-tos/connections/add-upstream-connection/#fields) above for what each one holds in the mode you picked.

**Step 6**: In **Field** mode only, select the **Field** on the upstream side and the **Field** on the locked downstream side.

**Step 7**: Click **Add**. The button stays disabled until both ends are complete.

**Step 8**: The new node appears on the upstream side and the canvas re-centers on it.

> **Tip**
>
> Right-clicking a row in a node's expanded field list and choosing **Add upstream** opens the panel already in **Field** mode with that field selected, which skips two steps.

> **Note**
>
> When the two fields belong to different containers, Qualytics also creates the container-level connection between those containers if one does not exist yet, so the relationship is visible at both levels.

> **Note**
>
> An external connection keeps pointing at the dataset by name. If that dataset is registered in Qualytics later, the manual connection is not moved to the new container: delete it and add the connection again on the container tab.

*Last updated: November 5, 2026.*
