> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firebolt.io/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.firebolt.io/feedback

```json
{
  "path": "/reference-sql/commands/data-definition/create-location",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

> Reference and syntax for the CREATE LOCATION statement.

# CREATE LOCATION

Creates a new location object in your Firebolt account, which is a secure, reusable object that stores the connection details and credentials for external data sources. Instead of entering these details each time you run a query or create a table, you can use a location object.

The location object stores the following:

* The source type specification
* Authentication credentials
* The data source URL
* Optional descriptive metadata

This makes it easier to manage data access, keeps your credentials safe, and saves you from having to repeat the same information across multiple queries.

You can use `LOCATION` to centralize credential storage with managed access with Role-Based Access Control ([RBAC](/overview/security/rbac)) for `CREATE`, `MODIFY`, and `USAGE` permissions for different users, use a single location definition for multiple tables and queries, and control access to sensitive data. `LOCATION` is version control-friendly because no sensitive credentials are stored in source code.

After you create a `LOCATION`, you can use the `information_schema.locations` view to see [details about all the locations](/reference-sql/information-schema/locations) in your account including source type, URL, description, owner and creation time.

For a comprehensive guide to understanding and using LOCATION objects, see [LOCATION objects](/guides/security/location).

**Related:**

This document covers `LOCATION` objects in general. For more information about specific types of `LOCATION` objects, including more in-depth examples, please see:

* [CREATE LOCATION (Amazon S3)](/reference-sql/commands/data-definition/create-location-s3)
* [CREATE LOCATION (Amazon Bedrock)](/reference-sql/commands/data-definition/create-location-bedrock)
* [CREATE LOCATION (Iceberg)](/reference-sql/commands/data-definition/create-location-iceberg)

**Topics:**

* [Syntax](#syntax)
* [Parameters](#parameters)
* [Examples](#examples)
* [Notes](#notes)
* [Error Handling](#error-handling)
* [Best Practices](#best-practices)
* [Limitations](#limitations)

## Syntax

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
CREATE LOCATION [ IF NOT EXISTS ] <location_name> WITH
  SOURCE = { CLOUD_STORAGE | AMAZON_S3 | AMAZON_BEDROCK | ICEBERG }
  [ , ... ]

-- Cloud Storage Location (auto-infers backend from URL)
CREATE LOCATION [ IF NOT EXISTS ] <location_name> WITH
  SOURCE = CLOUD_STORAGE
  CREDENTIALS = {
    ( AWS_ACCESS_KEY_ID = '<aws_access_key_id>'
      AWS_SECRET_ACCESS_KEY = '<aws_secret_access_key>'
      [ AWS_SESSION_TOKEN = '<aws_session_token>' ] )
    |
    ( AWS_ROLE_ARN = '<aws_role_arn>'
      [ AWS_ROLE_EXTERNAL_ID = '<aws_role_external_id>' ] )
  }
  URL = '<url>'
  [ DESCRIPTION = '<description>' ]

-- Amazon S3 Location (alias for CLOUD_STORAGE with S3 URL)
CREATE LOCATION [ IF NOT EXISTS ] <location_name> WITH
  SOURCE = AMAZON_S3
  CREDENTIALS = {
    ( AWS_ACCESS_KEY_ID = '<aws_access_key_id>'
      AWS_SECRET_ACCESS_KEY = '<aws_secret_access_key>'
      [ AWS_SESSION_TOKEN = '<aws_session_token>' ] )
    |
    ( AWS_ROLE_ARN = '<aws_role_arn>'
      [ AWS_ROLE_EXTERNAL_ID = '<aws_role_external_id>' ] )
  }
  URL = '<url>'
  [ DESCRIPTION = '<description>' ]

-- Amazon Bedrock Location
CREATE LOCATION [ IF NOT EXISTS ] <location_name> WITH
  SOURCE = AMAZON_BEDROCK
  CREDENTIALS = {
    ( AWS_ACCESS_KEY_ID = '<aws_access_key_id>'
      AWS_SECRET_ACCESS_KEY = '<aws_secret_access_key>'
      [ AWS_SESSION_TOKEN = '<aws_session_token>' ] )
    |
    ( AWS_ROLE_ARN = '<aws_role_arn>'
      [ AWS_ROLE_EXTERNAL_ID = '<aws_role_external_id>' ] )
  }
  [ DESCRIPTION = '<description>' ]

-- Iceberg Location
CREATE LOCATION [ IF NOT EXISTS ] <location_name> WITH
  SOURCE = ICEBERG
  CATALOG = { FILE_BASED | REST | DATABRICKS_UNITY }
  CATALOG_OPTIONS = {
    -- FILE_BASED
    ( URL = '<file_based_catalog_url>' )
    |
    -- REST
    ( URL = '<rest_catalog_url>'
      WAREHOUSE = '<warehouse>'
      NAMESPACE = '<namespace>'
      TABLE = '<table_name>' )
    |
    -- DATABRICKS_UNITY
    ( WORKSPACE_INSTANCE = '<workspace_instance>'
      CATALOG = '<uc_catalog_name>'
      SCHEMA = '<uc_schema_name>'
      TABLE = '<uc_table_name>' )
  }
  CREDENTIALS = {
    -- AWS Authentication
    ( AWS_ACCESS_KEY_ID = '<aws_access_key_id>'
      AWS_SECRET_ACCESS_KEY = '<aws_secret_access_key>'
      [ AWS_SESSION_TOKEN = '<aws_session_token>' ] )
    |
    ( AWS_ROLE_ARN = '<aws_role_arn>'
      [ AWS_ROLE_EXTERNAL_ID = '<aws_role_external_id>' ] )
    |
    -- OAuth Authentication
    ( OAUTH_CLIENT_ID = '<oauth_client_id>'
      OAUTH_CLIENT_SECRET = '<oauth_client_secret>'
      [ OAUTH_SCOPE = '<oauth_scope>' ]
      [ OAUTH_SERVER_URL = '<oauth_server_url>' ] )
    |
    ( BEARER_TOKEN = '<bearer_token>' )
  }
  [ DESCRIPTION = '<description>' ]
```

