CREATE EXTERNAL LOCATION

Registers a storage URL bound to a storage credential as a managed external location.

Category: configurationPrivilege: adminDeltaForge extension

Syntax

CREATE [OR REPLACE] EXTERNAL LOCATION [IF NOT EXISTS] <name>
  URL '<url>'
  WITH (STORAGE CREDENTIAL '<credential_name>')
  [OPTIONS (<key> = '<value>', ...)]
  [COMMENT '<description>']

Description

## Overview CREATE EXTERNAL LOCATION registers a managed storage location backed by a named storage credential. Tables, schemas, and zones can use the location as a storage root; the credential supplies the authentication material at access time. ## Behavior - The credential name must resolve to an existing storage credential. The executor validates this at CREATE time and rejects the statement if the credential is missing. - The URL is stored verbatim. The parser does not constrain the scheme; the runtime decides which schemes are honored based on the bound credential's type and the available object-store backends. - Existing location with the same name: without OR REPLACE or IF NOT EXISTS, CREATE raises an error. With OR REPLACE, the existing entry is overwritten. With IF NOT EXISTS, CREATE returns success without modifying the existing entry. - The reserved option `read_only = 'true'` marks the location as read-only. The flag is exposed in DESCRIBE EXTERNAL LOCATION output and consulted by the storage layer to reject writes. - Multiple external locations can share a single storage credential; there is no uniqueness constraint on the bound credential name. ## Access Control Requires the admin role. After creation, GRANT ON EXTERNAL LOCATION delegates fine-grained access to other principals. ## Compatibility DeltaForge extension.

Parameters

Name	Type	Description
`name`		Specifies the unique location name. Must be unique across external locations.
`url`		Specifies the storage root URL. Conventional schemes: `s3://`, `abfss://` (Azure Data Lake Gen2), `gs://`, `file://`. The parser does not validate the scheme.
`credential_name`		Specifies the bound storage credential. The credential must already exist; the executor validates this at CREATE time.
`options`		Specifies additional options. The reserved option `read_only = 'true'` marks the location as read-only and is reflected in the location's metadata.
`comment`		Optional human-readable description.
`or_replace`		When true, replace an existing location of the same name.
`if_not_exists`		When true, skip silently if a location with this name already exists.

Examples

-- S3 bucket bound to an IAM role credential
CREATE EXTERNAL LOCATION raw_data
  URL 's3://company-raw/'
  WITH (STORAGE CREDENTIAL 'prod_aws_role')
  COMMENT 'Raw landing zone';

-- Azure Data Lake Gen2 with managed identity
CREATE EXTERNAL LOCATION analytics_lake
  URL 'abfss://curated@analyticsdatalake.dfs.core.windows.net/'
  WITH (STORAGE CREDENTIAL 'prod_azure_mi');

-- Read-only location for an audit dataset
CREATE EXTERNAL LOCATION audit_archive
  URL 's3://company-audit/'
  WITH (STORAGE CREDENTIAL 'prod_aws_role')
  OPTIONS (read_only = 'true')
  COMMENT 'Read-only archive';

-- Idempotent bootstrap
CREATE EXTERNAL LOCATION IF NOT EXISTS raw_data
  URL 's3://company-raw/'
  WITH (STORAGE CREDENTIAL 'prod_aws_role');

Pitfalls

The URL is stored as supplied; the parser does not enforce a scheme list. Mismatches between the URL scheme and the bound credential's cloud (for example an `s3://` URL bound to an Azure managed identity) are caught only at runtime when reads or writes through the location fail.