CREATE EXTERNAL VOLUME¶

为账户中的 Apache 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 | s3CompatibleStorageParams }
      )
      [, (...), ...]
    )
  [ ALLOW_WRITES = { TRUE | FALSE }]
  [ COMMENT = '<string_literal>' ]

Copy

其中：

cloudProviderParams (for Amazon S3) ::=
  STORAGE_PROVIDER = '{ S3 | S3GOV }'
  STORAGE_AWS_ROLE_ARN = '<iam_role>'
  STORAGE_BASE_URL = '<protocol>://<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://...'
  [ USE_PRIVATELINK_ENDPOINT = { TRUE | FALSE } ]

Copy

s3CompatibleStorageParams ::=
  STORAGE_PROVIDER = 'S3COMPAT'
  STORAGE_BASE_URL = 's3compat://<bucket>[/<path>/]'
  CREDENTIALS = ( AWS_KEY_ID = '<string>' AWS_SECRET_KEY = '<string>' )
  STORAGE_ENDPOINT = '<s3_api_compatible_endpoint>'

Copy

必填参数¶

name

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

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

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

STORAGE_LOCATIONS = ( ( NAME = 'storage_location_name' { cloudProviderParams | s3CompatibleStorageParams } ) [, (...), ...] )

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

备注

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

可选参数¶

ALLOW_WRITES = '{ TRUE | FALSE }'

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

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

备注

如果计划将外部卷用于外部管理的 Iceberg 表，则可以将此参数设置为 FALSE。当使用外部 Iceberg 目录时，Snowflake 不会将数据或 Iceberg 元数据文件写入云存储。

默认：TRUE

COMMENT = 'string_literal'

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

默认：无值

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

备注

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

Amazon S3

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

'S3'：中国境外公共 AWS 区域的 S3 存储。

'S3GOV'：AWS 政府区域中的 S3 存储。

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

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

protocol 是以下其中一项：

s3 是指中国境外公共 AWS 区域的 S3 存储。

s3gov 代表政府区域中的 S3 存储。

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 (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 (https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html)>`_。

'NONE'：无加密。

KMS_KEY_ID = 'string' （仅适用于 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 (https://cloud.google.com/storage/docs/encryption/customer-managed-keys)>`_。

'NONE'：无加密。

KMS_KEY_ID = 'string' （仅适用于 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://...'
指定云存储位置的基本 URL（区分大小写）。

对于 Azure BLOB 存储，请指定 azure://account.blob.core.windows.net/container[/path/]，其中：

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

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

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

对于 Fabric OneLake, 请指定 azure://[region-]onelake.dfs | blob.fabric.microsoft.com/workspace/lakehouse/Files/path/，其中：

region 可选择指定端点区域；例如 westus。如果指定，则必须与 Microsoft Fabric 容量使用的区域相同，并且与 Snowflake 账户的托管区域相同。

dfs | blob 指定端点类型。

workspace 是 Fabric 工作区 ID 或工作区名称；例如 cfafbeb1-8037-4d0c-896e-a46fb27ff227 或 my_workspace。您必须为工作区和 Lakehouse 使用相同类型的标识符（ID 或名称）。

lakehouse 为 Lakehouse ID 或 Lakehouse 名称。您必须为工作区和 Lakehouse 使用相同类型的标识符（ID 或名称），例如 5b218778-e7a5-4d73-8187-f10824047715 或 my_lakehouse.Lakehouse。

path 是指定的 Lakehouse 和工作区中存储位置的路径。

预览版功能 – 开放

适用于所有账户。

备注

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

重要

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

USE_PRIVATELINK_ENDPOINT = { TRUE | FALSE }
指定是否使用出站专用连接。有关使用此参数的信息，请参阅 Microsoft Azure 外部存储卷的专用连接。

兼容 S3 的存储参数 (`s3CompatibleStorageParams`)¶

STORAGE_PROVIDER = 'S3COMPAT'

将兼容 S3 的存储指定为存储提供商。

STORAGE_BASE_URL = 's3compat://bucket[/path/]'

指定用于存储数据文件的外部位置（使用兼容 S3 API 端点访问的现有桶）的 URL，其中：

bucket 是桶的名称。
path 是一个可选的、区分大小写的路径（在 S3 术语中称为前缀），用于云存储位置中的文件（名称以通用字符串开头的文件）。

CREDENTIALS = ( AWS_KEY_ID = 'string' AWS_SECRET_KEY = 'string' )

指定用于连接和访问兼容 S3 的存储位置的安全凭据。

STORAGE_ENDPOINT = 's3_api_compatible_endpoint'

指定指向兼容 S3 的 API 端点的完全限定域名。

备注

存储端点不应包括桶名；例如，指定 mystorage.com，而不是 my_bucket.mystorage.com。

访问控制要求¶

用于执行此 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
如果您使用 Microsoft Fabric OneLake 存储位置的区域端点，请使用与 Microsoft Fabric 容量相同的区域。这也必须是托管您的 Snowflake 账户的同一区域。
关于元数据：

注意

客户应确保在使用 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

兼容 S3 的存储

创建一个外部卷，以定义一个兼容 S3 的存储位置。有关更多信息，请参阅为 S3 兼容存储配置外部卷。

CREATE OR REPLACE EXTERNAL VOLUME ext_vol_s3_compat
  STORAGE_LOCATIONS = (
    (
      NAME = 'my_s3_compat_storage_location'
      STORAGE_PROVIDER = 'S3COMPAT'
      STORAGE_BASE_URL = 's3compat://mybucket/unload/mys3compatdata'
      CREDENTIALS = (
        AWS_KEY_ID = '1a2b3c...'
        AWS_SECRET_KEY = '4x5y6z...'
      )
      STORAGE_ENDPOINT = 'mystorage.com'
    )
  )
  ALLOW_WRITES = FALSE;

Copy

CREATE EXTERNAL VOLUME¶

语法¶

必填参数¶

可选参数¶

云提供商参数 (cloudProviderParams)¶

兼容 S3 的存储参数 (s3CompatibleStorageParams)¶

访问控制要求¶

使用说明¶

示例¶

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

兼容 S3 的存储参数 (`s3CompatibleStorageParams`)¶