Create data recipients for Delta Sharing (Databricks-to-Databricks sharing)

This page explains how to create recipients in Delta Sharing, when the recipients are on a Databricks workspace that is enabled for Unity Catalog. To view, update, delete, grant share access, manage properties, or restrict access with IP lists for an existing recipient, see Manage data recipients for Delta Sharing.

A recipient is the named object that represents the identity of a user or group of users 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:

• Recipients with access to a Unity Catalog-enabled Databricks workspace:

  You can create a recipient object with a secure connection managed by Databricks. This sharing mode is called Databricks-to-Databricks sharing, and it is documented in this page.

• Recipients without access to a Unity Catalog-enabled Databricks workspace:

  You must use open sharing, with a secure connection that you manage using token-based authentication (either bearer tokens or OAuth federation). For information about creating open sharing recipients, see Enable Open ID Connect (OIDC) federation for Delta Sharing recipients and Create a recipient object for non-Databricks users using bearer tokens (open sharing).

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 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 an Azure Databricks workspace that has that Unity Catalog metastore attached.
• If you use a Databricks notebook to create the recipient, your compute must use Databricks Runtime 11.3 LTS or above and either standard or dedicated access mode (formerly shared and single user access modes).

For permissions required for other recipient operations (view, update, delete, grant share access, manage properties), see Manage data recipients for Delta Sharing.

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 compute in the workspace they intend to use.

Catalog Explorer

To get the sharing identifier using Catalog Explorer:

1. In your Azure 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 with me tab, click your Databricks sharing organization name in the upper right, and select Copy sharing identifier.

SQL

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

SELECT CURRENT_METASTORE();

CLI

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

databricks metastores summary

You can send your recipient 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 an Azure 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.

Catalog Explorer

1. In your Azure 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 New recipient.

4. Enter the Recipient name.

5. For Recipient type, select Databricks.

6. Enter the recipient's 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.

7. (Optional) Enter a comment.

8. Click Create.

9. (Optional) Create custom Recipient properties.

   On the recipient Overview tab, click the edit icon next to Recipient properties. Then add a property name (Key) and Value. For details, see Manage recipient properties.

SQL

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.

CLI

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.

Next steps

• Manage access to Delta Sharing data shares (for providers) — Grant the recipient access to one or more shares.
• Manage data recipients for Delta Sharing — View, update, delete, manage properties, or restrict access for an existing recipient.
• Create shares for Delta Sharing — Create the shares you want to grant the recipient access to.