Create and manage data recipients for Delta Sharing

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

A recipient is the named object that represents the identity of a user or group of users in the real world who consume shared data. The way you create recipients differs depending on whether or not your recipient has access to a Databricks workspace that is enabled for Unity Catalog:

• For recipients with access to a Databricks workspace that is enabled for Unity Catalog, you can create a recipient object with a secure connection managed entirely by Databricks. This sharing mode is called Databricks-to-Databricks sharing.

• For recipients without access to a Databricks workspace that is enabled for Unity Catalog, you must use open sharing, with a secure connection that you manage using token-based authentication.

For more information about these two sharing modes and when to choose which, see Open sharing versus Databricks-to-Databricks sharing.

Requirements

To create a recipient:

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

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

• If you use a Databricks notebook to create the recipient, your cluster must use Databricks Runtime 11.3 LTS or above and either shared or single-user cluster access mode.

For other recipient management operations (such as view, delete, update, and grant recipient access to a share) see the permissions requirements listed in the operation-specific sections of this article.

Create a recipient object for users who have access to Databricks (Databricks-to-Databricks sharing)

If your data recipient has access to a Databricks workspace that has been enabled for Unity Catalog, you can create a recipient object with an authentication type of DATABRICKS.

A recipient object with the authentication type of DATABRICKS represents a data recipient on a particular Unity Catalog metastore, identified in the recipient object definition by a sharing identifier string consisting of the metastore’s cloud, region, and UUID. The data shared with this recipient can be accessed only on that metastore.

Step 1: Request the recipient’s sharing identifier

Ask a recipient user to send you the sharing identifier for the Unity Catalog metastore that is attached to the workspaces where the recipient user or group of users will work with the shared data.

The sharing identifier is a string consisting of the metastore’s cloud, region, and UUID (the unique identifier for the metastore), in the format <cloud>:<region>:<uuid>.

For example, in the following screenshot, the complete sharing identifier string is aws:us-west-2:19a84bee-54bc-43a2-87de-023d0ec16016.

The recipient can find the identifier using Catalog Explorer, the Databricks Unity Catalog CLI, or the default SQL function CURRENT_METASTORE in a Databricks notebook or Databricks SQL query that runs on a Unity-Catalog-capable cluster in the workspace they intend to use.

To get the sharing identifier using Catalog Explorer:

1. In your Databricks workspace, click Catalog.

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

3. Above the Providers tab, click the Sharing identifier copy icon.

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

SELECT CURRENT_METASTORE();

Run the following command using the Databricks CLI. The sharing identifier is returned as the global_metastore_id.

databricks unity-catalog metastores get-summary

You can help the recipient by sending your contact the information contained in this step, or you can point them to Get access in the Databricks-to-Databricks model.

Step 2: Create the recipient

To create a recipient for Databricks-to-Databricks sharing, you can use Catalog Explorer, the Databricks Unity Catalog CLI, or the CREATE RECIPIENT SQL command in a Databricks notebook or the Databricks SQL query editor.

Permissions required: Metastore admin or user with the CREATE_RECIPIENT privilege for the Unity Catalog metastore where the data you want to share is registered.

1. In your Databricks workspace, click Catalog.

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

3. Click New Recipient.

4. Enter the recipient Name and Sharing identifier.

   Use the entire sharing identifier string in the format <cloud>:<region>:<uuid>. For example, aws:us-west-2:19a84bee-54bc-43a2-87de-023d0ec16016.

5. (Optional) Enter a comment.

6. Click Create.

7. (Optional) Create custom Recipient properties.

   Click Edit properties > +Add property. Then add a property name (Key) and Value. For details, see Manage recipient properties.

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

CREATE RECIPIENT [IF NOT EXISTS] <recipient-name>
USING ID '<sharing-identifier>'
[COMMENT "<comment>"];

Use the entire sharing identifier string in the format <cloud>:<region>:<uuid>. For example, aws:eu-west-1:g0c979c8-3e68-4cdf-94af-d05c120ed1ef.

You can also add custom properties for the recipient. For details, see Manage recipient properties.

Run the following command using the Databricks CLI. Replace the placeholder values:

• <recipient-name>: The name of the recipient.

