volumes

Creates, updates, deletes, gets or lists a volumes resource.

Overview

Name	volumes
Type	Resource
Id	databricks_workspace.catalog.volumes

Fields

The following fields are returned by SELECT queries:

read

Name	Datatype	Description
name	string	The name of the volume
metastore_id	string	The unique identifier of the metastore
volume_id	string	The unique identifier of the volume
catalog_name	string	The name of the catalog where the schema and the volume are
full_name	string	The three-level (fully qualified) name of the volume
schema_name	string	The name of the schema where the volume is
access_point	string
browse_only	boolean	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.
comment	string	The comment attached to the volume
created_at	integer
created_by	string	The identifier of the user who created the volume
▶encryption_details	object	Encryption options that apply to clients connecting to cloud storage.
owner	string	The identifier of the user who owns the volume
storage_location	string	The storage location on the cloud
updated_at	integer
updated_by	string	The identifier of the user who updated the volume last time
volume_type	string	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] [Learn more]: https://docs.databricks.com/aws/en/volumes/managed-vs-external (EXTERNAL, MANAGED)

list

Name	Datatype	Description
name	string	The name of the volume
metastore_id	string	The unique identifier of the metastore
volume_id	string	The unique identifier of the volume
catalog_name	string	The name of the catalog where the schema and the volume are
full_name	string	The three-level (fully qualified) name of the volume
schema_name	string	The name of the schema where the volume is
access_point	string
browse_only	boolean	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.
comment	string	The comment attached to the volume
created_at	integer
created_by	string	The identifier of the user who created the volume
▶encryption_details	object	Encryption options that apply to clients connecting to cloud storage.
owner	string	The identifier of the user who owns the volume
storage_location	string	The storage location on the cloud
updated_at	integer
updated_by	string	The identifier of the user who updated the volume last time
volume_type	string	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] [Learn more]: https://docs.databricks.com/aws/en/volumes/managed-vs-external (EXTERNAL, MANAGED)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
read	select	name, deployment_name	include_browse	Gets a volume from the metastore for a specific catalog and schema.
list	select	catalog_name, schema_name, deployment_name	include_browse, max_results, page_token	Gets an array of volumes for the current metastore under the parent catalog and schema.
create	insert	deployment_name, catalog_name, schema_name, name, volume_type		Creates a new volume.
update	update	name, deployment_name		Updates the specified volume under the specified parent catalog and schema.
delete	delete	name, deployment_name		Deletes a volume from the specified parent catalog and schema.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
catalog_name	string	The identifier of the catalog
deployment_name	string	The Databricks Workspace Deployment Name (default: dbc-abcd0123-a1bc)
name	string	The three-level (fully qualified) name of the volume
schema_name	string	The identifier of the schema
include_browse	boolean	Whether to include volumes in the response for which the principal can only access selective metadata for
max_results	integer	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_token	string	Opaque token returned by a previous request. It must be included in the request to retrieve the next page of results (pagination).

SELECT examples

read

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

SELECT
name,
metastore_id,
volume_id,
catalog_name,
full_name,
schema_name,
access_point,
browse_only,
comment,
created_at,
created_by,
encryption_details,
owner,
storage_location,
updated_at,
updated_by,
volume_type
FROM databricks_workspace.catalog.volumes
WHERE name = '{{ name }}' -- required
AND deployment_name = '{{ deployment_name }}' -- required
AND include_browse = '{{ include_browse }}'
;

list

Gets an array of volumes for the current metastore under the parent catalog and schema.

SELECT
name,
metastore_id,
volume_id,
catalog_name,
full_name,
schema_name,
access_point,
browse_only,
comment,
created_at,
created_by,
encryption_details,
owner,
storage_location,
updated_at,
updated_by,
volume_type
FROM databricks_workspace.catalog.volumes
WHERE catalog_name = '{{ catalog_name }}' -- required
AND schema_name = '{{ schema_name }}' -- required
AND deployment_name = '{{ deployment_name }}' -- required
AND include_browse = '{{ include_browse }}'
AND max_results = '{{ max_results }}'
AND page_token = '{{ page_token }}'
;

INSERT examples

create

Creates a new volume.

INSERT INTO databricks_workspace.catalog.volumes (
catalog_name,
schema_name,
name,
volume_type,
comment,
storage_location,
deployment_name
)
SELECT 
'{{ catalog_name }}' /* required */,
'{{ schema_name }}' /* required */,
'{{ name }}' /* required */,
'{{ volume_type }}' /* required */,
'{{ comment }}',
'{{ storage_location }}',
'{{ deployment_name }}'
RETURNING
name,
metastore_id,
volume_id,
catalog_name,
full_name,
schema_name,
access_point,
browse_only,
comment,
created_at,
created_by,
encryption_details,
owner,
storage_location,
updated_at,
updated_by,
volume_type
;

Manifest

# Description fields are for documentation purposes
- name: volumes
props:
  - name: deployment_name
    value: "{{ deployment_name }}"
    description: Required parameter for the volumes resource.
  - name: catalog_name
    value: "{{ catalog_name }}"
    description: |
      The name of the catalog where the schema and the volume are
  - name: schema_name
    value: "{{ schema_name }}"
    description: |
      The name of the schema where the volume is
  - name: name
    value: "{{ name }}"
    description: |
      The name of the volume
  - name: volume_type
    value: "{{ volume_type }}"
    description: |
      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] [Learn more]: https://docs.databricks.com/aws/en/volumes/managed-vs-external
  - name: comment
    value: "{{ comment }}"
    description: |
      The comment attached to the volume
  - name: storage_location
    value: "{{ storage_location }}"
    description: |
      The storage location on the cloud

UPDATE examples

update

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

UPDATE databricks_workspace.catalog.volumes
SET 
comment = '{{ comment }}',
new_name = '{{ new_name }}',
owner = '{{ owner }}'
WHERE 
name = '{{ name }}' --required
AND deployment_name = '{{ deployment_name }}' --required
RETURNING
name,
metastore_id,
volume_id,
catalog_name,
full_name,
schema_name,
access_point,
browse_only,
comment,
created_at,
created_by,
encryption_details,
owner,
storage_location,
updated_at,
updated_by,
volume_type;

DELETE examples

delete

Deletes a volume from the specified parent catalog and schema.

DELETE FROM databricks_workspace.catalog.volumes
WHERE name = '{{ name }}' --required
AND deployment_name = '{{ deployment_name }}' --required
;