CREATE DATABASE（目录链接）¶

为使用外部 Iceberg REST 目录的 Apache Iceberg™ 表创建新的目录链接的数据库。

语法¶

CREATE DATABASE <name>
  LINKED_CATALOG = ( catalogParams ),
  [ EXTERNAL_VOLUME = '<external_vol>' ]
  [ COMMENT = '<string_literal>' ]
  [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]
  [ CATALOG_CASE_SENSITIVITY = { CASE_SENSITIVE | CASE_INSENSITIVE } ]
  [ WITH CONTACT ( <purpose> = <contact_name> [ , <purpose> = <contact_name> ... ] ) ]

Copy

其中：

catalogParams ::=
  CATALOG = '<catalog_int>',
  [ ALLOWED_NAMESPACES = ('<namespace1>', '<namespace2>', ... ) ]
  [ BLOCKED_NAMESPACES = ('<namespace1>', '<namespace2>', ... ) ]
  [ ALLOWED_WRITE_OPERATIONS = { NONE | ALL } ]
  [ NAMESPACE_MODE = { IGNORE_NESTED_NAMESPACE | FLATTEN_NESTED_NAMESPACE } ]
  [ NAMESPACE_FLATTEN_DELIMITER = '<string_literal>' ]
  [ SYNC_INTERVAL_SECONDS = <value> ]

Copy

必填参数¶

name

指定目录链接的数据库的标识符；对于您的账户必须是唯一的。

此外，标识符必须以字母字符开头，且不能包含空格或特殊字符，除非整个标识符字符串放在双引号内（例如，"My object"）。放在双引号内的标识符也区分大小写。

有关更多信息，请参阅标识符要求。

可选参数¶

EXTERNAL_VOLUME = my_external_vol

指定一个外部卷，用于访问远程 Iceberg 表的数据和元数据。

如果使用系统提供的凭据，则不需要。

COMMENT = 'string_literal'

指定数据库的注释。

默认：无值

CATALOG_CASE_SENSITIVITY = { CASE_SENSITIVE | CASE_INSENSITIVE }

Specifies the case sensitivity that your external Iceberg catalog uses for identifiers.

CASE_SENSITIVE: The external Iceberg catalog uses case-sensitive identifiers. For example, Snowflake Open Catalog is a case-sensitive catalog.
- Snowflake matches identifiers exactly as they appear, including case. Snowflake automatically converts unquoted identifiers to uppercase, but quoted identifiers must match exactly the case in your external catalog.
- However, if the external Iceberg catalog is actually case insensitive, and normalizes to lowercase, you must surround identifiers in double quotes.
These requirements only apply to identifying existing schemas, tables, and table columns.
CASE_INSENSITIVE: The external Iceberg catalog uses case-insensitive identifiers. For example, Unity Catalog and AWS Glue are case-insensitive catalogs.
- If the external Iceberg catalog is case insensitive and you run one of the following commands, you must surround identifiers in double quotes:
  - CREATE ICEBERG TABLE
  - CREATE SCHEMA
  - ALTER ICEBERG TABLE ADD COLUMN
  - ALTER ICEBERG TABLE RENAME COLUMN
- However, if the external Iceberg catalog is actually case sensitive, Snowflake treats unquoted identifiers as case-insensitive and automatically converts unquoted identifiers to uppercase. When you create or query objects, Snowflake matches identifiers regardless of case, as long as they are unquoted.
  
  Using this pattern is discouraged because Snowflake can't resolve two different identifiers that differ in casing. This pattern only works when no two identifiers are different in casing only.
Except where otherwise noted, these requirements only apply to identifying existing schemas, tables, and table columns.

Default: CASE_INSENSITIVE

For more information on the requirements for identifier resolution, including examples, see Requirements for identifier resolution in a catalog-linked database.

TAG ( tag_name = 'tag_value' [ , tag_name = 'tag_value' , ... ] )

指定标签名称和标签字符串值。

标签值始终为字符串，标签值的最大字符数为 256。

有关在语句中指定标签的信息，请参阅 Tag quotas。

WITH CONTACT ( purpose = contact [ , purpose = contact ...] ): Associate the new object with one or more contacts.

目录参数 (catalogParams)¶

CATALOG = catalog_int

指定您的目录集成的名称。

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 are nested under 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', ... )

（可选）在远程目录中指定一个或多个命名空间，以进行自动表发现。

Snowflake blocks the specified namespaces and all namespaces and tables that are nested under them.

如果同时指定 ALLOWED_NAMESPACES 和 BLOCKED_NAMESPACES，则 BLOCKED_NAMESPACES 列表优先。例如，如果允许 ns1.ns2 但 ns1 被屏蔽，则 Snowflake 将无法同步 ns1.ns2。

