Use a catalog-linked database for Apache Iceberg™ tables¶

Considerations¶

Consider the following when you use a catalog-linked database:

• Supported only when you use a catalog integration for Iceberg REST (for example, Snowflake Open Catalog).

• Billing: During the preview period, Snowflake doesn’t bill for catalog-linked databases. Billing starts on September 1, 2025. To help you preview cost, the METERING_HISTORY and METERING_DAILY_HISTORY views will display credits used for catalog-linked databases before billing starts.

• To limit automatic table discovery to a specific set of namespaces, use the ALLOWED_NAMESPACES parameter. You can also use the BLOCKED_NAMESPACES parameter to block a set of namespaces.

• Snowflake doesn’t sync remote catalog access control (users or roles).

• You can create schemas or externally managed Iceberg tables in a catalog-linked database. Creating other Snowflake objects isn’t currently supported.

• Latency:

  • For databases linked to 7,500 namespaces in a remote catalog, namespace and table discovery takes about one hour.

  • For remote catalogs with 500,000 tables, the automated refresh process takes about one hour to complete. For namespaces with different latency requirements, we recommend that you create separate catalog-linked databases. Each database should reference a catalog integration with an appropriate auto-refresh interval (REFRESH_INTERVAL_SECONDS).

• For Iceberg tables in a catalog-linked database:

  • Snowflake doesn’t copy remote catalog table properties (such as retention policies or buffers), and doesn’t currently support altering table properties.

  • Automated refresh is enabled by default. If the table-uuid of an external table and the catalog-linked database table don’t match, refresh fails and Snowflake drops the table from the catalog-linked database; Snowflake doesn’t change the remote table.

  • If you drop a table from the remote catalog, Snowflake drops the table from the catalog-linked database. This action is asynchronous, so you might not see the change in the remote catalog right away.

  • If you rename a table in the remote catalog, Snowflake drops the existing table from the catalog-linked database and creates a table with the new name.

  • Masking policies and tags are supported. Other Snowflake-specific features including replication, cloning, and sharing aren’t supported.

  • The character that you choose for the NAMESPACE_FLATTEN_DELIMITER parameter can’t appear in your remote namespaces. During the autodiscovery process, Snowflake skips any namespace that contains the delimiter, and does not create a corresponding schema in your catalog-linked database.

  • If you specify anything other than _, $, uppercase letters, or numbers for the NAMESPACE_FLATTEN_DELIMITER parameter, you must put the schema name in quotes when you query the table.

  • For lowercase identifiers (including those defined in catalogs that only support lowercase identifiers), you must surround schema and table names in quotes when you query a table.

  • Using UNDROP ICEBERG TABLE isn’t supported.

• For writing to tables in a catalog-linked database:

  • Vended credentials aren’t supported.

  • Writing to tables in nested namespaces isn’t currently supported.

Workflow¶

The following steps cover how to create a catalog-linked database, check the sync status between Snowflake and your catalog, and create or query a table in the database.

1. Configure access

2. Create a catalog-linked database

3. Check the catalog sync status

4. Query a table or Write to your remote catalog

Configure access¶

Before you create a catalog-linked database, choose one of the following options to configure access to your external catalog and table storage.

Create a catalog-linked database¶

Create a catalog-linked database with the CREATE DATABASE (catalog-linked) command:

The following example creates a catalog-linked database that uses an external volume. It specifies a sync interval of 60 seconds (the default is 30). The sync interval tells Snowflake how often to poll your remote catalog.

CREATE DATABASE my_linked_db
  LINKED_CATALOG = (
    CATALOG = 'my_catalog_int',
    BLOCKED_NAMESPACES = ('my_blocked_namespace'),
    NAMESPACE_MODE = FLATTEN_NESTED_NAMESPACE,
    NAMESPACE_FLATTEN_DELIMITER = '-'
    SYNC_INTERVAL_SECONDS = 60
  )
  EXTERNAL_VOLUME = 'my_external_vol';

Alternatively, create a catalog-linked database that uses vended credentials. This example also specifies one allowed namespace.

CREATE DATABASE my_linked_db
  LINKED_CATALOG = (
    CATALOG = 'my_catalog_int_vended_creds',
    ALLOWED_NAMESPACES = ('my_namespace')
  );

Check the catalog sync status¶

To check whether Snowflake has successfully linked your remote catalog to your database, use the SYSTEM$CATALOG_LINK_STATUS function.

The function also provides information to help you identify tables in the remote catalog that fail to sync.

SELECT SYSTEM$CATALOG_LINK_STATUS('my_linked_db');

Query a table¶

After you create a catalog-linked database, Snowflake starts the table discovery process and automatically polls your linked catalog using the value of the SYNC_INTERVAL_SECONDS parameter (with a default interval of 30 seconds) to check for changes.

In the database, allowed namespaces from the remote catalog appear as schemas, and Iceberg tables appear under their respective schemas.

You can query the remote tables by using a SELECT statement.

For example:

USE DATABASE my_linked_db;

SELECT * FROM my_namespace.my_iceberg_table
  LIMIT 20;

Write to your remote catalog¶

You can use Snowflake to create namespaces and Iceberg tables in your linked catalog. For more information, see the following topics:

• Write support for externally managed Apache Iceberg™ tables

• Use CREATE SCHEMA to create namespaces in your external catalog

• Create an Iceberg table in a catalog-linked database