Create and manage volumes

  • Article

This article contains syntax examples for creating, managing, and dropping Unity Catalog 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.

Catalog Explorer

To create a volume in Catalog Explorer:

  1. In your Azure Databricks workspace, click Catalog icon 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.

SQL

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 'abfss://<container-name>@<storage-account>.dfs.core.chinacloudapi.cn/<path>/<directory>';

Note

When you define an external volume, cloud URI access to data under the volume path is governed by the privileges granted on the volume, not the privileges granted on the external location where the volume is stored.

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 and services using Unity Catalog.

Drop a volume

Catalog Explorer

To drop a volume in Catalog Explorer:

  1. In your Azure Databricks workspace, click Catalog icon Catalog.
  2. Search or browse for the volume that you want to drop and select it.
  3. Click the Kebab menu to the right of the volume name and select Delete.
  4. Click Delete in the dialog that appears to confirm.

SQL

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

Catalog Explorer

To rename a volume in Catalog Explorer:

  1. In your Azure Databricks workspace, click Catalog icon Catalog.
  2. Search or browse for the volume that you want to rename and select it.
  3. Click the Kebab menu to the right of the volume name and select Rename.
  4. Enter a name for the volume.
  5. Click Save.

SQL

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

Catalog Explorer

To change permissions a volume in Catalog Explorer, start by navigating to the permissions UI:

  1. In your Azure Databricks workspace, click Catalog icon 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.

SQL

Use GRANT and REVOKE to change permissions on a volume.

For example, the following syntax grants READ VOLUME on a volume:

GRANT READ VOLUME ON VOLUME <volume-name> TO <principal>

The following syntax to revokes WRITE VOLUME on a volume:

REVOKE WRITE VOLUME 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

Catalog Explorer

To change the owner of a volume in Catalog Explorer, do the following:

  1. In your Azure Databricks workspace, click Catalog icon 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 Edit Icon next to Owner.
  4. Type to search for a principal and select it.
  5. Click Save.

SQL

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.