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 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>';
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.
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
Use the following syntax to drop a volume:
DROP VOLUME IF EXISTS <volume-name>;
See DROP VOLUME.
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
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
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
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.