ALLOWED_WRITE_OPERATIONS = { NONE | ALL }

Specifies whether your catalog-linked database is read-only or writable.

NONE: Your catalog-linked database is read-only.

When your catalog-linked database is read only, any operation that you run that requires committing to the catalog fails. For example, DROP ICEBERG TABLE.
ALL: Your catalog-linked database is writable.

警告

When your catalog-linked database has write permissions enabled, Snowflake propagates table drops to the remote catalog, which removes the table and data from both systems.

Default: ALL

NAMESPACE_MODE = { IGNORE_NESTED_NAMESPACE | FLATTEN_NESTED_NAMESPACE }

指定 Snowflake 如何处理与目录链接的数据库中 Iceberg 表的命名空间。

IGNORE_NESTED_NAMESPACE：Snowflake 仅链接您目录的第一个命名空间级别中的表。
FLATTEN_NESTED_NAMESPACE：Snowflake 链接您目录的所有命名空间级别中的表。对于嵌套命名空间中的表，Snowflake 使用 NAMESPACE_FLATTEN_DELIMITER 参数来构建扁平化命名空间。使用此选项时，必须设置 NAMESPACE_FLATTEN_DELIMITER 参数。

例如，假设在命名空间 namespace3aa 中有一个名为 iceberg_table_5 的表：
```
my_catalog_linked_db
|-- namespace3
|   |-- namespace3a
|       |-- namespace3aa
|           |-- iceberg_table_5
```
Copy
如果设置 NAMESPACE_FLATTEN_DELIMITER = "/"，则可以指定 "my_catalog_linked_db"."namespace3/namespace3a/namespace3aa"."iceberg_table_5" 以引用该表。

默认值：IGNORE_NESTED_NAMESPACE

NAMESPACE_FLATTEN_DELIMITER = 'string_literal'

如果设置 NAMESPACE_MODE = FLATTEN_NESTED_NAMESPACE，则为必需项。指定分隔符，Snowflake 使用该分隔符为目录中的表构建扁平化命名空间。

重要

您为分隔符选择的字符无法出现在远程命名空间中。在自动发现过程中，Snowflake 会跳过任何包含分隔符的命名空间，并且不会在您的目录链接的数据库中创建相应的架构。

有效字符：Snowflake 标识符中允许的任何字符。

SYNC_INTERVAL_SECONDS = value

Specifies the time interval in seconds that Snowflake should use for automatically discovering schemas and tables in your remote catalog.

值：30 到 86400（1 天），含这两个值

默认值：30 秒

访问控制要求¶

用于执行此操作的角色必须至少具有以下权限：

权限	对象	备注
CREATE 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	外部卷	需要引用现有的外部卷。
USAGE	目录集成	需要引用现有目录集成。

权限

对象

备注

CREATE 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

外部卷

需要引用现有的外部卷。

USAGE

目录集成

需要引用现有目录集成。

有关创建具有指定权限集的自定义角色的说明，请参阅创建自定义角色。

有关对安全对象执行 SQL 操作的相应角色和权限授予的一般信息，请参阅访问控制概述。

使用说明¶

对于 ALLOWED_NAMESPACES 和 BLOCKED_NAMESPACES，如果集合已经包含父命名空间，则 Snowflake 不会存储嵌套命名空间。例如，如果您创建数据库并指定 ALLOWED_NAMESPACES = ('ns1', 'ns1.ns2', 'ns1.ns3')，Snowflake 仅存储 ns1，因为另外两个会自动包含在内。如果您在示例数据库上使用 GET_DDL，Snowflake 将返回 ALLOWED_NAMESPACES = ('ns1')。这同样适用于 BLOCKED_NAMESPACES。
查询目录链接的数据库中的表：
- Snowflake 会自动将未加引号的标识符（表名和列名）转换为大写。如果您的外部 Iceberg 目录使用区分大小写的标识符，则必须用双引号将表名和列名引起来。
  
  有关对象标识符的更多信息，请参阅标识符要求。
关于元数据：

注意

客户应确保在使用 Snowflake 服务时，不会将个人数据（用户对象除外）、敏感数据、出口管制数据或其他受监管数据作为元数据输入。有关更多信息，请参阅 Snowflake 中的元数据字段。

示例¶

Create a catalog-linked database with flattened, nested namespaces that uses an external volume.

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 DATABASE my_linked_db
  LINKED_CATALOG = (
    CATALOG = 'my_catalog_int_vended_creds',
    ALLOWED_NAMESPACES = ('my_namespace')
  );

Copy