• <sharing-identifier>: The entire sharing identifier string in the format <cloud>:<region>:<uuid>. For example, aws:eu-west-1:g0c979c8-3e68-4cdf-94af-d05c120ed1ef.

databricks unity-catalog recipients create --name <recipient-name> --sharing-id <sharing-identifier>

You can also add custom properties for the recipient. For details, see Manage recipient properties.

The recipient is created with the authentication_type of DATABRICKS.

Create a recipient object for all other users (open sharing)

If you want to share data with users outside of your Databricks workspace, regardless of whether they use Databricks themselves, you can use open Delta Sharing to share your data securely. Here’s how it works:

1. As a data provider, you create the recipient object in your Unity Catalog metastore.

2. When you create the recipient object, Databricks generates a token, a credential file that includes the token, and an activation link for you to share with the recipient. The recipient object has the authentication type of TOKEN.

3. The recipient accesses the activation link, downloads the credential file, and uses the credential file to authenticate and get read access to the tables you include in the shares you give them access to.

Step 1: Create the recipient

To create a recipient for open sharing, you can use Catalog Explorer, the Databricks Unity Catalog CLI, or the CREATE RECIPIENT SQL command in a Databricks notebook or the Databricks SQL query editor.

Permissions required: Metastore admin or user with the CREATE_RECIPIENT privilege for the Unity Catalog metastore where the data you want to share is registered.

1. In your Databricks workspace, click Catalog.

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

3. Click New Recipient.

4. Enter the recipient Name

5. (Optional) Enter a comment.

6. Click Create.

   You do not use the sharing identifier for open sharing recipients.

7. (Optional) Create custom Recipient properties.

   Click Edit properties > +Add property. Then add a property name (Key) and Value. For details, see Manage recipient properties.

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

CREATE RECIPIENT [IF NOT EXISTS] <recipient-name>
[COMMENT "<comment>"];

You can also add custom properties for the recipient. For details, see Manage recipient properties.

Run the following command using the Databricks CLI.

databricks unity-catalog recipients create --name <recipient-name>

You can also add custom properties for the recipient. For details, see Manage recipient properties.

Output includes the activation_url that you share with the recipient.

The recipient is created with the authentication_type of TOKEN.

Note

When you create the recipient, you have the option to limit recipient access to a restricted set of IP addresses. You can also add an IP access list to an existing recipient. See Use IP access lists to restrict Delta Sharing recipient access (open sharing).

Step 2: Get the activation link

To get the new recipient’s activation link, you can use Catalog Explorer, the Databricks Unity Catalog CLI, or the DESCRIBE RECIPIENT SQL command in a Databricks notebook or the Databricks SQL query editor.

If the recipient has already downloaded the credential file, the activation link is not returned or displayed.

Permissions required: Metastore admin, user with the USE RECIPIENT privilege, or the recipient object owner.

1. In your Databricks workspace, click Catalog.

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

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

4. On the recipient details page, copy the Activation link.

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

DESCRIBE RECIPIENT <recipient-name>;

Output includes the activation_link.

Run the following command using the Databricks CLI.

databricks unity-catalog recipients get --name <recipient-name>

Output includes the activation_url.

Grant the recipient access to a share

Once you’ve created the recipient and created shares, you can grant the recipient access to those shares.

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 (for providers).

Send the recipient their connection information

You must let the recipient know how to access the data that you are sharing with them. The information that you share with the recipient depends on whether you are using Databricks-to-Databricks sharing or open sharing:

• For Databricks-to-Databricks sharing, you send a link to instructions for accessing the data you are sharing.

  A provider object that lists available shares is automatically created in the recipient’s metastore. Recipients don’t need to do anything but view and select the shares they want to use. See Read data shared using Databricks-to-Databricks Delta Sharing (for recipients).

• For open sharing, you use a secure channel to share the activation link and a link to instructions for using it.

  You can download the credential file only once. Recipients should treat the downloaded credential as a secret and must not share it outside of their organization. If you have concerns that a credential may have been handled insecurely, you can rotate a recipient’s credential at any time. For more information about managing credentials to ensure secure recipient access, see Security considerations for tokens.

View recipients

