Create and manage shares for Delta Sharing
This article explains how to create and manage shares for Delta Sharing.
A share is a securable object in Unity Catalog that you can use for sharing the following data assets with one or more recipients:
Tables, views, or table partitions
Notebooks
If you share an entire schema (database), the recipient can access all of the tables and views in the schema at the moment you share it, along with any tables and views that are added to the schema in the future.
A share can contain data assets from only one Unity Catalog metastore. You can add or remove data assets 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 or views to a share, you must be:
The share owner and have the
USE SCHEMA
privilege on the schema that contains the table or view and theSELECT
privilege on the table or view. You must keep that privilege in order for the table or view to continue to be shared. If you lose it, the recipient cannot access the table or view through the share. Databricks therefore recommends that you use a group as the share owner.If you are sharing an entire schema, you must be the share owner and the schema owner, or have
USE SCHEMA
andSELECT
on the schema.
To add notebook files to a share, you must be:
The share owner and have
Can Read
permission on the notebook.
To grant recipient access to a share, you must be one of these:
Metastore admin.
User with delegated permissions or ownership on both the share and the recipient objects ((
USE SHARE
+SET SHARE PERMISSION
) or share owner) AND (USE RECIPIENT
or recipient owner).
To view shares, you must be one of these:
A metastore admin (can view all)
A user with the
USE SHARE
privilege (can view all)The share object owner
Compute requirements:
If you use a Databricks notebook to create the share, your cluster must use Databricks Runtime 11.3 LTS or above and the shared or single-user cluster access mode.
If you use SQL statements to add a schema to a share (or update or remove a schema), you must use a SQL warehouse on SQL compute version 2023.35 or above, or a cluster running Databricks Runtime 13.2 or above. Doing the same using Catalog Explorer has no compute requirements.
Create a share object
To create a share, you can use Catalog 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.
In your Databricks workspace, click
Catalog.
In the left pane, expand the Delta Sharing menu and select Shared by me.
Click Share data.
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 Catalog Explorer, the Databricks Unity Catalog CLI, or SQL commands in a Databricks notebook or the Databricks SQL query editor.
Permissions required: Owner of the share object, USE SCHEMA
on the schema that contains the table, and the SELECT
privilege on the table. You must maintain the SELECT
privilege for as long as you want to share the table. For more information, see Requirements.
In your Databricks workspace, click
Catalog.
In the left pane, expand the Delta Sharing menu and select Shared by me.
On the Shares tab, find the share you want to add a table to and click its name.
Click Manage assets > Add data assets.
On the Add tables page, select either an entire schema (database) or individual tables and views.
To select a table or view, first select the catalog, then the schema that contains the table or view, then the table or view itself.
You can search for tables by name, column name, or comment using workspace search. See Search for workspace objects.
To select a schema, first select the catalog and then the schema.
For detailed information about sharing schemas, see Add schemas to a share.
(Optional) Click Advanced table options to specify the following options. Alias and partitions are not available if you select an entire schema. Table history is included by default if you select an entire schema.
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 and Use recipient properties to do partition filtering.That you want to share the table history to allow recipients to perform time travel queries or read the table with Spark Structured Streaming, starting from version zero. Select History Sharing. Requires Databricks Runtime 12.1 or above.
The change data feed will also be shared if it is enabled on the source table and History Sharing is selected here, allowing recipients to track row-level changes between versions of the table.
Click Save.
Run the following command in a notebook or the Databricks SQL query editor to add a table:
ALTER SHARE <share-name> ADD TABLE <catalog-name>.<schema-name>.<table-name> [COMMENT "<comment>"]
[PARTITION(<clause>)] [AS <alias>]
[WITH HISTORY | WITHOUT HISTORY];
Run the following to add an entire schema. The ADD SCHEMA
command requires a SQL warehouse on SQL compute version 2023.35 or above, or a cluster running Databricks Runtime 13.2 or above. For detailed information about sharing schemas, see Add schemas to a share.
ALTER SHARE <share-name> ADD SCHEMA <catalog-name>.<schema-name>
[COMMENT "<comment>"];
Options include the following. PARTITION
and AS <alias>
are not available if you select an entire schema. WITH HISTORY
is selected by default for all tables if you select an entire schema.
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 and Use recipient properties to do partition filtering.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 HISTORY
orWITHOUT HISTORY
: WhenWITH HISTORY
is specified, share the table with full history, allowing recipients to perform time travel queries and streaming reads. The default behavior for table sharing isWITHOUT HISTORY
and for schema sharing isWITH HISTORY
. Requires Databricks Runtime 12.1 or above.You can allow recipients to track row-level changes between versions of the table by enabling change data feed on the source table and sharing it
WITH HISTORY
.
For more information about ALTER SHARE
options, see ALTER SHARE.
To add a table, run the following command using the Databricks CLI.
databricks unity-catalog shares update --name <share-name> \
--add-table <catalog>.<schema>.<table>
databricks unity-catalog shares update --name <share-name> \
--add-schema <schema>.<table>
To specify advanced options for tables (not available for schemas), you create a JSON file with those options and reference it in the CLI command. To learn about these options, view the instructions on the SQL tab.
{
"objects": [{
"shared_as": "default.mytable",
"history_data_sharing_status": "ENABLED",
"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. You can specify partitions when you add a table to a share or update a share, using Catalog Explorer, the Databricks Unity Catalog CLI, or SQL commands in a Databricks notebook or the Databricks SQL query editor. See Add tables to a share and Update shares.
Basic example
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");
Use recipient properties to do partition filtering
You can share a table partition that matches data recipient properties, also known as parameterized partition sharing.
Default properties include:
databricks.accountId
: The Databricks account that a data recipient belongs to (Databricks-to-Databricks sharing only).databricks.metastoreId
: The Unity Catalog metastore that a data recipient belongs to (Databricks-to-Databricks sharing only).databricks.name
: The name of the data recipient.
You can create any custom property you like when you create or update a recipient.
Filtering by recipient property enables you to share the same tables, using the same share, across multiple Databricks accounts, workspaces, and users while maintaining data boundaries between them.
For example, if your tables include a Databricks account ID column, you can create a single share with table partitions defined by Databricks account ID. When you share, Delta Sharing dynamically delivers to each recipient only the data associated with their Databricks account.

Without the ability to dynamically partition by property, you would have to create a separate share for each recipient.
To specify a partition that filters by recipient properties when you create or update a share, you can use Catalog Explorer or the CURRENT_RECPIENT
SQL function in a Databricks notebook or the Databricks SQL query editor:
Note
Recipient properties are available on Databricks Runtime 12.2 and above.
In your Databricks workspace, click
Catalog.
In the left pane, expand the Delta Sharing menu and select Shared by me.
On the Shares tab, find the share you want to update and click its name.
Click Manage assets > Add data assets.
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 objects.
(Optional) Click Advanced table options to add Partition specifications.
On the Add partition to a table dialog, add the property-based partition specification using the following syntax:
(<column-name> = CURRENT_RECIPIENT().<property-key>)
For example,
(country = CURRENT_RECIPIENT().country)
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>
(<column-name> = CURRENT_RECIPIENT().<property-key>;
For example,
ALTER SHARE acme ADD TABLE acme.default.some_table
PARTITION (country = CURRENT_RECIPIENT().country)
Add views to a share
Preview
This feature is in Public Preview.
Views are read-only objects created from one or more tables or other views. A view can be created from tables and other views that are contained in multiple schemas and catalogs in a Unity Catalog metastore. See Create views.
This section describes how to add views to a share using Catalog Explorer or SQL commands in a Databricks notebook or the Databricks SQL query editor. If you prefer to use the Databricks CLI or the Unity Catalog REST API, see PATCH /api/2.1/unity-catalog/shares/ in the REST API reference or Add a table to a share in the CLI reference.
Permissions required: Owner of the share object, USE SCHEMA
on the schema that contains the view, and SELECT
on the view. You must maintain the SELECT
privilege for as long as you want to share the view. For more information, see Requirements.
Additional requirements:
View sharing is supported only in Databricks-to-Databricks sharing.
Shareable views must be defined on Delta tables or other shareable views.
You must use a SQL warehouse or a cluster on Databricks Runtime 13.1 or above when you add a view to a share.
For requirements and limitations on recipient usage of views, see Read shared views.
To add views to a share:
In your Databricks workspace, click
Catalog.
In the left pane, expand the Delta Sharing menu and select Shared by me.
On the Shares tab, find the share you want to add a view to and click its name.
Click Manage assets > Add data assets.
On the Add tables page, search or browse for the view that you want to share and select it.
(Optional) Click Advanced table options to specify an Alias, or alternate view name, to make the view name more readable. The alias is the name that the recipient sees and must use in queries. Recipients cannot use the actual view name if an alias is specified.
Click Save.
Run the following command in a notebook or the Databricks SQL query editor:
ALTER SHARE <share-name> ADD VIEW <catalog-name>.<schema-name>.<view-name>
[COMMENT "<comment>"]
[AS <alias>];
Options include:
AS <alias>
: An alternate view name, or alias, to make the view name more readable. The alias is the view name that the recipient sees and must use in queries. Recipients cannot use the actual view name if an alias is specified.COMMENT "<comment>"
: Comments appear in the Catalog Explorer UI and when you list and display view details using SQL statements.
For more information about ALTER SHARE
options, see ALTER SHARE.
Add schemas to a share
Preview
This feature is in Public Preview.
When you add an entire schema to a share, your recipients will have access not only to all of the data assets in the schema at the time that you create the share, but any assets that are added to the schema over time. Tables shared this way always include full history.
Adding, updating, or removing a schema using SQL requires a SQL warehouse on SQL compute version 2023.35 or above, or a cluster running Databricks Runtime 13.2 or above. Doing the same using Catalog Explorer has no compute requirements.
Permissions required: Owner of the share object and owner of the schema (or a user with USE SCHEMA
and SELECT
privileges on the schema).
To add a schema to a share, follow the instructions in Add tables to a share, paying attention to the content that specifies how to add a schema.
Advanced table options, such as table aliases and partitions, are not available if you select an entire schema. If you have created aliases or partitions for any tables in the schema, these are removed when you add the entire schema to the share.
If you want to specify advanced options for a table that you are sharing using schema sharing, you must share the table using SQL and give the table an alias with a different schema name.
Add notebook files to a share
Use Catalog Explorer to add a notebook file to a share.
Permissions required: Owner of the share object and Can read
permission on the notebook you want to share.
In your Databricks workspace, click
Catalog.
In the left pane, expand the Delta Sharing menu and select Shared by me.
On the Shares tab, find the share you want to add a notebook to and click its name.
Click Manage assets and select Add notebook file.
On the Add notebook file page, click the file icon to browse for the notebook you want to share.
Click the file you want to share and click Select.
(Optionally) specify a user-friendly alias for the file in the Share as field. This is the identifier that recipients will see.
Click Save.
The shared notebook file now appears in the Notebook files list on the Assets tab.
Remove notebook files from shares
To remove a notebook file from a share:
In your Databricks workspace, click
Catalog.
In the left pane, expand the Delta Sharing menu and select Shared by me.
On the Shares tab, find the share that includes the notebook, and click the share name.
On the Assets tab, find the notebook file you want to remove from the share.
Click the
kebab menu (also known as the three-dot menu) to the right of the row, and select Delete notebook file.
On the confirmation dialog, click Delete.
Update notebook files in shares
To update a notebook that you have already shared, you must re-add it, giving it a new alias in the Share as field. Databricks recommends that you use a name that indicates the notebook’s revised status, such as <old-name>-update-1
. You may need to notify the recipient of the change. The recipient must select and clone the new notebook to take advantage of your update.
Grant recipients access to a share
To grant share access to recipients, you can use Catalog Explorer, the Databricks Unity Catalog CLI, or the GRANT ON SHARE
SQL command in a Databricks notebook or the Databricks SQL query editor.
Permissions required: One of the following:
Metastore admin.
Delegated permissions or ownership on both the share and the recipient objects ((
USE SHARE
+SET SHARE PERMISSION
) or share owner) AND (USE RECIPIENT
or recipient owner).
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 Catalog 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 admins and users with the USE SHARE
privilege 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.
In your Databricks workspace, click
Catalog.
In the left pane, expand the Delta Sharing menu and select Shared by me.
Open the Shares tab to view a list of shares.
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 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.
Permissions required: Metastore admin, USE SHARE
privilege, or share object owner.
In your Databricks workspace, click
Catalog.
In the left pane, expand the Delta Sharing menu and select Shared by me.
On the Shares tab, find and select the recipient.
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, views, and notebooks 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 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, you can use Catalog Explorer, the Databricks Unity Catalog CLI, or SQL commands in a Databricks notebook or the Databricks SQL query editor. You cannot use Catalog Explorer to rename the share.
Permissions required: To update the share owner, you must be one of the following: a metastore admin, the owner of the share object, or a user with both the USE SHARE
and SET SHARE PERMISSION
privileges. To update the share name, you must be a metastore admin (or user with the CREATE_SHARE
privilege) and share owner. To update any other share properties, you must be the owner.
In your Databricks workspace, click
Catalog.
In the left pane, expand the Delta Sharing menu and select Shared by me.
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 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 history sharing.
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 history sharing:
ALTER SHARE <share-name> ADD TABLE <table-name> WITH HISTORY;
For details about ALTER SHARE
parameters, see 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 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.
When you delete a share, recipients can no longer access the shared data.
Permissions required: Share object owner.
In your Databricks workspace, click
Catalog.
In the left pane, expand the Delta Sharing menu and select Shared by me.
On the Shares tab, find the share you want to delete and click its name.
Click the
kebab menu (also known as the three-dot menu) and select Delete.
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>