Unity Catalog Native 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:
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:
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>`;
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.
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.
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 and the Team Permissions Overview.
User Roles
Team Permissions
Checked on the datastore itself, in addition to the user role above.
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.
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.
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.
-
Examples
Worked scenarios: a Databricks workspace, several schemas of one catalog, an open-source Unity Catalog server, and a schema of mixed tables.
-
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.