Configure an external volume¶

An external volume is a named, account-level Snowflake object that you use to connect Snowflake to your external cloud storage for Iceberg tables. An external volume stores an identity and access management (IAM) entity for your storage location. Snowflake uses the IAM entity to securely connect to your storage for accessing table data, Iceberg metadata, and manifest files that store the table schema, partitions, and other metadata.

A single external volume can support one or more Iceberg tables.

You must create an external volume before you can create an Apache Iceberg™ table in Snowflake.

Create an external volume¶

The steps to create an external volume depend on your cloud storage provider.

For instructions, see the following topics:

Each external volume is associated with a particular Active storage location, and a single external volume can support multiple Iceberg tables. However, the number of external volumes you need depends on how you want to store, organize, and secure your table data.

You can use a single external volume if you want the data and metadata for all of your Snowflake-Iceberg tables in subdirectories under the same storage location (for example, in the same S3 bucket). To configure these directories for Snowflake-managed tables, see Data and metadata directories.

Alternatively, you can create multiple external volumes to secure various storage locations differently. For example, you might create the following external volumes:

A read-only external volume for externally managed Iceberg tables.
An external volume configured with read and write access for Snowflake-managed tables.

Verify an external volume¶

Verify an external volume to check that Snowflake can successfully authenticate to your storage provider using an external volume that you’ve configured. You can verify an external volume by using SQL or Snowsight.

Use SQL¶

To verify an external volume by using SQL, call the SYSTEM$VERIFY_EXTERNAL_VOLUME function.

Specify the name of the external volume that you want to verify.

SELECT SYSTEM$VERIFY_EXTERNAL_VOLUME('my_s3_external_volume');

Copy

Use Snowsight¶

To verify an external volume by using Snowsight, follow these steps:

Sign in to Snowsight.
In the navigation menu, select Catalog » External data.
Select the External volumes tab.
Select the external volume whose connection you want to verify.
Select … » Verify connection.

Set a default external volume at the account, database, or schema level¶

You can either set an existing external volume as the default or set a new external volume as the default when you create it.

Set an existing external volume as the default¶

To set an existing external volume as the default to use for Iceberg tables, you can set the EXTERNAL_VOLUME parameter at the following levels:

Account:

Account administrators can use the ALTER ACCOUNT command to set the parameter for the account. If the value is set for the account, all Iceberg tables created in the account read from and write to this external volume by default.

Object:

Users can execute the appropriate CREATE <object> or ALTER <object> command to override the EXTERNAL_VOLUME parameter value at the database or schema level. The lowest-scoped declaration is used: schema > database > account.

In addition to the minimum privileges required to modify an object using the appropriate ALTER <object_type> command, a role must have the USAGE privilege on the external volume.

Note

Changes to the EXTERNAL_VOLUME parameter only apply to tables created after the change. Existing tables continue to use the external volume specified when they were created.
Alternatively, you can set a default external volume at the account, database, or schema level when you create the external volume by using Snowsight.

Example¶

The following statement sets an external volume (my_s3_vol) for a database named my_database_1:

ALTER DATABASE my_database_1
  SET EXTERNAL_VOLUME = 'my_s3_vol';

Copy

After setting an external volume at the database level, you can create an Iceberg table in that database without specifying an external volume. The following statement creates an Iceberg table in my_database_1 that uses Snowflake as the catalog and uses the default external volume (my_s3_vol) set for the database.

CREATE ICEBERG TABLE iceberg_reviews_table (
  id STRING,
  product_name STRING,
  product_id STRING,
  reviewer_name STRING,
  review_date DATE,
  review STRING
)
CATALOG = 'SNOWFLAKE'
BASE_LOCATION = 'my/product_reviews/';

Copy

Set a new external volume as the default¶

To set a new external volume as the default to use for Iceberg tables, when you create the external volume in Snowsight, use the Scope field in the configuration settings to set the external volume as the default at the account, database, or schema level.

For instructions on how to create an external volume in Snowsight, see the following sections:

Grant USAGE privileges to an external volume by using Snowsight¶

The USAGE privilege grants the ability to reference the external volume and view details for the external volume. For more information, see External volume privileges.

