Manage data recipients for Delta Sharing

This page describes how providers manage existing Delta Sharing recipients in Databricks. A recipient is the named object that represents the identity of a user or group with whom you share data.

If you are a data recipient looking to manage a provider object you imported from a credential file, see Manage Delta Sharing providers for data recipients instead.

To create a recipient, see Create data recipients for Delta Sharing (Databricks-to-Databricks sharing), Create a recipient object for non-Databricks users using bearer tokens (open sharing), or Enable Open ID Connect (OIDC) federation for Delta Sharing recipients. To manage shares, see Manage shares for Delta Sharing.

Grant the recipient access to a share

After 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 Manage access to Delta Sharing data shares (for providers).

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 have the USE RECIPIENT privilege to view all recipients in the metastore. Other users have access only to the recipients that they own.

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, in the upper-right corner, click Share > Delta Sharing.

3. On the Shared by me tab, click Recipients.

SQL

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

SQL

SHOW RECIPIENTS [LIKE <pattern>];

CLI

Run the following command using the Databricks CLI.

Bash

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 (DATABRICKS, TOKEN, OAUTH_CLIENT_CREDENTIALS, or OIDC_FEDERATION).
• If the recipient uses open sharing with bearer tokens: token lifetime, activation link, activation status (whether the credential has been downloaded), and IP access lists, if assigned.
• If the recipient uses open sharing with OIDC federation: recipient endpoint, MTLS endpoint, federation policies, 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.

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, in the upper-right corner, click Share > Delta Sharing.

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

SQL

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

SQL

DESCRIBE RECIPIENT <recipient-name>;

CLI

Run the following command using the Databricks CLI.

Bash

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

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, in the upper-right corner, click Share > Delta Sharing.

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

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

SQL

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

SQL

SHOW GRANTS TO RECIPIENT <recipient-name>;

CLI

Run the following command using the Databricks CLI.

Bash

databricks recipients share-permissions <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 have the CREATE RECIPIENT privilege and be the owner to update the name. You must be the owner to update the comment or custom properties.

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, in the upper-right corner, click Share > Delta Sharing.

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

4. 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 the edit icon next to Recipient properties. Then add a property name (Key) and Value. For details, see Manage recipient properties.

   • Token-authenticated recipients only:

     • View and copy the Authentication link. See Get the activation link
     • Under Token Management, rotate or update the bearer token. See Manage recipient tokens.

   • OIDC federated recipients only:

     • Under OIDC federation policies, click Add policies. See Enable Open ID Connect (OIDC) federation for Delta Sharing recipients.
     • View and copy Recipient endpoint and Recipient MTLS endpoint.

SQL

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

SQL

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.

CLI

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

JSON

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

Bash

databricks recipients update --json-file update-recipient-settings.json

For more information about properties, see Manage recipient properties.

(Optional) Restrict recipient access using access lists

You can limit recipient access to a restricted set of IP addresses for open sharing recipients. 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

You must use a SQL warehouse or compute running Databricks Runtime 12.2 or 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.

Catalog Explorer

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 the gear icon > Delta Sharing > Shared by me > Recipients and selecting the recipient.

2. On the lower‑right side of the page, under Recipient properties, click the pencil next to databricks.metastoreID for a Databricks recipient or next to databricks.name for an open recipient.

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.

SQL

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

SQL

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:

SQL

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:

SQL

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

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

CLI

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.

Bash

databricks recipients create \
--json='{
  "name": "<recipient-name>",
  "properties_kvpairs": {
    "properties": {
      "<property-key>": "<property-value>",
    }
  }
}'

For example:

Bash

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:

Bash

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.

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, in the upper-right corner, click Share > Delta Sharing.

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

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

5. Click the kebab menu and select Delete.

6. On the confirmation dialog, click Delete.

SQL

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

SQL

DROP RECIPIENT [IF EXISTS] <recipient-name>;

CLI

Run the following command using the Databricks CLI.

Bash

databricks recipients delete <recipient-name>