Volume
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
MANAGEDEXTERNAL
- storage_locationstring
The cloud storage URL where the files of the volume are stored. For an external volume, it must be set on creation to a path within an existing external location. For a managed volume, it must be omitted on creation; the volume is placed under the managed storage location of the parent schema, catalog, or metastore, and the assigned path is returned in this field.
- ownerstring
The user or group that owns the volume. The user who creates a volume becomes its owner; the owner can be changed afterwards with an update.
- commentstring[ 1 .. 65536 ] characters
The comment attached to the volume
- full_namestringOutput only
The three-level (fully qualified) name of the volume, in the form catalog_name.schema_name.name.
- volume_idstringOutput only
The unique identifier of the volume
- metastore_idstringOutput only
The unique identifier of the metastore
- created_atint64Output only
Time at which the volume was created, in epoch milliseconds.
- created_bystring
The identifier of the user who created the volume
- updated_atint64Output only
Time at which the volume was last updated, in epoch milliseconds.
- updated_bystringOutput only
The identifier of the user who updated the volume last time
- access_pointstringOutput only
The AWS access point to use when accessing S3 for the storage location of this volume.
- browse_onlybooleanOutput only
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.
Get a Volume GA
GET
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_argstringRequiredpath
The fully qualified name of the volume.
- include_browsebooleanquery
Whether to include volumes for which the principal can only access selective metadata through the BROWSE privilege.
Response
Returns the VolumeInfo object.
List Volumes GA
GET
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_namestringRequiredquery
The name of the catalog that contains the schema.
- schema_namestringRequiredquery
The name of the schema whose volumes are listed.
- include_browsebooleanquery
Whether to include volumes for which the principal can only access selective metadata through the BROWSE privilege.
- max_resultsint32<= 10000query
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.
- 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.
Create a Volume GA
POST
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 the 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 must also 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.
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
MANAGEDEXTERNAL
- storage_locationstring
The cloud storage URL where the files of the volume are stored. For an external volume, it must be set on creation to a path within an existing external location. For a managed volume, it must be omitted on creation; the volume is placed under the managed storage location of the parent schema, catalog, or metastore, and the assigned path is returned in this field.
- ownerstring
The user or group that owns the volume. The user who creates a volume becomes its owner; the owner can be changed afterwards with an update.
- commentstring[ 1 .. 65536 ] characters
The comment attached to the volume
- created_bystring
The identifier of the user who created the volume
Response
Returns the VolumeInfo object.
Update a Volume GA
PATCH
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 can be updated.
API scopes: unity-catalog
Parameters
- full_name_argstringRequiredpath
The three-level (fully qualified) name of the volume
Request body
- new_namestring
The new name for the volume. Set it to rename 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
MANAGEDEXTERNAL
- storage_locationstring
The cloud storage URL where the files of the volume are stored. For an external volume, it must be set on creation to a path within an existing external location. For a managed volume, it must be omitted on creation; the volume is placed under the managed storage location of the parent schema, catalog, or metastore, and the assigned path is returned in this field.
- ownerstring
The user or group that owns the volume. The user who creates a volume becomes its owner; the owner can be changed afterwards with an update.
- commentstring[ 1 .. 65536 ] characters
The comment attached to the volume
- created_bystring
The identifier of the user who created the volume
Response
Returns the VolumeInfo object.
Delete a Volume GA
DELETE
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_argstringRequiredpath
The three-level (fully qualified) name of the volume