Manage shares for Delta Sharing

This page describes how to view, update, and delete existing Delta Sharing shares in Databricks. A share is a securable object in Unity Catalog that bundles tables, views, volumes, notebooks, AI models, and other data assets for sharing with one or more recipients.

To create a new share or add data assets to an existing share, see Create shares for Delta Sharing. To grant a recipient access to a share, see Manage access to Delta Sharing data shares (for providers). To manage the data recipients you share with, see Manage data recipients for Delta Sharing.

To learn more about the sharing model, see Shares, providers, and recipients.

Requirements

Check that you meet the listed requirements for each task you want to complete.

Task	Requirements
Grant recipient access to a share	Be a metastore admin. OR Be a user with delegated permissions or ownership on both the share and the recipient objects, which means the user must fulfill both of the following requirements: Have both USE SHARE and SET SHARE PERMISSION privileges OR be the share owner Have USE RECIPIENT privilege OR be the recipient owner
View shares	Be a metastore admin (can view all). OR Be a user with the USE SHARE privilege (can view all). OR Be the share object owner.
Update share owner	Be a metastore admin.
Update share name	Have the CREATE SHARE privilege. Be the share owner.
Update other share properties	Be the share owner.
Delete shares	Be the share object owner.

View shares and share details

Check that you meet the requirements before viewing shares and share details.

To view a list of shares or details about a share, use Catalog Explorer, the Databricks Unity Catalog CLI, or SQL commands in a Databricks notebook or the Databricks SQL query editor.

Share details include the following:

• The share's owner, creator, creation timestamp, updater, updated timestamp, comments.
• Data assets in the share.
• Recipients with access to the share.

Catalog Explorer

1. In your Databricks workspace, click Catalog.

2. At the top of the Catalog pane, click the gear icon and select Delta Sharing.

   Alternatively, from the Quick access page, click the Delta Sharing > button.

3. Open the Shares tab to view a list of shares.

4. View share details on the Details tab.

SQL

To view a list of shares, run the following command in a notebook or the Databricks SQL query editor. Optionally, replace <pattern> with a LIKE predicate.

SQL

SHOW SHARES [LIKE <pattern>];

To view details about a specific share, run the following command.

SQL

DESCRIBE SHARE <share-name>;

To view details about all tables, views, and volumes in a share, run the following command.

SQL

SHOW ALL IN SHARE <share-name>;

CLI

To view a list of shares, run the following command using the Databricks CLI.

Bash

databricks shares list

To view details about a specific share, run the following command.

Bash

databricks shares get <share-name>

View the recipients who have permissions on a share

Check that you meet the requirements before viewing the recipients.

To view the list of shares that a recipient has been granted access to, use Catalog Explorer, the Databricks Unity Catalog CLI, or the SHOW GRANTS TO RECIPIENT SQL command in a Databricks notebook or the Databricks SQL query editor.

Catalog Explorer

1. In your Databricks workspace, click Catalog.

2. At the top of the Catalog pane, click the gear icon and select Delta Sharing.

   Alternatively, from the Quick access page, click the Delta Sharing > button.

3. On the Shared by me tab, find and select the recipient.

4. Go to the Recipients tab to view the list of recipients who can access the share.

SQL

Run the following command in a notebook or the Databricks SQL query editor.

SQL

SHOW GRANTS ON SHARE <share-name>;

CLI

Run the following command using the Databricks CLI.

Bash

databricks shares share-permissions <share-name>

Update shares

Check that you meet the requirements before making updates to a share.

You can update a share in the following ways:

• Rename a share.
• Remove tables, views, volumes, and schemas from a share.
• Add or update a comment on a share.
• Rename a table's alias (the table name displayed to the recipient).
• Enable or disable access to a table's history data, allowing recipients to perform time travel queries or streaming reads of the table.
• Add, update, or remove partition definitions.
• Change the share owner.

