Manage clean rooms

Preview

This feature is in Public Preview.

This article describes how to manage clean rooms, including how to:

Update a clean room owner and comment
Add, remove, and edit data assets and notebooks
Grant access to a clean room
Monitor clean room activity
Delete a clean room

These tasks can be performed by all collaborators in a clean room.

Before you begin

Managing clean rooms requires the following permissions, depending on the task:

To view a clean room in the clean room list or to view clean room details, you must be the owner of the clean room, a metastore admin, or have one of the following privileges on the clean room: MODIFY CLEAN ROOM, EXECUTE CLEAN ROOM TASK, or BROWSE.
To update the owner of a clean room, you must be the owner of the clean room or a metastore admin.
To add and remove data assets and notebooks in a clean room and to update a comment, you must be the owner of the clean room or have the MODIFY CLEAN ROOM privilege on the clean room.
To grant access to a clean room, you must be the owner or a metastore admin.
To delete a clean room, you must be the owner.

Note

The creator is automatically assigned as the owner of the clean room in their Databricks account. The collaborator organization’s metastore admin is automatically assigned ownership of the clean room in their Databricks account. You can transfer ownership. See Manage Unity Catalog object ownership.

Update a clean room

In your Databricks workspace, click Catalog.
On the Quick access page, click the Clean Rooms > button.

Alternatively, click the gear icon at the top of the Catalog pane and select Clean Rooms.
Select the clean room from the list.
Make any of the following updates:
- Edit comment: Click the edit icon next to the comment. Comment changes apply only to the clean room securable in your Unity Catalog metastore. It does not get propogated to other collaborators.
- Transfer owner: Click the edit icon next to the Owner name.
- Add tables and volumes: See Step 3. Add data assets and notebooks to the clean room.
- Remove tables and volumes: Click the kebab menu (also known as the three-dot menu) on the asset row and select Remove data asset.
- Add notebooks: See Step 3. Add data assets and notebooks to the clean room.
- Update notebooks: Click the kebab menu on the notebook row and select Update notebook. In the dialog, browse for and select the updated notebook.
  
  Make any updates directly in the notebook before you select it in the Clean Rooms interface.
- Remove notebooks: Click the kebab menu on the notebook row and select Delete notebook.

Grant access to a clean room

The clean room owner has all privileges on the clean room. The clean room owner and the metastore owner are the only roles that can grant other principals access to the clean room. The creator is automatically assigned as the owner of the clean room in their Databricks account. The collaborator organization’s metastore admin is automatically assigned ownership of the clean room in their Databricks account. You can transfer ownership. See Manage Unity Catalog object ownership.

The owner can grant the following privileges on a clean room:

BROWSE, which lets you list the clean room and view details like comment, owner, assets, and run history.
MODIFY CLEAN ROOM, which lets you do everything that BROWSE grants, plus add and remove data assets, add and remove notebooks, and update comments.
EXECUTE CLEAN ROOM TASK, which lets you do everything that BROWSE grants, plus run notebooks in a clean room.

To grant a principal privileges on a clean room:

In your Databricks workspace, click Catalog.
At the top of the Catalog pane, click the gear icon and select Clean Rooms.

Alternatively, from the Quick access page, click the Clean Rooms > button.
Select the clean room from the list.
Go to the Permissions tab.
Select the user, group, or service principal, click Grant, and select the privileges you want to grant.

For more information about granting privileges, see Manage privileges in Unity Catalog.

Monitor clean room notebook runs

All notebook runs from all collaborators are logged on the Runs tab in the Clean Rooms UI. You can filter runs by status and collaborator who ran the task.

In your Databricks workspace, click Catalog.
On the Quick access page, click the Clean Rooms > button.

Alternatively, click the gear icon at the top of the Catalog pane and select Clean Rooms.
Select the clean room from the list.
Go to the Runs tab.

You can also view runs for a specific notebook by selecting the notebook in the clean room UI and going to the Runs tab on the notebook details page.

Monitor clean room logs

The clean_room_events system table logs all clean-room related events in your Databricks metastore and enables you to view all actions that you and other collaborators took on your clean rooms.

To learn how to use this system table to gain insight into clean room activities, see Clean room events system table reference.

Delete a clean room

When you delete a clean room, collaborators are unable to use it, but it appears on their list of clean rooms until they delete the clean room object on their side. When you delete a clean room, running tasks are canceled immediately.

In your Databricks workspace, click Catalog.
On the Quick access page, click the Clean Rooms > button.

Alternatively, click the gear icon at the top of the Catalog pane and select Clean Rooms.
Select the clean room from the list.
Click the kebab menu on the upper right corner of the page.
Select Delete.
Confirm that you want to delete the clean room, and click Delete.

Troubleshoot clean room issues

You may encounter the following error messages or issues when you work with clean rooms.

Other collaborators have left the clean room, so the clean room is no longer usable. Please delete this clean room securable.

In a no-trust clean room, any collaborator can delete the central clean room. This error message means that the other collaborator deleted the central clean room, and your reference to the central clean room is no longer valid. You can only delete the clean room object in your Databricks workspace. You cannot use it.

Collaborator X already has a clean room named Y

No collaborator can change the clean room name. This ensures that all collaborators can reference the clean room name without ambiguity. This error means that the other collaborator already has a clean room with the same name as the one you chose. Choose another clean room name.

Please accept the Serverless terms of service before using Clean Rooms

Serverless compute is required for central clean rooms. You do not need to enable serverless compute in your own workspace to use clean rooms. But you do need to accept the serverless compute terms of service. See Enable serverless compute. If you need assistance, contact your Databricks representative.

Invited collaborator cannot see the clean room

Only a metastore admin can view a clean room when it is initially created in an invited collaborator’s metastore. Some workspaces that are enabled for Unity Catalog don’t have a metastore admin assigned. You must assign the metastore admin role in order to start working with the clean room. See Assign a metastore admin.