ALTER WAREHOUSE¶

语法¶

ALTER WAREHOUSE [ IF EXISTS ] [ <name> ] { SUSPEND | RESUME [ IF SUSPENDED ] }

ALTER WAREHOUSE [ IF EXISTS ] [ <name> ] ABORT ALL QUERIES

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

ALTER WAREHOUSE [ IF EXISTS ] <name> SET [ objectProperties ]
                                         [ objectParams ]

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

ALTER WAREHOUSE [ IF EXISTS ] <name> UNSET TAG <tag_name> [ , <tag_name> ... ]

ALTER WAREHOUSE [ IF EXISTS ] <name> UNSET { <property_name> | <param_name> } [ , ... ]

其中：

objectProperties ::=
  WAREHOUSE_TYPE = { STANDARD | 'SNOWPARK-OPTIMIZED' }
  WAREHOUSE_SIZE = { XSMALL | SMALL | MEDIUM | LARGE | XLARGE | XXLARGE | XXXLARGE | X4LARGE | X5LARGE | X6LARGE }
  WAIT_FOR_COMPLETION = { TRUE | FALSE }
  MAX_CLUSTER_COUNT = <num>
  MIN_CLUSTER_COUNT = <num>
  SCALING_POLICY = { STANDARD | ECONOMY }
  AUTO_SUSPEND = { <num> | NULL }
  AUTO_RESUME = { TRUE | FALSE }
  RESOURCE_MONITOR = <monitor_name>
  COMMENT = '<string_literal>'
  ENABLE_QUERY_ACCELERATION = { TRUE | FALSE }
  QUERY_ACCELERATION_MAX_SCALE_FACTOR = <num>

Copy

objectParams ::=
  MAX_CONCURRENCY_LEVEL = <num>
  STATEMENT_QUEUED_TIMEOUT_IN_SECONDS = <num>
  STATEMENT_TIMEOUT_IN_SECONDS = <num>

Copy

属性/参数¶

name

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

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

备注

仓库标识符可能是必需的，也可能是可选的，具体取决于以下因素：

• 恢复/暂停仓库或中止对仓库的查询时，如果当前正在为会话使用仓库，则可以忽略标识符。

• 重命名仓库或对仓库执行任何其他操作时，必须 指定标识符。

{ SUSPEND | RESUME [ IF SUSPENDED ] }

指定要对仓库执行的操作：

• SUSPEND 从仓库中移除所有计算节点，并将该仓库置于“暂停”状态。

• RESUME [ IF SUSPENDED ] 会预配计算资源，从而将暂停的仓库置于可用的“正在运行”状态。

  可选的 IF SUSPENDED 子句指定在恢复已在运行的仓库时，ALTER WAREHOUSE 命令是否成功完成：

  • 如果忽略，并且仓库已在运行，则该命令失败，并返回错误。

  • 如果指定，则无论仓库是否在运行，该命令都会成功完成。

ABORT ALL QUERIES

中止仓库上当前正在运行或排队的所有查询。

RENAME TO new_name

指定仓库的新标识符；对于您的账户必须唯一。

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

SET ...

指定要为仓库设置的一个或多个属性/参数（用空格、逗号或新行分隔）：

WAREHOUSE_TYPE = { STANDARD | 'SNOWPARK-OPTIMIZED' }

指定仓库类型。

有效值:

• STANDARD、'STANDARD'

• 'SNOWPARK-OPTIMIZED'

默认值:

STANDARD

备注

要使用包含连字符的值 ('SNOWPARK-OPTIMIZED')，则必须将值放在单引号内，如下所示。

WAREHOUSE_SIZE = string_constant

指定虚拟仓库的大小。大小决定了每个集群中的计算资源量，因此决定了仓库在运行的时候使用的 Credit。

有关更多信息，请参阅 调整仓库大小。

有效值:

• XSMALL、'X-SMALL'

• SMALL

• MEDIUM

• LARGE

• XLARGE、'X-LARGE'

• XXLARGE、X2LARGE、'2X-LARGE'

• XXXLARGE、X3LARGE、'3X-LARGE'

• X4LARGE、'4X-LARGE'

• X5LARGE、'5X-LARGE'

• X6LARGE、'6X-LARGE'

默认值:

XLARGE

备注

• XSMALL、SMALL、X5LARGE 和 X6LARGE 大小不支持 Snowpark-Optimized Warehouses。Snowpark-Optimized Warehouses 的默认大小为 MEDIUM。

• 要使用包含连字符的值（例如 '2X-LARGE'），则必须将值放在单引号内，如下所示。

• 若要阻止 ALTER WAREHOUSE 命令立即返回，使其等到大小调整完成再返回，请添加 WAIT_FOR_COMPLETION 参数。

