# Add a Unity Catalog Native Datastore with a New Connection

Source: https://userguide.qualytics.io/source-datastore/datastore/native/unity-catalog/how-tos/add-new-connection/

This page walks you through adding a **Unity Catalog Native** source datastore while creating its connection: every field the form asks for, section by section, followed by the steps to test and finish.

Once the datastore is created, run a Sync to discover the tables in the selected schema. Objects that Unity Catalog Native cannot read, such as views, do not become containers: the Sync's warning says how many were skipped, and names any table the catalog listed but Qualytics could not read. The rest of the schema syncs normally.

> **Tip: Already have a connection?**
>
> To add a Unity Catalog Native datastore on a connection that already exists, go to [Add with an Existing Connection](https://userguide.qualytics.io/source-datastore/datastore/native/unity-catalog/how-tos/add-existing-connection/).

Before you start, review the [Unity Catalog Native Permissions](https://userguide.qualytics.io/source-datastore/datastore/native/unity-catalog/deep-dive/permissions/) and the [Authentication](https://userguide.qualytics.io/source-datastore/datastore/native/unity-catalog/deep-dive/authentication/) page. Reaching the catalog is not enough on its own: the identity also needs to be allowed to read table files from outside Databricks, and the cloud storage has to accept traffic from your Qualytics deployment.

> **Warning**
>
> Unity Catalog Native cannot be used as an enrichment datastore. After you add it as a source, link a separate enrichment datastore as its destination to store anomalies and metadata: either [during creation](https://userguide.qualytics.io/source-datastore/enrichment-datastore/how-tos/link-during-creation/) or [afterwards](https://userguide.qualytics.io/source-datastore/enrichment-datastore/how-tos/link-enrichment/).

## Field reference

After you choose **New Connection**, the form shows three sections. **Connection Properties** holds everything that belongs to the connection, including the **Secrets Management** and **Authentication** groups inside it. **Location** holds the schema to monitor, and **General** holds the datastore's own settings.

### Connection Properties

These fields define the catalog Qualytics connects to. They belong to the connection, so they can be reused by other datastores later. **Secrets Management** and **Authentication**, described next, sit inside this section.

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| **Connection Name** | Yes | Text | A label for the saved connection (e.g., `acme_prod_catalog`), so other datastores can reuse it later. |
| **URL** | Yes | Text | The Databricks workspace URL, for example `https://<workspace>.cloud.databricks.com`, or the URL of an open-source Unity Catalog server. |
| **Catalog** | Yes | Option | The Unity Catalog catalog to monitor. Once the URL and the credential are filled in, the dropdown lists the catalogs that credential can see. You can also type a name. A connection monitors one catalog. |

> **Note: The catalog belongs to the connection**
>
> Unlike the schema, the catalog is saved with the connection, next to the URL and the credential. Every datastore that reuses the connection reads from that catalog. To monitor a second catalog, create a second connection.

### Authentication

Shown inside **Connection Properties**. Setting **Type** changes the credential fields shown below it, so pick the tab that matches your choice. See [Unity Catalog Native Authentication](https://userguide.qualytics.io/source-datastore/datastore/native/unity-catalog/deep-dive/authentication/) for which credential to choose and which identity it names.

**Tab: Access Token**

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| **Type** | No | Option | Set to **Access Token**, which is the default (`TOKEN` in the API). |
| **Access Token** | Yes | Text | A token the catalog issued, such as a Databricks personal access token. Stored encrypted and never displayed back. |

**Tab: OAuth (Service Principal)**

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| **Type** | No | Option | Set to **OAuth (Service Principal)** (`OAUTH` in the API). |
| **Client ID** | Yes | Text | The service principal's application ID. |
| **Client Secret** | Yes | Text | The secret generated for that service principal. Stored encrypted and never displayed back. |
| **Token Endpoint** | No | Text | Where Qualytics requests access tokens. Leave it empty to use the **URL** followed by `/oidc/v1/token`. |

### Secrets Management

Also inside **Connection Properties**, and optional. Use it only if you want Qualytics to pull credentials from a secrets manager instead of typing them into the form. Turn on **HashiCorp Vault** to show the fields below. Despite the label, any secrets manager that exposes a compatible REST API works. See [HashiCorp Vault](https://userguide.qualytics.io/source-datastore/datastore/connection/hashicorp-vault/deep-dive/introduction/).

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| **Login URL** | Yes | Text | The full URL of the login endpoint (e.g., `https://vault.example.com/v1/auth/approle/login`). With Vault namespaces, add the namespace after `/v1/`, as in `/v1/<namespace>/auth/approle/login`. |
| **Credentials Payload** | Yes | Text | A JSON body containing the credentials Vault expects (e.g., `{"role_id":"...","secret_id":"..."}`). |
| **Token JSONPath** | Yes | Text | The JSONPath that extracts the client token from Vault's response. Defaults to `$.auth.client_token`. |
| **Secret URL** | Yes | Text | The full URL of the secret, including `https://` and the host (e.g., `https://vault.example.com/v1/secret/data/unity`). With Vault namespaces, add the namespace after `/v1/`. |
| **Token Header Name** | Yes | Text | The HTTP header name used to send the token. Defaults to `X-Vault-Token`. |
| **Data JSONPath** | Yes | Text | The JSONPath that extracts the key/value pairs from Vault's response. Use `$.data.data` for a KV version 2 secret (its API path contains `/data/`) and `$.data` for KV version 1 or the database secrets engine. The form pre-fills `$.data`. |

> **Note**
>
> Reference a key from the secret in the **URL** field or in any **Authentication** field other than **Type** with `${key}`, for example `${token}`. Write it with braces (`${key}`, never `$.key`) and match the key name's case. Qualytics resolves it each time the connection is opened, so a changed value takes effect on the next connection. Setup steps, the namespace rule, and a troubleshooting page are on the [HashiCorp Vault](https://userguide.qualytics.io/source-datastore/datastore/connection/hashicorp-vault/deep-dive/introduction/) pages.

### Location

Pick the schema Qualytics should read from. Unlike **Connection Properties**, this section belongs to the datastore rather than to the connection, so it is filled in on both flows.

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| **Schema** | Yes | Option | One or more schemas of the selected catalog to monitor. The dropdown lists the schemas that the credential can see in that catalog, and you can also type a name. Each schema you pick becomes its own Qualytics datastore. |

### General

The datastore's own settings.

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| **Name** | Yes | Text | The datastore name in Qualytics. Comes suggested from the connection name and the schema, so you can leave it blank to accept that suggestion. |
| **Group** | No | Option | Organizes your datastores under a shared group in the navigation tree. Select an existing group, or turn on **Add New Group** to create one. |
| **Teams** | Yes | Option | Select one or more teams to associate with this source datastore. |
| **Initiate Sync** | No | Checkbox | Ask Qualytics to run the first Sync for you once the datastore is created. You can always run a Sync yourself from the datastore afterwards. |

> **Note: Selecting more than one schema**
>
> When you pick several schemas in **Location**, each one becomes its own datastore and **Name** is replaced by **Name Template**, a naming pattern applied to all of them. Use `{{schema}}` as the placeholder for the schema name: `prod_{{schema}}` becomes `prod_sales`, `prod_finance`, and so on. Left empty, each datastore is named from the connection name and its schema.

Below the form, an information banner lists the **Public addresses** and **Private addresses** your datastore connections originate from. Allow the ones that match your network setup through your security groups or firewall rules, on the catalog side and on the storage side. See [Permissions](https://userguide.qualytics.io/source-datastore/datastore/native/unity-catalog/deep-dive/permissions/) for the services involved.

## Steps

**Step 1**: Navigate to the **Datastores** page.

**Step 2**: Click the **Add**  button at the top-right corner and choose **Source**  from its menu.

**Step 3**: The **Datastore** step opens, the first of two.

**Step 4**: Select **New Connection** next to the **Search**  field.

**Step 5**: Select **Unity Catalog Native** from the connector grid. Use the search field to filter connectors by name.

**Step 6**: Fill in the fields of **Connection Properties**, **Authentication**, **Location**, and **General**, as described in the [Field reference](https://userguide.qualytics.io/source-datastore/datastore/native/unity-catalog/how-tos/add-new-connection/#field-reference). Fill in the **URL** and the credential first, so that the **Catalog** and **Schema** dropdowns can list what that credential can see.

**Step 7**: Click **Test connection**. A success message confirms that the connection has been verified.

> **Info**
>
> The **Finish** and **Next** buttons stay disabled until the connection test passes on the current values. If you change a connection field after a successful test, test again. If the test fails, see [Troubleshooting](https://userguide.qualytics.io/source-datastore/datastore/native/unity-catalog/troubleshooting/).

**Step 8**: Click **Finish** to create the datastore.

> **Tip**
>
> To link an enrichment destination so Qualytics can store anomalies and metadata from the first operation, click **Next** instead of **Finish**. See [Link Enrichment on Datastore Creation](https://userguide.qualytics.io/source-datastore/enrichment-datastore/how-tos/link-during-creation/).

**Step 9**: A success dialog confirms that your datastore has been added. Click **Go to your datastore** to open its page.

*Last updated: October 9, 2026.*
