Manage external locations

This article describes how to list, view, update, grant permissions on, and delete external locations.

Note

Databricks recommends governing file access using volumes. See What are Unity Catalog volumes?.

Describe an external location

To see the properties of an external location, including permissions and workspace access, you can use Catalog Explorer or a SQL command.

In the sidebar, click Catalog.
At the top of the Catalog pane, click the gear icon and select External Locations.

Alternatively, from the Quick access page, click the External data > button to go to the External Locations tab.
Click the name of an external location to view its properties.

Run the following command in a notebook or the Databricks SQL editor. Replace <location-name> with the name of the external location.

DESCRIBE EXTERNAL LOCATION <location-name>;

Show grants on an external location

To show grants on an external location, use a command like the following. You can optionally filter the results to show only the grants for the specified principal.

SHOW GRANTS [<principal>] ON EXTERNAL LOCATION <location-name>;

Replace the placeholder values:

<location-name>: The name of the external location that authorizes reading from and writing to the S3 bucket in your cloud tenant.
<principal>: The email address of an account-level user or the name of an account-level group.

Note

If a group name contains a space, use back-ticks around it (not apostrophes).

Grant permissions on an external location

This section describes how to grant and revoke permissions on an external location using Catalog Explorer and SQL commands in a notebook or Databricks SQL query. For information about using the Databricks CLI or Terraform instead, see the Databricks Terraform documentation and What is the Databricks CLI?.

You can grant the following permissions on an external location:

CREATE EXTERNAL TABLE
CREATE EXTERNAL VOLUME
CREATE MANAGED STORAGE

Permissions required: The CREATE EXTERNAL LOCATION privilege on both the metastore and the storage credential referenced in the external location. Metastore admins have CREATE EXTERNAL LOCATION on the metastore by default.

To grant permission to use an external location:

In the sidebar, click Catalog.
At the top of the Catalog pane, click the gear icon and select External Locations.

Alternatively, from the Quick access page, click the External data > button to go to the External Locations tab.
Click the name of an external location to open its properties.
Click Permissions.
To grant permission to users or groups, select each identity, then click Grant.
To revoke permissions from users or groups, select each identity, then click Revoke.

Run the following SQL command in a notebook or SQL query editor. This example grants the ability to create an external table that references the external location:

GRANT CREATE EXTERNAL TABLE ON EXTERNAL LOCATION <location-name> TO <principal>;

Replace the placeholder values:

<location-name>: The name of the external location that authorizes reading from and writing to the S3 bucket in your cloud tenant.
<principal>: The email address of an account-level user or the name of an account-level group.

Note

If a group name contains a space, use back-ticks around it (not apostrophes).

Change the owner of an external location

An external location’s creator is its initial owner. To change the owner to a different account-level user or group, run the following command in a notebook or the Databricks SQL editor or use Catalog Explorer. Replace the placeholder values:

<location-name>: The name of the credential.
<principal>: The email address of an account-level user or the name of an account-level group.

ALTER EXTERNAL LOCATION <location-name> OWNER TO <principal>

Mark an external location as read-only

If you want users to have read-only access to an external location, you can use Catalog Explorer to mark the external location as read-only.

Making external locations read-only:

Prevents users from writing to files in those external locations, regardless of any write permissions granted by the IAM role that underlies the storage credential, and regardless of the Unity Catalog permissions granted on that external location.
Prevents users from creating managed tables or volumes in those external locations.
Enables the system to validate the external location properly at creation time.

You can mark external locations as read-only when you create them.

You can also use Catalog Explorer to change read-only status after creating an external location:

In the sidebar, click Catalog.
At the top of the Catalog pane, click the gear icon and select External Locations.

Alternatively, from the Quick access page, click the External data > button to go to the External Locations tab.
Select the external location, click the kebab menu next to the Test connection button, and select Edit.
On the edit dialog, click Advanced Options and select the Limit to read-only use option.
Click Update.

Configure an encryption algorithm on an external location

AWS supports server-side encryption (SSE) with Amazon S3 managed keys (SSE-S3) or AWS KMS keys (SSE-KMS) for protecting data in S3. If your S3 bucket requires SSE encryption, you can configure an encryption algorithm in your external location to allow external tables and volumes in Unity Catalog to access data in your S3 bucket. SSE is not supported with external tables shared using Delta Sharing.

In the sidebar, click Catalog.
At the top of the Catalog pane, click the gear icon and select External Locations.
Select the external location. The external location must use an IAM role for a storage credential.
Click the kebab menu next to the Test connection button, and select Edit.
On the edit dialog, click Advanced Options.
Under Encryption Algorithm select SSE-SE or SSE-KMS depending on your encryption key.

For SSE-KMS, under Encryption KMS key arn paste the ARN of the KMS key referenced by clients when accessing the S3 location.
Click Update.

Modify an external location

An external location’s owner can rename, change the URI, and change the storage credential of the external location.

To rename an external location, do the following:

Run the following command in a notebook or the Databricks SQL editor. Replace the placeholder values:

<location-name>: The name of the location.
<new-location-name>: A new name for the location.

ALTER EXTERNAL LOCATION <location-name> RENAME TO <new-location-name>;

To change the URI that an external location points to in your cloud tenant, do the following:

Run the following command in a notebook or the Databricks SQL editor. Replace the placeholder values:

<location-name>: The name of the external location.
<url>: The new storage URL the location should authorize access to in your cloud tenant.

ALTER EXTERNAL LOCATION location_name SET URL '<url>' [FORCE];

The FORCE option changes the URL even if external tables depend upon the external location.

To change the storage credential that an external location uses, do the following:

Run the following command in a notebook or the Databricks SQL editor. Replace the placeholder values:

<location-name>: The name of the external location.
<credential-name>: The name of the storage credential that grants access to the location’s URL in your cloud tenant.

ALTER EXTERNAL LOCATION <location-name> SET STORAGE CREDENTIAL <credential-name>;

Delete an external location

To delete (drop) an external location you must be its owner. To delete an external location, do the following:

Run the following command in a notebook or the Databricks SQL editor. Items in brackets are optional. Replace <location-name> with the name of the external location.

DROP EXTERNAL LOCATION [IF EXISTS] <location-name>;