CREATE EXTERNAL VOLUME¶

为账户中的 Iceberg 表创建新的外部卷或替换现有的外部卷。

另请参阅：: ALTER EXTERNAL VOLUME、DROP EXTERNAL VOLUME、SHOW EXTERNAL VOLUMES、DESCRIBE EXTERNAL VOLUME

本主题内容：

语法¶

CREATE [ OR REPLACE ] EXTERNAL VOLUME [IF NOT EXISTS]
  <name>
  STORAGE_LOCATIONS =
    (
      (
        NAME = '<storage_location_name>'
        cloudProviderParams
      )
      [, (...), ...]
    )
  [ ALLOW_WRITES = { TRUE | FALSE }]
  [ COMMENT = '<string_literal>' ]

Copy

其中：

cloudProviderParams (for Amazon S3) ::=
  STORAGE_PROVIDER = 'S3'
  STORAGE_AWS_ROLE_ARN = '<iam_role>'
  STORAGE_BASE_URL = 's3://<bucket>[/<path>/]'
  [ STORAGE_AWS_EXTERNAL_ID = '<external_id>' ]
  [ ENCRYPTION = ( [ TYPE = 'AWS_SSE_S3' ] |
              [ TYPE = 'AWS_SSE_KMS' [ KMS_KEY_ID = '<string>' ] ] |
              [ TYPE = 'NONE' ] ) ]

Copy

cloudProviderParams (for Google Cloud Storage) ::=
  STORAGE_PROVIDER = 'GCS'
  STORAGE_BASE_URL = 'gcs://<bucket>[/<path>/]'
  [ ENCRYPTION = ( [ TYPE = 'GCS_SSE_KMS' ] [ KMS_KEY_ID = '<string>' ] |
              [ TYPE = 'NONE' ] ) ]

Copy

cloudProviderParams (for Microsoft Azure) ::=
  STORAGE_PROVIDER = 'AZURE'
  AZURE_TENANT_ID = '<tenant_id>'
  STORAGE_BASE_URL = 'azure://<account>.blob.core.windows.net/<container>[/<path>/]'

Copy

必填参数¶

name

指定外部卷的标识符（名称）的字符串；在账户中必须是唯一的。

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

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

STORAGE_LOCATIONS = ( ( NAME = 'storage_location_name' cloudProviderParams ) [, (...), ...] )

不同区域和云平台（可选）中的一组命名云存储位置。

备注

创建的每个外部卷都支持单个活动存储位置。
使用 Snowflake 作为 Iceberg 目录时，目前不支持跨云和跨区域的表。

可选参数¶

ALLOW_WRITES = '{ TRUE | FALSE }'

指定是否允许对外部卷执行写操作；对于使用 Snowflake 作为目录的 Iceberg 表，必须将此参数设置为 TRUE。

此参数的值还必须与您对每个指定存储位置的云存储账户设置的权限相匹配。

默认：TRUE

COMMENT = 'string_literal'

为外部卷指定注释的字符串（字面量）。

默认：无值

云提供商参数 (`cloudProviderParams`)¶

备注

KMS 密钥由 Amazon S3 或 Google Cloud Storage 实例中的存储所有者管理。服务主体（IAM 角色和 GCS 服务账户）必须被授予使用 KMS 密钥的权限。有关更多信息，请参阅加密 Iceberg 表文件。

Amazon S3

STORAGE_PROVIDER = 'S3'
指定存储数据文件的云存储提供商。

STORAGE_AWS_ROLE_ARN = 'iam_role'
为 AWS Identity and Access Management (IAM) 角色指定区分大小写的 Amazon 资源名称 (ARN)，该角色授予对包含数据文件的 S3 桶的权限。有关更多信息，请参阅为 Amazon S3 配置外部卷。

STORAGE_BASE_URL = 's3://bucket[/path/]'
指定云存储位置的基本 URL，其中：

bucket 是存储数据文件的 S3 桶的名称。

path 是一个可选路径，可用于提供对桶中对象的精细控制。

重要

要创建使用外部目录的 Iceberg 表，Parquet 数据文件和 Iceberg 元数据文件必须在 STORAGE_BASE_URL 位置内。

