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:

1. In your Databricks workspace, click Catalog.

2. Search or browse for the schema that you want to add the volume to and select it.

3. Click the Create Volume button. (You must have sufficient privileges.)

4. Enter a name for the volume.

5. If you wish to create an external volume, do the following:

   1. Choose an external location in which to create the volume.

   2. Edit the path to reflect the sub-directory where you want to create the volume.

6. Provide a comment (optional).

7. 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 'gcs://<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	USE SCHEMA, CREATE VOLUME
Catalog	USE 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:

1. In your Databricks workspace, click Catalog.

2. Search or browse for the volume that you want to drop and select it.

3. Click the to the right of the volume name and select Delete.

4. Click Delete in the dialog that appears to confirm.

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

To rename a volume in Catalog Explorer:

1. In your Databricks workspace, click Catalog.

2. Search or browse for the volume that you want to rename and select it.

3. Click the to the right of the volume name and select Rename.

4. Enter a name for the volume.

5. 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:

1. In your Databricks workspace, click Catalog.

2. Search or browse for the volume that you want to modify change permissions on and select it.

3. Click the Permissions tab. Granted and inherited privleges on the volume are displayed.

To grant new privileges, do the following:

1. Click Grant.

2. Type to search for a principal. Select the principal you wish to grant privileges. You can select multiple principals.

3. Select the privileges you wish to grant.

4. 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:

1. Select one or more grants.

2. Click Revoke.

3. 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:

1. In your Databricks workspace, click Catalog.

2. Search or browse for the volume that you want to change ownership for and select it.

3. In the About this volume pane, click the next to Owner.

4. Type to search for a principal and select it.

5. 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.