Creates a new location object in your Firebolt account, which is a secure, reusable object that stores the connection details and credentials for Iceberg 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 specific and examples for location objects for Iceberg. For more on location objects in general, see CREATE LOCATION.

Iceberg locations currently support three catalog types: REST, FILE_BASED, and DATABRICKS_UNITY (as syntactic sugar top of REST). Each catalog accepts a different set of parameters and credentials.

Topics:

​
Syntax

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>' ] )
  }
  [ DESCRIPTION = '<description>' ]

​
Parameters

​
Common Parameters

ParameterDescription
<location_name>A unique identifier for the location within your account.
SOURCEThe external data source type. Currently, AMAZON_S3 and ICEBERG are supported. This should be ICEBERG for Iceberg locations.
DESCRIPTIONOptional metadata describing the location’s purpose.

​
Iceberg Parameters

ParameterDescription
CATALOGThe type of Iceberg catalog. Supported values: FILE_BASED, REST, or DATABRICKS_UNITY.
CATALOG_OPTIONSConfiguration options specific to the chosen catalog type.
CREDENTIALSAuthentication credentials for accessing the Iceberg catalog. Depending on the type of catalog, either AWS or OAuth credentials are used.

​
AWS Authentication Parameters

Use AWS authentication parameters for FILE_BASED catalogs.

ParameterDescription
AWS_ACCESS_KEY_IDYour AWS access key ID for key-based authentication.
AWS_SECRET_ACCESS_KEYYour AWS secret access key for key-based authentication.
AWS_SESSION_TOKENOptional temporary session token for temporary credentials.
AWS_ROLE_ARNThe ARN of the IAM role to assume for role-based authentication.
AWS_ROLE_EXTERNAL_IDOptional external ID for role assumption.

​
OAuth Authentication Parameters

Use OAuth authentication parameters for REST or DATABRICKS_UNITY catalogs.

ParameterDescription
OAUTH_CLIENT_IDThe OAuth client ID for authentication.
OAUTH_CLIENT_SECRETThe OAuth client secret for authentication.
OAUTH_SCOPEOptional OAuth scope for authentication.
OAUTH_SERVER_URLOptional OAuth server URL for authentication.

​
Iceberg Catalog-Specific Parameters

FILE_BASED Catalog
ParameterDescription
URLThe URL for the file-based catalog. This must be a valid S3 URL.
REST Catalog
ParameterDescription
URLThe REST catalog URL.
WAREHOUSEThe warehouse identifier.
NAMESPACEThe namespace identifier.
TABLEThe table name.
DATABRICKS_UNITY Catalog
ParameterDescription
WORKSPACE_INSTANCEThe Databricks workspace instance.
CATALOGThe Unity Catalog name.
SCHEMAThe Unity Catalog schema name.
TABLEThe Unity Catalog table name.

​
Examples

​
File-based catalog

Used to access Iceberg tables directly from S3.

For file-based Iceberg catalogs, use AWS key-based or role-based authentication in CREDENTIALS.

With access key and secret:

CREATE LOCATION my_location
WITH 
  SOURCE = 'ICEBERG'
  CATALOG = 'FILE_BASED'
  CATALOG_OPTIONS = (
    URL = 's3://my-bucket/path/to/iceberg/table'
  )
  CREDENTIALS = ( AWS_ACCESS_KEY_ID = '1231' AWS_SECRET_ACCESS_KEY = '567' );

SELECT * FROM READ_ICEBERG(LOCATION => my_location) LIMIT 5;

With access key, secret, and session token:

CREATE LOCATION my_location
WITH 
  SOURCE = 'ICEBERG'
  CATALOG = 'FILE_BASED'
  CATALOG_OPTIONS = (
    URL = 's3://my-bucket/path/to/iceberg/table'
  )
  CREDENTIALS = ( AWS_ACCESS_KEY_ID = '1231' AWS_SECRET_ACCESS_KEY = '567' SESSION_TOKEN = 'session-token' );

SELECT * FROM READ_ICEBERG(LOCATION => my_location) LIMIT 5;

With role:

CREATE LOCATION my_location
WITH 
  SOURCE = 'ICEBERG'
  CATALOG = 'FILE_BASED'
  CATALOG_OPTIONS = (
    URL = 's3://my-bucket/path/to/iceberg/table'
  )
  CREDENTIALS = ( AWS_ROLE_ARN = 'arn:aws:iam::123456789012:role/S3Access' );

SELECT * FROM READ_ICEBERG(LOCATION => my_location) LIMIT 5;

With role and external id:

CREATE LOCATION my_location
WITH 
  SOURCE = 'ICEBERG'
  CATALOG = 'FILE_BASED'
  CATALOG_OPTIONS = (
    URL = 's3://my-bucket/path/to/iceberg/table'
  )
  CREDENTIALS = ( AWS_ROLE_ARN = 'arn:aws:iam::123456789012:role/S3Access' AWS_ROLE_EXTERNAL_ID = 'my-external-id' );

SELECT * FROM READ_ICEBERG(LOCATION => my_location) LIMIT 5;

​
REST catalog

Used to access Iceberg in REST catalogs, that implement the Iceberg REST API spec.

For generic REST Iceberg catalogs, use OAuth parameters for CREDENTIALS.

CREATE LOCATION my_location
WITH 
  SOURCE = 'ICEBERG'
  CATALOG = 'REST'
  CATALOG_OPTIONS = (
    URL = 'https://my-iceberg-rest-catalog/api'
    WAREHOUSE  = 'my_warehouse'
    NAMESPACE = 'my_namespace'
    TABLE = 'my_table_name'
  )
  CREDENTIALS = (
    OAUTH_CLIENT_ID = '00000000-0000-0000-0000-000000000000'
    OAUTH_CLIENT_SECRET = '1234'
    OAUTH_SCOPE = 'example_permission:all'
    -- OAUTH_SERVER_URL is only needed for REST catalogs that don't support the /v1/oauth/tokens endpoint. If /v1/oauth/tokens is supported, it can be omitted.
    OAUTH_SERVER_URL = 'https://my-iceberg-rest-catalog/example/token'
  );

SELECT * FROM READ_ICEBERG(LOCATION => my_location) LIMIT 5;

​
Databricks Unity Catalog

Used to access Iceberg tables in a Databricks Unity Catalog. Offered as syntactic sugar on top of CATALOG = 'REST', for users who may be more familiar with Databricks Unity Catalog terminology.

For configuring Unity Catalog in your Databricks workspace, see Databricks - Set up and manage Unity Catalog. Note that you will need to enable credential vending in your Unity Catalog, see Databricks - Unity Catalog credential vending for external system access. For general information about reading Databricks tables from Iceberg clients, see Databricks - Read Databricks tables from Iceberg clients.

For Databricks Unity Catalogs, use OAuth parameters for CREDENTIALS.

CREATE LOCATION my_location
WITH 
  SOURCE = 'ICEBERG'
  CATALOG = 'DATABRICKS_UNITY'
  CATALOG_OPTIONS = (
    WORKSPACE_INSTANCE = '000-0000000000000.cloud.databricks.com'
    CATALOG  = 'my_uc_catalog_name'
    SCHEMA = 'my_uc_schema_name'
    TABLE = 'my_uc_table_name'
  )
  CREDENTIALS = (
    OAUTH_CLIENT_ID = '00000000-0000-0000-0000-000000000000'
    OAUTH_CLIENT_SECRET = '1234'
    -- OAUTH_SCOPE and OAUTH_SERVER_URL are not needed
  );

SELECT * FROM READ_ICEBERG(LOCATION => my_location) LIMIT 5;

​
Snowflake Open catalog (as a generic REST catalog)

Iceberg tables in Snowflake Open Catalog can currently be read by using a LOCATION with CATALOG = 'REST'.

For setting up a Snowflake Open Catalog in your account, see Snowflake - Snowflake Open Catalog overview. Note that you will need to enable credential vending for your Iceberg tables, see Snowflake - Use catalog-vended credentials for Apache Iceberg™ tables. For general information about reading Snowflake Open Catalog tables from Iceberg clients, see Snowflake - Checking your REST catalog configuration.

For Snowflake Open catalogs, use OAuth parameters for CREDENTIALS.

CREATE LOCATION my_location
WITH 
  SOURCE = 'ICEBERG'
  CATALOG = 'REST'
  CATALOG_OPTIONS = (
    URL = 'https://abc123.us-west-2.aws.myapi.com/polaris/api/catalog'
    WAREHOUSE  = 'my_warehouse'
    NAMESPACE = 'my_catalog_name'
    TABLE = 'my_table_name'
  )
  CREDENTIALS = (
    OAUTH_CLIENT_ID = '00000000-0000-0000-0000-000000000000'
    OAUTH_CLIENT_SECRET = '1234'
    OAUTH_SCOPE = 'PRINCIPAL_ROLE:ALL'
    -- OAUTH_SERVER_URL is not needed
  );

SELECT * FROM READ_ICEBERG(LOCATION => my_location) LIMIT 5;