Volume

View as Markdown

GetGET /api/2.1/unity-catalog/volumes/{full_name_arg}ListGET /api/2.1/unity-catalog/volumesCreatePOST /api/2.1/unity-catalog/volumesUpdatePATCH /api/2.1/unity-catalog/volumes/{full_name_arg}DeleteDELETE /api/2.1/unity-catalog/volumes/{full_name_arg}

VolumeInfo object

namestring

The name of the volume

catalog_namestring

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

schema_namestring

The name of the schema where the volume is

volume_typestring

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. Learn more

Values: MANAGED, EXTERNAL

storage_locationstring

The storage location on the cloud

ownerstring

The identifier of the user who owns the volume

commentstring

The comment attached to the volume

Constraints: [ 1 .. 65536 ] characters

full_namestring

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

volume_idstring

The unique identifier of the volume

metastore_idstring

The unique identifier of the metastore

created_atint64

created_bystring

The identifier of the user who created the volume

updated_atint64

updated_bystring

The identifier of the user who updated the volume last time

access_pointstring

The AWS access point to use when accesing s3 for this external location.

browse_onlyboolean

Indicates whether the principal is limited to retrieving metadata for the associated object through the BROWSE privilege when include_browse is enabled in the request.

View as Markdown

The VolumeInfo object

{
  "name": "string",
  "catalog_name": "string",
  "schema_name": "string",
  "volume_type": "string",
  "storage_location": "string",
  "owner": "string",
  "comment": "string",
  "full_name": "string",
  "volume_id": "string",
  "metastore_id": "string",
  "created_at": 0,
  "created_by": "string",
  "updated_at": 0,
  "updated_by": "string",
  "access_point": "string",
  "browse_only": true
}

Get GA

GET /api/2.1/unity-catalog/volumes/{full_name_arg}

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

API scopes: unity-catalog

Parameters

full_name_argstringpath

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

include_browsebooleanquery

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

Response

Returns the VolumeInfo object.

View as Markdown

Response

{
  "name": "string",
  "catalog_name": "string",
  "schema_name": "string",
  "volume_type": "string",
  "storage_location": "string",
  "owner": "string",
  "comment": "string",
  "full_name": "string",
  "volume_id": "string",
  "metastore_id": "string",
  "created_at": 0,
  "created_by": "string",
  "updated_at": 0,
  "updated_by": "string",
  "access_point": "string",
  "browse_only": true
}

List GA

GET /api/2.1/unity-catalog/volumes

Gets an array of 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 receive 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.

PAGINATION BEHAVIOR: The API is by default paginated, a page may contain zero results while still providing a next_page_token. Clients must continue reading pages until next_page_token is absent, which is the only indication that the end of results has been reached.

API scopes: unity-catalog

Parameters

catalog_namestringquery

The identifier of the catalog

schema_namestringquery

The identifier of the schema

include_browsebooleanquery

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

max_resultsint32query

Maximum number of volumes to return (page length).

If not set, the page length is set to a server configured value (10000, as of 1/29/2024).

• when set to a value greater than 0, the page length is the minimum of this value and a server configured value (10000, as of 1/29/2024);
• when set to 0, the page length is set to a server configured value (10000, as of 1/29/2024) (recommended);
• when set to a value less than 0, an invalid parameter error is returned;

Note: this parameter controls only the maximum number of volumes to return. The actual number of volumes returned in a page may be smaller than this value, including 0, even if there are more pages.

Constraints: <= 10000

page_tokenstringquery

Opaque token returned by a previous request. It must be included in the request to retrieve the next page of results (pagination).

Response

Returns a list of VolumeInfo objects.

View as Markdown

Response

{
  "volumes": [
    {
      "name": "string",
      "catalog_name": "string",
      "schema_name": "string",
      "volume_type": "string",
      "storage_location": "string",
      "owner": "string",
      "comment": "string",
      "full_name": "string",
      "volume_id": "string",
      "metastore_id": "string",
      "created_at": 0,
      "created_by": "string",
      "updated_at": 0,
      "updated_by": "string",
      "access_point": "string",
      "browse_only": true
    }
  ],
  "next_page_token": "string"
}

