# Unity Catalog Native Permissions

Source: https://userguide.qualytics.io/source-datastore/datastore/native/unity-catalog/deep-dive/permissions/

Two separate things have to be granted before someone can put a Unity Catalog Native datastore to work, and they are granted in different places:

- **In your Unity Catalog**, the identity Qualytics connects with needs to see the catalog and schema, read the tables, and be allowed to read their files from outside Databricks. Without the last of these the connection tests and syncs cleanly and then cannot read a single row.
- **In Qualytics**, the person doing the work needs a user role and a team permission. Without them the datastore exists but they cannot create, change, or run operations on it.

The rest of this page covers both, in that order.

---

## Access in your Unity Catalog

Because Unity Catalog Native reads the table files itself, it needs more than the grants a query tool would need. Reading table definitions is enough to list catalogs, schemas, and tables, and a datastore set up that way syncs successfully and then fails the first time it tries to profile or scan. Grant the access below before the first operation, not after.

Qualytics never writes through this connector, so read access is all it asks for.

### Grants on a Databricks workspace

The identity behind the access token or the service principal needs these privileges on every catalog and schema Qualytics monitors:

| Privilege | Granted on | Why it is needed |
| --- | --- | --- |
| `USE CATALOG` | The catalog | List the catalog and its schemas |
| `USE SCHEMA` | Each schema to monitor | List the schema's tables and read their definitions |
| `SELECT` | The tables, or the whole schema | Read the data during Profile and Scan operations |
| `EXTERNAL USE SCHEMA` | Each schema to monitor | Let a tool outside Databricks obtain the storage credential for a table's files |

The last privilege is the one query tools never need and the one most often forgotten. Databricks hands a table's files to an outside reader only when the identity holds `EXTERNAL USE SCHEMA` on the schema, and only when a metastore admin has turned on **external data access** for the metastore. Both are set in Databricks, not in Qualytics.

Replace the placeholders with your own values:

```sql
GRANT USE CATALOG ON CATALOG <catalog_name> TO `<principal>`;
GRANT USE SCHEMA ON SCHEMA <catalog_name>.<schema_name> TO `<principal>`;
GRANT SELECT ON SCHEMA <catalog_name>.<schema_name> TO `<principal>`;
GRANT EXTERNAL USE SCHEMA ON SCHEMA <catalog_name>.<schema_name> TO `<principal>`;
```

> **Note: Managed tables**
>
> Databricks allows outside readers to read managed tables, not to write to them. Qualytics only reads, so a managed table and an external table are monitored the same way.

### Grants on an open-source Unity Catalog server

The token or service principal needs read access to the catalog and schema, the same as any other client of the server. The server also has to hold a storage credential for the location of every table Qualytics reads, so that it can hand Qualytics a short-lived credential for the files. A server that knows a table's location but holds no credential for it can list the table and cannot let anyone read it.

### Network access

Allow your Qualytics deployment to reach the services below. The **Add Datastore** form shows the addresses your connections originate from, under **Public addresses** and **Private addresses**, so you can copy the ones that match your network setup into your security groups or firewall rules.

| Service | Typical port | Why it is needed |
| --- | --- | --- |
| The Databricks workspace or the Unity Catalog server | 443 | Catalogs, schemas, table definitions, and storage credentials |
| The token endpoint | 443 | Access tokens, for **OAuth (Service Principal)** only. On Databricks it is the workspace itself. |
| The cloud storage holding the tables | 443 | The data itself, during Profile and Scan operations |

The storage credential Unity Catalog hands out grants permission to read the files. It does not open a network path. If the bucket, container, or storage account only accepts traffic from inside Databricks or from a private network, Qualytics cannot reach the files even with a valid credential. Allow the deployment's addresses on the storage side as well.

> **Tip: The credential identifies Qualytics in your audit logs**
>
> Every catalog request and every file read is made as the identity on the connection. A service principal created for Qualytics, with grants limited to the schemas it monitors, makes its activity easy to find in Databricks audit logs and easy to revoke.

