Creates a new catalog-linked database for Apache Iceberg™ tables that use an external Iceberg REST catalog.
Syntax¶CREATE DATABASE <name> LINKED_CATALOG = ( catalogParams ), [ EXTERNAL_VOLUME = '<external_vol>' ] [ COMMENT = '<string_literal>' ] [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]
Copy
Where:
Required parameters¶catalogParams ::= CATALOG = '<catalog_int>', [ ALLOWED_NAMESPACES = ('<namespace1>', '<namespace2>', ... ) ] [ BLOCKED_NAMESPACES = ('<namespace1>', '<namespace2>', ... ) ] [ NAMESPACE_MODE = { IGNORE_NESTED_NAMESPACE | FLATTEN_NESTED_NAMESPACE } ] [ NAMESPACE_FLATTEN_DELIMITER = '<string_literal>' ] [ SYNC_INTERVAL_SECONDS = <value> ]Copy
name
Specifies the identifier for the catalog-linked database; must be unique for your account.
In addition, the identifier must start with an alphabetic character and cannot contain spaces or special characters unless the entire identifier string is enclosed in double quotes (for example, "My object"). Identifiers enclosed in double quotes are also case-sensitive.
For more information, see Identifier requirements.
EXTERNAL_VOLUME = my_external_vol
Specifies an external volume that provides access to the data and metadata for your remote Iceberg tables.
Not required if using vended credentials.
COMMENT = 'string_literal'
Specifies a comment for the database.
Default: No value
TAG ( tag_name = 'tag_value' [ , tag_name = 'tag_value' , ... ] )
Specifies the tag name and the tag string value.
The tag value is always a string, and the maximum number of characters for the tag value is 256.
For information about specifying tags in a statement, see Tag quota for objects.
CATALOG = catalog_int
Specifies the name of your catalog integration.
ALLOWED_NAMESPACES = ('namespace1', 'namespace2', ... )
Optionally specifies one or more namespaces in your remote catalog to limit the scope of automatic table discovery. Snowflake syncs the specified namespaces and all namespaces and tables that descend from them. If a nested namespace is in the ALLOWED_NAMESPACES list but you set the NAMESPACE_MODE parameter to IGNORE_NESTED_NAMESPACE, Snowflake does not sync the nested namespace or any schemas and tables under it.
BLOCKED_NAMESPACES = ('namespace1', 'namespace2', ... )
Optionally specifies one or more namespaces in your remote catalog to block for automatic table discovery.
Snowflake blocks the specified namespaces and all namespaces and tables that descend from them.
If you specify both ALLOWED_NAMESPACES and BLOCKED_NAMESPACES, the BLOCKED_NAMESPACES list takes precedence. For example, if ns1.ns2 is allowed, but ns1 is blocked, then Snowflake won’t sync ns1.ns2.
NAMESPACE_MODE = { IGNORE_NESTED_NAMESPACE | FLATTEN_NESTED_NAMESPACE }
Specifies how Snowflake handles namespaces for Iceberg tables in the catalog-linked database.
IGNORE_NESTED_NAMESPACE: Snowflake links only tables in the first namespace level for your catalog.
FLATTEN_NESTED_NAMESPACE: Snowflake links 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. With this option, you must set the NAMESPACE_FLATTEN_DELIMITER parameter.
For example, consider a table named iceberg_table_5 in the namespace3aa namespace:
my_catalog_linked_db |-- namespace3 | |-- namespace3a | |-- namespace3aa | |-- iceberg_table_5
Copy
If you set NAMESPACE_FLATTEN_DELIMITER = "/", you can specify "my_catalog_linked_db"."namespace3/namespace3a/namespace3aa"."iceberg_table_5" to reference the table.
Default: IGNORE_NESTED_NAMESPACE
NAMESPACE_FLATTEN_DELIMITER = 'string_literal'
Required if you set NAMESPACE_MODE = FLATTEN_NESTED_NAMESPACE. Specifies a delimiter, which Snowflake uses to construct flattened namespaces for tables in your catalog.
Important
The character that you choose for a delimiter 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.
Valid characters: Any characters allowed in Snowflake identifiers.
SYNC_INTERVAL_SECONDS = 'value'
Specifies the time interval (in seconds) that Snowflake should use for automatically discovering schemas and tables in your remote catalog.
Values: 30 to 86400 (1 day), inclusive
Default: 30 seconds
A role used to execute this operation must have the following privileges at a minimum:
Privilege
Object
Notes
CREATE DATABASE
Account
Required to create a new database.
Only the SYSADMIN role, or a higher role, has this privilege by default. The privilege can be granted to additional roles as needed.
USAGE
External Volume
Required to reference an existing external volume.
USAGE
Catalog integration
Required to reference an existing catalog integration.
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¶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 databases linked to AWS Glue, you must use lowercase letters and surround the schema, table, and column names in double quotes. This is also required for other Iceberg REST catalogs that only support lowercase identifiers.
The following example shows a valid query:
The following statements aren’t valid, because they use uppercase letters or omit the double quotes:
CREATE SCHEMA s1; CREATE SCHEMA "Schema1";
Copy
Using UNDROP ICEBERG TABLE isn’t supported.
Sharing with a listing is supported for tables that use an external volume. Direct sharing isn’t currently 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.
For ALLOWED_NAMESPACES and BLOCKED_NAMESPACES, Snowflake doesn’t store nested namespaces if the set already contains the parent namespace. For example, if you create a database and specify ALLOWED_NAMESPACES = ('ns1', 'ns1.ns2', 'ns1.ns3'), Snowflake only stores ns1 since the other two are automatically included. If you use GET_DDL on the example database, Snowflake returns ALLOWED_NAMESPACES = ('ns1'). The same applies for BLOCKED_NAMESPACES.
For querying tables in a catalog-linked database:
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.
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.
Create a catalog-linked database with flattened nested namespaces.
CREATE DATABASE my_linked_db
LINKED_CATALOG = (
CATALOG = 'my_catalog_int',
NAMESPACE_MODE = FLATTEN_NESTED_NAMESPACE,
NAMESPACE_FLATTEN_DELIMITER = '-'
)
EXTERNAL_VOLUME = 'my_external_vol';
Copy
Create a catalog-linked database that uses vended credentials and specifies one allowed namespace:
CREATE DATABASE my_linked_db
LINKED_CATALOG = (
CATALOG = 'my_catalog_int_vended_creds',
ALLOWED_NAMESPACES = ('my_namespace')
);
Copy
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