Databricks Unity Catalog grants: best practices

all clouds4 min read

This guide explains the Unity Catalog privilege model and the grant patterns that work in production on Azure Databricks.

The privilege model#

These rules explain the Unity Catalog privilege model. The Unity Catalog access control documentation is the primary source.

  • Data access needs traversal. SELECT on a table is not enough. The principal also needs USE CATALOG on the catalog and USE SCHEMA on the schema. Check both traversal privileges when a table query returns PERMISSION_DENIED.
  • BROWSE shows metadata only. A principal with BROWSE sees the object in the explorer and still cannot read it. Grant the action privilege as well.
  • Inheritance covers future children. GRANT SELECT ON SCHEMA reaches every table in that schema, including tables created later. A table-level grant does not.
  • A child revoke does not cancel inherited access. Narrow a parent SELECT grant when a child table needs different access. Beta ABAC DENY policies provide a separate, limited control: they deny MANAGE ACCESS CONTROL, including access through ownership or inheritance. They do not deny SELECT. Metastore admins are exempt.
  • MANAGE is an administrative privilege. It permits grant changes, ownership transfer, and object deletion. It does not automatically grant data access, but its holder can grant that access to themselves unless an applicable ABAC DENY policy prevents it. Do not use it as a reader role.
  • Own with groups, not people. Access breaks when an individual owner leaves. Use ALTER … OWNER TO a group.
  • Account groups, not workspace-local groups. Workspace-local groups cannot receive Unity Catalog privileges. See the principal reference.

See the privilege reference for each privilege's scope and requirements.

Grant access to one table#

Use an account group that represents the reader role. The following example assumes the group, catalog, schema, and table already exist. Replace the names for your environment. An authorized owner or grant administrator must apply these statements.

GRANT USE CATALOG ON CATALOG analytics TO `finance_readers`;
GRANT USE SCHEMA ON SCHEMA analytics.gold TO `finance_readers`;
GRANT SELECT ON TABLE analytics.gold.customers TO `finance_readers`;

This pattern grants access to one table. It does not grant access to every table in the schema. Test with a reader identity that has no broader grants through another group. An administrator's successful query does not prove that the reader role works.

Choose the inheritance boundary#

Use a schema-level grant only when the group should read every current and future table in that schema. This is an alternative to the table-level SELECT statement above:

GRANT SELECT ON SCHEMA analytics.gold TO `finance_readers`;

Keep the parent usage grants. Do not place a restricted table under a broadly readable schema and expect a table-level revoke to create an exception. Narrow the parent grant or choose a separate schema with a different access policy.

Before you remove a broad grant, list the dependent groups and workloads. Establish their replacement access, then test the intended restrictions. See manage privileges.

Inspect direct and inherited grants#

List the visible direct and inherited table grants:

SELECT grantee, privilege_type, inherited_from
FROM system.information_schema.table_privileges
WHERE table_catalog = 'analytics'
  AND table_schema = 'gold'
  AND table_name = 'customers'
ORDER BY grantee;

This query returns principals, not the users inside each group. It can also omit grants when the caller has MANAGE but does not own the object. Use SHOW GRANTS or Catalog Explorer when you need the complete object grant list.

Row filters and column masks add controls to these grants. They do not replace the grants. See PII and ABAC governance for ABAC policies.

To inspect a named group's grants, check each level:

SHOW GRANTS `finance_readers` ON CATALOG analytics;
SHOW GRANTS `finance_readers` ON SCHEMA analytics.gold;
SHOW GRANTS `finance_readers` ON TABLE analytics.gold.customers;

Run these checks as a caller with permission to inspect the target grants. A restricted caller does not necessarily see every principal's permissions. Confirm the caller's identity and account group membership before you interpret an incomplete result. See SHOW GRANTS and table privileges in the information schema.

Troubleshoot access without broadening it#

  1. Confirm the catalog, schema, and table names in the failed query.
  2. Check the caller's account identity and group membership.
  3. Check USE CATALOG, USE SCHEMA, and SELECT at their applicable levels.
  4. Check inherited access through all applicable groups.
  5. Inspect row filters and column masks when the query succeeds but its results differ.
  6. Repeat the test with the intended reader identity.

Do not add ALL PRIVILEGES or MANAGE to make a read query pass. Record the failed operation and grant only the privilege that it requires. If the account group is absent, fix identity provisioning before you change table permissions. See Entra ID integration.

Separate ownership from routine access#

Assign object ownership to a group with a clear operational owner. Keep reader groups separate from groups that administer grants or delete objects. Document who approves membership in each administrative group.

When Terraform owns the grants, record approved changes in that configuration. Do not leave an emergency SQL grant outside the normal review process. A later deployment can conflict with an undocumented change. Use the Terraform and bundles ownership guide to assign one deployment owner to each shared resource.

Referenced by

Related topics and tags