ALTER EXTERNAL VOLUME

修改现有 :ref:` 外部卷 <label-tables_iceberg_external_volume_def>` 的属性。

另请参阅：

CREATE EXTERNAL VOLUME、DROP EXTERNAL VOLUME、SHOW EXTERNAL VOLUMES、DESCRIBE EXTERNAL VOLUME

本主题内容：

语法

ALTER EXTERNAL VOLUME [ IF EXISTS ] <name> ADD STORAGE_LOCATION =
                                             (
                                             NAME = '<storage_location_name>'
                                             cloudProviderParams
                                             )

ALTER EXTERNAL VOLUME [ IF EXISTS ] <name> REMOVE STORAGE_LOCATION '<storage_location_name>'

ALTER EXTERNAL VOLUME [ IF EXISTS ] <name> SET ALLOW_WRITES = TRUE

ALTER EXTERNAL VOLUME [ IF EXISTS ] <name> SET COMMENT = '<string_literal>'
Copy

其中：

cloudProviderParams (for Amazon S3) ::=
  STORAGE_PROVIDER = 'S3'
  STORAGE_AWS_ROLE_ARN = '<iam_role>'
  STORAGE_BASE_URL = 's3://<bucket>[/<path>/]'
  [ 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

指定要改变的外部卷的标识符。

如果标识符包含空格或特殊字符，则整个字符串必须放在双引号内。放在双引号内的标识符也区分大小写。

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

ADD STORAGE_LOCATION

将命名的存储位置添加到外部卷定义中。要添加多个存储位置，请为每个存储位置执行 ALTER EXTERNAL VOLUME 语句。

备注

Iceberg 表对集合中的第一个存储位置进行写入和读取，该集合与您的 Snowflake 账户位于同一区域。要查看外部卷定义和存储位置区域，请执行 DESCRIBE EXTERNAL VOLUME。

REMOVE STORAGE_LOCATION

从外部卷定义中移除指定的存储位置。要移除多个存储位置，请为每个存储位置执行 ALTER EXTERNAL VOLUME 语句。

备注

如果您尝试删除账户中 Iceberg 表使用的活动存储位置，ALTER EXTERNAL VOLUME 语句将失败。

SET ...

指定要为外部卷设置的一个或多个属性/参数（用空格、逗号或换行符分隔）：

ALLOW_WRITES = TRUE

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

COMMENT = 'string_literal'

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

云提供商参数 (cloudProviderParams)

Amazon S3

STORAGE_PROVIDER = 'S3'

指定存储数据文件的云存储提供商。

STORAGE_AWS_ROLE_ARN = iam_role

指定 AWS Identity and Access Management (IAM) 角色的 Amazon Resource Name (ARN)，该角色授予对包含数据文件的 S3 桶的权限。有关更多信息，请参阅 配置对 Amazon S3 的安全访问。

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

指定云存储位置的基本 URL，其中：

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

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

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 是一个可选路径，可用于提供对桶中对象的精细控制。

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://account.blob.core.windows.net/container[/path/]'

指定云存储位置的基本 URL，其中：

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

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

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

访问控制要求

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

权限

对象

备注

OWNERSHIP

外部卷

OWNERSHIP is a special privilege on an object that is automatically granted to the role that created the object, but can also be transferred using the GRANT OWNERSHIP command to a different role by the owning role (or any role with the MANAGE GRANTS privilege).

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

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

使用说明

关于元数据：

注意

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

示例

以下示例从 exvol1 外部卷中移除名为 my-us-east-1 的存储位置：

ALTER EXTERNAL VOLUME exvol1 REMOVE STORAGE_LOCATION 'my-us-east-1';
Copy

以下示例将存储位置添加到外部卷：

Amazon S3

ALTER EXTERNAL VOLUME exvol1
  ADD STORAGE_LOCATION =
    (
      NAME = 'my-s3-us-central-2'
      STORAGE_PROVIDER = 'S3'
      STORAGE_BASE_URL = 's3://my_bucket_us_central-1/'
      STORAGE_AWS_ROLE_ARN = 'arn:aws:iam::123456789012:role/myrole'
    );
Copy

Google Cloud Storage

ALTER EXTERNAL VOLUME exvol2
  ADD STORAGE_LOCATION =
    (
      NAME = 'my-gcs-europe-west4'
      STORAGE_PROVIDER = 'GCS'
      STORAGE_BASE_URL = 'gcs://my_bucket_europe-west4/'
    );
Copy

Microsoft Azure

ALTER EXTERNAL VOLUME exvol3
  ADD STORAGE_LOCATION =
    (
      NAME = 'my-azure-japaneast'
      STORAGE_PROVIDER = 'AZURE'
      STORAGE_BASE_URL = 'azure://sfcdev1.blob.core.windows.net/my_container_japaneast/'
      AZURE_TENANT_ID = 'a9876545-4321-987b-b23c-2kz436789d0'
    );
Copy
语言: 中文