Create and manage shares for Delta Sharing

This article explains how to create and manage shares for Delta Sharing.

A share is a named object that contains a collection of tables in a Unity Catalog metastore that you want to share with one or more recipients. A share can contain tables from only one metastore. You can add or remove tables from a share at any time.

For more information, see Shares and recipients.

Requirements

To create a share:

  • You must be a metastore admin or have the CREATE_SHARE privilege for the Unity Catalog metastore where the data you want to share is registered.

  • You must create the share using a Databricks workspace that has that Unity Catalog metastore attached.

To add tables to a share, you must be one of these:

  • A metastore admin.

  • The share owner, who must also have the SELECT privilege on the table. You must keep that privilege in order for the table to continue to be shared. If you lose it, the recipient cannot access the table through the share. Databricks therefore recommends that you use a group as the share owner.

Compute requirements:

  • If you use a Databricks notebook to create the share, your cluster must use Databricks Runtime 11.2 or above and a Unity-Catalog-capable cluster access mode.

  • If you use Databricks SQL, your SQL warehouse must use compute version 2022.35 and above.

Create a share object

To create a share, you can use Data Explorer, the Databricks Unity Catalog CLI, or the CREATE SHARE SQL command in a Databricks notebook or the Databricks SQL query editor.

Permissions required: Metastore admin or user with the CREATE_SHARE privilege for the metastore.

  1. In your Databricks workspace, click Data Icon Data.

  2. In the left pane, expand the Delta Sharing menu and select Shared by me.

  3. Click Share data.

  4. Enter the share Name and an optional comment.

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

CREATE SHARE [IF NOT EXISTS] <share_name>
[COMMENT "<comment>"];

Run the following command using the Databricks CLI.

databricks unity-catalog shares create --name <share_name>

Add tables to a share

To add tables to a share, you can use Data Explorer, the Databricks Unity Catalog CLI, or SQL commands in a Databricks notebook or the Databricks SQL query editor.

Permissions required: Metastore admin or the owner of the share object. Owners must also have the SELECT privilege on the table and must maintain that privilege for as long as you want to share the table. For more information, see Requirements.

  1. In your Databricks workspace, click Data Icon Data.

  2. In the left pane, expand the Delta Sharing menu and select Shared by me.

  3. On the Shares tab, find the share you want to add a table to and click its name.

  4. Click Add tables.

  5. On the Add tables page, select the catalog and database that contain the table, then select the table.

    If you aren’t sure which catalog and database contain the table, you can search for it by name, column name, or comment using workspace search. See Search for workspace assets.

  6. (Optional) Click Advanced table options to specify:

    • An alternate table name, or Alias to make the table name more readable. The alias is the table name that the recipient sees and must use in queries. Recipients cannot use the actual table name if an alias is specified.

    • A Partition (for example, (column = 'value')) if you want to share only part of the table. See Specify table partitions to share.

    • That you want to share the change data feed, allowing recipients to track row-level changes between versions of the table query table data by version, starting from the current table version. Select Share CDF.

  7. Click Save.

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

ALTER SHARE <share_name> ADD TABLE <catalog_name>.<schema_name>.<table_name>  [COMMENT "<comment>"]
   [PARTITION(<clause>)] [AS <alias>]
   [WITH CHANGE DATA FEED [START VERSION <version>]];

Options include:

  • PARTITION(<clause>): If you want to share only part of the table, you can specify a partition. For example, (column = 'value') See Specify table partitions to share.

  • AS <alias>: An alternate table name, or Alias to make the table name more readable. The alias is the table name that the recipient sees and must use in queries. Recipients cannot use the actual table name if an alias is specified.

  • WITH CHANGE DATA FEED [START VERSION <version>]: Indicates that you want to share the change data feed, allowing recipients to track row-level changes between versions of the table query table data by version. By default, the change data feed starts from the current table version, but you can specify a different start version.

For more information about ALTER SHARE options, see ALTER SHARE or ALTER SHARE.

Run the following command using the Databricks CLI.

databricks unity-catalog shares update --name <share_name> \
                                  --add-table <catalog>.<schema>.<table>

To specify advanced options, you create a JSON file with those options and reference it in the CLI command:

{
    "objects": [{
            "shared_as": "default.mytable",
            "cdf_enabled": true,
            "start_version": 2,
            "partitions": [{
                    "values": [{
                            "name": "a",
                            "op": "EQUAL",
                            "value": "1"
                    }]
            }]
    }]
}

Reference the file when you add the table. Replace update-share.json with the filename of the JSON file.

databricks unity-catalog shares update --name <share_name> \
                                  --add-table <catalog>.<schema>.<table>
                                  --json-file update-share.json

To learn about additional parameters, run databricks unity-catalog shares update --help.

For information about removing tables from a share, see Update shares.

Specify table partitions to share