To view a list of recipients, you can use Catalog Explorer, the Databricks Unity Catalog CLI, or the SHOW RECIPIENTS SQL command in a Databricks notebook or the Databricks SQL query editor.

Permissions required: You must be a metastore admin or have the USE RECIPIENT privilege to view all recipients in the metastore. Other users have access only to the recipients that they own.

1. In your Databricks workspace, click Catalog.

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

3. Open the Recipients tab.

Run the following command in a notebook or the Databricks SQL query editor. Optionally, replace <pattern> with a `LIKE` predicate.

SHOW RECIPIENTS [LIKE <pattern>];

Run the following command using the Databricks CLI.

databricks unity-catalog recipients list

View recipient details

To view details about a recipient, you can use Catalog Explorer, the Databricks Unity Catalog CLI, or the DESCRIBE RECIPIENT SQL command in a Databricks notebook or the Databricks SQL query editor.

Permissions required: Metastore admin, user with the USE RECIPIENT privilege, or the recipient object owner.

Details include:

• The recipient’s creator, creation timestamp, comments, and authentication type (TOKEN or DATABRICKS).

• If the recipient uses open sharing: the token lifetime, activation link, activation status (whether the credential has been downloaded), and IP access lists, if assigned.

• If the recipient uses Databricks-to-Databricks sharing: the cloud, region, and metastore ID of the recipient’s Unity Catalog metastore, as well as activation status.

• Recipient properties, including custom properties. See Manage recipient properties.

1. In your Databricks workspace, click Catalog.

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

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

4. View recipient details on the Details tab.

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

DESCRIBE RECIPIENT <recipient-name>;

Run the following command using the Databricks CLI.

databricks unity-catalog recipients get --name <recipient-name>

View a recipient’s share permissions

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, user with the USE RECIPIENT privilege, or the recipient object owner.

1. In your Databricks workspace, click Catalog.

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

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

4. Go to the Shares tab to view the list of shares shared with the recipient.

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

SHOW GRANTS TO RECIPIENT <recipient-name>;

Run the following command using the Databricks CLI.

databricks unity-catalog recipients list-permissions --name <recipient-name>

Update a recipient

To update a recipient, you can use Catalog Explorer, the Databricks Unity Catalog CLI, or the ALTER RECIPIENT SQL command in a Databricks notebook or the Databricks SQL query editor.

Properties you can update include recipient name, owner, comment, and custom properties. You cannot update the recipient name using Catalog Explorer.

Permissions required: You must be a metastore admin or owner of the recipient object to update the owner. You must be a metastore admin (or user with the CREATE_RECIPIENT privilege) and the owner to update the name. You must be the owner to update the comment or custom properties.

1. In your Databricks workspace, click Catalog.

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

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

4. On the details page, you can:

   • Update the owner.

   • Edit or add a comment.

   • Edit, remove, or add custom Recipient properties.

     Click Edit properties. To add a property, click +Add property and enter a property name (Key) and Value. For details, see Manage recipient properties.

Run one or more of the following commands in a notebook or the Databricks SQL query editor.

ALTER RECIPIENT <recipient-name> RENAME TO <new-recipient-name>;

ALTER RECIPIENT <recipient-name> OWNER TO <new-owner>;

COMMENT ON RECIPIENT <recipient-name> IS "<new-comment>";

ALTER RECIPIENT <recipient-name> SET PROPERTIES ( <property-key>  =  property_value [, ...] )

ALTER RECIPIENT <recipient-name> UNSET PROPERTIES ( <property-key> [, ...] )

For more information about properties, see Manage recipient properties.

Create a JSON file that includes an update to the recipient name, comment, owner, IP access list, or custom properties.

{
    "name": "new-recipient-name",
    "owner": "someone-else@example.com",
    "comment": "something new",
    "ip_access_list": {
            "allowed_ip_addresses": ["8.8.8.8", "8.8.8.4/10"]
    },
    "property": {
            "country": "us",
            "id": "001"
    }
}

Then run the following command using the Databricks CLI. Replace <recipient-name> with the current recipient name and replace update-recipient-settings.json with the filename of the JSON file.

databricks unity-catalog recipients update --name <recipient-name> --json-file update-recipient-settings.json

For more information about properties, see Manage recipient properties.

