ALTER STAGE¶

修改现有的已命名内部或外部暂存区的属性。

另请参阅：: CREATE STAGE、DROP STAGE、SHOW STAGES、DESCRIBE STAGE

语法¶

ALTER STAGE [ IF EXISTS ] <name> RENAME TO <new_name>

ALTER STAGE [ IF EXISTS ] <name> SET TAG <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]

ALTER STAGE <name> UNSET TAG <tag_name> [ , <tag_name> ... ]

-- Internal stage
ALTER STAGE [ IF EXISTS ] <name> SET
  { [ COMMENT = '<string_literal>' ] }

-- External stage
ALTER STAGE [ IF EXISTS ] <name> SET {
    [ externalStageParams ]
    [ COMMENT = '<string_literal>' ]
    }

Copy

其中：

externalStageParams (for Amazon S3) ::=
  [ URL = 's3://<bucket>[/<path>/]' ]
  [ { STORAGE_INTEGRATION = <integration_name> } | { CREDENTIALS = ( {  { AWS_KEY_ID = '<string>' AWS_SECRET_KEY = '<string>' [ AWS_TOKEN = '<string>' ] } | AWS_ROLE = '<string>'  } ) } ]
  [ ENCRYPTION = ( [ TYPE = 'AWS_CSE' ] [ MASTER_KEY = '<string>' ] |
                   [ TYPE = 'AWS_SSE_S3' ] |
                   [ TYPE = 'AWS_SSE_KMS' [ KMS_KEY_ID = '<string>' ] |
                   [ TYPE = 'NONE' ] ) ]

Copy

externalStageParams (for Google Cloud Storage) ::=
  [ URL = 'gcs://<bucket>[/<path>/]' ]
  [ STORAGE_INTEGRATION = <integration_name> } ]
  [ ENCRYPTION = ( [ TYPE = 'GCS_SSE_KMS' ] [ KMS_KEY_ID = '<string>' ] | [ TYPE = 'NONE' ] ) ]

Copy

externalStageParams (for Microsoft Azure) ::=
  [ URL = 'azure://<account>.blob.core.windows.net/<container>[/<path>/]' ]
  [ { STORAGE_INTEGRATION = <integration_name> } | { CREDENTIALS = ( [ AZURE_SAS_TOKEN = '<string>' ] ) } ]
  [ ENCRYPTION = ( [ TYPE = { 'AZURE_CSE' | 'NONE' } ] [ MASTER_KEY = '<string>' ] ) ]

Copy

目录表语法¶

ALTER STAGE [ IF EXISTS ] <name> SET DIRECTORY = ( { ENABLE = TRUE | FALSE } )

ALTER STAGE [ IF EXISTS ] <name> REFRESH [ SUBPATH = '<relative-path>' ]

Copy

参数¶

name

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

RENAME TO new_name

指定暂存区的新标识符；对于架构来说必须唯一。

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

可以将对象移动到其他数据库和/或架构，同时选择重命名对象。为此，请指定一个限定 new_name 值，该值分别以 db_name.schema_name.object_name 或 schema_name.object_name 的形式包含新数据库和/或架构名称。

备注

目标数据库和/或架构必须已存在。此外，新位置中不能存在同名对象；否则，该语句将返回错误。
除非对象所有者（即对对象拥有 OWNERSHIP 权限的角色）也拥有目标架构，否则禁止将对象移动到托管访问架构。

SET ...

指定要为暂存区设置的选项/属性：

URL = ' ... '、.STORAGE_INTEGRATION = ...、.CREDENTIALS = ( ... )、.ENCRYPTION = ( ... ): 为外部暂存区修改特定于云的 URL、存储集成或凭据，和/或加密。有关更多详细信息，请参阅 :ref:` 外部暂存区参数 <label-alter_stage_externalstageparams>` （本主题内容）。

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

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

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

有关在语句中指定标签的信息，请参阅对象和列的标签配额。

COMMENT = 'string_literal': 为暂存区添加注释或覆盖现有注释。

备注

不要使用 CREATE STAGE、ALTER STAGE、CREATE TABLE 或 ALTER TABLE 命令指定文件格式选项或复制选项。建议您使用 COPY INTO <table> 命令指定文件格式选项或复制选项。

外部暂存区参数 (`externalStageParams`)¶

URL = 'cloud_specific_url'

如果一个暂存区没有 URL，它就是一个内部暂存区

警告

