ALTER TASK

修改现有任务的属性。

另请参阅：

CREATE TASK、DROP TASK、SHOW TASKS、DESCRIBE TASK

语法

ALTER TASK [ IF EXISTS ] <name> RESUME | SUSPEND

ALTER TASK [ IF EXISTS ] <name> REMOVE AFTER <string> [ , <string> , ... ] | ADD AFTER <string> [ , <string> , ... ]

ALTER TASK [ IF EXISTS ] <name> SET
  [ { WAREHOUSE = <string> } | { USER_TASK_MANAGED_INITIAL_WAREHOUSE_SIZE = <string> } ]
  [ SCHEDULE = '{ <number> MINUTE | USING CRON <expr> <time_zone> }' ]
  [ CONFIG = <configuration_string> ]
  [ ALLOW_OVERLAPPING_EXECUTION = TRUE | FALSE ]
  [ USER_TASK_TIMEOUT_MS = <num> ]
  [ SUSPEND_TASK_AFTER_NUM_FAILURES = <num> ]
  [ ERROR_INTEGRATION = <integration_name> ]
  [ COMMENT = <string> ]
  [ <session_parameter> = <value> [ , <session_parameter> = <value> ... ] ]
  [ TASK_AUTO_RETRY_ATTEMPTS = <num> ]

ALTER TASK [ IF EXISTS ] <name> UNSET
  [ WAREHOUSE ]
  [ SCHEDULE ]
  [ CONFIG ]
  [ ALLOW_OVERLAPPING_EXECUTION ]
  [ USER_TASK_TIMEOUT_MS ]
  [ SUSPEND_TASK_AFTER_NUM_FAILURES ]
  [ COMMENT ]
  [ <session_parameter> [ , <session_parameter> ... ] ]
  [ , ... ]

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

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

ALTER TASK [ IF EXISTS ] <name> SET FINALIZE = <string>

ALTER TASK [ IF EXISTS ] <name> UNSET FINALIZE

ALTER TASK [ IF EXISTS ] <name> MODIFY AS <sql>

ALTER TASK [ IF EXISTS ] <name> MODIFY WHEN <boolean_expr>
Copy

参数

name

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

RESUME | SUSPEND

指定要对任务执行的操作：

  • RESUME 会将暂停的任务置于“Started”状态。请注意，账户目前最多可有 30000 个已启动的任务。

    在恢复任务图的根任务之前，请先恢复所有子任务。要以递归方式恢复根任务的子任务，请使用 SYSTEM$TASK_DEPENDENTS_ENABLE。

  • SUSPEND 将任务置于“已暂停”状态。

如果按照间隔 (number MINUTE) 设置任务计划，则计划的 基本间隔时间 将重置为恢复任务时的当前时间。

基本间隔时间从当前时钟时间开始间隔计数器。例如，如果将 INTERVAL 值设置为 10，并且在 9:03 AM 恢复任务，则任务将在 9:13 AM、9:23 AM 运行，以此类推。请注意，我们仅保证任务不会在设置的间隔出现 之前 执行。在当前示例中，任务可以首先在 9:14 AM 运行，但不会在 9:12 AM 运行。

REMOVE AFTER string [ , string , ... ]

为 任务图 中的此子任务，指定一个或多个当前前置任务的名称。

如果移除某个子任务的所有前置任务，则这个旧子任务将变为独立任务或根任务，具体取决于其他任务是否将这个旧子任务标识为其前置任务。如果旧子任务成为根任务，则默认情况下此任务处于暂停状态，必须手动恢复。

ADD AFTER string [ , string , ... ]

指定一个或多个现有任务的名称，以添加为 任务图 中此子任务的前置任务。当所有前置任务都成功完成运行时，任务图中的每个子任务才会运行。有关更多信息，请参阅 CREATE TASK 中 AFTER 参数的描述。

每个子任务最多有 100 个前置任务。

SET ...

指定以下一项或两项：

  • 要为任务设置的一个（或多个）属性（用空格、逗号或换行符分隔）。有关可设置的属性的更多详细信息，请参阅 CREATE TASK。

  • 任务运行时要为会话设置的会话参数列表（以逗号分隔）。任务支持所有会话参数。有关完整列表，请参阅 参数。

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

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

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

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