## Parameters

### Common Parameters

| Parameter         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<location_name>` | A unique identifier for the location within your account.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `SOURCE`          | The external data source type. Currently, `CLOUD_STORAGE` (see [CREATE LOCATION (Amazon S3)](/reference-sql/commands/data-definition/create-location-s3)), `AMAZON_S3` (alias for `CLOUD_STORAGE` with S3 URL, see [CREATE LOCATION (Amazon S3)](/reference-sql/commands/data-definition/create-location-s3)), `AMAZON_BEDROCK` (see [CREATE LOCATION (Amazon Bedrock)](/reference-sql/commands/data-definition/create-location-bedrock)), and `ICEBERG` (see [CREATE LOCATION (Iceberg)](/reference-sql/commands/data-definition/create-location-iceberg)) are supported. |
| `DESCRIPTION`     | Optional metadata describing the location's purpose.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |

### Cloud Storage Parameters

| Parameter     | Description                                                                                  |
| :------------ | :------------------------------------------------------------------------------------------- |
| `CREDENTIALS` | Authentication credentials for cloud storage access.                                         |
| `URL`         | The data source URL in the format: `s3://{bucket_name}/{path}`. This must be a valid S3 URL. |

### Amazon S3 Parameters

| Parameter     | Description                                                                                  |
| :------------ | :------------------------------------------------------------------------------------------- |
| `CREDENTIALS` | Authentication credentials for Amazon S3 access.                                             |
| `URL`         | The data source URL in the format: `s3://{bucket_name}/{path}`. This must be a valid S3 URL. |

### Amazon Bedrock Parameters