修改暂存区的 URL 参数可能会中断依赖于暂存区的对象的以下功能：

利用云消息传递来触发数据加载的管道对象（即，AUTO_INGEST = TRUE）。
利用云消息传递触发元数据刷新的外部表（即，AUTO_REFRESH = TRUE）。

Amazon S3

URL = 's3://bucket[/path/]'
修改用于存储数据文件以进行加载/卸载的外部位置（现有 S3 桶）的 URL，其中：

bucket 是 S3 桶的名称。

请注意，不支持非公共 AWS 区域（如政府区域）中的 S3 桶。

path 是云存储位置中文件（即文件的名称以通用字符串开头）的可选路径（区分大小写），用于限制要加载的文件集。不同的云存储服务也可以将路径称为前缀或 文件夹。

Google Cloud Storage

URL = 'gcs://bucket[/path/]'
修改用于存储数据文件以进行加载/卸载的外部位置（现有 GCS 桶）的 URL，其中：

bucket 是 GCS 桶的名称。

path 是云存储位置中文件（即文件的名称以通用字符串开头）的可选路径（区分大小写），用于限制要加载的文件集。不同的云存储服务也可以将路径称为前缀或 文件夹。

Microsoft Azure

URL = 'azure://account.blob.core.windows.net/container[/path/]'
修改用于存储数据文件以供加载的外部位置（现有 Azure 容器）的 URL，其中：

account 是 Azure 账户的名称（例如 myaccount）。将 blob.core.windows.net 端点用于所有受支持类型的 Azure Blob 存储账户，包括 Data Lake Storage Gen2。

container 是 Azure 容器的名称（例如 mycontainer）。

path 是云存储位置中文件（即文件的名称以通用字符串开头）的可选路径（区分大小写），用于限制要加载的文件集。不同的云存储服务也可以将路径称为前缀或 文件夹。

STORAGE_INTEGRATION = integration_name 或 . CREDENTIALS = ( cloud_specific_credentials )

仅当 Amazon S3、Google Cloud Storage 或 Microsoft Azure 为专用时才需要；公共桶/容器不需要

Amazon S3

STORAGE_INTEGRATION = integration_name
指定将外部云存储的身份验证责任委托给 Snowflake Identity and Access Management (IAM) 实体的存储集成的名称。有关更多详细信息，请参阅 CREATE STORAGE INTEGRATION。

备注

我们强烈建议使用存储集成。此选项避免了在创建暂存或加载数据时使用 CREDENTIALS 参数提供云存储凭据的需要。

CREDENTIALS = ( AWS_KEY_ID = 'string' AWS_SECRET_KEY = 'string' [ AWS_TOKEN = 'string' ] ) 或 . CREDENTIALS = ( AWS_ROLE = 'string' )
修改安全凭据，这些凭据用于连接到 AWS，以及访问暂存要加载/卸载文件的专用 S3 桶。有关更多信息，请参阅配置对 Amazon S3 的安全访问。

您指定的凭证取决于您是否将桶的 Snowflake 访问权限与 AWS IAM (Identity & Access Management) 用户或角色关联：

IAM ** 用户： ** IAM 凭据是必需的。临时（又名“作用域”）凭据由 AWS Security Token Service (STS) 生成，由三个组件组成：

AWS_KEY_ID

AWS_SECRET_KEY

AWS_TOKEN

访问专用桶需要这三个组件。指定时间段后，临时凭证将过期，无法再使用。然后，您必须生成一组新的有效临时凭据。

重要

COPY 命令还允许使用永久（又名“长期”）凭据；但是，出于安全原因，Snowflake 不建议使用它们。如果必须使用永久凭据，Snowflake 建议定期为外部暂存区生成新的永久凭据。

IAM 角色： 省略安全凭证和访问密钥，而是使用 AWS_ROLE 并指定 AWS 角色 ARN (Amazon Resource Name) 来标识角色。

重要

使用 AWS IAM 角色访问私有 S3 桶以加载或卸载数据的功能现已弃用（即在未来版本中将删除支持，TBD）。我们强烈建议修改使用此功能的任何现有 S3 暂存区，改为引用存储集成对象。有关说明，请参阅选项 1：配置 Snowflake 存储集成以访问 Amazon S3。

Google Cloud Storage

STORAGE_INTEGRATION = integration_name
指定将外部云存储的身份验证责任委托给 Snowflake Identity and Access Management (IAM) 实体的存储集成的名称。有关更多详细信息，请参阅 CREATE STORAGE INTEGRATION。

