external_locations

Creates, updates, deletes, gets or lists an external_locations resource.

Overview

Name	`external_locations`
Type	Resource
Id	`databricks_workspace.catalog.external_locations`

Fields

The following fields are returned by SELECT queries:

get
list

Name	Datatype	Description
`name`	`string`	Name of the external location.
`credential_id`	`string`	Unique ID of the location's storage credential.
`metastore_id`	`string`	Unique identifier of metastore hosting the external location.
`credential_name`	`string`	Name of the storage credential used with this location.
`browse_only`	`boolean`
`comment`	`string`	User-provided free-form text description.
`created_at`	`integer`	Time at which this external location was created, in epoch milliseconds.
`created_by`	`string`	Username of external location creator.
`enable_file_events`	`boolean`	Whether to enable file events on this external location. Default to `true`. Set to `false` to disable file events.
▶`encryption_details`	`object`	Encryption options that apply to clients connecting to cloud storage.
`fallback`	`boolean`	Indicates whether fallback mode is enabled for this external location. When fallback mode is enabled, the access to the location falls back to cluster credentials if UC credentials are not sufficient.
▶`file_event_queue`	`object`	File event queue settings. If `enable_file_events` is not `false`, must be defined and have exactly one of the documented properties.
`isolation_mode`	`string`	Create a collection of name/value pairs.<br /><br />Example enumeration:<br /><br />>>> class Color(Enum):<br />... RED = 1<br />... BLUE = 2<br />... GREEN = 3<br /><br />Access them by:<br /><br />- attribute access::<br /><br />>>> Color.RED<br /><Color.RED: 1><br /><br />- value lookup:<br /><br />>>> Color(1)<br /><Color.RED: 1><br /><br />- name lookup:<br /><br />>>> Color['RED']<br /><Color.RED: 1><br /><br />Enumerations can be iterated over, and know how many members they have:<br /><br />>>> len(Color)<br />3<br /><br />>>> list(Color)<br />[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]<br /><br />Methods can be added to enumerations, and members can have their own<br />attributes -- see the documentation for details. (ISOLATION_MODE_ISOLATED, ISOLATION_MODE_OPEN)
`owner`	`string`	The owner of the external location.
`read_only`	`boolean`	Indicates whether the external location is read-only.
`updated_at`	`integer`	Time at which external location this was last modified, in epoch milliseconds.
`updated_by`	`string`	Username of user who last modified the external location.
`url`	`string`	Path URL of the external location.

