ALTER ICEBERG TABLE … REFRESH¶

Refreshes the metadata for an Apache Iceberg™ table that uses an external Iceberg catalog. Refreshing an Iceberg table synchronizes the table metadata with the most recent table changes.

This topic refers to Iceberg tables as simply “tables” except where specifying Iceberg tables avoids confusion.

See also:: CREATE ICEBERG TABLE , DROP ICEBERG TABLE , SHOW ICEBERG TABLES , DESCRIBE ICEBERG TABLE

Syntax¶

ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> REFRESH [ '<metadata_file_relative_path>' ]

For Parquet Direct tables:

ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> REFRESH [ '<relative_path>' ]

Parameters¶

table_name

Identifier for the table to refresh.

If the identifier contains spaces or special characters, the entire string must be enclosed in double quotes. Identifiers enclosed in double quotes are also case-sensitive.

For more information, see Identifier requirements.

'metadata_file_relative_path'

Specifies a metadata file path for a table created from Iceberg files in object storage. The path must be relative to the active storage location of the external volume associated with the table.

The following table shows what value to specify based on an example storage location:

Active storage location for the table’s external volume	`s3://mybucket_us_east_1`
Full path to the metadata file	`s3://mybucket_us_east_1/metadata/v1.metadata.json`
Value to specify as the `'metadata_file_relative_path'`	`metadata/v1.metadata.json` (without a leading forward slash)

Note

If the table uses AWS Glue as the catalog, or is created from Delta table files, don’t specify a metadata file path.
Omit the leading forward slash (/) in the metadata file path.
Before Snowflake version 7.34, a parameter named BASE_LOCATION (also called FILE_PATH in previous versions) was required to create a table from Iceberg files in object storage. The parameter specified a relative path from the EXTERNAL_VOLUME location.

To refresh a table that you created using the old syntax, specify a path relative to the BASE_LOCATION. For example, if the full path to your metadata file is s3://mybucket_us_east_1/my_base_location/metadata/v1.metadata.json, specify metadata/v1.metadata.json as the {metadata-file-relative-path}.

'relative_path'

For Parquet Direct tables (preview), specifies a path to a Parquet file or to a directory of Parquet files, relative to the table’s BASE_LOCATION. Snowflake registers new, changed, and deleted files under that path. If you omit the path, Snowflake refreshes all files under the BASE_LOCATION.

Snowflake matches the path as a prefix, not as an exact name. Snowflake refreshes every file whose path, relative to the BASE_LOCATION, begins with the string that you specify. For example, if your BASE_LOCATION contains the directories sales and sales_archive:

'/sales' refreshes the files in both sales and sales_archive.
'/sales/' refreshes only the files in sales.

To refresh only one directory, end the path with a slash (/). To refresh a single file, specify the full file name, such as '/sales/part-00001.parquet'. For examples, see Refresh a Parquet Direct table.

Note

If you specify a path that doesn’t exist, the refresh proceeds as if you didn’t specify a path.
You can’t manually refresh a Parquet Direct table that has AUTO_REFRESH = TRUE. Disable auto-refresh first.

Access control requirements¶

A role used to execute this operation must have the following privileges at a minimum:

Privilege	Object	Notes
OWNERSHIP	Iceberg table	OWNERSHIP is a special privilege on an object that is automatically granted to the role that created the object, but can also be transferred using the GRANT OWNERSHIP command to a different role by the owning role (or any role with the MANAGE GRANTS privilege).
USAGE	External volume	Not required if using vended credentials.
USAGE	Catalog integration

Operating on an object in a schema requires at least one privilege on the parent database and at least one privilege on the parent schema.

For instructions on creating a custom role with a specified set of privileges, see Creating custom roles.

For general information about roles and privilege grants for performing SQL actions on securable objects, see Overview of Access Control.

Usage notes¶

Only the table owner (that is, the role with the OWNERSHIP privilege on the table) or higher can execute this command.
Using the ALTER ICEBERG TABLE … REFRESH command in transactions (implicit or explicit) is not supported.
Considerations for Delta Direct tables: When you refresh a Delta Direct table using this command, Snowflake processes up to 1,000 Delta commit files per refresh and can perform a checkpoint refresh (full refresh) under certain conditions. For the 1,000 commit file limit, checkpoint refresh triggers, and examples, see Refresh.
Considerations for Parquet Direct tables: Each refresh registers Parquet files and incurs data registration charges for the bytes added. For more information, see Billing.
Regarding metadata:

Attention

Examples¶

Refresh a table¶

This example manually refreshes the metadata for a table for the following scenarios:

The table uses AWS Glue for the Iceberg catalog.
The table is based on Delta table files in object storage.

For these scenarios, you don’t specify a metadata file path in the refresh command.

ALTER ICEBERG TABLE myIcebergTable REFRESH;

Refresh a table created from Iceberg files in object storage¶

This example manually refreshes the table metadata based on changes in a new metadata file. In this example, the full path to the metadata file is <external-volume-storage-base-url>/path/to/metadata/v2.metadata.json.

When specifying a metadata file, you don’t include a leading forward slash (/) in the metadata file path.

ALTER ICEBERG TABLE my_iceberg_table REFRESH 'path/to/metadata/v2.metadata.json';

Note

Before Snowflake version 7.34, a parameter named BASE_LOCATION (also called FILE_PATH in previous versions) was required to create a table from Iceberg files in object storage. The parameter specified a relative path from the EXTERNAL_VOLUME location.

To refresh a table that you created using the old syntax, specify a path relative to the BASE_LOCATION. For example, if the full path to your metadata file is s3://mybucket_us_east_1/my_base_location/metadata/v1.metadata.json, specify metadata/v1.metadata.json as the {metadata-file-relative-path}.

Refresh a Parquet Direct table¶

The following examples refresh a Parquet Direct table named orders. The table’s BASE_LOCATION contains the following Hive-partitioned directories:

region=us/order_date=2026-10-01/part-00001.parquet
region=us/order_date=2026-10-02/part-00001.parquet
region=us_east/order_date=2026-10-01/part-00001.parquet
region=eu/order_date=2026-10-01/part-00001.parquet

Refresh all files under the table’s BASE_LOCATION:

ALTER ICEBERG TABLE orders REFRESH;

Refresh only the region=us directory. The trailing slash limits the refresh to that directory:

ALTER ICEBERG TABLE orders REFRESH '/region=us/';

Without the trailing slash, the path is a prefix of both region=us and region=us_east, so the following statement refreshes the files in both directories:

ALTER ICEBERG TABLE orders REFRESH '/region=us';

Refresh a single partition:

ALTER ICEBERG TABLE orders REFRESH '/region=us/order_date=2026-10-01/';

Refresh every October 2026 partition in the region=us directory. This example omits the trailing slash on purpose, so that the path matches both order_date=2026-10-01 and order_date=2026-10-02:

ALTER ICEBERG TABLE orders REFRESH '/region=us/order_date=2026-10';

Refresh a single Parquet file:

ALTER ICEBERG TABLE orders REFRESH '/region=us/order_date=2026-10-01/part-00001.parquet';