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

With a catalog-linked database, you can now access multiple remote Iceberg tables from Snowflake without creating individual externally managed tables.

A catalog-linked database is a Snowflake database connected to an external Iceberg REST catalog. Snowflake automatically syncs with the external catalog to detect namespaces and Iceberg tables, and registers the remote tables to the catalog-linked database.

Considerations¶

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

  • Supported only when using a catalog integration for Snowflake Open Catalog or for Iceberg REST.

  • You can use the ALLOWED_NAMESPACES parameter to limit the scope of automatic table discovery to a particular namespace in your remote catalog. Specifying multiple namespaces isn’t currently supported.

  • Snowflake doesn’t sync any access control (users or roles) that you have configured in your remote catalog.

  • Creating other Snowflake objects (such as views) in a catalog-linked database isn’t supported.

  • Using vended credentials isn’t currently supported for writing to externally managed tables.

  • For Iceberg tables in a catalog-linked database:

    • Snowflake doesn’t copy table properties that you have set in the remote catalog (for example, retention policies or buffers).

    • Automated refresh is enabled by default.

    • Dropped or renamed tables in the remote catalog aren’t reflected in the catalog-linked database.

    • Snowflake-specific features such as replication, cloning, sharing (including listings), and data governance aren’t supported.

Create a catalog-linked database¶

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

  1. Configure access

  2. Create a database

  3. Check the catalog sync status

  4. Query an Iceberg table in the database

Configure access¶

Before you create a catalog-linked database, you must configure access to your external catalog and table storage.

Option 1: Configure an external volume and catalog integration¶

With this option, you configure an external volume and a catalog integration. Choose this option if your remote Iceberg catalog doesn’t support credential vending or if you want to write to the Iceberg tables in your remote catalog.

  1. Configure an external volume for the cloud storage service that stores the data and metadata of your remote Iceberg tables:

  2. Configure a catalog integration for your remote Iceberg catalog:

Option 2: Configure a catalog integration with vended credentials¶

Note

This feature is supported only for tables that store their data and metadata in Amazon S3.

With this option, your remote Iceberg catalog must support credential vending.

For instructions, see Use catalog-vended credentials for Apache Iceberg™ tables.

Create a database¶

Create a catalog-linked database with the CREATE DATABASE … LINKED_CATALOG command:

The following example creates a catalog-linked database that uses an external volume:

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

Note

This example specifies NAMESPACE_MODE = FLATTEN_NESTED_NAMESPACE, which tells Snowflake to link tables in all namespace levels for your catalog. For a table in a nested namespace, Snowflake uses the NAMESPACE_FLATTEN_DELIMITER parameter to construct a flattened namespace.

For more information, see CREATE DATABASE (catalog-linked).

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')
  );
Copy

Check the catalog sync status¶

After you create a catalog-linked database, you can use the SYSTEM$CATALOG_LINK_STATUS function to check if Snowflake has successfully linked to your remote catalog.

To help you troubleshoot, 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');
Copy

Query an Iceberg table in the database¶

After you create a catalog-linked database, Snowflake starts the table discovery process and automatically polls your linked catalog for changes on a periodic basis (with a sync interval of 5 minutes). 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 using a SELECT statement.

Note

Snowflake automatically converts unquoted identifiers (table and column names) to uppercase. If your external Iceberg catalog uses case-sensitive identifiers, you must surround table and column names in double quotes.

For more information about object identifiers, see Identifier requirements.

For example:

USE DATABASE my_linked_db;

SELECT * FROM my_namespace.my_iceberg_table
  LIMIT 20;
Copy
Language: English