Enable a workspace for Unity Catalog

This article explains how to enable a workspace for Unity Catalog by assigning a Unity Catalog metastore.

Important

On March 6, 2024, Databricks started to enable new workspaces for Unity Catalog automatically, with a rollout proceeding gradually. If your workspace was enabled for Unity Catalog automatically, this article does not apply to you.

To determine if your workspace is already enabled for Unity Catalog, see Step 1: Confirm that your workspace is enabled for Unity Catalog.

About enabling workspaces for Unity Catalog

Enabling Unity Catalog for a workspace means that:

  • Users in that workspace can potentially access the same data that users in other workspaces in your account can access, and data stewards can manage that data access centrally, across workspaces

  • Data access is audited automatically

  • Identity federation is enabled for the workspace, allowing admins to manage identities centrally using the account console and other account-level interfaces. This includes assigning users to workspaces.

To enable a Databricks workspace for Unity Catalog, you assign the workspace to a Unity Catalog metastore. A metastore is the top-level container for data in Unity Catalog. Each metastore exposes a 3-level namespace (catalog.schema.table) by which data can be organized.

You can share a single metastore across multiple Databricks workspaces in an account. Each linked workspace has the same view of the data in the metastore, and you can manage data access control across workspaces. You can create one metastore per region and attach it to any number of workspaces in that region.

Considerations before you enable a workspace for Unity Catalog

Before you enable a workspace for Unity Catalog, you should:

  • Understand the privileges of workspace admins in workspaces that are enabled for Unity Catalog, and review your existing workspace admin assignments.

    Workspace admin is a privileged role that you should distribute carefully.

    Workspace admins can manage operations for their workspace including adding users and service principals, creating clusters, and delegating other users to be workspace admins. If your workspace was enabled for Unity Catalog automatically, the workspace admin also has a number of additional privileges by default, including the ability to create most Unity Catalog object types and grant access to the ones they create. See Admin privileges in Unity Catalog.

    If your workspace was not enabled for Unity Catalog automatically, then your workspace admins have no more access to Unity Catalog objects by default than any other user, but they do have the ability to perform workspace management tasks such as managing job ownership and viewing notebooks, which may give indirect access to data registered in Unity Catalog.

    Account admins can restrict workspace admin privileges using the the RestrictWorkspaceAdmins setting. See Restrict workspace admins.

    If you use workspaces to isolate user data access, you might want to use workspace-catalog bindings. Workspace-catalog bindings enable you to limit catalog access by workspace boundaries. For example, you can ensure that workspace admins and users can only access production data in prod_catalog from a production workspace environment, prod_workspace. The default is to share the catalog with all workspaces attached to the current metastore. Likewise, you can bind access to external locations such that they are accessible only from specified workspaces. See Limit catalog access to specific workspaces and (Optional) Assign an external location to specific workspaces.

  • Update any automation that has been configured to manage users, groups, and service principals, such as SCIM provisioning connectors and Terraform automation, so that they refer to account endpoints instead of workspace endpoints. See Account-level and workspace-level SCIM provisioning.

  • Be aware that enabling a workspace for Unity Catalog cannot be reversed. Once you enable the workspace, you will manage users, groups, and service principals for this workspace using account-level interfaces.

Requirements

Before you can enable your workspace for Unity Catalog, you must have a Unity Catalog metastore configured for your Databricks account. See Create a Unity Catalog metastore.

Enable your workspace for Unity Catalog

When you create a metastore, you are prompted to assign workspaces to that metastore, which enables those workspaces for Unity Catalog. You can also return to the account console to enable a workspace for Unity Catalog at any time, including when you create workspaces using the account console. Note that most workspaces are automatically enabled for Unity Catalog when you create them. See Automatic enablement of Unity Catalog.

To enable an existing workspace for Unity Catalog using the account console:

  1. As an account admin, log in to the account console.

  2. Click Catalog icon Catalog.

  3. Click the metastore name.

  4. Click the Workspaces tab.

  5. Click Assign to workspace.

  6. Select one or more workspaces. You can type part of the workspace name to filter the list.

  7. Scroll to the bottom of the dialog, and click Assign.

  8. On the confirmation dialog, click Enable.

To enable Unity Catalog when you create a workspace using the account console:

  1. As an account admin, log in to the account console.

  2. Click Workspaces Icon Workspaces.

  3. Click Create workspace.

  4. On the Create workspace page, click the Enable Unity Catalog toggle.

  5. On the confirmation dialog, click Enable.

  6. Select the Metastore.

  7. Complete the workspace creation configuration and click Save.

When the assignment is complete, the workspace appears in the metastore’s Workspaces tab, and the metastore appears on the workspace’s Configuration tab.