| Parameter     | Description                                           |
| :------------ | :---------------------------------------------------- |
| `CREDENTIALS` | Authentication credentials for Amazon Bedrock access. |

### Iceberg Parameters

| Parameter         | Description                                                                                                                               |
| :---------------- | :---------------------------------------------------------------------------------------------------------------------------------------- |
| `CATALOG`         | The type of Iceberg catalog. Supported values: `FILE_BASED`, `REST`, or `DATABRICKS_UNITY`.                                               |
| `CATALOG_OPTIONS` | Configuration options specific to the chosen catalog type.                                                                                |
| `CREDENTIALS`     | Authentication credentials for accessing the Iceberg catalog. Depending on the type of catalog, either AWS or OAuth credentials are used. |

#### AWS Authentication Parameters

| Parameter               | Description                                                      |
| :---------------------- | :--------------------------------------------------------------- |
| `AWS_ACCESS_KEY_ID`     | Your AWS access key ID for key-based authentication.             |
| `AWS_SECRET_ACCESS_KEY` | Your AWS secret access key for key-based authentication.         |
| `AWS_SESSION_TOKEN`     | Optional temporary session token for temporary credentials.      |
| `AWS_ROLE_ARN`          | The ARN of the IAM role to assume for role-based authentication. |
| `AWS_ROLE_EXTERNAL_ID`  | Optional external ID for role assumption.                        |

#### OAuth Authentication Parameters

| Parameter             | Description                                                                           |        |
| :-------------------- | :------------------------------------------------------------------------------------ | ------ |
| `OAUTH_CLIENT_ID`     | The OAuth client ID for authentication.                                               |        |
| `OAUTH_CLIENT_SECRET` | The OAuth client secret for authentication.                                           |        |
| `OAUTH_SCOPE`         | Optional OAuth scope for authentication.                                              |        |
| `OAUTH_SERVER_URL`    | Optional OAuth server URL for authentication.                                         |        |
| `BEARER_TOKEN`        | OAuth bearer token for authentication. Only supported for `DATABRICKS_UNITY` catalog. | `TEXT` |

#### Iceberg Catalog-Specific Parameters

##### FILE\_BASED Catalog

| Parameter | Description                         |
| :-------- | :---------------------------------- |
| `URL`     | The URL for the file-based catalog. |

##### REST Catalog

| Parameter   | Description               |
| :---------- | :------------------------ |
| `URL`       | The REST catalog URL.     |
| `WAREHOUSE` | The warehouse identifier. |
| `NAMESPACE` | The namespace identifier. |
| `TABLE`     | The table name.           |

##### DATABRICKS\_UNITY Catalog

| Parameter            | Description                        |
| :------------------- | :--------------------------------- |
| `WORKSPACE_INSTANCE` | The Databricks workspace instance. |
| `CATALOG`            | The Unity Catalog name.            |
| `SCHEMA`             | The Unity Catalog schema name.     |
| `TABLE`              | The Unity Catalog table name.      |

## Examples

