Add a Unity Catalog Native Datastore with a 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.

Already have a connection?

To add a Unity Catalog Native datastore on a connection that already exists, go to Add with an Existing Connection.

Before you start, review the Unity Catalog Native Permissions and the 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 or afterwards.

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	Type	Description
Connection Name	Text	A label for the saved connection (e.g., `acme_prod_catalog`), so other datastores can reuse it later.
URL	Text	The Databricks workspace URL, for example `https://<workspace>.cloud.databricks.com`, or the URL of an open-source Unity Catalog server.
Catalog	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.

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 for which credential to choose and which identity it names.

Access TokenOAuth (Service Principal)

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

Field	Type	Description
Type	Option	Set to OAuth (Service Principal) (`OAUTH` in the API).
Client ID	Text	The service principal's application ID.
Client Secret	Text	The secret generated for that service principal. Stored encrypted and never displayed back.
Token Endpoint	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.

Field	Type	Description
Login URL	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	Text	A JSON body containing the credentials Vault expects (e.g., `{"role_id":"...","secret_id":"..."}`).
Token JSONPath	Text	The JSONPath that extracts the client token from Vault's response. Defaults to `$.auth.client_token`.
Secret URL	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	Text	The HTTP header name used to send the token. Defaults to `X-Vault-Token`.
Data JSONPath	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 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		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	Type	Description
Name	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	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	Option	Select one or more teams to associate with this source datastore.
Initiate Sync	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.

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

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.

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