Name	Datatype	Description
`name`	`string`	Name of the external location.
`credential_id`	`string`	Unique ID of the location's storage credential.
`metastore_id`	`string`	Unique identifier of metastore hosting the external location.
`credential_name`	`string`	Name of the storage credential used with this location.
`browse_only`	`boolean`
`comment`	`string`	User-provided free-form text description.
`created_at`	`integer`	Time at which this external location was created, in epoch milliseconds.
`created_by`	`string`	Username of external location creator.
`enable_file_events`	`boolean`	Whether to enable file events on this external location. Default to `true`. Set to `false` to disable file events.
▶`encryption_details`	`object`	Encryption options that apply to clients connecting to cloud storage.
`fallback`	`boolean`	Indicates whether fallback mode is enabled for this external location. When fallback mode is enabled, the access to the location falls back to cluster credentials if UC credentials are not sufficient.
▶`file_event_queue`	`object`	File event queue settings. If `enable_file_events` is not `false`, must be defined and have exactly one of the documented properties.
`isolation_mode`	`string`	Create a collection of name/value pairs.<br /><br />Example enumeration:<br /><br />>>> class Color(Enum):<br />... RED = 1<br />... BLUE = 2<br />... GREEN = 3<br /><br />Access them by:<br /><br />- attribute access::<br /><br />>>> Color.RED<br /><Color.RED: 1><br /><br />- value lookup:<br /><br />>>> Color(1)<br /><Color.RED: 1><br /><br />- name lookup:<br /><br />>>> Color['RED']<br /><Color.RED: 1><br /><br />Enumerations can be iterated over, and know how many members they have:<br /><br />>>> len(Color)<br />3<br /><br />>>> list(Color)<br />[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]<br /><br />Methods can be added to enumerations, and members can have their own<br />attributes -- see the documentation for details. (ISOLATION_MODE_ISOLATED, ISOLATION_MODE_OPEN)
`owner`	`string`	The owner of the external location.
`read_only`	`boolean`	Indicates whether the external location is read-only.
`updated_at`	`integer`	Time at which external location this was last modified, in epoch milliseconds.
`updated_by`	`string`	Username of user who last modified the external location.
`url`	`string`	Path URL of the external location.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
`get`	`select`	`name`, `deployment_name`	`include_browse`	Gets an external location from the metastore. The caller must be either a metastore admin, the owner
`list`	`select`	`deployment_name`	`include_browse`, `include_unbound`, `max_results`, `page_token`	Gets an array of external locations (ExternalLocationInfo objects) from the metastore. The caller
`create`	`insert`	`deployment_name`, `name`, `url`, `credential_name`		Creates a new external location entry in the metastore. The caller must be a metastore admin or have
`update`	`update`	`name`, `deployment_name`		Updates an external location in the metastore. The caller must be the owner of the external location,
`delete`	`delete`	`name`, `deployment_name`	`force`	Deletes the specified external location from the metastore. The caller must be the owner of the

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
`deployment_name`	`string`	The Databricks Workspace Deployment Name (default: dbc-abcd0123-a1bc)
`name`	`string`	Name of the external location.
`force`	`boolean`	Force deletion even if there are dependent external tables or mounts.
`include_browse`	`boolean`	Whether to include external locations in the response for which the principal can only access selective metadata for
`include_unbound`	`boolean`	Whether to include external locations not bound to the workspace. Effective only if the user has permission to update the location–workspace binding.
`max_results`	`integer`	Maximum number of external locations to return. If not set, all the external locations are returned (not recommended). - when set to a value greater than 0, the page length is the minimum of this value and a server configured value; - when set to 0, the page length is set to a server configured value (recommended); - when set to a value less than 0, an invalid parameter error is returned;
`page_token`	`string`	Opaque pagination token to go to next page based on previous query.

`SELECT` examples

get
list

Gets an external location from the metastore. The caller must be either a metastore admin, the owner

SELECT
name,
credential_id,
metastore_id,
credential_name,
browse_only,
comment,
created_at,
created_by,
enable_file_events,
encryption_details,
fallback,
file_event_queue,
isolation_mode,
owner,
read_only,
updated_at,
updated_by,
url
FROM databricks_workspace.catalog.external_locations
WHERE name = '{{ name }}' -- required
AND deployment_name = '{{ deployment_name }}' -- required
AND include_browse = '{{ include_browse }}'
;

Gets an array of external locations (ExternalLocationInfo objects) from the metastore. The caller

SELECT
name,
credential_id,
metastore_id,
credential_name,
browse_only,
comment,
created_at,
created_by,
enable_file_events,
encryption_details,
fallback,
file_event_queue,
isolation_mode,
owner,
read_only,
updated_at,
updated_by,
url
FROM databricks_workspace.catalog.external_locations
WHERE deployment_name = '{{ deployment_name }}' -- required
AND include_browse = '{{ include_browse }}'
AND include_unbound = '{{ include_unbound }}'
AND max_results = '{{ max_results }}'
AND page_token = '{{ page_token }}'
;

`INSERT` examples

create
Manifest

Creates a new external location entry in the metastore. The caller must be a metastore admin or have

INSERT INTO databricks_workspace.catalog.external_locations (
name,
url,
credential_name,
comment,
enable_file_events,
encryption_details,
fallback,
file_event_queue,
read_only,
skip_validation,
deployment_name
)
SELECT 
'{{ name }}' /* required */,
'{{ url }}' /* required */,
'{{ credential_name }}' /* required */,
'{{ comment }}',
{{ enable_file_events }},
'{{ encryption_details }}',
{{ fallback }},
'{{ file_event_queue }}',
{{ read_only }},
{{ skip_validation }},
'{{ deployment_name }}'
RETURNING
name,
credential_id,
metastore_id,
credential_name,
browse_only,
comment,
created_at,
created_by,
enable_file_events,
encryption_details,
fallback,
file_event_queue,
isolation_mode,
owner,
read_only,
updated_at,
updated_by,
url
;

