volumes command group

The volumes command group within the Databricks CLI contains commands to manage volumes in Unity Catalog. Volumes provide features for accessing, storing, governing, organizing and processing files. See What are Unity Catalog volumes?.

databricks volumes create

Create a new volume.

The user could create either an external volume or a managed volume. An external volume will be created in the specified external location, while a managed volume will be located in the default location which is specified by the parent schema, or the parent catalog, or the metastore.

For the volume creation to succeed, the user must satisfy following conditions:

• The caller must be a metastore admin, or be the owner of the parent catalog and schema, or have the USE_CATALOG privilege on the parent catalog and the USE_SCHEMA privilege on the parent schema.
• The caller must have CREATE VOLUME privilege on the parent schema.

For an external volume, the following conditions also need to be satisfied:

• The caller must have CREATE EXTERNAL VOLUME privilege on the external location.
• There are no other tables, nor volumes existing in the specified storage location. - The specified storage location is not under the location of other tables, nor volumes, or catalogs or schemas.

databricks volumes create CATALOG_NAME SCHEMA_NAME NAME VOLUME_TYPE [flags]

Arguments

CATALOG_NAME

    The name of the catalog where the schema and the volume are

SCHEMA_NAME

    The name of the schema where the volume is

NAME

    The name of the volume

VOLUME_TYPE

    The type of the volume. An external volume is located in the specified external location. A managed volume is located in the default location which is specified by the parent schema, or the parent catalog, or the Metastore. See Managed vs. external volumes. Supported values: EXTERNAL, MANAGED

Options

--comment string

    The comment attached to the volume.

--json JSON

    The inline JSON string or the @path to the JSON file with the request body.

--storage-location string

    The storage location on the cloud.

Global flags

Examples

The following example creates a managed volume:

databricks volumes create my_catalog my_schema my_volume MANAGED

The following example creates an external volume with a comment:

databricks volumes create my_catalog my_schema my_external_volume EXTERNAL --storage-location s3://my-bucket/my-volume --comment "External volume for data processing"

databricks volumes delete

Delete a volume from the specified parent catalog and schema.

The caller must be a metastore admin or an owner of the volume. For the latter case, the caller must also be the owner or have the USE_CATALOG privilege on the parent catalog and the USE_SCHEMA privilege on the parent schema.

databricks volumes delete NAME [flags]

Arguments

NAME

    The three-level (fully qualified) name of the volume

Options

Global flags

Examples

The following example deletes a volume:

databricks volumes delete my_catalog.my_schema.my_volume

databricks volumes list

List volumes for the current metastore under the parent catalog and schema.

The returned volumes are filtered based on the privileges of the calling user. For example, the metastore admin is able to list all the volumes. A regular user needs to be the owner or have the READ VOLUME privilege on the volume to recieve the volumes in the response. For the latter case, the caller must also be the owner or have the USE_CATALOG privilege on the parent catalog and the USE_SCHEMA privilege on the parent schema.

There is no guarantee of a specific ordering of the elements in the array.

databricks volumes list CATALOG_NAME SCHEMA_NAME [flags]

Arguments

CATALOG_NAME

    The identifier of the catalog

SCHEMA_NAME

    The identifier of the schema

Options

--include-browse

    Whether to include volumes in the response for which the principal can only access selective metadata for.

--max-results int

    Maximum number of volumes to return (page length).

--page-token string

    Opaque token returned by a previous request.

Global flags

Examples

The following example lists all volumes in a catalog and schema:

databricks volumes list my_catalog my_schema

databricks volumes read

Get a volume from the metastore for a specific catalog and schema.

The caller must be a metastore admin or an owner of (or have the READ VOLUME privilege on) the volume. For the latter case, the caller must also be the owner or have the USE_CATALOG privilege on the parent catalog and the USE_SCHEMA privilege on the parent schema.

databricks volumes read NAME [flags]

Arguments

NAME

    The three-level (fully qualified) name of the volume

Options

--include-browse

    Whether to include volumes in the response for which the principal can only access selective metadata for.

Global flags

Examples

The following example gets information about a volume:

databricks volumes read my_catalog.my_schema.my_volume

The following example gets volume information including browse metadata:

databricks volumes read my_catalog.my_schema.my_volume --include-browse

databricks volumes update

Update the specified volume under the specified parent catalog and schema.

The caller must be a metastore admin or an owner of the volume. For the latter case, the caller must also be the owner or have the USE_CATALOG privilege on the parent catalog and the USE_SCHEMA privilege on the parent schema.

Currently only the name, the owner or the comment of the volume could be updated.

databricks volumes update NAME [flags]

Arguments

NAME

    The three-level (fully qualified) name of the volume

Options

--comment string

    The comment attached to the volume.

--json JSON

    The inline JSON string or the @path to the JSON file with the request body.

--new-name string

    New name for the volume.

--owner string

    The identifier of the user who owns the volume.

Global flags

Examples

The following example updates a volume's comment:

databricks volumes update my_catalog.my_schema.my_volume --comment "Updated comment for my volume"

The following example changes the owner of a volume:

databricks volumes update my_catalog.my_schema.my_volume --owner someone@example.com

The following example renames a volume:

databricks volumes update my_catalog.my_schema.my_volume --new-name my_new_volume_name

Global flags

--debug

  Whether to enable debug logging.

-h or --help

    Display help for the Databricks CLI or the related command group or the related command.

--log-file string

    A string representing the file to write output logs to. If this flag is not specified then the default is to write output logs to stderr.

--log-format format

    The log format type, text or json. The default value is text.

--log-level string

    A string representing the log format level. If not specified then the log format level is disabled.

-o, --output type

    The command output type, text or json. The default value is text.

-p, --profile string

    The name of the profile in the ~/.databrickscfg file to use to run the command. If this flag is not specified then if it exists, the profile named DEFAULT is used.

--progress-format format

    The format to display progress logs: default, append, inplace, or json

-t, --target string

    If applicable, the bundle target to use