* [Create a location](#create-a-location)
* [Create a location with a description](#create-a-location-with-a-description)
* [Create a location only if it doesn't exist](#create-a-location-only-if-it-doesnt-exist)
* [Use a location to load data into an external table](#use-a-location-to-load-data-into-an-external-table)
* [Use a location to load data using COPY statements](#use-a-location-to-load-data-using-copy-statements)
* [Use a location to load data with a TVF](#use-a-location-to-load-data-with-a-tvf)
* [Alter a location](#alter-a-location)
* [Delete a location](#delete-a-location)

### Create a location

The following code example creates a location that uses keys to authenticate to AWS:

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
CREATE LOCATION my_location WITH
  SOURCE = AMAZON_S3
  CREDENTIALS = ( AWS_ACCESS_KEY_ID = '1231' AWS_SECRET_ACCESS_KEY = '567' )
  URL = 's3://my-bucket/path/to/data'
```

### Create a location with a description

The following code example creates a location object named `my_location`, for an Amazon S3 data source with the specified URL and description:

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
CREATE LOCATION my_location WITH
  SOURCE = AMAZON_S3
  CREDENTIALS = ( AWS_ACCESS_KEY_ID = '1231' AWS_SECRET_ACCESS_KEY = '567' )
  URL = 's3://my-bucket/path/to/data'
  DESCRIPTION = 'Main data storage location'
```

### Create a location only if it doesn't exist

The following code example uses an access key to authenticate to AWS using a location only if it doesn't already exist:

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
CREATE LOCATION IF NOT EXISTS my_location WITH
  SOURCE = AMAZON_S3
  CREDENTIALS = ( AWS_ACCESS_KEY_ID = '1231' AWS_SECRET_ACCESS_KEY = '567' )
  URL = 's3://my-bucket/path/to/data'
```

### Use a location to load data into an external table

The following code example creates an external table `my_ext_table` that uses a previously created location `my_location` to load Parquet data files matching the \*.parquet pattern from Amazon S3:

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
CREATE EXTERNAL TABLE my_ext_table (
  c_id    INT,
  c_name  TEXT
)
LOCATION = my_location
OBJECT_PATTERN = '*.parquet'
TYPE = PARQUET
```

For more information about using locations in external tables, see [CREATE EXTERNAL TABLE](/reference-sql/commands/data-definition/create-external-table).

### Use a location to load data using COPY statements

The following code example uses `COPY FROM` to load Parquet data files matching the \*.parquet pattern from `my_location` into `my_table`:

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
COPY INTO my_table
FROM my_location
WITH
  OBJECT_PATTERN = '*.parquet'
  TYPE = PARQUET
```

For more information, see [COPY TO](/reference-sql/commands/data-management/copy-to) and [COPY FROM](/reference-sql/commands/data-management/copy-from).

### Use a `LOCATION` to load data with a TVF

You can use `LOCATION` to load data using table-valued functions (TVFs) such as [READ\_CSV](/reference-sql/functions-reference/table-valued/read_csv), [READ\_PARQUET](/reference-sql/functions-reference/table-valued/read_parquet), and [LIST\_OBJECTS](/reference-sql/functions-reference/table-valued/list-objects).

The following code example uses `READ_CSV` to query data from a CSV file stored in `my_location`, using the first row as headers for column names:

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
SELECT * FROM READ_CSV(
  LOCATION => 'my_location',
  header => TRUE
)
```

### Alter a location

Firebolt does not yet support altering a location that has been created. This feature will be available in a future release.

### Delete a location

You can use [DROP LOCATION](/reference-sql/commands/data-definition/drop-location) to remove a location from your Firebolt account.

The following code example deletes a `LOCATION` from your Firbolt account:

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
DROP LOCATION [IF EXISTS] <location_name> [WITH FORCE]
```

<Note>
  Deleting a location will affect all objects that depend on the `LOCATION` that you are dropping.
</Note>

## Notes

* All identifiers are case-insensitive unless enclosed in double-quotes
* Locations cannot be created on the system engine
* For more information about object identifiers, see [Object identifiers](/reference-sql/lexical-structure/object-identifiers)

## Error Handling

The system uses secure error handling for location objects:

* Generic error messages ensure security by not exposing sensitive information.
* Detailed error information is only available to users with the necessary permissions.
* Users without the required permissions are provided with instructions to contact an administrator.

## Best Practices

1. Use location objects instead of embedding credentials directly in queries or table definitions.
2. Regularly rotate credentials stored in location objects.
3. Follow the principle of least privilege when assigning permissions.
4. Use clear and descriptive names and descriptions for location objects.
5. Keep a record of dependencies before removing any location objects.

## Limitations

* The `DROP CASCADE` functionality is not supported.
* The source type cannot be modified for existing location objects.
* Location objects cannot be used alongside inline credentials in the same statement.
* Historical versions of credentials are not maintained.