Unity Catalog CLI

Note

The Unity Catalog CLI is Experimental.

The Unity Catalog CLI requires Databricks CLI 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.

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

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.

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.

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. See also Rename a storage credential.

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. See also List storage credentials.

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. See also View a storage credential.

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. See also Delete a storage credential.

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.

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.

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. See also Modify an external location.

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. See also Describe an external location.

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. See also Delete an external location.

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 a catalog.

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 a schema.

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 Create tables and Create your first table.

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 Grant and manage access to Delta Sharing data shares.

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.

See also Databricks: Read shared data using Unity Catalog

To create a provider, you must:

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.