Configure a catalog integration for Delta Sharing¶

Use the CREATE CATALOG INTEGRATION (Delta Sharing) command to create a catalog integration that uses the Delta Sharing protocol to read Delta tables from a remote Delta Sharing server. After you create the catalog integration, you can create a catalog-linked database to query the shared Delta tables from Snowflake.

Considerations¶

Consider the following when you use a Delta Sharing catalog integration:

• Tables are read-only in Snowflake. A catalog-linked database that uses a Delta Sharing catalog integration supports only read operations. You can’t insert into, update, or create tables in the catalog-linked database from Snowflake.

• Table format must be Delta. A Delta Sharing catalog integration supports only Delta tables (TABLE_FORMAT = DELTA).

• Authentication is by bearer token. Snowflake authenticates to the Delta Sharing server by using the bearer token issued to the recipient. Store the bearer token securely and rotate it before it expires.

• Vended credentials are required for table access. Snowflake uses vended credentials returned by the Delta Sharing server to access the underlying table data in cloud storage. The Delta Sharing server must support vended credentials.

Prerequisites¶

Before you begin, make sure that you have:

• A Snowflake account where you can create a catalog integration. You must use the ACCOUNTADMIN role, or a role that has the CREATE INTEGRATION privilege on the account.

• Access to a Delta Sharing server (the provider) that has:

  • A share exposed to an open recipient that uses bearer-token authentication.
  • The recipient credential file that the provider generates for that recipient.

  For Databricks Unity Catalog, follow Delta Sharing in the Databricks documentation to enable Delta Sharing on your metastore, create a share, create an open recipient with token authentication, and download the recipient credential file. Then return to this topic to configure the catalog integration in Snowflake.

About the recipient credential file¶

At the time of writing, the Delta share credential file is a JSON file from the Delta Sharing provider that contains the endpoint URL and the bearer token Snowflake uses to authenticate. The file contains content like the following:

{
  "shareCredentialsVersion": 1,
  "bearerToken": "...",
  "endpoint": "https://<delta-sharing-server>/api/2.0/delta-sharing/metastores/<metastore-id>",
  "expirationTime": "2027-03-25T20:08:11.118Z"
}

When you create the catalog integration, you specify the endpoint and bearerToken values from this file.

Step 1: Create the catalog integration¶

Use the CREATE CATALOG INTEGRATION (Delta Sharing) command to create a Delta Sharing catalog integration in Snowflake. Use the endpoint and bearerToken values from the recipient credential file.

The following example creates a Delta Sharing catalog integration:

USE ROLE ACCOUNTADMIN;

CREATE OR REPLACE CATALOG INTEGRATION my_delta_sharing_int
  CATALOG_SOURCE = DELTA_SHARING
  TABLE_FORMAT = DELTA
  REST_CONFIG = (
    CATALOG_URI = '<endpoint_from_credential>'
    CATALOG_NAME = 'shares/<share_name>'
    ACCESS_DELEGATION_MODE = VENDED_CREDENTIALS
  )
  REST_AUTHENTICATION = (
    TYPE = BEARER
    BEARER_TOKEN = '<bearer_token_from_credential>'
  )
  ENABLED = TRUE;

Where:

• CATALOG_URI is the endpoint value from the recipient credential file.
• CATALOG_NAME is shares/ followed by the name of the Delta Sharing share. For example, if your share is named sales_share, specify CATALOG_NAME = 'shares/sales_share'.
• BEARER_TOKEN is the bearerToken value from the recipient credential file.

Step 2: Verify the catalog integration¶

After you create the catalog integration, verify that Snowflake can connect to the Delta Sharing server.

1. Verify the catalog integration configuration by calling the SYSTEM$VERIFY_CATALOG_INTEGRATION function:

   Copy codeExpand code block

   SELECT SYSTEM$VERIFY_CATALOG_INTEGRATION('my_delta_sharing_int');

   Show lessSee more

   Scroll to top

   

2. List the namespaces (schemas) in the share by calling the SYSTEM$LIST_NAMESPACES_FROM_CATALOG function:

   Copy codeExpand code block

   SELECT SYSTEM$LIST_NAMESPACES_FROM_CATALOG('my_delta_sharing_int');

   Show lessSee more

   Scroll to top

   

3. List the tables in a schema by calling the SYSTEM$LIST_ICEBERG_TABLES_FROM_CATALOG function:

   Copy codeExpand code block

   SELECT SYSTEM$LIST_ICEBERG_TABLES_FROM_CATALOG(
     'my_delta_sharing_int',
     '<schema_name_in_share>'
   );

   Show lessSee more

   Scroll to top

   

Step 3: Create a catalog-linked database¶

After you verify the catalog integration, create a catalog-linked database that surfaces the Delta tables from the share as queryable tables in Snowflake.

The following example creates a read-only catalog-linked database named delta_sharing_cld:

CREATE OR REPLACE DATABASE delta_sharing_cld
  LINKED_CATALOG = (
    CATALOG = my_delta_sharing_int
    ALLOWED_WRITE_OPERATIONS = 'NONE'
    SYNC_INTERVAL_SECONDS = 30
  );

Where:

• CATALOG is the name of the catalog integration that you created in Step 1: Create the catalog integration.
• ALLOWED_WRITE_OPERATIONS = 'NONE' makes the database read-only. Write operations against Delta tables shared through Delta Sharing aren’t supported.
• SYNC_INTERVAL_SECONDS controls how often Snowflake syncs the catalog-linked database with the remote share. Adjust this value based on how frequently the tables in the share change.

For more information about catalog-linked databases, including additional parameters, see Use a catalog-linked database for Apache Iceberg™ tables and CREATE DATABASE (catalog-linked).

Step 4: Query Delta tables¶

After Snowflake syncs the catalog-linked database, you can query the shared Delta tables like any other table in Snowflake.

For example:

SELECT *
  FROM delta_sharing_cld.<schema_name>.<table_name>;