CREATE LOCATION (Amazon S3)

Creates a new location object in your Firebolt account, which is a secure, reusable object that stores the connection details and credentials for Amazon S3 data sources. Instead of entering these details each time you run a query or create a table, you can use a location object. This document captures specifics and examples for location objects for Amazon S3. Both options are supported and will appear as CLOUD_STORAGE (S3) in the information_schema.locations view. For a comprehensive guide to LOCATION objects, see LOCATION objects. For more on location objects syntax in general, see CREATE LOCATION.

Syntax

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 is supported as an alias for CLOUD_STORAGE.

Parameters

Common Parameters

Parameter	Description
`<location_name>`	A unique identifier for the location within your account.
`SOURCE`	The external data source type. For Amazon S3 locations, you can use either `CLOUD_STORAGE` (which auto-infers the storage backend from the URL) or `AMAZON_S3` (which is an alias for `CLOUD_STORAGE` with an S3 URL).
`DESCRIPTION`	Optional metadata describing the location’s purpose.

Amazon S3 Parameters

Parameter	Description
`SOURCE`	Can be set to `CLOUD_STORAGE` (recommended, auto-infers backend from URL) or `AMAZON_S3` (alias for `CLOUD_STORAGE` with S3 URL) for Amazon S3 locations.
`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.

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.

Examples

Authenticate using an access key
Authenticate using a role
Create a location with an AWS session token

Authenticate using an access key

The following code examples use keys to authenticate to AWS. Both CLOUD_STORAGE and AMAZON_S3 are shown:

-- Using CLOUD_STORAGE (recommended)
CREATE LOCATION my_location WITH
  SOURCE = CLOUD_STORAGE
  CREDENTIALS = ( AWS_ACCESS_KEY_ID = '1231' AWS_SECRET_ACCESS_KEY = '567' )
  URL = 's3://my-bucket/path/to/data'

-- Using AMAZON_S3 (alias)
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'

Authenticate using a role

The following code examples use a role to authenticate to AWS and include a recommended external ID. Both CLOUD_STORAGE and AMAZON_S3 are shown:

-- Using CLOUD_STORAGE (recommended)
CREATE LOCATION my_location WITH
  SOURCE = CLOUD_STORAGE
  CREDENTIALS = ( AWS_ROLE_ARN = 'arn:aws:iam::123456789012:role/S3Access' AWS_ROLE_EXTERNAL_ID = 'my-external-id' )
  URL = 's3://my-bucket/path/to/data'

-- Using AMAZON_S3 (alias)
CREATE LOCATION my_location WITH
  SOURCE = AMAZON_S3
  CREDENTIALS = ( AWS_ROLE_ARN = 'arn:aws:iam::123456789012:role/S3Access' AWS_ROLE_EXTERNAL_ID = 'my-external-id' )
  URL = 's3://my-bucket/path/to/data'

For role-based AWS access you can additionally set an external ID. An external ID is a value you choose and control that AWS checks when Firebolt assumes your role, adding a second condition on top of your account’s unique IAM principal. Configuring one is a recommended best practice. See IAM roles.

AWS_ROLE_EXTERNAL_ID is optional. To assume the role without an external ID, omit it:

CREATE LOCATION my_location WITH
  SOURCE = CLOUD_STORAGE
  CREDENTIALS = ( AWS_ROLE_ARN = 'arn:aws:iam::123456789012:role/S3Access' )
  URL = 's3://my-bucket/path/to/data'

Create a location with an AWS session token

The following code examples create a location object named my_location, for an Amazon S3 data source with the specified URL and AWS session token. Both CLOUD_STORAGE and AMAZON_S3 are shown:

-- Using CLOUD_STORAGE (recommended)
CREATE LOCATION my_location WITH
  SOURCE = CLOUD_STORAGE
  CREDENTIALS = ( AWS_ACCESS_KEY_ID = '1231' AWS_SECRET_ACCESS_KEY = '567' AWS_SESSION_TOKEN = 'session-token' )
  URL = 's3://my-bucket/path/to/data'

-- Using AMAZON_S3 (alias)
CREATE LOCATION my_location WITH
  SOURCE = AMAZON_S3
  CREDENTIALS = ( AWS_ACCESS_KEY_ID = '1231' AWS_SECRET_ACCESS_KEY = '567' AWS_SESSION_TOKEN = 'session-token' )
  URL = 's3://my-bucket/path/to/data'

Overview

Performance and Observability

Security

Self-Managed

Managed service

Guides

SQL reference

Release notes

API reference

Legal

Syntax

Parameters

Common Parameters

Amazon S3 Parameters

AWS Authentication Parameters

Examples

Authenticate using an access key

Authenticate using a role

Create a location with an AWS session token

​Syntax

​Parameters

​Common Parameters

​Amazon S3 Parameters

​AWS Authentication Parameters

​Examples

​Authenticate using an access key

​Authenticate using a role

​Create a location with an AWS session token

Syntax

Parameters

Common Parameters

Amazon S3 Parameters

AWS Authentication Parameters

Examples

Authenticate using an access key

Authenticate using a role

Create a location with an AWS session token