Unity Catalog CLI

Note

Unity Catalog is in Public Preview. However, 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 (Preview) resources such as metastores, storage credentials, external locations, catalogs, schemas, tables, and their permissions. For Delta Sharing enabled Unity Catalog metastores, you can also use the Unity Catalog CLI to work with Delta Sharing shares, recipients, and providers. For more information, see:

You run Unity Catalog CLI subcommands by appending them to databricks unity-catalog.

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.0
  -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 \
                                           --storage-root s3://my-bucket/abcdefghij

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

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. See also 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 Data permissions.

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 Manage privileges.

Catalog

databricks unity-catalog permissions get --catalog main

Output:

{
  "privilege_assignments": [
    {
      "principal": "account users",
      "privileges": [
        "USAGE"
      ]
    }
  ]
}

Schema

databricks unity-catalog permissions get --schema main.default

Output:

{
  "privilege_assignments": [
    {
      "principal": "account users",
      "privileges": [
        "USAGE"
      ]
    }
  ]
}

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 Manage privileges.

Catalog

databricks unity-catalog permissions update --catalog \
                                            --json-file update-catalog-permissions.json

update-catalog-permissions.json:

{
  "changes": [
    {
      "principal": "account users",
      "add": [ "USAGE" ],
      "remove": [ "CREATE" ]
    }
  ]
}

Schema

databricks unity-catalog permissions update --schema \
                                            --json-file update-schema-permissions.json

update-schema-permissions.json:

{
  "changes": [
    {
      "principal": "account users",
      "add": [ "USAGE" ],
      "remove": [ "CREATE" ]
    },
    {
      "principal": "admin team",
      "add": [ "CREATE" ]
    }
  ]
}

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 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 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 Manage shares. See also Share data using Delta Sharing (Preview).

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

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 Add or remove tables from a share.

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

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

Update a share’s permissions

To display usage documentation, run databricks unity-catalog shares update-permissions --help. See also Manage privileges for a recipient.

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 List shares.

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 List shares.

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.

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 Manage recipients. See also Share data using Delta Sharing (Preview).

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

To generate a new activation URL for a receipient, 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 Rotate a recipient’s credential.

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 List 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 Manage privileges for a recipient.

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 Describe a recipient.

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

Use the unity-catalog providers subcommand to work with Delta Sharing data providers. See Share data using Delta Sharing (Preview).

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

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.