STORAGE_AWS_EXTERNAL_ID = 'external_id'
（可选）指定 Snowflake 与 AWS 建立信任关系所使用的外部 ID。您必须在为此外部卷配置的 IAM 角色的信任策略中指定相同的外部 ID。有关更多信息，请参阅向第三方授予 AWS 资源访问权限时如何使用外部 ID (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html)。

如果未为此参数指定值，当您创建外部卷时 Snowflake 将自动生成外部 ID。

ENCRYPTION = ( [ TYPE = 'AWS_SSE_S3' ] | [ TYPE = 'AWS_SSE_KMS' [ KMS_KEY_ID = 'string' ] ] | [ TYPE = 'NONE' ] )
指定加密外部卷上的数据所需的属性。

TYPE = ...
指定使用的加密类型。可能的值：

'AWS_SSE_S3'：使用 S3 托管式加密密钥进行服务器端加密。有关更多信息，请参阅使用具有 Amazon S3 托管式加密密钥的服务器端加密 (SSE-S3) (https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingServerSideEncryption.html)。

'AWS_SSE_KMS'：使用 KMS 中存储的密钥进行服务器端加密。有关更多信息，请参阅使用 AWS Key Management Service 进行服务器端加密 (SSE-KMS) (https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html)。

'NONE'：无加密。

KMS_KEY_ID = 'string'`（仅适用于 :samp:`AWS_SSE_KMS 加密）
（可选）指定用于加密写入桶中的文件的 AWS KMS 托管式密钥 ID。如果未提供任何值，则使用默认 KMS 密钥加密文件以写入数据。

请注意，读取数据时将忽略此值。

Google Cloud Storage

STORAGE_PROVIDER = 'GCS'
指定存储数据文件的云存储提供商。

STORAGE_BASE_URL = 'gcs://bucket[/path/]'
指定云存储位置的基本 URL，其中：

bucket 是用于存储数据文件的云存储桶的名称。

path 是一个可选路径，可用于提供对桶中对象的精细控制。

重要

要创建使用外部目录的 Iceberg 表，Parquet 数据文件和 Iceberg 元数据文件必须在 STORAGE_BASE_URL 位置内。

ENCRYPTION = ( [ TYPE = 'GCS_SSE_KMS' ] [ KMS_KEY_ID = 'string' ] | [ TYPE = 'NONE' ] )
指定加密外部卷上的数据所需的属性。

TYPE = ...
指定使用的加密类型。可能的值：

