shares

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

Overview

Name	shares
Type	Resource
Id	databricks_workspace.sharing.shares

Fields

The following fields are returned by SELECT queries:

get

Name	Datatype	Description
name	string	Name of the share.
comment	string
created_at	integer	Time at which this share was created, in epoch milliseconds.
created_by	string	Username of share creator.
▶objects	array	A list of shared data objects within the share.
owner	string	Username of current owner of share.
storage_location	string	Storage Location URL (full path) for the share.
storage_root	string	Storage root URL for the share.
updated_at	integer	Time at which this share was updated, in epoch milliseconds.
updated_by	string	Username of share updater.

list

Name	Datatype	Description
name	string	Name of the share.
comment	string
created_at	integer	Time at which this share was created, in epoch milliseconds.
created_by	string	Username of share creator.
▶objects	array	A list of shared data objects within the share.
owner	string	Username of current owner of share.
storage_location	string	Storage Location URL (full path) for the share.
storage_root	string	Storage root URL for the share.
updated_at	integer	Time at which this share was updated, in epoch milliseconds.
updated_by	string	Username of share updater.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	name, deployment_name	include_shared_data	Gets a data object share from the metastore. The caller must have the USE_SHARE privilege on the
list	select	deployment_name	max_results, page_token	Gets an array of data object shares from the metastore. If the caller has the USE_SHARE privilege on
create	insert	deployment_name, name		Creates a new share for data objects. Data objects can be added after creation with update. The
update	update	name, deployment_name		Updates the share with the changes and data objects in the request. The caller must be the owner of
delete	delete	name, deployment_name		Deletes a data object share from the metastore. The caller must be an owner of the share.

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
deployment_name	string	The Databricks Workspace Deployment Name (default: dbc-abcd0123-a1bc)
name	string	The name of the share.
include_shared_data	boolean	Query for data to include in the share.
max_results	integer	Maximum number of shares to return. - when set to 0, the page length is set to a server configured value (recommended); - when set to a value greater than 0, the page length is the minimum of this value and a server configured value; - when set to a value less than 0, an invalid parameter error is returned; - If not set, all valid shares are returned (not recommended). - Note: The number of returned shares might be less than the specified max_results size, even zero. The only definitive indication that no further shares can be fetched is when the next_page_token is unset from the response.
page_token	string	Opaque pagination token to go to next page based on previous query.

SELECT examples

get

Gets a data object share from the metastore. The caller must have the USE_SHARE privilege on the

SELECT
name,
comment,
created_at,
created_by,
objects,
owner,
storage_location,
storage_root,
updated_at,
updated_by
FROM databricks_workspace.sharing.shares
WHERE name = '{{ name }}' -- required
AND deployment_name = '{{ deployment_name }}' -- required
AND include_shared_data = '{{ include_shared_data }}'
;

list

Gets an array of data object shares from the metastore. If the caller has the USE_SHARE privilege on

SELECT
name,
comment,
created_at,
created_by,
objects,
owner,
storage_location,
storage_root,
updated_at,
updated_by
FROM databricks_workspace.sharing.shares
WHERE deployment_name = '{{ deployment_name }}' -- required
AND max_results = '{{ max_results }}'
AND page_token = '{{ page_token }}'
;

INSERT examples

create

Creates a new share for data objects. Data objects can be added after creation with update. The

INSERT INTO databricks_workspace.sharing.shares (
name,
comment,
storage_root,
deployment_name
)
SELECT 
'{{ name }}' /* required */,
'{{ comment }}',
'{{ storage_root }}',
'{{ deployment_name }}'
RETURNING
name,
comment,
created_at,
created_by,
objects,
owner,
storage_location,
storage_root,
updated_at,
updated_by
;

Manifest

# Description fields are for documentation purposes
- name: shares
props:
  - name: deployment_name
    value: "{{ deployment_name }}"
    description: Required parameter for the shares resource.
  - name: name
    value: "{{ name }}"
    description: |
      Name of the share.
  - name: comment
    value: "{{ comment }}"
    description: |
      User-provided free-form text description.
  - name: storage_root
    value: "{{ storage_root }}"
    description: |
      Storage root URL for the share.

UPDATE examples

update

Updates the share with the changes and data objects in the request. The caller must be the owner of

UPDATE databricks_workspace.sharing.shares
SET 
comment = '{{ comment }}',
new_name = '{{ new_name }}',
owner = '{{ owner }}',
storage_root = '{{ storage_root }}',
updates = '{{ updates }}'
WHERE 
name = '{{ name }}' --required
AND deployment_name = '{{ deployment_name }}' --required
RETURNING
name,
comment,
created_at,
created_by,
objects,
owner,
storage_location,
storage_root,
updated_at,
updated_by;

DELETE examples

delete

Deletes a data object share from the metastore. The caller must be an owner of the share.

DELETE FROM databricks_workspace.sharing.shares
WHERE name = '{{ name }}' --required
AND deployment_name = '{{ deployment_name }}' --required
;