Add a Unity Catalog volume resource to a Databricks app

Add Unity Catalog volumes as Databricks Apps resources so your app can read from and write to files and directories stored in Unity Catalog with governance and access control. Volumes provide persistent storage for unstructured data, such as configuration files, model artifacts, logs, or other file-based data that your app needs.

Privilege requirements

To access files in a Unity Catalog volume, the app's service principal must have the USE CATALOG privilege on the parent catalog, the USE SCHEMA privilege on the parent schema, and the READ VOLUME or WRITE VOLUME privilege on the volume. When you add the volume resource, Databricks automatically grants these privileges to the app's service principal.

For this automatic granting to succeed, one of the following must be true for each privilege:

• For USE CATALOG: Either all account users have the USE CATALOG privilege on the catalog, or you have the MANAGE privilege on the catalog.
• For USE SCHEMA: Either all account users have the USE SCHEMA privilege on the schema, or you have the MANAGE privilege on the schema.
• For READ VOLUME or WRITE VOLUME: Either all account users have the READ VOLUME or WRITE VOLUME privilege on the volume, or you have the MANAGE privilege on the volume.

See Unity Catalog privileges and securable objects.

Add a Unity Catalog volume resource

Before you add a volume as an app resource, check that you meet the prerequisites.

1. In the App resources section when you create or edit an app, click + Add resource.
2. Select UC volume as the resource type.
3. Choose a Unity Catalog volume from the available volumes in your workspace. The volume must already exist in Unity Catalog.
4. Select the appropriate permission level for your app:
   • Can read: Grants the app permission to read files and directories stored in the volume. This is appropriate for apps that only need to access data.
   • Can read and write: Grants the app permission to add, remove, or modify files and directories in the volume. Choose this permission if your app needs to write data, such as saving outputs or logs.
5. (Optional) Specify a custom resource key, which is how you reference the volume in your app configuration. The default key is volume.

Environment variables

When you deploy an app with a Unity Catalog volume resource, Databricks exposes the volume path through environment variables that you can reference using the valueFrom field.

For more information, see Use environment variables to access resources.

Remove a Unity Catalog volume resource

When you remove a Unity Catalog volume resource from an app, the app's service principal loses access to the volume. The volume itself remains unchanged and continues to be available for other users and applications that have appropriate permissions.

Best practices

Consider the following when you work with Unity Catalog volume resources:

• Grant minimal permissions. Use Can read permissions unless your app needs to write data to the volume.
• Use Unity Catalog volumes instead of Databricks File System for new applications, as volumes provide better governance, access control, and compatibility with cloud storage.
• Organize your data within volumes using a clear directory structure to make it easier to manage permissions and access patterns.
• Use separate volumes for different data types or sensitivity levels to apply appropriate access controls.