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.
Syntax¶ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> REFRESH [ '<metadata_file_relative_path>' ]
Copy
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.
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
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.
Snowflake processes a maximum of 1000 Delta commit files each time you refresh a table using CREATE/ALTER … REFRESH. If your table has over 1000 commit files, you can do additional manual refreshes. Each time, the refresh process continues from where the last one stopped.
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.
When you refresh an existing table, Snowflake processes Delta commit files, but not checkpoint files. If table maintenance removes stale log and data files for the source Delta table, you should refresh Delta-based Iceberg tables in Snowflake more frequently than the retention period of Delta logs and data files.
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.
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;
Copy
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';
Copy
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.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4