Microsoft Azure

STORAGE_INTEGRATION = integration_name
指定将外部云存储的身份验证责任委托给 Snowflake Identity and Access Management (IAM) 实体的存储集成的名称。有关更多详细信息，请参阅 CREATE STORAGE INTEGRATION。

备注

我们强烈建议使用存储集成。此选项避免了在创建暂存或加载数据时使用 CREDENTIALS 参数提供云存储凭据的需要。

CREDENTIALS = ( AZURE_SAS_TOKEN = 'string' )
修改 SAS（共享访问签名）令牌，它们用于连接到 Azure，以及访问暂存包含已加载数据的文件的专用容器。凭据由 Azure 生成。

ENCRYPTION = ( cloud_specific_encryption )

仅从加密文件加载/卸载时需要；如果存储位置和文件未加密，则不需要

数据加载:: 修改用于解密存储位置中的加密文件和提取数据的加密设置。
数据卸载:: 修改用于加密卸载到存储位置的文件的加密设置。

Amazon S3

ENCRYPTION = ( [ TYPE = 'AWS_CSE' ] [ MASTER_KEY = '<string>' ] | [ TYPE = 'AWS_SSE_S3' ] | [ TYPE = 'AWS_SSE_KMS' ] [ KMS_KEY_ID = '<string>' ] | [ TYPE = 'NONE' ] )

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

AWS_CSE：客户端加密（需要一个 MASTER_KEY 值）。目前，您提供的客户端 ` 主密钥 <https://csrc.nist.gov/glossary/term/master_key (https://csrc.nist.gov/glossary/term/master_key)>`_ 只能是对称密钥。请注意，当提供 MASTER_KEY 值时，Snowflake 假定 TYPE = AWS_CSE （即，当提供 MASTER_KEY 值时，不需要 TYPE）。

AWS_SSE_S3：不需要其他加密设置的服务器端加密。

AWS_SSE_KMS：接受可选的 KMS_KEY_ID 值服务端加密。

有关加密类型的详细信息，请参阅客户端加密 (http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingClientSideEncryption.html) 或 ` 服务器端加密 <http://docs.aws.amazon.com/AmazonS3/latest/dev/serv-side-encryption.html (http://docs.aws.amazon.com/AmazonS3/latest/dev/serv-side-encryption.html)>`_ 的 AWS 文档。

NONE：无加密。

MASTER_KEY = 'string' （仅适用于 AWS_CSE 加密）
指定用于加密桶中文件的客户端主密钥。主密钥必须是 Base64 编码形式的 128 位或 256 位密钥。

KMS_KEY_ID = 'string' （仅适用于 AWS_SSE_KMS 加密）
（可选）指定用于加密卸载到桶中的文件的 AWS KMS 托管密钥的 ID。如果未提供任何值，则默认 KMS 密钥 ID 用于在卸载时加密文件。

请注意，数据加载时会忽略此值。

Google Cloud Storage

ENCRYPTION = ( [ TYPE = 'GCS_SSE_KMS' | 'NONE' ] [ KMS_KEY_ID = 'string' ] )

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

GCS_SSE_KMS：接受可选的 KMS_KEY_ID 值服务端加密。

有关更多信息，请参阅 Google Cloud Platform 文档：

https://cloud.google.com/storage/docs/encryption/customer-managed-keys (https://cloud.google.com/storage/docs/encryption/customer-managed-keys)

https://cloud.google.com/storage/docs/encryption/using-customer-managed-keys (https://cloud.google.com/storage/docs/encryption/using-customer-managed-keys)

NONE：无加密。

KMS_KEY_ID = 'string' （仅适用于 GCS_SSE_KMS 加密）
（可选）指定用于加密卸载到桶中的文件的 Cloud KMS 托管密钥的 ID。如果未提供任何值，则桶中默认设置的 KMS 密钥 ID 用于在卸载时加密文件。

请注意，数据加载时会忽略此值。如果服务账户有足够的权限来解密桶中的数据，则加载操作应会成功。

Microsoft Azure

ENCRYPTION = ( [ TYPE = 'AZURE_CSE' | 'NONE' ] [ MASTER_KEY = 'string' ] )

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

AZURE_CSE：客户端加密（需要一个 MASTER_KEY 值）。有关信息，请参阅 Microsoft Azure 文档中的 ` 客户端加密信息 <https://docs.microsoft.com/en-us/azure/storage/common/storage-client-side-encryption (https://docs.microsoft.com/en-us/azure/storage/common/storage-client-side-encryption)>`_。