Create GA

POST /api/2.1/unity-catalog/volumes

Creates 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, following conditions also need to satisfy

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

API scopes: unity-catalog

Request body

namestring

The name of the volume

catalog_namestring

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

schema_namestring

The name of the schema where the volume is

volume_typestring

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. Learn more

Values: MANAGED, EXTERNAL

storage_locationstring

The storage location on the cloud

ownerstring

The identifier of the user who owns the volume

commentstring

The comment attached to the volume

Constraints: [ 1 .. 65536 ] characters

full_namestring

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

volume_idstring

The unique identifier of the volume

metastore_idstring

The unique identifier of the metastore

created_atint64

created_bystring

The identifier of the user who created the volume

updated_atint64

updated_bystring

The identifier of the user who updated the volume last time

access_pointstring

The AWS access point to use when accesing s3 for this external location.

browse_onlyboolean

Indicates whether the principal is limited to retrieving metadata for the associated object through the BROWSE privilege when include_browse is enabled in the request.

Response

Returns the VolumeInfo object.

View as Markdown

Request

{
  "name": "string",
  "catalog_name": "string",
  "schema_name": "string",
  "volume_type": "string",
  "storage_location": "string",
  "owner": "string",
  "comment": "string",
  "full_name": "string",
  "volume_id": "string",
  "metastore_id": "string",
  "created_at": 0,
  "created_by": "string",
  "updated_at": 0,
  "updated_by": "string",
  "access_point": "string",
  "browse_only": true
}

Response

{
  "name": "string",
  "catalog_name": "string",
  "schema_name": "string",
  "volume_type": "string",
  "storage_location": "string",
  "owner": "string",
  "comment": "string",
  "full_name": "string",
  "volume_id": "string",
  "metastore_id": "string",
  "created_at": 0,
  "created_by": "string",
  "updated_at": 0,
  "updated_by": "string",
  "access_point": "string",
  "browse_only": true
}

Update GA

PATCH /api/2.1/unity-catalog/volumes/{full_name_arg}

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

API scopes: unity-catalog

Parameters

full_name_argstringpath

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

Request body

new_namestring

New name for the volume.

namestring

The name of the volume

catalog_namestring

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

schema_namestring

The name of the schema where the volume is

volume_typestring

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. Learn more

Values: MANAGED, EXTERNAL

storage_locationstring

The storage location on the cloud

ownerstring

The identifier of the user who owns the volume

commentstring

The comment attached to the volume

Constraints: [ 1 .. 65536 ] characters

full_namestring

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

volume_idstring

The unique identifier of the volume

metastore_idstring

The unique identifier of the metastore

created_atint64

created_bystring

The identifier of the user who created the volume

updated_atint64

updated_bystring

The identifier of the user who updated the volume last time

access_pointstring

The AWS access point to use when accesing s3 for this external location.

browse_onlyboolean

Indicates whether the principal is limited to retrieving metadata for the associated object through the BROWSE privilege when include_browse is enabled in the request.

Response

Returns the VolumeInfo object.

View as Markdown

Request

{
  "new_name": "string",
  "name": "string",
  "catalog_name": "string",
  "schema_name": "string",
  "volume_type": "string",
  "storage_location": "string",
  "owner": "string",
  "comment": "string",
  "full_name": "string",
  "volume_id": "string",
  "metastore_id": "string",
  "created_at": 0,
  "created_by": "string",
  "updated_at": 0,
  "updated_by": "string",
  "access_point": "string",
  "browse_only": true
}

Response

{
  "name": "string",
  "catalog_name": "string",
  "schema_name": "string",
  "volume_type": "string",
  "storage_location": "string",
  "owner": "string",
  "comment": "string",
  "full_name": "string",
  "volume_id": "string",
  "metastore_id": "string",
  "created_at": 0,
  "created_by": "string",
  "updated_at": 0,
  "updated_by": "string",
  "access_point": "string",
  "browse_only": true
}

Delete GA

DELETE /api/2.1/unity-catalog/volumes/{full_name_arg}

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

API scopes: unity-catalog

Parameters

full_name_argstringpath

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

View as Markdown

Response

{}