'GCS_SSE_KMS'：使用 KMS 中存储的密钥进行服务器端加密。有关更多信息，请参阅客户管理的加密密钥 (https://cloud.google.com/storage/docs/encryption/customer-managed-keys)。

'NONE'：无加密。

KMS_KEY_ID = 'string'`（仅适用于 :code:`GCS_SSE_KMS 加密）
指定用于加密写入桶的文件的云 KMS 托管式密钥 ID。

请注意，读取数据时将忽略此值。如果服务账户对数据和任何指定的 KMS 密钥具有足够的权限，则读取操作应会成功。

Microsoft Azure

STORAGE_PROVIDER = 'AZURE'
指定存储数据文件的云存储提供商。

AZURE_TENANT_ID = 'tenant_id'
为允许和阻止的存储账户所属的 Office 365 租户指定 ID。外部卷只能对一个租户进行身份验证，因此允许和阻止的存储位置必须引用同属于此租户的存储账户。

要查找租户 ID，请登录 Azure 门户并点击 Azure Active Directory » Properties。租户 ID 将显示在 Tenant ID 字段中。

STORAGE_BASE_URL = 'azure://account.blob.core.windows.net/container[/path/]'
指定云存储位置的基本 URL，其中：

account 是 Azure 账户的名称。例如 myaccount。

container 是存储数据文件的 Azure 容器的名称。

path 是一个可选路径，可用于提供对容器中逻辑目录的精细控制。

备注

使用 azure:// 前缀，而不是 https://。

重要

要创建使用外部目录的 Iceberg 表，Parquet 数据文件和 Iceberg 元数据文件必须在 STORAGE_BASE_URL 位置内。

访问控制要求¶

用于执行此 SQL 命令的角色必须至少具有以下权限：

权限	对象	备注
CREATE EXTERNAL VOLUME	账户	Only the ACCOUNTADMIN role has this privilege by default. The privilege can be granted to additional roles as needed.

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

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

使用说明¶

重要

仅限 Amazon S3 存储中的外部卷： 如果在没有指定外部 ID 的情况下重新创建外部卷（使用 CREATE OR REPLACE EXTERNAL VOLUME 语法），则必须重复这些步骤，为 Snowflake 账户的 AWS Identity and Access Management (IAM) 用户授予 S3 存储位置所需的访问权限。有关更多信息，请参阅为 Amazon S3 配置外部卷中关于为 Snowflake 账户检索 AWS IAM 用户的说明。

如果一个或多个 Iceberg 表与外部卷关联，您无法删除或替换外部卷。

要查看依赖于外部卷的表，您可以使用 SHOW ICEBERG TABLES 命令和使用 RESULT_SCAN 对 external_volume_name 列进行筛选的查询。

备注

列标识符 (external_volume_name) 区分大小写。指定与 SHOW ICEBERG TABLES 输出中显示的完全相同的列标识符。

例如：
```
SHOW ICEBERG TABLES;

SELECT * FROM TABLE(
  RESULT_SCAN(
      LAST_QUERY_ID()
    )
  )
  WHERE "external_volume_name" = 'my_external_volume_1';
```
Copy
关于元数据：

注意

客户应确保在使用 Snowflake 服务时，不会将个人数据（用户对象除外）、敏感数据、出口管制数据或其他受监管数据作为元数据输入。有关更多信息，请参阅 Snowflake 中的元数据字段。
CREATE OR REPLACE <object> 语句是原子的。也就是说，当对象被替换时，旧对象将被删除，新对象将在单个事务中创建。

示例¶

以下示例创建外部卷，这些卷定义了不同云提供商的存储位置：

Amazon S3

以下示例创建一个外部卷，其中定义了采用加密的 Amazon S3 存储位置：

CREATE OR REPLACE EXTERNAL VOLUME exvol
  STORAGE_LOCATIONS =
      (
        (
            NAME = 'my-s3-us-west-2'
            STORAGE_PROVIDER = 'S3'
            STORAGE_BASE_URL = 's3://MY_EXAMPLE_BUCKET/'
            STORAGE_AWS_ROLE_ARN = 'arn:aws:iam::123456789012:role/myrole'
            ENCRYPTION=(TYPE='AWS_SSE_KMS' KMS_KEY_ID='1234abcd-12ab-34cd-56ef-1234567890ab')
        )
      );

Copy

Google Cloud Storage

以下示例创建一个外部卷，该卷定义了 GCS 加密存储位置：

CREATE EXTERNAL VOLUME exvol
  STORAGE_LOCATIONS =
    (
      (
        NAME = 'my-us-east-1'
        STORAGE_PROVIDER = 'GCS'
        STORAGE_BASE_URL = 'gcs://mybucket1/path1/'
        ENCRYPTION=(TYPE='GCS_SSE_KMS' KMS_KEY_ID = '1234abcd-12ab-34cd-56ef-1234567890ab')
      )
    );

Copy

Microsoft Azure

以下示例创建一个外部卷，该卷定义了采用加密的 Azure 存储位置：

CREATE EXTERNAL VOLUME exvol
  STORAGE_LOCATIONS =
    (
      (
        NAME = 'my-azure-northeurope'
        STORAGE_PROVIDER = 'AZURE'
        STORAGE_BASE_URL = 'azure://exampleacct.blob.core.windows.net/my_container_northeurope/'
        AZURE_TENANT_ID = 'a123b4c5-1234-123a-a12b-1a23b45678c9'
      )
    );

Copy

CREATE EXTERNAL VOLUME¶

语法¶

必填参数¶

可选参数¶

云提供商参数 (cloudProviderParams)¶

访问控制要求¶

使用说明¶

示例¶

云提供商参数 (`cloudProviderParams`)¶