# Description fields are for documentation purposes
- name: external_locations
props:
  - name: deployment_name
    value: "{{ deployment_name }}"
    description: Required parameter for the external_locations resource.
  - name: name
    value: "{{ name }}"
    description: |
      Name of the external location.
  - name: url
    value: "{{ url }}"
    description: |
      Path URL of the external location.
  - name: credential_name
    value: "{{ credential_name }}"
    description: |
      Name of the storage credential used with this location.
  - name: comment
    value: "{{ comment }}"
    description: |
      User-provided free-form text description.
  - name: enable_file_events
    value: {{ enable_file_events }}
    description: |
      Whether to enable file events on this external location. Default to `true`. Set to `false` to disable file events.
  - name: encryption_details
    description: |
      :param fallback: bool (optional) Indicates whether fallback mode is enabled for this external location. When fallback mode is enabled, the access to the location falls back to cluster credentials if UC credentials are not sufficient.
    value:
      sse_encryption_details:
        algorithm: "{{ algorithm }}"
        aws_kms_key_arn: "{{ aws_kms_key_arn }}"
  - name: fallback
    value: {{ fallback }}
  - name: file_event_queue
    description: |
      File event queue settings. If `enable_file_events` is not `false`, must be defined and have exactly one of the documented properties.
    value:
      managed_aqs:
        managed_resource_id: "{{ managed_resource_id }}"
        queue_url: "{{ queue_url }}"
        resource_group: "{{ resource_group }}"
        subscription_id: "{{ subscription_id }}"
      managed_pubsub:
        managed_resource_id: "{{ managed_resource_id }}"
        subscription_name: "{{ subscription_name }}"
      managed_sqs:
        managed_resource_id: "{{ managed_resource_id }}"
        queue_url: "{{ queue_url }}"
      provided_aqs:
        managed_resource_id: "{{ managed_resource_id }}"
        queue_url: "{{ queue_url }}"
        resource_group: "{{ resource_group }}"
        subscription_id: "{{ subscription_id }}"
      provided_pubsub:
        managed_resource_id: "{{ managed_resource_id }}"
        subscription_name: "{{ subscription_name }}"
      provided_sqs:
        managed_resource_id: "{{ managed_resource_id }}"
        queue_url: "{{ queue_url }}"
  - name: read_only
    value: {{ read_only }}
    description: |
      Indicates whether the external location is read-only.
  - name: skip_validation
    value: {{ skip_validation }}
    description: |
      Skips validation of the storage credential associated with the external location.

`UPDATE` examples

update

Updates an external location in the metastore. The caller must be the owner of the external location,

UPDATE databricks_workspace.catalog.external_locations
SET 
comment = '{{ comment }}',
credential_name = '{{ credential_name }}',
enable_file_events = {{ enable_file_events }},
encryption_details = '{{ encryption_details }}',
fallback = {{ fallback }},
file_event_queue = '{{ file_event_queue }}',
force = {{ force }},
isolation_mode = '{{ isolation_mode }}',
new_name = '{{ new_name }}',
owner = '{{ owner }}',
read_only = {{ read_only }},
skip_validation = {{ skip_validation }},
url = '{{ url }}'
WHERE 
name = '{{ name }}' --required
AND deployment_name = '{{ deployment_name }}' --required
RETURNING
name,
credential_id,
metastore_id,
credential_name,
browse_only,
comment,
created_at,
created_by,
enable_file_events,
encryption_details,
fallback,
file_event_queue,
isolation_mode,
owner,
read_only,
updated_at,
updated_by,
url;

`DELETE` examples

delete

Deletes the specified external location from the metastore. The caller must be the owner of the

DELETE FROM databricks_workspace.catalog.external_locations
WHERE name = '{{ name }}' --required
AND deployment_name = '{{ deployment_name }}' --required
AND force = '{{ force }}'
;

Overview​

Fields​

Methods​

Parameters​

SELECT examples​

INSERT examples​

UPDATE examples​

DELETE examples​