To grant USAGE privileges to an external volume by using Snowsight, follow these steps:

Sign in to Snowsight.
Switch to a role that has OWNERSHIP privileges on the external volume that you want to grant USAGE privileges to.

For instructions on switching a role, see Switch your primary role. For more information on the OWNERSHIP privilege, see External volume privileges.
In the navigation menu, select Catalog » External data.
Select the External volumes tab.
Select the external volume that you want to grant USAGE privileges on.
Select + Privilege.
From the Roles field, select the role that you want to grant the USAGE privilege for the external volume.
From the Privileges field, select USAGE.
Select Grant privileges.

Add a storage location by using Snowsight¶

Note

To add a storage location to an external volume by using SQL, use the ADD STORAGE_LOCATION parameter of the ALTER EXTERNAL VOLUME command.

To add a named storage location to an external volume by using Snowsight, follow these steps:

Sign in to Snowsight.
Switch to a role that has OWNERSHIP privilege on the external volume for which you want to add a storage location.

For instructions, see Switch your primary role.
In the navigation menu, select Catalog » External data.
Select the External volumes tab.
Select the external volume that you want to add a storage location to.
Select … » Add storage location

Select your cloud storage provider and specify the configuration for the storage location that you’re adding:

Select the Amazon S3 tab.

Specify the configuration for the storage location that you’re adding:

Field	Description
Location name	Enter a name for your additional storage location.
Region type	Specifies the cloud storage provider that stores your data files. Standard (default): S3 storage in public AWS regions outside of China. Government (GovCloud): S3 storage in AWS government regions.
S3 role ARN	Specifies the case-sensitive Amazon Resource Name (ARN) of the AWS identity and access management (IAM) role that grants privileges on the S3 bucket containing your data files. You recorded this value when you created an IAM role.
Encryption (optional)	Specifies the encryption type used. Possible values are: None (default): No encryption. SSE-S3: Server-side encryption using S3-managed encryption keys. For more information, see Using server-side encryption with Amazon S3-managed encryption keys (SSE-S3). SSE-KMS (enter key): Server-side encryption using keys stored in KMS. For more information, see Using server-side encryption with AWS Key Management Service (SSE-KMS).
Connectivity	Specifies whether to use outbound private connectivity to harden your security posture. For information about using this parameter, see Private connectivity to external volumes for Amazon Web Services. Possible values are: Public (default): Use the public internet. Private (AWS PrivateLink): Use outbound private connectivity.
Storage base URL	Specifies the base URL for your additional storage location.

Select the Microsoft Azure tab.

Specify the configuration for the storage location that you’re adding:

Field	Description
Location name	Enter a name for your additional storage location.
Storage base URL	Specifies the base URL for your additional storage location.
Azure tenant ID	specify your Azure tenant ID. To find your Azure tenant ID, see How to find your Microsoft Entra tenant ID in the Microsoft Entra documentation.
Use PrivateLink endpoint	Specifies whether to use outbound private connectivity to harden your security posture. For information about using outbound private connectivity, see Private connectivity to external volumes for Microsoft Azure.

Select Google Cloud tab.
Specify the configuration for the storage location that you’re adding:

Field

Description

Location name

Enter a name for your additional storage location.

Storage base URL

Specifies the base URL for your additional storage location.

Encryption (optional)

Specifies the encryption type used. Possible values are:

None (default): No encryption.
SSE-KMS (enter key): Server-side encryption using keys stored in KMS. For more information, see customer-managed encryption keys.

Select the S3 Compatible tab.

Specify the configuration for the storage location that you’re adding:

Field	Description
Location name	Enter a name for your additional storage location.
Storage base URL	Specifies the base URL for your cloud storage location.
AWS key ID	Specifies the AWS key ID for connecting to and accessing your S3-compatible storage location.
AWS secret key	Specifies the AWS secret key for connecting to and accessing your S3-compatible storage location.
Storage endpoint	Specifies a fully qualified domain that points to your S3-compatible API endpoint. Note The storage endpoint should not include a bucket name; for example, specify `example.com` instead of `my_bucket.example.com`.

Select Add storage location.