Manage recipient tokens (open sharing)

If you are sharing data with a recipient using open sharing, you may need to rotate that recipient’s token.

You should rotate a recipient’s credential and generate a new activation link in the following circumstances:

• When the existing recipient token is about to expire.

• If a recipient loses their activation URL or if it is compromised.

• If the credential is corrupted, lost, or compromised after it is downloaded by a recipient.

• When you modify the recipient token lifetime for a metastore. See Modify the recipient token lifetime.

Security considerations for tokens

At any given time, a recipient can have at most two tokens: an active token and a rotated token. Until the rotated token expires, attempting to rotate the token again results in an error.

When you rotate a recipient’s token, you can optionally set --existing-token-expire-in-seconds to the number of seconds before the existing recipient token expires. If you set the value to 0, the existing recipient token expires immediately.

Databricks recommends that you set --existing-token-expire-in-seconds to a relatively short period that gives the recipient organization time to access the new activation URL while minimizing the amount of time that the recipient has two active tokens. If you suspect that the recipient token is compromised, Databricks recommends that you force the existing recipient token to expire immediately.

If a recipient’s existing activation URL has never been accessed and the recipient has not been rotated, rotating the recipient invalidates the existing activation URL and replaces it with a new one.

If all recipient tokens have expired, rotating the recipient replaces the existing activation URL with a new one. Databricks recommends that you promptly rotate or drop a recipient whose token has expired.

If a recipient activation link is inadvertently sent to the wrong person or is sent over an insecure channel, Databricks recommends that you:

1. Revoke the recipient’s access to the share.

2. Rotate the recipient and set --existing-token-expire-in-seconds to 0.

3. Share the new activation link with the intended recipient over a secure channel.

4. After the activation URL has been accessed, grant the recipient access to the share again.

In extreme situations, instead of rotating the recipient’s token, you can drop and re-create the recipient.

Rotate a recipient’s token

To rotate a recipient’s token, you can use Catalog Explorer or the Databricks Unity Catalog CLI.

Permissions required: Recipient object owner.

1. In your Databricks workspace, click Catalog.

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

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

4. On the Details tab, under Token Expiration, click Rotate.

5. On the Rotate token dialog, set the token to expire either immediately or for a set period of time. For advice about when to expire existing tokens, see Security considerations for tokens.

6. Click Rotate.

7. On the Details tab, copy the new Activation link and share it with the recipient over a secure channel. See Step 2: Get the activation link.

1. Run the following command using the Unity Catalog CLI. Arguments in brackets are optional. Replace the placeholder values:

   • <recipient-name>: the name of the recipient.

   • <expiration-seconds>: Optional. The number of seconds until the existing recipient token should expire. During this period, the existing token will continue to work. A value of 0 means the existing token expires immediately. For advice about when to expire existing tokens, see Security considerations for tokens.

   databricks unity-catalog rotate-recipient-token \
     --name <recipient-name> \
     [--existing-token-expire-in-seconds <expiration-seconds>]
   

2. Get the recipient’s new activation link and share it with the recipient over a secure channel. See Step 2: Get the activation link.

Modify the recipient token lifetime

If you need to modify the default recipient token lifetime for your Unity Catalog metastore, you can use Catalog Explorer or the Databricks Unity Catalog CLI.

Note

The recipient token lifetime for existing recipients is not updated automatically when you change the default recipient token lifetime for a metastore. In order to apply the new token lifetime to a given recipient, you must rotate their token. See Manage recipient tokens (open sharing).

Permissions required: Account admin.

1. Log in to the account console.

2. In the sidebar, click Catalog.

3. Click the metastore name.

4. Enable Set expiration.

5. Enter a number of seconds, minutes, hours, or days, and select the unit of measure.

6. Click Enable.

If you disable Set expiration, recipient tokens do not expire. Databricks recommends that you configure tokens to expire.

Create a JSON file that includes an update to the metastore’s delta_sharing_recipient_token_lifetime_in_seconds value. If you set this value to 0, recipient tokens do not expire. Databricks recommends that you configure tokens to expire.

{
  "delta_sharing_recipient_token_lifetime_in_seconds": 86400,
}