UNSET ...

指定要为任务取消设置的一个（或多个）属性和/或会话参数，这会将其重置为默认值。

您可以使用单个 ALTER 语句重置多个属性/参数；但是，每个属性/参数 必须 用逗号分隔。重置属性/参数时，请仅指定名称；指定属性/参数的值将返回错误。

sql

指定任务运行时要执行的 SQL 代码：

  • 单一 SQL 语句

  • 调用存储过程

  • 使用 Snowflake Scripting 的过程逻辑

    请注意，目前 Snowsight 和 Classic Console 不支持创建或修改任务以使用 Snowflake Scripting。请改用 SnowSQL 或其他命令行客户端。

备注

在创建任务 之前，请验证您在任务中引用的 SQL 代码是否按预期执行。任务旨在自动执行已经过全面测试的 SQL 代码。

WHEN boolean_expr

指定布尔 SQL 表达式。当任务被触发时（基于其 SCHEDULE 或 AFTER 设置），它会验证表达式的条件以确定是否执行。如果` 不 :emph:`满足表达式的条件，则任务跳过当前运行。将此任务标识为前置任务的任何任务都不会运行。

要验证 WHEN 表达式的条件，不需要虚拟仓库。验证改为在云服务层中处理。每次任务评估其 WHEN 条件且未运行时，都会产生象征性费用。每次触发任务时，费用都会累积，直到任务运行为止。届时，费用将转换为 Snowflake Credit，并添加到任务运行的计算资源使用量中。

通常，与任务执行时间相比，用于验证条件的计算时间微不足道。最佳实践是，尽可能使计划的任务运行时间和实际的任务运行时间保持一致。避免与实际任务运行严重不同步的任务计划。例如，如果大约每 24 小时将数据插入具有流的表中一次，则不要安排每分钟检查一次流数据的任务。每次运行时用于验证 WHEN 表达式的费用通常微不足道，但费用会累积。

请注意，如果云服务的每日消耗量低于 计算资源每日使用量的 10% 配额，则不会累积云服务费用。

目前，SQL 表达式支持使用以下函数进行计算：

SYSTEM$STREAM_HAS_DATA

指明指定的流是否包含变更跟踪数据。用于在流不包含变更数据时跳过当前任务运行。

如果结果为 FALSE，则任务不会运行。

SYSTEM$GET_PREDECESSOR_RETURN_VALUE

检索任务图中的前置任务的返回值。用于根据返回的结果决定是否应运行任务。

