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

To display usage documentation, run databricks unity-catalog metastores create --help. See also Create a Unity Catalog metastore.

databricks unity-catalog metastores create --name my-metastore \
                                           --region us-west-2 \
                                           --storage-root s3://my-bucket/abcdefghij

If you do not specify the region, the metastore is created in your current workspace region.

Output:

{
  "name": "my-metastore",
  "storage_root": "s3://my-bucket/abcdefghij/12a345b6-7890-1cd2-3456-e789f0a12b34",
  "metastore_id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
  "created_at": 1656112029354,
  "created_by": "someone@example.com",
  "updated_at": 1656112029354,
  "updated_by": "someone@example.com",
  "delta_sharing_enabled": false,
  "owner": "someone@example.com",
  "region": "us-west-2",
  "cloud": "aws",
  "global_metastore_id": "aws:us-west-2:12a345b6-7890-1cd2-3456-e789f0a12b34",
  "delta_sharing_scope": "INTERNAL",
  "privilege_model_version": "0.1"
}

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.

Output:

{
  "name": "my-metastore",
  "storage_root": "s3://my-bucket/abcdefghij/12a345b6-7890-1cd2-3456-e789f0a12b34",
  "default_data_access_config_id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
  "metastore_id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
  "created_at": 1656365260817,
  "created_by": "someone@example.com",
  "updated_at": 1656366434069,
  "updated_by": "someone@example.com",
  "delta_sharing_enabled": true,
  "owner": "someone@example.com",
  "delta_sharing_recipient_token_lifetime_in_seconds": 86400,
  "region": "us-west-2",
  "storage_root_credential_id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
  "cloud": "aws",
  "global_metastore_id": "aws:us-west-2:12a345b6-7890-1cd2-3456-e789f0a12b34",
  "delta_sharing_scope": "INTERNAL_AND_EXTERNAL",
  "privilege_model_version": "0.1"
}

List available metastores

To display usage documentation, run databricks unity-catalog metastores list --help.

databricks unity-catalog metastores list

Output:

{
  "metastores": [
    {
      "name": "my-metastore",
      "storage_root": "s3://my-bucket/abcdefghij/12a345b6-7890-1cd2-3456-e789f0a12b34",
      "default_data_access_config_id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
      "metastore_id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
      "created_at": 1656365260817,
      "created_by": "someone@example.com",
      "updated_at": 1656366434069,
      "updated_by": "someone@example.com",
      "delta_sharing_enabled": true,
      "owner": "someone@example.com",
      "delta_sharing_recipient_token_lifetime_in_seconds": 86400,
      "region": "us-west-2",
      "storage_root_credential_id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
      "cloud": "aws",
      "global_metastore_id": "aws:us-west-2:12a345b6-7890-1cd2-3456-e789f0a12b34",
      "delta_sharing_scope": "INTERNAL_AND_EXTERNAL",
      "privilege_model_version": "0.1"
    },
    {
      "...": "..."
    }
  ]
}

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.

Output:

{
  "name": "my-metastore",
  "storage_root": "s3://my-bucket/abcdefghij/12a345b6-7890-1cd2-3456-e789f0a12b34",
  "default_data_access_config_id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
  "metastore_id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
  "created_at": 1656365260817,
  "created_by": "someone@example.com",
  "updated_at": 1656366434069,
  "updated_by": "someone@example.com",
  "delta_sharing_enabled": true,
  "owner": "someone@example.com",
  "delta_sharing_recipient_token_lifetime_in_seconds": 86400,
  "region": "us-west-2",
  "storage_root_credential_id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
  "cloud": "aws",
  "global_metastore_id": "aws:us-west-2:12a345b6-7890-1cd2-3456-e789f0a12b34",
  "delta_sharing_scope": "INTERNAL_AND_EXTERNAL",
  "privilege_model_version": "0.1"
}

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

Output:

{
  "metastore_id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
  "name": "my-metastore",
  "default_data_access_config_id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
  "storage_root_credential_id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
  "cloud": "aws",
  "region": "us-west-2",
  "global_metastore_id": "aws:us-west-2:12a345b6-7890-1cd2-3456-e789f0a12b34",
  "storage_root_credential_name": "my-storage-root-credential"
}

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

To display usage documentation, run databricks unity-catalog storage-credentials --help.

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

databricks unity-catalog storage-credentials create --json-file create-storage-credential.json

create-storage-credential.json:

{
  "name": "my-storage-root-credential",
  "aws_iam_role": {
    "role_arn": "arn:aws:iam::123456789012:role/my-role"
  }
}

Output:

