ALTER ICEBERG TABLE … REFRESH¶

Syntax¶

ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> REFRESH [ '<metadata_file_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.

Access control requirements¶

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

The USAGE privilege on the parent database and schema are required to perform operations on any object in a 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.

• Refresh operations during CREATE and ALTER … REFRESH can process a maximum of 1,000 Delta commit files per operation.

  Note

  Snowflake uses Delta checkpoint files when creating an Iceberg table. The 1,000 commit file limit only applies to commits after the latest checkpoint.

• Regarding metadata:

  Attention

  Customers should ensure that no personal data (other than for a User object), sensitive data, export-controlled data, or other regulated data is entered as metadata when using the Snowflake service. For more information, see Metadata fields in Snowflake.

Examples¶

ALTER ICEBERG TABLE myIcebergTable REFRESH;

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