To share only part of a table when you add the table to a share, you can provide a partition specification. The following SQL example shares part of the data in the inventory table, partitioned by the year, month, and date columns:

  • Data for the year 2021.

  • Data for December 2020.

  • Data for December 25, 2019.

ALTER SHARE share_name
ADD TABLE inventory
PARTITION (year = "2021"),
          (year = "2020", month = "Dec"),
          (year = "2019", month = "Dec", date = "2019-12-25");

You can specify partitions when you add a table to a share or update a share, whether you use SQL commands like the example above, Data Explorer, or the CLI. See Add tables to a share and Update shares.

Grant recipients access to a share

To grant share access to recipients, you can use Data Explorer, the Databricks Unity Catalog CLI, or the GRANT ON SHARE SQL command in a Databricks notebook or the Databricks SQL query editor.

For instructions, see Grant and manage access to Delta Sharing data shares. This article also explains how to revoke a recipient’s access to a share.

View shares and share details

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

Permissions required: The list of shares returned depends on your role and permissions. Metastore admin see all shares. Otherwise, you can view only the shares for which you are the share object owner.

Details include:

  • The share’s owner, creator, creation timestamp, updater, updated timestamp, comments.

  • Tables and partitions in the share.

  • Recipients with access to the share.

  1. In your Databricks workspace, click Data Icon Data.

  2. In the left pane, expand the Delta Sharing menu and select Shared by me.

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

  4. View share details on the Details tab.

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.

SHOW SHARES [LIKE <pattern>];

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

DESCRIBE SHARE <share_name>;

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

SHOW ALL IN SHARE <share_name>;

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

databricks unity-catalog shares list

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

databricks unity-catalog shares get --name <share_name>

View the recipients who have permissions on a share

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

Permissions required: Metastore admin or share object owner.

  1. In your Databricks workspace, click Data Icon Data.

  2. In the left pane, expand the Delta Sharing menu and select Shared by me.

  3. On the Shares tab, find and select the recipient.

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

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

SHOW GRANTS ON SHARE <share_name>;

Run the following command using the Databricks CLI.

databricks unity-catalog shares list-permissions --name <share_name>

Update shares

In addition to adding tables to a share, you can:

  • Rename a share.

  • Remove tables from a share.

  • Add or update a comment on a share.

  • Change a table’s alias (the table name as seen by the recipient).

  • Enable or disable access to a table’s change data feed, allowing recipients to track row-level changes between versions of the table and query table data by version, starting from the current table version.

  • Add, update, or remove partition definitions.

  • Change the share owner.

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

Permissions required: You must be a metastore admin or owner of the share object to update the owner. You must be a metastore admin (or user with the CREATE_SHARE privilege) and share owner to update the share name. You must be the owner to update any other share properties.

  1. In your Databricks workspace, click Data Icon Data.

  2. In the left pane, expand the Delta Sharing menu and select Shared by me.

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

On the share details page, you can do the following:

  • Click the Edit icon edit icon next to the Owner or Comment field to update these values.

  • Click Edit tables to update all other properties:

    • To remove a table, use the Edit tables browser to find the table. Clear the checkmark next to the table name to remove it from the share.

    • Click Advanced table options to change an alias; add, update, or remove partition definitions; or enable and disable change data feed.

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

Rename a share:

ALTER SHARE <share_name> RENAME TO <new_share_name>;

Remove tables from a share:

ALTER SHARE share_name REMOVE TABLE <table_name>;

Add or update a comment on a share:

COMMENT ON SHARE <share_name> IS '<comment>';

Add or modify partitions for a table in a share:

ALTER SHARE <share_name> ADD TABLE <table_name> PARTITION(<clause>);

Change share owner:

ALTER SHARE <share_name> OWNER TO  '<principal>'

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

Enable change data feed:

ALTER SHARE <share_name> ADD TABLE <table_name> WITH DATA CHANGE FEED START VERSION <start_version>;

For details about ALTER SHARE parameters, see ALTER SHARE or ALTER SHARE.

Run the following commands using the Databricks CLI.

Rename a share:

databricks unity-catalog shares update --name <share_name> --new-name <new_share_name>

Remove tables from a share:

databricks unity-catalog shares update --name <share_name> --remove-table <table_name>

Add or update a comment on a share:

databricks unity-catalog shares update --name <share_name> --comment '<comment>'

Change share owner:

databricks unity-catalog shares update --name <share_name> --owner '<principal>'

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

Delete a share

To delete a share, you can use Data 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.

When you delete a share, recipients can no longer access the shared data.

Permissions required: Share object owner.

  1. In your Databricks workspace, click Data Icon Data.

  2. In the left pane, expand the Delta Sharing menu and select Shared by me.

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

  4. Click the Kebab menu kebab menu (also known as the three-dot menu) and select Delete.

  5. On the confirmation dialog, click Delete.

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

DROP SHARE [IF EXISTS] <share_name>;

Run the following command using the Databricks CLI.

databricks unity-catalog shares delete --name <share_name>