To make these updates to shares, use Catalog Explorer, the Databricks Unity Catalog CLI, or SQL commands in a Databricks notebook or the Databricks SQL query editor. However, you cannot use Catalog Explorer to rename the share.

Catalog Explorer

1. In your Databricks workspace, click Catalog.

2. At the top of the Catalog pane, click the gear icon and select Delta Sharing.

   Alternatively, from the Quick access page, click the Delta Sharing > button.

3. On the Shared by me tab, find the share you want to update and click its name.

On the share details page, do the following:

• Click the edit icon next to the Owner or Comment field to update these values.
• Click the kebab menu button in an asset row to remove it.
• Click Manage assets > Edit assets to update all other properties:
  • To remove an asset, clear the checkbox next to the asset.
  • To add, update, or remove partition definitions, click Advanced options.

SQL

Run the following commands in a notebook or the Databricks SQL editor.

Rename a share:

SQL

ALTER SHARE <share-name> RENAME TO <new-share-name>;

Remove tables from a share:

SQL

ALTER SHARE share_name REMOVE TABLE <table-name>;

Remove volumes from a share:

SQL

ALTER SHARE share_name REMOVE VOLUME <volume-name>;

Add or update a comment on a share:

SQL

COMMENT ON SHARE <share-name> IS '<comment>';

Add or modify partitions for a table in a share:

SQL

ALTER SHARE <share-name> ADD TABLE <table-name> PARTITION(<clause>);

Change share owner:

SQL

ALTER SHARE <share-name> OWNER TO  '<principal>'

-- Principal must be an account-level user email address or group name.

Enable history sharing for a table:

SQL

ALTER SHARE <share-name> ADD TABLE <table-name> WITH HISTORY;

For details about ALTER SHARE parameters, see ALTER SHARE.

CLI

Run the following commands using the Databricks CLI.

Rename a share:

Bash

databricks shares update <share-name> --name <new-share-name>

Remove tables from a share:

Bash

databricks shares update <share-name> \
  --json '{
    "updates": [
      {
        "action": "REMOVE",
        "data_object": {
          "name": "<table-full-name>",
          "data_object_type": "TABLE",
          "shared_as": "<table-alias>"
        }
      }
    ]
  }'

Remove volumes from a share (using Databricks CLI 0.210 or above):

Bash

databricks shares update <share-name> \
  --json '{
    "updates": [
      {
        "action": "REMOVE",
        "data_object": {
          "name": "<volume-full-name>",
          "data_object_type": "VOLUME",
          "string_shared_as": "<volume-alias>"
        }
      }
    ]
  }'

note

Use the name property if there is no alias for the volume. Use string_shared_as if there is an alias.

Add or update a comment on a share:

Bash

databricks shares update <share-name> --comment '<comment>'

Change share owner:

Bash

databricks  shares update <share-name> --owner '<principal>'

Principal must be an account-level user email address or group name.

Considerations when updating share owner

Who the share owner is affects how authorization and security features, such as ABAC policies, are evaluated. Transferring share ownership to an over-privileged user allows recipients to have over-privileged access if you have a table or schema secured by ABAC policies.

Delete shares

When you delete a share, recipients can no longer access the shared data. Check that you meet the requirements before deleting a share object.

To delete a share, use Catalog Explorer, the Databricks Unity Catalog CLI, or the DELETE SHARE SQL command in a Databricks notebook or the Databricks SQL query editor. You must be an owner of the share.

Catalog Explorer

1. In your Databricks workspace, click Catalog.

2. At the top of the Catalog pane, click the gear icon and select Delta Sharing.

   Alternatively, from the Quick access page, click the Delta Sharing > button.

3. On the Shared by me tab, find the share you want to delete and click its name.

4. Click the kebab menu and select Delete.

5. On the confirmation dialog, click Delete.

SQL

Run the following command in a notebook or the Databricks SQL query editor.

SQL

DROP SHARE [IF EXISTS] <share-name>;

CLI

Run the following command using the Databricks CLI.

Bash

databricks shares delete <share-name>