shares command group

The shares command group within the Databricks CLI allows you to manage shares in Unity Catalog.

A share is a container instantiated with shares create. Once created you can iteratively register a collection of existing data assets defined within the metastore using shares update. You can register data assets under their original name, qualified by their original schema, or provide alternate exposed names.

databricks shares create

Create a new share for data objects. Data objects can be added after creation with update. The caller must be a metastore admin or have the CREATE_SHARE privilege on the metastore.

databricks shares create NAME [flags]

Arguments

NAME

    Name of the share.

Options

--comment string

    User-provided free-form text description.

--json JSON

    The inline JSON string or the @path to the JSON file with the request body.

--storage-root string

    Storage root URL for the share.

Global flags

Examples

The following examples create a share named my-analytics-share with a comment:

databricks shares create my-analytics-share --comment "Sales analytics data share"

The following example creates a share with a specific storage root:

databricks shares create my-analytics-share --storage-root "s3://my-bucket/share-data"

databricks shares delete

Delete a share from the metastore. The caller must be an owner of the share.

databricks shares delete NAME [flags]

Arguments

NAME

    The name of the share.

Options

Global flags

Examples

The following example deletes a share named my-analytics-share:

databricks shares delete my-analytics-share

databricks shares get

Get a share from the metastore. The caller must be a metastore admin or the owner of the share.

databricks shares get NAME [flags]

Arguments

NAME

    The name of the share.

Options

--include-shared-data

    Query for data to include in the share.

Global flags

Examples

The following example gets information about a share named my-analytics-share:

databricks shares get my-analytics-share

The following example gets a share with details about the shared data:

databricks shares get my-analytics-share --include-shared-data

databricks shares list

List shares from the metastore. The caller must be a metastore admin or the owner of the share. There is no guarantee of a specific ordering of the elements in the array.

databricks shares list [flags]

Arguments

None

Options

--max-results int

    Maximum number of shares to return.

--page-token string

    Opaque pagination token to go to next page based on previous query.

Global flags

Examples

The following example lists all shares:

databricks shares list

databricks shares update

Update the share with the changes and data objects in the request. The caller must be the owner of the share or a metastore admin.

When the caller is a metastore admin, only the owner field can be updated.

In the case the share name is changed, updateShare requires that the caller is the owner of the share and has the CREATE_SHARE privilege.

If there are notebook files in the share, the storage_root field cannot be updated.

For each table that is added through this method, the share owner must also have SELECT privilege on the table. This privilege must be maintained indefinitely for recipients to be able to access the table. Typically, you should use a group as the share owner.

Table removals through update do not require additional privileges.

databricks shares update NAME [flags]

Arguments

NAME

    The name of the share.

Options

--comment string

    User-provided free-form text description.

--json JSON

    The inline JSON string or the @path to the JSON file with the request body.

--new-name string

    New name for the share.

--owner string

    Username of current owner of share.

--storage-root string

    Storage root URL for the share.

Global flags

Examples

The following example updates a share's comment:

databricks shares update my-analytics-share --comment "Updated sales analytics data share"

The following example changes a share's name:

databricks shares update my-analytics-share --new-name "sales-analytics-share"

The following example updates a share's owner:

databricks shares update my-analytics-share --owner "someone@example.com"

The following example updates a share using JSON configuration:

databricks shares update my-analytics-share --json '{
  "comment": "Updated share with new tables",
  "objects": [
    {
      "name": "sales.customers",
      "data_object_type": "TABLE"
    }
  ]
}'

databricks shares share-permissions

Get permissions for a data share from the metastore. The caller must be a metastore admin or the owner of the share.

databricks shares share-permissions NAME [flags]

Arguments

NAME

    The name of the share.

Options

--max-results int

    Maximum number of permissions to return.

--page-token string

    Opaque pagination token to go to next page based on previous query.

Global flags

Examples

The following example gets permissions for a share named my-analytics-share:

databricks shares share-permissions my-analytics-share

databricks shares update-permissions

Update the permissions for a data share in the metastore. The caller must be a metastore admin or an owner of the share.

For new recipient grants, the user must also be the recipient owner or metastore admin. recipient revocations do not require additional privileges.

databricks shares update-permissions NAME [flags]

Arguments

NAME

    The name of the share.

Options

--json JSON

    The inline JSON string or the @path to the JSON file with the request body.

--omit-permissions-list

    Optional.

Global flags

Examples

The following example grants permissions to a recipient:

databricks shares update-permissions my-analytics-share --json '{
  "changes": [
    {
      "principal": "recipient-name",
      "add": ["SELECT"]
    }
  ]
}'

The following example revokes permissions from a recipient:

databricks shares update-permissions my-analytics-share --json '{
  "changes": [
    {
      "principal": "recipient-name",
      "remove": ["SELECT"]
    }
  ]
}'

Global flags

--debug

  Whether to enable debug logging.

-h or --help

    Display help for the Databricks CLI or the related command group or the related command.

--log-file string

    A string representing the file to write output logs to. If this flag is not specified then the default is to write output logs to stderr.

--log-format format

    The log format type, text or json. The default value is text.

--log-level string

    A string representing the log format level. If not specified then the log format level is disabled.

-o, --output type

    The command output type, text or json. The default value is text.

-p, --profile string

    The name of the profile in the ~/.databrickscfg file to use to run the command. If this flag is not specified then if it exists, the profile named DEFAULT is used.

--progress-format format

    The format to display progress logs: default, append, inplace, or json

-t, --target string

    If applicable, the bundle target to use