---

## Permissions in Qualytics

Qualytics checks two layers, and an action is allowed only when both pass.

- **User roles** are workspace-wide: **Member**, **Manager**, and **Admin**.
- **Team permissions** are granted per datastore through the teams a user belongs to: **Reporter**, **Viewer**, **Drafter**, **Author**, and **Editor**.

For the full reference, see [User Roles](https://userguide.qualytics.io/settings/access/users/roles/overview/) and the [Team Permissions Overview](https://userguide.qualytics.io/settings/access/teams/team-permissions/overview/).

### User Roles

| Action | Member | Manager | Admin |
| --- | --- | --- | --- |
| View the datastore and its activity | Allowed | Allowed | Allowed |
| Create a Unity Catalog Native datastore | Not allowed | Allowed | Allowed |
| Edit the datastore's settings | Allowed | Allowed | Allowed |
| Run and schedule Sync, Profile, and Scan | Allowed | Allowed | Allowed |
| Link an enrichment destination | Allowed | Allowed | Allowed |
| Unlink an enrichment destination | Not allowed | Not allowed | Allowed |
| Delete the datastore | Not allowed | Not allowed | Allowed |

### Team Permissions

Checked on the datastore itself, in addition to the user role above.

| Action | Reporter | Viewer | Drafter | Author | Editor |
| --- | --- | --- | --- | --- | --- |
| View the datastore and its activity | Allowed | Allowed | Allowed | Allowed | Allowed |
| Preview the datastore's data | Not allowed | Allowed | Allowed | Allowed | Allowed |
| Edit the datastore's settings | Not allowed | Not allowed | Not allowed | Not allowed | Allowed |
| Run and schedule Sync, Profile, and Scan | Not allowed | Not allowed | Not allowed | Not allowed | Allowed |
| Link an enrichment destination | Not allowed | Not allowed | Not allowed | Not allowed | Allowed |

### How the two layers meet

To **create** a Unity Catalog Native datastore, a user needs the **Manager** role *and* the **Editor** team permission on at least one of the teams chosen for the new datastore. The form requires at least one team. Through the API, a request that names no team assigns the datastore to the Public team, so the user needs **Editor** on that team instead.

To **edit** it, **run an operation** on it, or **link an enrichment destination**, a user needs the **Member** role or higher *and* the **Editor** team permission on that datastore, through at least one of the teams the datastore belongs to.

To **delete** it, or to **unlink** its enrichment destination, a user needs the **Admin** role. No team permission is consulted.

> **Info: Admins bypass team permissions**
>
> A user with the **Admin** role passes every team permission check, on any datastore, whether or not they belong to a team that owns it.

> **Tip: Who should hold what**
>
> Give the **Editor** team permission to the people who own the catalog day to day, since it is what gates running a Sync after a schema change. Reserve the **Manager** role for whoever onboards new catalogs, and the **Admin** role for the few people who should be able to remove a datastore.

---

## See Also

- **Authentication**

  Access tokens and OAuth service principals: which credential goes in which field, the token endpoint, and how secrets are stored.

  [Authentication](https://userguide.qualytics.io/source-datastore/datastore/native/unity-catalog/deep-dive/authentication/)
- **Examples**

  Worked scenarios: a Databricks workspace, several schemas of one catalog, an open-source Unity Catalog server, and a schema of mixed tables.

  [Examples](https://userguide.qualytics.io/source-datastore/datastore/native/unity-catalog/deep-dive/examples/)
- **Best Practices**

  Recommendations for planning one connection per catalog, choosing the credential, keeping reads inside the credential window, and splitting tables with the Databricks connector.

  [Best Practices](https://userguide.qualytics.io/source-datastore/datastore/native/unity-catalog/deep-dive/best-practices/)

*Last updated: October 9, 2026.*