NONE：无加密。

MASTER_KEY = 'string' （仅适用于 AZURE_CSE 加密）
指定用于加密或解密文件的客户端主密钥。主密钥必须是 Base64 编码形式的 128 位或 256 位密钥。

目录表参数¶

ENABLE = TRUE | FALSE

指定是否向暂存区添加目录表。当值为 TRUE 时，将向暂存区添加目录表。

备注

与 S3 兼容的外部暂存区不支持将此参数设置为 TRUE。无法自动刷新与 S3 兼容的外部暂存区的元数据。

默认：FALSE

REFRESH

访问目录表定义中引用的暂存数据文件并更新表元数据：

路径中的新文件将添加到表元数据中。
对路径中文件的更改将在表元数据中更新。
路径中不再存在的文件将从表元数据中移除。

您可以在每次将文件添加到暂存区、更新或删除文件时执行此命令。此步骤将元数据与目录表的暂存区定义中的最新关联文件集同步。

SUBPATH = '<relative-path>'

（可选）指定相对路径以刷新数据文件的特定子集的元数据。

访问控制要求¶

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

权限	对象	备注
OWNERSHIP	暂存区	在更改暂存区属性以及使用以下语法在暂存区上启用或禁用目录目录表时必需：ALTER STAGE ...SET DIRECTORY。 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).
WRITE	暂存区	在使用以下语法刷新元数据时必需：ALTER STAGE ...REFRESH。

权限

对象

备注

OWNERSHIP

暂存区

在更改暂存区属性以及使用以下语法在暂存区上启用或禁用目录目录表时必需：ALTER STAGE ...SET DIRECTORY。

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).

WRITE

暂存区

在使用以下语法刷新元数据时必需：ALTER STAGE ...REFRESH。

请注意，对架构中的对象进行操作还需要对父数据库和架构具有 USAGE 权限。

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

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

使用说明¶

关于元数据：

注意

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

示例¶

将 my_int_stage 重命名为 new_int_stage：

ALTER STAGE my_int_stage RENAME TO new_int_stage;

Copy

更改 my_ext_stage`（在“:doc:`create-stage”示例中创建的），以将 URL 更改为引用 files 文件夹中名为 new 的子文件夹。如果引用此暂存区的 COPY INTO <table> 命令在任何记录上遇到数据错误，将跳过该文件。所有其他复制选项都设置为默认值：

ALTER STAGE my_ext_stage
SET URL='s3://loading/files/new/'
COPY_OPTIONS = (ON_ERROR='skip_file');

Copy

更改 my_ext_stage，以将提供的凭据替换为对名为 myint 的存储集成的引用：

ALTER STAGE my_ext_stage SET STORAGE_INTEGRATION = myint;

Copy

更改 my_ext_stage 以指定暂存区的新访问密钥 ID 和秘密访问密钥：

ALTER STAGE my_ext_stage SET CREDENTIALS=(AWS_KEY_ID='d4c3b2a1' AWS_SECRET_KEY='z9y8x7w6');
Copy
（上述示例中使用的凭据值仅用于说明目的）

更改 my_ext_stage3 以将暂存区的加密类型更改为 AWS_SSE_S3 服务器端加密：

ALTER STAGE my_ext_stage3 SET ENCRYPTION=(TYPE='AWS_SSE_S3');

Copy

目录表示例¶

将一个目录表添加到一个名为 mystage 的现有暂存区：

ALTER STAGE mystage SET DIRECTORY = ( ENABLE = TRUE );

Copy

在名为 mystage 的暂存区中手动刷新目录表元数据：

ALTER STAGE mystage REFRESH;

+-------------------------+----------------+-------------------------------+
| file                    | status         | description                   |
|-------------------------+----------------+-------------------------------|
| data/json/myfile.json   | REGISTERED_NEW | File registered successfully. |
+-------------------------+----------------+-------------------------------+

Copy

在名为 mystage 的暂存区中手动刷新 data 路径中文件的目录表元数据：

ALTER STAGE mystage REFRESH SUBPATH = 'data';

Copy

ALTER STAGE¶

语法¶

目录表语法¶

参数¶

外部暂存区参数 (externalStageParams)¶

目录表参数¶

访问控制要求¶

使用说明¶

示例¶

目录表示例¶

外部暂存区参数 (`externalStageParams`)¶