WAIT_FOR_COMPLETION = { TRUE | FALSE }

调整仓库大小时，可以使用此参数阻止 ALTER WAREHOUSE 命令返回，使其等到大小调整完所有计算资源的预配后再返回。如将仓库调整到较大的大小，阻止返回命令可让您了解，计算资源已完全预配完毕，并且仓库已准备好使用所有新资源执行查询。

有效值:

• TRUE：ALTER WAREHOUSE 命令将阻塞，直至仓库大小调整完成。

• FALSE：在仓库大小调整完成之前，ALTER WAREHOUSE 会立即返回。

默认值:

FALSE

备注

• 该参数的值不会持久保留，如果您希望在此命令返回之前完成仓库大小调整，则必须在每次执行时将此参数设置为 TRUE。

• 如果设置为 TRUE，并且您中止了 ALTER WAREHOUSE 命令，则仅中止等待，仓库大小调整将继续执行至完成。若要将仓库调整回其原始大小，需要执行另一个 ALTER WAREHOUSE 命令。

• 此参数必须与 WAREHOUSE_SIZE 参数配合使用，否则将引发异常。

MAX_CLUSTER_COUNT = num

指定多集群仓库的最大集群数。对于单集群仓库，此值始终为 1。

有效值:

1 至 10

请注意，指定大于 1 的值，表示仓库是多集群仓库；但是，只有在 Snowflake Enterprise Edition （或更高）中设置更高值。

有关更多信息，请参阅 多集群仓库。

默认值:

``1``（单集群仓库）

小技巧

对于 Snowflake Enterprise Edition（或更高版本），我们建议始终将此值设置为大于 1 的值，以帮助维护（多集群）仓库的高可用性和最佳性能。这也有助于确保在集群发生故障时（虽然较为少见）保持连续性。

MIN_CLUSTER_COUNT = num

为多集群仓库指定最小集群数。

有效值:

1 至 10

但请注意，MIN_CLUSTER_COUNT 必须小于或等于 MAX_CLUSTER_COUNT：

• 如果两个参数相等，则仓库以 最大化 模式运行。

• 如果 MIN_CLUSTER_COUNT 小于 MAX_CLUSTER_COUNT，则仓库在 自动扩展 模式下运行。

有关更多信息，请参阅 多集群仓库。

默认值:

1

SCALING_POLICY = { STANDARD | ECONOMY }

对象参数，用于指定在自动扩展模式下运行的多集群仓库中自动启动和关闭集群的策略。

有关此参数的详细说明，请参阅 为多集群仓库设置扩展策略。

AUTO_SUSPEND = { num | NULL }

指定仓库在处于不活动状态多少秒之后自动暂停。

有效值:

0 或更大的任意整数，或者 NULL：

• 暂停仓库的后台进程大约每 30 秒运行一次，因此，此属性的设置不是为了启用对仓库暂停的精确控制。

• 虽然允许设置小于 30 的值或不是 30 的倍数的值，但由于仓库暂停的轮询间隔为 30 秒，可能不会产生预期的行为。

• 设置 0 或 NULL 值表示仓库永不暂停。

默认值:

``600``（仓库处于不活动状态 10 分钟后自动暂停）

重要

不 建议将 AUTO_SUSPEND 设置为 0 或 NULL，除非查询工作负载需要持续运行的仓库。请注意，这可能会导致使用大量 Credit（并相应地产生高额的费用），尤其是对于较大的仓库。

有关更多详细信息，请参阅 仓库注意事项。

AUTO_RESUME = { TRUE | FALSE }

指定在向仓库提交 SQL 语句（例如，查询）时，是否自动恢复仓库。如果为 FALSE，则仅当使用 ALTER WAREHOUSE 或通过 Snowflake Web 界面显式恢复时，仓库才会再次启动。

有效值:

• TRUE：在提交新查询时，仓库将恢复。

• FALSE：仅当使用 ALTER WAREHOUSE 或通过 Snowflake Web 界面显式恢复时，仓库才会恢复。

默认值:

:code:`TRUE`（向仓库提交 SQL 语句时，仓库会自动恢复）

INITIALLY_SUSPENDED = { TRUE | FALSE }

在更改仓库时不适用

RESOURCE_MONITOR = monitor_name

指定显式分配给仓库的资源监视器的标识符。显式将资源监视器分配给仓库时，监视器将控制仓库（以及该监视器分配到的所有其他仓库）使用的每月 Credit。

有效值:

任何现有资源监视器。

有关更多详细信息，请参阅 使用资源监视器。

默认值:

无值（未为仓库分配任何资源监视器）

小技巧

要查看所有资源监视器及其标识符，请使用 SHOW RESOURCE MONITORS 命令。

COMMENT = 'string_literal'

添加注释或覆盖仓库的现有注释。