{
  "id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
  "name": "my-storage-root-credential",
  "aws_iam_role": {
    "role_arn": "arn:aws:iam::123456789012:role/my-role",
    "unity_catalog_iam_arn": "arn:aws:iam::414351767826:role/my-role",
    "external_id": "12a345b6-7890-1cd2-3456-e789f0a12b34"
  },
  "owner": "someone@example.com",
  "metastore_id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
  "created_at": 1656366379705,
  "created_by": "someone@example.com",
  "updated_at": 1656366379705,
  "updated_by": "someone@example.com",
  "used_for_managed_storage": true
}

Update a storage credential’s settings

To display usage documentation, run databricks unity-catalog storage-credentials update --help.

databricks unity-catalog storage-credentials update --name my-storage-root-credential
                                                    --json-file update-storage-credential.json

update-storage-credential.json:

{
  "name": "my-storage-root-credential-2",
  "aws_iam_role": {
    "role_arn": "arn:aws:iam::123456789012:role/my-role"
  }
}

Output:

{
  "id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
  "name": "my-storage-root-credential-2",
  "aws_iam_role": {
    "role_arn": "arn:aws:iam::123456789012:role/my-role",
    "unity_catalog_iam_arn": "arn:aws:iam::414351767826:role/my-role",
    "external_id": "12a345b6-7890-1cd2-3456-e789f0a12b34"
  },
  "owner": "someone@example.com",
  "metastore_id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
  "created_at": 1656366379705,
  "created_by": "someone@example.com",
  "updated_at": 1656366379705,
  "updated_by": "someone@example.com",
  "used_for_managed_storage": true
}

List available storage credentials

To display usage documentation, run databricks unity-catalog storage-credentials list --help. ```bash databricks unity-catalog storage-credentials list ```

Output:

"storage_credentials": [
  {
    "id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
    "name": "my-storage-root-credential",
    "aws_iam_role": {
      "role_arn": "arn:aws:iam::123456789012:role/my-role",
      "unity_catalog_iam_arn": "arn:aws:iam::123456789012:role/my-role",
      "external_id": "12a345b6-7890-1cd2-3456-e789f0a12b34"
    },
    "owner": "someone@example.com",
    "metastore_id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
    "created_at": 1656366379705,
    "created_by": "someone@example.com",
    "updated_at": 1656366379705,
    "updated_by": "someone@example.com",
    "used_for_managed_storage": true
  },
  {
    "...": "..."
  }
]

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

Output:

{
  "id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
  "name": "my-storage-root-credential",
  "aws_iam_role": {
    "role_arn": "arn:aws:iam::123456789012:role/my-storage-root-credential",
    "unity_catalog_iam_arn": "arn:aws:iam::414351767826:role/my-role",
    "external_id": "12a345b6-7890-1cd2-3456-e789f0a12b34"
  },
  "owner": "someone@example.com",
  "metastore_id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
  "created_at": 1656353829777,
  "created_by": "someone@example.com",
  "updated_at": 1656353829777,
  "updated_by": "someone@example.com"
}

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

To display usage documentation, run databricks unity-catalog external-locations --help.

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

databricks unity-catalog external-locations create --name my-external-location \
                                                   --url s3://my-bucket/abcdefghij \
                                                   --storage-credential-name my-storage-root-credential

Output:

{
  "name": "my-external-location",
  "url": "s3://my-bucket/abcdefghij",
  "credential_name": "my-storage-root-credential",
  "owner": "someone@example.com",
  "metastore_id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
  "credential_id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
  "created_at": 1656370003059,
  "created_by": "someone@example.com",
  "updated_at": 1656370003059,
  "updated_by": "someone@example.com",
  "read_only": false
}

Validate an external location and credential pair

To display usage documentation, run databricks unity-catalog external-locations validate --help.

Validate an external location URL and credential pair before you create them

databricks unity-catalog external-locations validate --url s3://my-bucket/abcdefghij \
                                                     --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"
    }
  ]
}

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"
}

Output:

{
  "name": "my-external-location-2",
  "url": "s3://my-bucket/abcdefghij",
  "credential_name": "my-storage-root-credential",
  "owner": "someone@example.com",
  "metastore_id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
  "credential_id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
  "created_at": 1656370003059,
  "created_by": "someone@example.com",
  "updated_at": 1656370379651,
  "updated_by": "someone@example.com",
  "read_only": false
}

List available external locations

To display usage documentation, run databricks unity-catalog external-locations list --help.

databricks unity-catalog external-locations list

Output:

{
  "external_locations": [
    {
      "name": "my-external-location",
      "url": "s3://my-bucket/abcdefghij",
      "credential_name": "my-storage-root-credential",
      "owner": "someone@example.com",
      "metastore_id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
      "credential_id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
      "created_at": 1656370003059,
      "created_by": "someone@example.com",
      "updated_at": 1656370379651,
      "updated_by": "someone@example.com",
      "read_only": false
    },
    {
      "...": "..."
    }
  ]
}

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

Output:

{
  "name": "my-external-location",
  "url": "s3://my-bucket/abcdefghij",
  "credential_name": "my-storage-root-credential",
  "owner": "someone@example.com",
  "metastore_id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
  "credential_id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
  "created_at": 1656370003059,
  "created_by": "someone@example.com",
  "updated_at": 1656370003059,
  "updated_by": "someone@example.com",
  "read_only": false
}

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

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

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 are tables and views? and Tutorial: Create your first table and grant privileges.

To display usage documentation, run databricks unity-catalog tables --help.

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

Output:

{
  "tables": [
    {
      "name": "mytable",
      "catalog_name": "main",
      "schema_name": "default",
      "table_type": "MANAGED",
      "data_source_format": "DELTA",
      "columns": [
        {
          "name": "id",
          "type_text": "int",
          "type_json": "{\"name\":\"id\",\"type\":\"integer\",\"nullable\":true,\"metadata\":{}}",
          "type_name": "INT",
          "type_precision": 0,
          "type_scale": 0,
          "position": 0,
          "nullable": true
        },
        {
          "name": "name",
          "type_text": "string",
          "type_json": "{\"name\":\"name\",\"type\":\"string\",\"nullable\":true,\"metadata\":{}}",
          "type_name": "STRING",
          "type_precision": 0,
          "type_scale": 0,
          "position": 1,
          "nullable": true
        },
        {
          "name": "age",
          "type_text": "int",
          "type_json": "{\"name\":\"age\",\"type\":\"integer\",\"nullable\":true,\"metadata\":{}}",
          "type_name": "INT",
          "type_precision": 0,
          "type_scale": 0,
          "position": 2,
          "nullable": true
        }
      ],
      "storage_location": "s3://my-bucket/abcdefghij/12a345b6-7890-1cd2-3456-e789f0a12b34/tables/12a345b6-7890-1cd2-3456-e789f0a12b34",
      "owner": "someone@example.com",
      "properties": {
        "delta.lastCommitTimestamp": "1656371979000",
        "delta.lastUpdateVersion": "0",
        "delta.minWriterVersion": "2",
        "delta.minReaderVersion": "1",
        "delta.checkpoint.writeStatsAsStruct": "true",
        "delta.checkpoint.writeStatsAsJson": "false"
      },
      "metastore_id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
      "full_name": "main.default.mytable",
      "data_access_configuration_id": "00000000-0000-0000-0000-000000000000",
      "created_at": 1656371992807,
      "created_by": "someone@example.com",
      "updated_at": 1656371992807,
      "updated_by": "someone@example.com",
      "table_id": "12a345b6-7890-1cd2-3456-e789f0a12b34"
    },
    {
      "...": "..."
    }
  ]
}

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

Output:

{
  "name": "mytable",
  "catalog_name": "main",
  "schema_name": "default",
  "table_type": "MANAGED",
  "data_source_format": "DELTA",
  "columns": [
    {
      "name": "id",
      "type_text": "int",
      "type_json": "{\"name\":\"id\",\"type\":\"integer\",\"nullable\":true,\"metadata\":{}}",
      "type_name": "INT",
      "type_precision": 0,
      "type_scale": 0,
      "position": 0,
      "nullable": true
    },
    {
      "name": "name",
      "type_text": "string",
      "type_json": "{\"name\":\"name\",\"type\":\"string\",\"nullable\":true,\"metadata\":{}}",
      "type_name": "STRING",
      "type_precision": 0,
      "type_scale": 0,
      "position": 1,
      "nullable": true
    },
    {
      "name": "age",
      "type_text": "int",
      "type_json": "{\"name\":\"age\",\"type\":\"integer\",\"nullable\":true,\"metadata\":{}}",
      "type_name": "INT",
      "type_precision": 0,
      "type_scale": 0,
      "position": 2,
      "nullable": true
    }
  ],
  "storage_location": "s3://my-bucket/abcdefghij/12a345b6-7890-1cd2-3456-e789f0a12b34/tables/12a345b6-7890-1cd2-3456-e789f0a12b34",
  "owner": "someone@example.com",
  "properties": {
    "delta.lastCommitTimestamp": "1656371979000",
    "delta.lastUpdateVersion": "0",
    "delta.minWriterVersion": "2",
    "delta.minReaderVersion": "1",
    "delta.checkpoint.writeStatsAsStruct": "true",
    "delta.checkpoint.writeStatsAsJson": "false"
  },
  "metastore_id": "12a345b6-7890-1cd2-3456-e789f0a12b34",
  "full_name": "main.default.mytable",
  "data_access_configuration_id": "00000000-0000-0000-0000-000000000000",
  "created_at": 1656371992807,
  "created_by": "someone@example.com",
  "updated_at": 1656371992807,
  "updated_by": "someone@example.com",
  "table_id": "12a345b6-7890-1cd2-3456-e789f0a12b34"
}

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

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 a Databricks user shares data with outside of the 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

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

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.