使用说明

  • 恢复或暂停任务（分别使用 ALTER TASK ... RESUME 或 ALTER TASK ... SUSPEND）需要任务的 OWNERSHIP 或 OPERATE 权限。

    任务恢复后，Snowflake 会验证对任务具有 OWNERSHIP 权限的角色是否也对分配给任务的仓库具有 USAGE 权限，以及全局 EXECUTE TASK 权限；如果没有，则会产生错误。

    只有账户管理员（具有 ACCOUNTADMIN 角色的用户）可以向角色授予全局 EXECUTE TASK 权限。为简化使用，我们建议创建自定义角色（例如 TASKADMIN）并为该角色分配 EXECUTE TASK 权限。然后，任何可以授予权限的角色（例如 SECURITYADMIN 或任何具有 MANAGE GRANTS 权限的角色）均可将此自定义角色授予任何任务所有者角色，以允许其修改自己的任务。有关创建自定义角色和角色层次结构的说明，请参阅 配置访问控制。

  • 只有任务所有者（即，具有任务的 OWNERSHIP 权限的角色）才能设置或取消设置任务的属性。

  • 在更改配置时，您无法更新单个键值对。相反，您必须提供表示完整配置的整个替换 json 字符串。

  • 您必须先暂停独立任务，然后才能对其进行修改。

  • 您必须先暂停 任务图 中的根任务，然后才能修改任务图中的 任何 任务、暂停或恢复子任务或者添加子任务（使用 ALTER TASK ... AFTER）。

  • 任务图最多总共可有 1000 个处于已恢复或已暂停状态的任务（包括根任务）。

  • 要以递归方式恢复与任务图中根任务关联的所有相关任务，请查询 SYSTEM$TASK_DEPENDENTS_ENABLE 函数，而不是单独启用每个任务（使用 ALTER TASK ... RESUME）。

  • 默认情况下，如果 DML 语句在未显式启动事务的情况下执行，则在语句结束时，如果成功则自动提交，如果失败则回滚。此行为称为 自动提交，使用 AUTOCOMMIT 参数进行控制。此参数 必须 设置为 TRUE。如果 AUTOCOMMIT 参数在账户级别设置为 FALSE，则对于单个任务，将该参数设置为 TRUE（使用 ALTER TASK ...SET AUTOCOMMIT = TRUE）。

  • 当任务暂停时，该任务的任何当前运行（即 TASK_HISTORY 输出中具有 EXECUTING 状态的运行）都将完成。要中止指定任务的运行，请执行 SYSTEM$USER_TASK_CANCEL_ONGOING_EXECUTIONS 函数。

  • 针对任务的单个运行的计算资源 要么 由 Snowflake（即无服务器计算模型）管理，要么由用户指定的虚拟仓库管理。要将依赖于仓库的任务转换为无服务器计算模型，请取消设置 WAREHOUSE。

  • 如果任务失败并出现意外错误，您可以收到有关该错误的通知。有关配置任务错误通知的更多信息，请参阅 为任务启用错误通知。

  • 关于元数据：

    注意

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

  • 关于终结器任务：

    • 当您 SET FINALIZE = <root task name> 时，此函数会将一个普通任务配置为与给定根任务关联的终结器任务。

    • 当您 UNSET FINALIZE 时，终结器任务将变为没有计划或前置任务的普通独立任务。

    • SET FINALIZE 与 SET SCHEDULE 和 ADD AFTER 相冲突。如果任务具有现有计划或前置任务，也将使 SET FINALIZE 查询失败。

    • 要更改根任务的已定义终结器任务，首先使用 UNSET FINALIZE 取消设置终结器任务，然后使用 SET FINALIZE = <root task name> 更新根任务的终结器任务。

    • 在修改、设置或取消设置终结器任务之前，必须暂停根任务。

示例

以下示例启动任务的操作：

ALTER TASK mytask RESUME;
Copy

以下示例将任务转换为无服务器计算模型，并将 xsmall 设置为要为任务的首次无服务器运行设置的计算资源量：

ALTER TASK mytask UNSET WAREHOUSE;

ALTER TASK mytask SET USER_TASK_MANAGED_INITIAL_WAREHOUSE_SIZE = 'XSMALL';
Copy

以下示例为任务运行所属的会话设置 TIMEZONE 和 CLIENT_TIMESTAMP_TYPE_MAPPING 会话参数：

ALTER TASK mytask SET TIMEZONE = 'America/Los_Angeles', CLIENT_TIMESTAMP_TYPE_MAPPING = TIMESTAMP_LTZ;
Copy

以下示例为任务设置不同的计划：

ALTER TASK mytask SET SCHEDULE = 'USING CRON */3 * * * * UTC';
Copy

以下示例移除 mytask 子任务的当前前置任务（pred_task1、pred_task2），并将这些任务替换为不同的前置任务 (pred_task3)：

ALTER TASK mytask REMOVE AFTER pred_task1, pred_task2;

ALTER TASK mytask ADD AFTER pred_task3;
Copy

以下示例更改与任务关联的 SQL 语句。现在，该任务在运行时查询 CURRENT_VERSION 函数：

ALTER TASK mytask MODIFY AS SELECT CURRENT_VERSION();
Copy

下面的示例修改与任务关联的 WHEN 条件。（按计划或在前置任务任务成功运行后）触发时，任务现在仅当 mystream 流包含数据时才运行：

ALTER TASK mytask MODIFY WHEN SYSTEM$STREAM_HAS_DATA('MYSTREAM');
Copy

使用新配置或替换配置更新现有任务。

ALTER TASK task_with_config SET
      CONFIG=$${"output_directory": "/temp/prod_directory/", "environment": "prod"}$$;
Copy

从现有任务中移除配置。

ALTER TASK task_with_config UNSET CONFIG;
Copy
语言: 中文