Then run the following command using the Databricks CLI. Replace 12a345b6-7890-1cd2-3456-e789f0a12b34 with the metastore UUID, and replace update-metastore.json with the filename of the JSON file.

databricks unity-catalog metastores update --id 12a345b6-7890-1cd2-3456-e789f0a12b34 \
  --json-file update-metastore.json

(Optional) Restrict recipient access using access lists

You can limit recipient access to a restricted set of IP addresses when you configure the recipient object. See Use IP access lists to restrict Delta Sharing recipient access (open sharing).

Manage recipient properties

Recipient objects include predefined properties that you can use to refine data sharing access. For example, you can use them to do the following:

• Share different table partitions with different recipients, enabling you to use the same shares with multiple recipients while maintaining data boundaries between them.

• Share dynamic views that limit recipient access to table data at the row or column level based on recipient properties.

You can also create custom properties.

The predefined properties start with databricks. and include the following:

• 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.

Custom properties that might be of value could include, for example, country. For example, if you attach the custom property 'country' = 'us' to a recipient, you can partition table data by country and share only rows that have US data with the recipients that have that property assigned. You can also share a dynamic view that restricts row or column access based on recipient properties. For more detailed examples, see Use recipient properties to do partition filtering and Add dynamic views to a share to filter rows and columns.

Requirements

Recipient properties are supported in Databricks Runtime 12.2 and above.

Add properties when you create or update a recipient

You can add properties when you create a recipient or update them for an existing recipient. 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: Metastore admin or user with the CREATE RECIPIENT privilege for the Unity Catalog metastore.

When you create or update a recipient using Catalog Explorer, add or update custom properties by doing the following:

1. Go to the Recipient details page.

   If you are creating a new recipient, you land on this page after you click Create. If you are updating an existing recipient, go to this page by clicking Delta Sharing > Shared by me > Recipients and selecting the recipient.

2. Click Edit properties > +Add property.

3. Enter a property name (Key) and Value.

   For example, if you want to filter shared data by country and share only US data with this recipient, you can create a key named “country” with a value of “US.”

4. Click Save.

To add a custom property when you create a recipient, run the following command in a notebook or the Databricks SQL query editor:

CREATE RECIPIENT [IF NOT EXISTS] <recipient-name>
[USING ID '<sharing-identifier>'] /* Skip this if you are using open sharing */
[COMMENT "<comment>"]
PROPERTIES ( '<property-key>' = '<property-value>' [, ...] );

<property-key> can be a string literal or identifier. <property-value> must be a string literal.

For example:

CREATE RECIPIENT acme PROPERTIES ('country' = 'us', 'partner_id' = '001');

To add, edit, or delete custom properties for an existing recipient, run one of the following:

ALTER RECIPIENT <recipient-name> SET PROPERTIES ( '<property-key>' = '<property-value>' [, ...] );

ALTER RECIPIENT <recipient-name> UNSET PROPERTIES ( '<property-key>' );

To add custom properties when you create a recipient, run the following command using the Databricks CLI. Replace the placeholder values:

• <recipient-name>: The name of the recipient.

• <property-key> can be a string literal or identifier.

• <property-value> must be a string literal.

databricks unity-catalog recipients create --name <recipient-name> --property <property-key>=<property-value>

For example:

databricks unity-catalog recipients create --name acme --property country=us --property partner_id=001

To add or edit custom properties for an existing recipient, use update instead of create:

databricks unity-catalog recipients update --name acme --property country=us --property partner_id=001

View recipient properties

To view recipient properties, follow the instructions in View recipient details.

Delete a recipient

To delete a recipient, you can use Catalog Explorer, the Databricks Unity Catalog CLI, or the DROP RECIPIENT SQL command in a Databricks notebook or the Databricks SQL query editor. You must be the recipient object owner to delete the recipient.

When you delete a recipient, the users represented by the recipient can no longer access the shared data. Tokens that recipients use in an open sharing scenario are invalidated.

Permissions required: Recipient object owner.

1. In your Databricks workspace, click Catalog.

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

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

4. Click the 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 RECIPIENT [IF EXISTS] <recipient-name>;

Run the following command using the Databricks CLI.

databricks unity-catalog recipients delete --name <recipient-name>