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

In your Databricks workspace, click Catalog.
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.
On the Shared by me tab, click New recipient.
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.
(Optional) Enter a comment.
Click Create.
(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.
<authentication-type>: Set to DATABRICKS when a sharing identifier string in the format <cloud>:<region>:<uuid> is provided for <sharing-identifier>.

databricks recipients create <recipient-name> <authentication-type> --sharing-code <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:

As a data provider, you create the recipient object in your Unity Catalog metastore.
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.
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.

In your Databricks workspace, click Catalog.
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.
On the Shared by me tab, click New recipient.
Enter the recipient Name
(Optional) Enter a comment.
Click Create.

You do not use the sharing identifier for open sharing recipients.
Copy the activation link.

Alternatively, you can get the activation link later. See Step 2: Get the activation link.
(Optional) Create custom Recipient properties.

On the recipient Details tab, 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 recipients create <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 Restrict Delta Sharing recipient access using IP access lists (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.

In your Databricks workspace, click Catalog.
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.
On the Shared by me tab, click Recipients, and select the recipient.
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 recipients get <recipient-name>

Output includes the activation_url.

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.

In your Databricks workspace, click Catalog.
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.
On the Shared by me tab, click Recipients.

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

In your Databricks workspace, click Catalog.
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.
On the Shared by me tab, click Recipients, and select the recipient.

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 recipients get <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.

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.

In your Databricks workspace, click Catalog.
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.
On the Shared by me tab, click Recipients, and select the recipient.
On the recipient details page:
- Update the owner.
- Edit or add a comment.
- Rename the recipient.
  
  Click the kebab menu and select Rename.
- 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 recipients update --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. Rotating a token consists of setting an existing token to expire and replacing it with a new token and activation URL.

You should rotate a recipient’s token and generate a new activation URL 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. The rotated token is one that has been set to expire and be replaced by the active 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—that is, the one to be rotated—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 existing recipient token is compromised, Databricks recommends that you force it to expire immediately.

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

If all recipient tokens have expired, rotating the token 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 URL is inadvertently sent to the wrong person or is sent over an insecure channel, Databricks recommends that you:

Revoke the recipient’s access to the share.
Rotate the recipient and set --existing-token-expire-in-seconds to 0.
Share the new activation URL with the intended recipient over a secure channel.
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.

In your Databricks workspace, click Catalog.
In the left pane, expand the Delta Sharing menu and select Shared by me.
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.
On the Shared by me tab, click Recipients, and select the recipient.
On the Details tab, under Token Expiration, click Rotate.
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.
Click Rotate.
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.

Run the following command using the Databricks CLI. Replace the placeholder values:
- <recipient-name>: the name of the recipient.
- <expiration-seconds>: 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 recipients rotate-token \
<recipient-name> \
<expiration-seconds>
```
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.

Log in to the account console.
In the sidebar, click Catalog.
Click the metastore name.
Under Delta Sharing recipient token lifetime, click Edit.
Enable Set expiration.
Enter a number of seconds, minutes, hours, or days, and select the unit of measure.
Click Save.

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

Run the following command using the Databricks CLI. Replace 12a345b6-7890-1cd2-3456-e789f0a12b34 with the metastore UUID, and replace 86400 with number of seconds before the recipient token expires. If you set this value to 0, recipient tokens do not expire. Databricks recommends that you configure tokens to expire.

databricks metastores update \
12a345b6-7890-1cd2-3456-e789f0a12b34 \
--delta-sharing-recipient-token-lifetime-in-seconds 86400

(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 Restrict Delta Sharing recipient access using IP access lists (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:

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 the gear icon > Delta Sharing > Shared by me > Recipients and selecting the recipient.
Click Edit properties > +Add property.
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.”
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 recipients create \
--json='{
  "name": "<recipient-name>",
  "properties_kvpairs": {
    "properties": {
      "<property-key>": "<property-value>",
    }
  }
}'

For example:

databricks recipients create \
--json='{
  "name": "<recipient-name>",
  "properties_kvpairs": {
    "properties": {
      "country": "us",
      "partner_id":"001"
    }
  }
}'

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

databricks recipients update \
--json='{
  "name": "<recipient-name>",
  "properties_kvpairs": {
    "properties": {
      "country": "us",
      "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.

In your Databricks workspace, click Catalog.
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.
On the Shared by me tab, click Recipients, and select the recipient.
On the Recipients tab, find and select the recipient.
Click the kebab menu and select Delete.
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 recipients delete <recipient-name>

Create and manage data recipients for Delta Sharing

Requirements

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

Step 1: Request the recipient’s sharing identifier

Step 2: Create the recipient

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

Step 1: Create the recipient

Step 2: Get the activation link

Grant the recipient access to a share

Send the recipient their connection information

View recipients

View recipient details

View a recipient’s share permissions

Update a recipient

Manage recipient tokens (open sharing)

Security considerations for tokens

Rotate a recipient’s token

Modify the recipient token lifetime

(Optional) Restrict recipient access using access lists

Manage recipient properties

Requirements

Add properties when you create or update a recipient

View recipient properties

Delete a recipient