Unity Catalog CLI (legacy)
Important
This documentation has been retired and might not be updated.
This information applies to legacy Databricks CLI versions 0.18 and below. Databricks recommends that you use newer Databricks CLI version 0.205 or above instead. See What is the Databricks CLI?. To find your version of the Databricks CLI, run databricks -v
.
To migrate from Databricks CLI version 0.18 or below to Databricks CLI version 0.205 or above, see Databricks CLI migration.
Note
The Unity Catalog CLI is Experimental.
The Unity Catalog CLI requires Databricks CLI (legacy) 0.17.0 or above, configured with authentication. To update the Databricks CLI or to list the installed version, see Update the CLI.
Option and field sample values in the following examples are for illustrative purposes only.
Use the Unity Catalog CLI to work with:
- Unity Catalog resources such as metastores, storage credentials, external locations, catalogs, schemas, tables, and their permissions.
- Delta Sharing resources such as shares, recipients, and providers.
You run Unity Catalog CLI subcommands by appending them to databricks unity-catalog
. These subcommands call the Unity Catalog API, which also includes the Delta Sharing API.
To display usage documentation, run databricks unity-catalog --help
.
Output:
Usage: databricks unity-catalog [OPTIONS] COMMAND [ARGS]...
Utility to interact with Databricks Unity Catalog.
Options:
-v, --version 0.17.1
-h, --help Show this message and exit.
Commands:
catalogs
external-locations
lineage
metastores
permissions
providers
recipients
schemas
shares
storage-credentials
tables
Metastores
Use the unity-catalog metastores
subcommand to work with metastores.
To display usage documentation, run databricks unity-catalog metastores --help
.
- Create a metastore
- Link a metastore with a workspace
- Update a metastore's settings
- List available metastores
- Get information about a metastore
- Get summarized information about the current metastore
- Get the current metastore assignment for a workspace
- Unlink a metastore from a workspace
- Delete a metastore
Create a metastore
To display usage documentation, run databricks unity-catalog metastores create --help
. See also Create a Unity Catalog metastore.
Note
Creating a metastore does not automatically associate the metastore with a workspace or a storage credential. To complete these tasks, see Link a metastore with a workspace, Create a storage credential, and Update a metastore's settings.
Link a metastore with a workspace
If you run this command on a workspace that already has an assigned metastore, you will update that workspace's assigned metastore.
To display usage documentation, run databricks unity-catalog metastores assign --help
.
databricks unity-catalog metastores assign --workspace-id 1234567890123456 \
--metastore-id 12a345b6-7890-1cd2-3456-e789f0a12b34 \
--default-catalog-name main
To get the workspace ID, see Workspace instance names, URLs, and IDs.
To get the metastore ID, run databricks unity-catalog metastores get-summary
. For an example, see Get summarized information about the current metastore.
Output:
{}
See also Create a Unity Catalog metastore.
Update a metastore's settings
To display usage documentation, run databricks unity-catalog metastores update --help
.
databricks unity-catalog metastores update --id 12a345b6-7890-1cd2-3456-e789f0a12b34 \
--json-file update-metastore.json
To get the metastore ID, run databricks unity-catalog metastores get-summary
. For an example, see Get summarized information about the current metastore.
update-metastore.json
:
{
"storage_root_credential_id": "12a345b6-7890-1cd2-3456-e789f0a12b34"
}
To get the storage root credential ID, see Get information about a storage credential.
List available metastores
To display usage documentation, run databricks unity-catalog metastores list --help
.
databricks unity-catalog metastores list
Get information about a metastore
To display usage documentation, run databricks unity-catalog metastores get --help
.
databricks unity-catalog metastores get --id 12a345b6-7890-1cd2-3456-e789f0a12b34
To get the metastore ID, run databricks unity-catalog metastores get-summary
. For an example, see Get summarized information about the current metastore.
Get summarized information about the current metastore
To display usage documentation, run databricks unity-catalog metastores get-summary --help
.
databricks unity-catalog metastores get-summary
Get the current metastore assignment for a workspace
To display usage documentation, run databricks unity-catalog metastores get-assignment --help
.
databricks unity-catalog metastores get-assignment
Output:
{
"workspace_id": 1234567890123456,
"metastore_id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
"default_catalog_name": "main"
}
Unlink a metastore from a workspace
To display usage documentation, run databricks unity-catalog metastores unassign --help
.
databricks unity-catalog metastores unassign --workspace-id 1234567890123456 \
--metastore-id 12a345b6-7890-1cd2-3456-e789f0a12b34
To get the workspace ID, see Workspace instance names, URLs, and IDs.
To get the metastore ID, run databricks unity-catalog metastores get-summary
. For an example, see Get summarized information about the current metastore.
Output:
{}
Delete a metastore
Warning
Before you delete a metastore, you must delete any workspaces that use the metastore or remove the metastore link to those workspaces. Contact Azure Databricks support for assistance with removing metastore links from workspaces.
To display usage documentation, run databricks unity-catalog metastores delete --help
.
To forcibly delete the metastore, use the --force
option.
databricks unity-catalog metastores delete --id 12a345b6-7890-1cd2-3456-e789f0a12b34
To get the metastore ID, run databricks unity-catalog metastores get-summary
. For an example, see Get summarized information about the current metastore.
If the operation is successful, no results are returned.
Storage credentials
Use the unity-catalog storage-credentials
subcommand to work with storage credentials. See Create a storage credential for connecting to Azure Data Lake Storage Gen2.
To display usage documentation, run databricks unity-catalog storage-credentials --help
.
- Create a storage credential
- Update a storage credential's settings
- List available storage credentials
- Get information about a storage credential
- Delete a storage credential
Create a storage credential
To display usage documentation, run databricks unity-catalog storage-credentials create --help
.
See also Create a storage credential for connecting to Azure Data Lake Storage Gen2.
Update a storage credential's settings
To display usage documentation, run databricks unity-catalog storage-credentials update --help
.
List available storage credentials
To display usage documentation, run databricks unity-catalog storage-credentials list --help
.
databricks unity-catalog storage-credentials list
Get information about a storage credential
To display usage documentation, run databricks unity-catalog storage-credentials get --help
.
databricks unity-catalog storage-credentials get --name my-storage-root-credential
Delete a storage credential
To display usage documentation, run databricks unity-catalog storage-credentials delete --help
.
To forcibly delete the storage credential, use the --force
option.
databricks unity-catalog storage-credentials delete --name my-storage-root-credential
If the operation is successful, no results are returned.
External locations
Use the unity-catalog external-locations
subcommand to work with external locations. See Create an external location to connect cloud storage to Azure Databricks.
To display usage documentation, run databricks unity-catalog external-locations --help
.
- Create an external location
- Validate an external location and credential pair
- Update an external location's settings
- List available external locations
- Get information about an external location
- Delete an external location
Create an external location
To display usage documentation, run databricks unity-catalog external-locations create --help
. See also Create an external location to connect cloud storage to Azure Databricks.
Validate an external location and credential pair
To display usage documentation, run databricks unity-catalog external-locations validate --help
.
Validate an external location name and credential pair after you create them
databricks unity-catalog external-locations validate --name my-external-location \
--cred-name my-storage-root-credential
Output:
{
"isDir": true,
"results": [
{
"operation": "READ",
"result": "PASS"
},
{
"operation": "LIST",
"result": "PASS"
},
{
"operation": "WRITE",
"result": "PASS"
},
{
"operation": "DELETE",
"result": "PASS"
}
]
}
Update an external location's settings
To display usage documentation, run databricks unity-catalog external-locations update --help
.
databricks unity-catalog external-locations update --name my-external-location \
--json-file update-external-location.json
udpate-external-location.json
:
{
"name": "my-external-location-2"
}
List available external locations
To display usage documentation, run databricks unity-catalog external-locations list --help
.
databricks unity-catalog external-locations list
Get information about an external location
To display usage documentation, run databricks unity-catalog external-locations get --help
.
databricks unity-catalog external-locations get --name my-external-location
Delete an external location
To display usage documentation, run databricks unity-catalog external-locations delete --help
.
To forcibly delete the external location, use the --force
option.
databricks unity-catalog external-locations delete --name my-external-location
If the operation is successful, no results are returned.
Catalogs
Use the unity-catalog catalogs
subcommand to work with catalogs.
To display usage documentation, run databricks unity-catalog catalogs --help
.
- Create a catalog
- Update a catalog's settings
- List available catalogs
- Get information about a catalog
- Delete a catalog
Create a catalog
To display usage documentation, run databricks unity-catalog catalogs create --help
. See also Create catalogs.
databricks unity-catalog catalogs create --name my-catalog
Output:
{
"name": "my-catalog",
"owner": "someone@example.com",
"metastore_id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
"created_at": 1656113178995,
"created_by": "someone@example.com",
"updated_at": 1656113178995,
"updated_by": "someone@example.com",
"catalog_type": "MANAGED_CATALOG"
}
Update a catalog's settings
To display usage documentation, run databricks unity-catalog catalogs update --help
.
databricks unity-catalog catalogs update --name my-catalog \
--json-file update-catalog.json
update-catalog.json
:
{
"name": "my-catalog-2",
"owner": "someone@example.com"
}
Output:
{
"name": "my-catalog-2",
"owner": "someone@example.com",
"metastore_id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
"created_at": 1656355967835,
"created_by": "someone@example.com",
"updated_at": 1656356095989,
"updated_by": "someone@example.com",
"catalog_type": "MANAGED_CATALOG"
}
List available catalogs
To display usage documentation, run databricks unity-catalog catalogs list --help
.
databricks unity-catalog catalogs list
Output:
{
"catalogs": [
{
"name": "main",
"owner": "someone@example.com",
"comment": "Main catalog (auto-created)",
"metastore_id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
"created_at": 1656112029355,
"created_by": "someone@example.com",
"updated_at": 1656112029355,
"updated_by": "someone@example.com",
"catalog_type": "MANAGED_CATALOG"
},
{
"...": "..."
}
]
}
Get information about a catalog
To display usage documentation, run databricks unity-catalog catalogs get --help
.
databricks unity-catalog catalogs get --name my-catalog
Output:
{
"name": "my-catalog",
"owner": "someone@example.com",
"metastore_id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
"created_at": 1656113178995,
"created_by": "someone@example.com",
"updated_at": 1656113178995,
"updated_by": "someone@example.com",
"catalog_type": "MANAGED_CATALOG"
}
Delete a catalog
To display usage documentation, run databricks unity-catalog catalogs delete --help
. See also Delete a catalog.
To forcibly delete a catalog, use the --purge
option.
databricks unity-catalog catalogs delete --name my-catalog
If the operation is successful, no results are returned.
Schemas
Use the unity-catalog schemas
subcommand to work with schemas.
To display usage documentation, run databricks unity-catalog schemas --help
.
- Create a schema
- Change a schema's settings
- List available schemas
- Get information about a schema
- Delete a schema
Create a schema
To display usage documentation, run databricks unity-catalog schemas create --help
. See also Create schemas.
databricks unity-catalog schemas create --catalog-name my-catalog \
--name my-schema
Output:
{
"name": "my-schema",
"catalog_name": "my-catalog",
"owner": "someone@example.com",
"metastore_id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
"full_name": "my-catalog.my-schema",
"created_at": 1656113607800,
"created_by": "someone@example.com",
"updated_at": 1656113607800,
"updated_by": "someone@example.com"
}
Change a schema's settings
To display usage documentation, run databricks unity-catalog schemas update --help
.
databricks unity-catalog schemas update --full-name my-catalog.my-schema \
--json-file update-schema.json
update-schema.json
:
{
"name": "my-schema-2",
"owner": "someone@example.com"
}
Output:
{
"name": "my-schema-2",
"catalog_name": "my-catalog",
"owner": "someone@example.com",
"comment": "Default schema (auto-created)",
"metastore_id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
"full_name": "my-catalog.my-schema-2",
"created_at": 1656355967837,
"created_by": "someone@example.com",
"updated_at": 1656356592786,
"updated_by": "someone@example.com"
}
List available schemas
To display usage documentation, run databricks unity-catalog schemas list --help
.
databricks unity-catalog schemas list --catalog-name my-catalog
Output:
{
"schemas": [
{
"name": "default",
"catalog_name": "my-catalog",
"owner": "someone@example.com",
"comment": "Default schema (auto-created)",
"metastore_id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
"full_name": "my-catalog.default",
"created_at": 1656113178996,
"created_by": "someone@example.com",
"updated_at": 1656113178996,
"updated_by": "someone@example.com"
},
{
"...": "..."
}
]
}
Get information about a schema
To display usage documentation, run databricks unity-catalog schemas get --help
.
databricks unity-catalog schemas get --full-name my-catalog.my-schema
Output:
{
"name": "my-schema",
"catalog_name": "my-catalog",
"owner": "someone@example.com",
"metastore_id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
"full_name": "my-catalog.my-schema",
"created_at": 1656113607800,
"created_by": "someone@example.com",
"updated_at": 1656113607800,
"updated_by": "someone@example.com"
}
Delete a schema
To display usage documentation, run databricks unity-catalog schemas delete --help
. See also Delete a schema.
To forcibly delete a schema, use the --purge
option.
databricks unity-catalog schemas delete --full-name my-catalog.my-schema
If the operation is successful, no results are returned.
Tables
Use the unity-catalog tables
subcommand to work with tables.
Note
Creating tables with the Unity Catalog CLI is not supported. To create tables, see What is a table? and Tutorial: Create your first table and grant privileges.
To display usage documentation, run databricks unity-catalog tables --help
.
- List available tables
- List summaries of available tables
- Get information about a table
- Delete a table
List available tables
To display usage documentation, run databricks unity-catalog tables list --help
.
databricks unity-catalog tables list --catalog-name main \
--schema-name default
List summaries of available tables
To display usage documentation, run databricks unity-catalog tables list-summaries --help
.
databricks unity-catalog tables list-summaries --catalog-name main
Output:
{
"tables": [
{
"full_name": "main.default.mytable",
"table_type": "MANAGED"
},
{
"...": "..."
}
]
}
Get information about a table
To display usage documentation, run databricks unity-catalog tables get --help
.
databricks unity-catalog tables get --full-name main.default.mytable
Delete a table
To display usage documentation, run databricks unity-catalog tables delete --help
.
databricks unity-catalog tables delete --full-name main.default.mytable
If the operation is successful, no results are returned.
Lineages
Use the unity-catalog lineage
subcommand to work with table and column lineages.
To display usage documentation, run databricks unity-catalog lineage --help
.
List a table's lineage
To display usage documentation, run databricks unity-catalog lineage table --help
.
databricks unity-catalog lineage table --table-name main.default.mytable \
--level 1
List a column's lineage
To display usage documentation, run databricks unity-catalog lineage column --help
.
databricks unity-catalog lineage column --table-name main.default.mytable \
--column-name id
Permissions
Use the unity-catalog permissions
subcommand to work with permissions for securable objects. See also Manage privileges in Unity Catalog.
To display usage documentation, run databricks unity-catalog permissions --help
.
Get information about permissions for a securable object
To display usage documentation, run databricks unity-catalog permissions get --help
. See also Unity Catalog privileges and securable objects.
Catalog
databricks unity-catalog permissions get --catalog main
Output:
{
"privilege_assignments": [
{
"principal": "account users",
"privileges": [
"USE CATALOG"
]
}
]
}
Schema
databricks unity-catalog permissions get --schema main.default
Output:
{
"privilege_assignments": [
{
"principal": "account users",
"privileges": [
"USE SCHEMA"
]
}
]
}
Table
databricks unity-catalog permissions get --table main.default.mytable
Output:
{
"privilege_assignments": [
{
"principal": "account users",
"privileges": [
"SELECT"
]
}
]
}
Storage credential
databricks unity-catalog permissions get --storage-credential my-storage-root-credential
Output:
{
"privilege_assignments": [
{
"principal": "account users",
"privileges": [
"READ_FILES"
]
}
]
}
External location
databricks unity-catalog permissions get --external-location my-external-location
Output:
{
"privilege_assignments": [
{
"principal": "account users",
"privileges": [
"READ_FILES"
]
}
]
}
Update a securable object's permissions
To display usage documentation, run databricks unity-catalog permissions update --help
. See also Unity Catalog privileges and securable objects.
Catalog
databricks unity-catalog permissions update --catalog \
--json-file update-catalog-permissions.json
update-catalog-permissions.json
:
{
"changes": [
{
"principal": "account users",
"add": [ "USE CATALOG" ],
"remove": [ "CREATE SCHEMA" ]
}
]
}
Schema
databricks unity-catalog permissions update --schema \
--json-file update-schema-permissions.json
update-schema-permissions.json
:
{
"changes": [
{
"principal": "account users",
"add": [ "USE SCHEMA" ],
"remove": [ "CREATE TABLE" ]
},
{
"principal": "admin team",
"add": [ "CREATE TABLE" ]
}
]
}
Table
databricks unity-catalog permissions update --table \
--json-file update-table-permissions.json
update-table-permissions.json
:
{
"changes": [
{
"principal": "account users",
"add": [ "SELECT" ],
"remove": [ "MODIFY" ]
},
{
"principal": "admin team",
"add": [ "ALL" ]
}
]
}
Storage credential
databricks unity-catalog permissions update --storage-credential \
--json-file update-storage-credential-permissions.json
update-storage-credential-permissions.json
:
{
"changes": [
{
"principal": "account users",
"remove": [ "READ FILES" ]
},
{
"principal": "storage team",
"add": [ "READ FILES",
"WRITE FILES",
"CREATE EXTERNAL TABLE"
]
},
{
"principal": "admin team",
"add": [ "ALL" ]
}
]
}
External location
databricks unity-catalog permissions update --external-location \
--json-file update-external-location-permissions.json
update-external-location-permissions.json
:
{
"changes": [
{
"principal": "account users",
"remove": [ "READ FILES" ]
},
{
"principal": "storage team",
"add": [ "READ FILES",
"WRITE FILES",
"CREATE EXTERNAL TABLE"
]
},
{
"principal": "admin team",
"add": [ "ALL" ]
}
]
}
Shares
Use the unity-catalog shares
subcommand to work with shares, which are objects that contain collections of tables in a Delta Sharing enabled Unity Catalog metastore that you want to share as a group with Delta Sharing recipients. A share can contain tables from only a single metastore. See Create and manage shares for Delta Sharing.
To display usage documentation, run databricks unity-catalog shares --help
.
- Create a share
- Update a share's settings
- Update a share's permissions
- List available shares
- Get information about a share
- List a share's permissions
- Delete a share
Create a share
To display usage documentation, run databricks unity-catalog shares create --help
. See also Create and manage shares for Delta Sharing.
databricks unity-catalog shares create --name my-share
Output:
{
"name": "my-share",
"created_at": 1656433327533,
"created_by": "someone@example.com",
"owner": "someone@example.com"
}
Update a share's settings
To display usage documentation, run databricks unity-catalog shares update --help
. See also Update shares.
Add a table to a share
databricks unity-catalog shares update --name my-share \
--add-table main.default.mytable
Output:
{
"name": "my-share",
"objects": [
{
"name": "main.default.mytable",
"data_object_type": "TABLE",
"added_at": 1656434168847,
"added_by": "someone@example.com",
"shared_as": "default.mytable",
"cdf_enabled": false
}
],
"created_at": 1656433327533,
"created_by": "someone@example.com",
"owner": "someone@example.com"
}
See also Add tables to a share.
Remove a table from a share
databricks unity-catalog shares update --name my-share \
--remove-table main.default.mytable
Output:
{
"name": "my-share",
"created_at": 1656433327533,
"created_by": "someone@example.com",
"owner": "someone@example.com"
}
See also Add tables to a share.
Update a share's permissions
To display usage documentation, run databricks unity-catalog shares update-permissions --help
. See also Manage access to Delta Sharing data shares (for providers).
databricks unity-catalog shares update-permissions --name my-share \
--json-file update-share-permissions.json
update-share-permissions.json
:
{
"privilege_assignments": [
{
"principal": "my-recipient",
"privileges": [
"SELECT"
]
}
]
}
List available shares
To display usage documentation, run databricks unity-catalog shares list --help
. See also View shares and share details.
databricks unity-catalog shares list
Output:
{
"shares": [
{
"name": "my-share",
"created_at": 1656433327533,
"created_by": "someone@example.com",
"owner": "someone@example.com"
},
{
"...": "..."
}
]
}
Get information about a share
To display usage documentation, run databricks unity-catalog shares get --help
. See also View shares and share details.
databricks unity-catalog shares get --name my-share
Output:
{
"name": "my-share",
"created_at": 1656433327533,
"created_by": "someone@example.com",
"owner": "someone@example.com"
}
List a share's permissions
To display usage documentation, run databricks unity-catalog shares list-permissions --help
. See also View the recipients who have permissions on a share.
databricks unity-catalog shares list-permissions --name my-share
Output:
{
"privilege_assignments": [
{
"principal": "my-recipient",
"privileges": [
"SELECT"
]
}
]
}
Delete a share
To display usage documentation, run databricks unity-catalog shares delete --help
. See also Delete a share.
databricks unity-catalog shares delete --name my-share
If the operation is successful, no results are returned.
Recipients
Use the unity-catalog recipients
subcommand to work with data recipients for Delta Sharing enabled Unity Catalog metastores. Data recipients are people or groups whom an Azure Databricks user shares data with outside of the Azure Databricks user's organization. See Create and manage data recipients for Delta Sharing.
To display usage documentation, run databricks unity-catalog recipients --help
.
- Create a recipient
- Change a recipient's settings
- Rotate a recipient's token
- List available recipients
- List a recipient's share permissions
- Get information about a recipient
- Delete a recipient
Create a recipient
To display usage documentation, run databricks unity-catalog recipients create --help
. See also Create and manage data recipients for Delta Sharing.
To generate a new activation URL for a recipient, run databricks unity-catalog recipients rotate-token
. For an example, see Rotate a recipient's token.
databricks unity-catalog recipients create --name my-recipient
Output:
{
"name": "my-recipient",
"created_at": 1656435288003,
"created_by": "someone@example.com",
"tokens": [
{
"id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
"created_at": 1656435288005,
"created_by": "someone@example.com",
"activation_url": "https://example.com/delta_sharing/retrieve_config.html?<unique-id>",
"expiration_time": 1656521688006,
"updated_at": 1656435288006,
"updated_by": "someone@example.com"
}
],
"authentication_type": "TOKEN",
"updated_at": 1656435288003,
"updated_by": "someone@example.com",
"owner": "someone@example.com"
}
Change a recipient's settings
To display usage documentation, run databricks unity-catalog recipients update --help
.
databricks unity-catalog recipients update --name my-recipient \
--json-file update-recipient-settings.json
update-recipient-settings.json
:
{
"name": "my-recipient-2"
}
Output:
{
"name": "my-recipient-2",
"created_at": 1656435288003,
"created_by": "someone@example.com",
"tokens": [
{
"id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
"created_at": 1656435288005,
"created_by": "someone@example.com",
"expiration_time": 1656436808507,
"updated_at": 1656435908507,
"updated_by": "someone@example.com"
},
{
"id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
"created_at": 1656435908509,
"created_by": "someone@example.com",
"activation_url": "https://example.com/delta_sharing/retrieve_config.html?<unique-id>",
"expiration_time": 1656522308510,
"updated_at": 1656435908510,
"updated_by": "someone@example.com"
}
],
"authentication_type": "TOKEN",
"updated_at": 1656436740986,
"updated_by": "someone@example.com",
"owner": "someone@example.com"
}
Rotate a recipient's token
To display usage documentation, run databricks unity-catalog recipients rotate-token --help
. See also Manage recipient tokens (open sharing).
databricks unity-catalog recipients rotate-token --name my-recipient \
--existing-token-expire-in-seconds 900
Output:
{
"name": "my-recipient",
"created_at": 1656435288003,
"created_by": "someone@example.com",
"tokens": [
{
"id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
"created_at": 1656435288005,
"created_by": "someone@example.com",
"expiration_time": 1656436808507,
"updated_at": 1656435908507,
"updated_by": "someone@example.com"
},
{
"id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
"created_at": 1656435908509,
"created_by": "someone@example.com",
"activation_url": "https://example.com/delta_sharing/retrieve_config.html?<unique-id>",
"expiration_time": 1656522308510,
"updated_at": 1656435908510,
"updated_by": "someone@example.com"
}
],
"authentication_type": "TOKEN",
"updated_at": 1656435288003,
"updated_by": "someone@example.com",
"owner": "someone@example.com"
}
List available recipients
To display usage documentation, run databricks unity-catalog recipients list --help
. See also View recipients.
databricks unity-catalog recipients list
Output:
{
"recipients": [
{
"name": "my-recipient",
"created_at": 1656435288003,
"created_by": "someone@example.com",
"tokens": [
{
"id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
"created_at": 1656435288005,
"created_by": "someone@example.com",
"activation_url": "https://example.com/delta_sharing/retrieve_config.html?<unique-id>",
"expiration_time": 1656521688006,
"updated_at": 1656435288006,
"updated_by": "someone@example.com"
}
],
"authentication_type": "TOKEN",
"updated_at": 1656435288003,
"updated_by": "someone@example.com",
"owner": "someone@example.com"
}
]
}
List a recipient's share permissions
To display usage documentation, run databricks unity-catalog recipients list-permissions --help
. See also View a recipient's share permissions.
databricks unity-catalog recipients list-permissions --name my-recipient
Output:
{
"permissions_out": [
{
"share_name": "my-share",
"privilege_assignments": [
{
"privileges": [
"SELECT"
]
}
]
}
]
}
Get information about a recipient
To display usage documentation, run databricks unity-catalog recipients get --help
. See also View recipient details.
databricks unity-catalog recipients get --name my-recipient
Output:
{
"name": "my-recipient",
"created_at": 1656435288003,
"created_by": "someone@example.com",
"tokens": [
{
"id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
"created_at": 1656435288005,
"created_by": "someone@example.com",
"activation_url": "https://example.com/delta_sharing/retrieve_config.html?<unique-id>",
"expiration_time": 1656521688006,
"updated_at": 1656435288006,
"updated_by": "someone@example.com"
}
],
"authentication_type": "TOKEN",
"updated_at": 1656435288003,
"updated_by": "someone@example.com",
"owner": "someone@example.com"
}
Delete a recipient
To display usage documentation, run databricks unity-catalog recipients delete --help
. See also Delete a recipient.
databricks unity-catalog recipients delete --name my-recipient
If the operation is successful, no results are returned.
Providers
If you are a Delta Sharing shared data recipient, use the unity-catalog providers
subcommand to work with Delta Sharing data providers. See Manage Delta Sharing providers (for data recipients).
To display usage documentation, run databricks unity-catalog providers --help
.
- Create a provider
- Update a provider's settings
- List available providers
- Get information about a provider
- List a provider's available shares
- Delete a provider
Create a provider
If you are a recipient of data shared using the open sharing protocol and you are using a Databricks workspace that is attached to a Unity Catalog metastore, you can create a provider object in your Unity Catalog metastore. You can then manage access to the shared data using Unity Catalog.
Important
This scenario is rare. If you are using a Databricks workspace that is enabled for Unity Catalog, and another Databricks customer is sharing data with you, they should use Databricks-to-Databricks sharing. With Databricks-to-Databricks sharing, provider objects are created for you in Unity Catalog.
To create a provider, you must:
- Be a metastore admin or user with the
CREATE_PROVIDER
privilege for the metastore. - Have access to the downloaded credential file. See Get access in the open sharing model.
Run the following command, replacing my-provider
with the name you want to give to the provider and config.share
with the path to your downloaded credential file, which is named config.share by default.
databricks unity-catalog providers create --name my-provider \
--recipient-profile-json-file config.share
Update a provider's settings
To display usage documentation, run databricks unity-catalog providers update --help
.
databricks unity-catalog providers update --name my-provider \
--new-name my-provider-2
List available providers
To display usage documentation, run databricks unity-catalog providers list --help
.
databricks unity-catalog providers list
Get information about a provider
To display usage documentation, run databricks unity-catalog providers get --help
.
databricks unity-catalog providers get --name my-provider
List a provider's available shares
To display usage documentation, run databricks unity-catalog providers list-shares --help
.
databricks unity-catalog providers list-shares --name my-provider
Delete a provider
To display usage documentation, run databricks unity-catalog providers delete --help
.
databricks unity-catalog providers delete --name my-provider
If the operation is successful, no results are returned.