MAX_CONCURRENCY_LEVEL = num

对象参数，用于指定仓库集群执行的 SQL 语句（即查询和 DML）的并发级别。在达到该级别时：

• 对于单集群仓库或多集群仓库（在最大化模式下），其他语句将排队，直至有资源可用。

• 对于多集群仓库（在自动扩展模式下），将启动其他集群。

此参数可以与 STATEMENT_QUEUED_TIMEOUT_IN_SECONDS 结合使用，以确保仓库永远不会积压。

有关此参数的详细说明，请参阅 MAX_CONCURRENCY_LEVEL。

STATEMENT_QUEUED_TIMEOUT_IN_SECONDS = num

对象参数，该参数指定在系统取消 SQL 语句（查询、DDL、DML 等）之前，语句可在仓库中排队的时间量（以秒为单位）。

此参数可以与 MAX_CONCURRENCY_LEVEL 结合使用，以确保仓库永远不会积压。

有关此参数的详细说明，请参阅 STATEMENT_QUEUED_TIMEOUT_IN_SECONDS。

STATEMENT_TIMEOUT_IN_SECONDS = num

对象参数，指定系统在多久（以秒为单位）后取消运行中的 SQL 语句（查询、DDL、DML 等）。

有关此参数的详细说明，请参阅 STATEMENT_TIMEOUT_IN_SECONDS。

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

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

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

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

ENABLE_QUERY_ACCELERATION = { TRUE | FALSE }

指定是否为依赖此仓库获取计算资源的查询启用 Query Acceleration Service。

Enterprise Edition 功能

Query Acceleration Service 需要 Enterprise Edition（或更高版本）。如需咨询升级事宜，请联系 Snowflake 支持部门 (https://community.snowflake.com/s/article/How-To-Submit-a-Support-Case-in-Snowflake-Lodge)。

有效值:

• TRUE 启用查询加速

• FALSE 禁用查询加速

默认值:

FALSE：查询加速已禁用

QUERY_ACCELERATION_MAX_SCALE_FACTOR = num

指定租用计算资源以加速查询的最大扩展系数。 扩展系数用作基于 仓库大小 的乘数。

将 QUERY_ACCELERATION_MAX_SCALE_FACTOR 设置为 0 可以消除限制，并允许查询根据需要租用尽可能多的资源来为查询提供服务。

无论 QUERY_ACCELERATION_MAX_SCALE_FACTOR 值如何，用于加速查询的可用计算资源量都受服务中可用的资源和其他并发请求的数量的约束。有关更多详细信息，请参阅 调整比例因子。

有效值:

0 至 100

默认值:

8

UNSET ...

指定要为数据库取消设置的一个（或多个）属性和/或参数，这会将它们重置为默认值：

• property_name

• param_name

  • TAG tag_name [ , tag_name ... ]

您可以使用单个 ALTER 语句重置多个属性/参数；但是，每个属性/参数 必须 用逗号分隔。此外，在重置属性/参数时，仅指定名称；无需指定任何值。

备注

UNSET 可用于取消设置仓库的所有属性和参数，但 WAREHOUSE_SIZE 除外，后者只能使用 SET 更改。

访问控制要求¶

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

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

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

使用说明¶

• 仓库 不需要 暂停即可设置或更改其任何属性（类型除外）。

• 若要更改仓库类型，仓库必须处于 suspended 状态。执行以下语句以暂停仓库：

  ALTER WAREHOUSE mywh SUSPEND;
  

  Copy

• 在更改仓库大小时，更改不会影响到当前正在执行的任何语句（包括查询）。在语句完成、计算资源完全预配之后，所有后续语句都会使用新的大小。

• 暂停仓库 不会 中止仓库在暂停时正在处理的任何查询。相反，仓库会完成此类查询，然后关停用于处理查询的计算资源。在此期间，仓库处于 静默 模式。在所有计算资源均关停时，仓库的状态将变为暂停。

• 关于元数据：

  注意

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

• 恢复 Snowpark 优化型虚拟仓库所需时间可能比标准仓库更长。

• Snowpark-Optimized Warehouses 不支持 查询加速。

• Snowpark-Optimized Warehouses 不支持 XSMall、SMALL、X5LARGE 或 X6LARGE 仓库大小。

• 指定 IF EXISTS 子句要求正在使用的角色或活动角色层次结构中的角色具有仓库的适当 仓库权限。

示例¶

将仓库 wh1 重命名为 wh2：

ALTER WAREHOUSE IF EXISTS wh1 RENAME TO wh2;

Copy

恢复名为 my_wh 的仓库，然后在仓库运行的过程中更改仓库的大小：

ALTER WAREHOUSE my_wh RESUME;

ALTER WAREHOUSE my_wh SET warehouse_size=MEDIUM;

Copy