Create and manage volumes
This article contains syntax examples for creating, managing, and dropping Unity Catalog volumes.
For instructions on uploading, managing, or working with files in volumes, see Manage files in volumes.
For details on exploring volumes and their contents, see Explore storage and find data files.
For a general overview of volumes, see What are Unity Catalog volumes?.
For details about managed and external volumes, see Managed vs. external volumes.
For Unity Catalog permission details, see What are the privileges for volumes?.
Create a volume
When you create a volume using SQL, Catalog Explorer, or other tools, a managed volume is created by default. To create an external volume, you associate the volume with an external location.
The following instructions include example syntax for creating managed volumes and optionally specifying a cloud object storage location to create an external volume.
To create a volume in Catalog Explorer:
In your Databricks workspace, click Catalog.
Search or browse for the schema that you want to add the volume to and select it.
Click the Create Volume button. (You must have sufficient privileges.)
Enter a name for the volume.
If you wish to create an external volume, do the following:
Choose an external location in which to create the volume.
Edit the path to reflect the sub-directory where you want to create the volume.
Provide a comment (optional).
Click Create.
To create a managed volume, use the following syntax:
CREATE VOLUME <catalog>.<schema>.<volume-name>;
To create an external volume, add the LOCATION
clause, as in the following example:
CREATE EXTERNAL VOLUME <catalog>.<schema>.<external-volume-name>
LOCATION 's3://<external-location-bucket-path>/<directory>';
Note
When you define a volume, cloud URI access to data under the volume path is governed by the permissions of the volume.
See CREATE VOLUME.
Required permissions
You must have the following permissions to create a volume:
Resource |
Permissions required |
---|---|
Schema |
|
Catalog |
|
By default, managed volumes are created in the managed storage location associated with the containing schema. See Specify a managed storage location in Unity Catalog.
To create an external volumes, you must also have the CREATE EXTERNAL VOLUME
privilege for the external location that manages the cloud object storage specified in your LOCATION
clause. See Connect to cloud object storage using Unity Catalog.
Drop a volume
To drop a volume in Catalog Explorer:
In your Databricks workspace, click Catalog.
Search or browse for the volume that you want to drop and select it.
Click the to the right of the volume name and select Delete.
Click Delete in the dialog that appears to confirm.
Note
Dropping a managed volume marks the contained files for deletion, while dropping an external volume does not. See Behavior differences between managed and external volumes.
Required permissions
Only users with owner privileges can drop a volume. See Volume ownership.
Rename a volume
To rename a volume in Catalog Explorer:
In your Databricks workspace, click Catalog.
Search or browse for the volume that you want to rename and select it.
Click the to the right of the volume name and select Rename.
Enter a name for the volume.
Click Save.
Use the following syntax to rename a volume:
ALTER VOLUME <volume-name> RENAME TO <new-volume-name>
See ALTER VOLUME.
Required permissions
Only users with owner privileges can rename a volume. See Volume ownership.
Change permissions on a volume
To change permissions a volume in Catalog Explorer, start by navigating to the permissions UI:
In your Databricks workspace, click Catalog.
Search or browse for the volume that you want to modify change permissions on and select it.
Click the Permissions tab. Granted and inherited privleges on the volume are displayed.
To grant new privileges, do the following:
Click Grant.
Type to search for a principal. Select the principal you wish to grant privileges. You can select multiple principals.
Select the privileges you wish to grant.
Click Grant.
Note
If the principal does not have USE CATALOG
and USE SCHEMA
privileges on parent resources, a warning appears that additional privileges are required. If you have sufficient permissions on the parent resources to grant those privileges, a checkbox appears to also grant those privileges.
To revoke privileges, do the following:
Select one or more grants.
Click Revoke.
Click Revoke in the dialog that appears to confirm.
Use GRANT
and REVOKE
to change permissions on a volume.
For example, the following syntax grants READ FILES
on a volume:
GRANT READ FILES ON VOLUME <volume-name> TO <principal>
The following syntax to revokes WRITE FILES
on a volume:
REVOKE WRITE FILES ON VOLUME <volume-name> TO <principal>
See Manage privileges in Unity Catalog.
Required permissions
Only users with owner privileges can permissions of a volume. See Volume ownership.
Change volume owner
To change the owner of a volume in Catalog Explorer, do the following:
In your Databricks workspace, click Catalog.
Search or browse for the volume that you want to change ownership for and select it.
In the About this volume pane, click the next to Owner.
Type to search for a principal and select it.
Click Save.
Use the following syntax to change the owner of a volume:
ALTER VOLUME <volume-name> SET OWNER TO <principal-name>
See ALTER VOLUME.
Required permissions
Only users with owner privileges can change the owner of a volume. See Volume ownership.