ALTER 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 = { '<num> { HOURS | MINUTES | SECONDS }'
               | '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> ]
  [ SUCCESS_INTEGRATION = <integration_name> ]
  [ LOG_LEVEL = '<log_level>' ]
  [ COMMENT = <string> ]
  [ <session_parameter> = <value>
    [ , <session_parameter> = <value> ... ] ]
  [ TASK_AUTO_RETRY_ATTEMPTS = <num> ]
  [ USER_TASK_MINIMUM_TRIGGER_INTERVAL_IN_SECONDS = <num> ]
  [ TARGET_COMPLETION_INTERVAL = '<num> { HOURS | MINUTES | SECONDS }' ]
  [ SERVERLESS_TASK_MIN_STATEMENT_SIZE= 'XSMALL | SMALL
    | MEDIUM | LARGE | XLARGE | XXLARGE' ]
  [ SERVERLESS_TASK_MAX_STATEMENT_SIZE= 'XSMALL | SMALL
    | MEDIUM | LARGE | XLARGE | XXLARGE' ]
  [ CONTACT <purpose> = <contact_name> [ , <purpose> = <contact_name> ... ] ]
  [ EXECUTE AS USER <user_name> ]


ALTER TASK [ IF EXISTS ] <name> UNSET
  [ WAREHOUSE ]
  [ SCHEDULE ]
  [ CONFIG ]
  [ ALLOW_OVERLAPPING_EXECUTION ]
  [ USER_TASK_TIMEOUT_MS ]
  [ SUSPEND_TASK_AFTER_NUM_FAILURES ]
  [ LOG_LEVEL ]
  [ COMMENT ]
  [ <session_parameter> [ , <session_parameter> ... ] ]
  [ TARGET_COMPLETION_INTERVAL ]
  [ SERVERLESS_TASK_MIN_STATEMENT_SIZE ]
  [ SERVERLESS_TASK_MAX_STATEMENT_SIZE ]
  [ CONTACT <purpose> [ , ... ]]
  [ EXECUTE AS USER ]


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>

ALTER TASK [ IF EXISTS ] <name> REMOVE WHEN

参数¶

name

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

RESUME | SUSPEND

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

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

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

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

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

基本间隔时间从当前时钟时间开始间隔计数器。例如，如果将 INTERVAL 值设置为 10 MINUTES,并且在 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 ...

指定以下一项或两项：

• One or more properties to set for the task, which are separated by blank spaces, commas, or new lines. For more details about the properties you can set, see CREATE TASK.

  在任务上设置配置时，您需要为该任务指定默认配置字符串。您可以使用 EXECUTE TASK 命令替换单次执行的默认配置。

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

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

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

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

  有关在语句中指定标签的信息，请参阅 Tag quotas。

• CONTACT purpose = contact [ , purpose = contact ... ]

  将现有对象与一个或多个 联系人 关联起来。

  您不能在同一语句中使用其他属性设置 CONTACT 属性。

UNSET ...

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

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

要将联系人与任务分离，请指定 UNSET CONTACT purpose。您不能在同一语句中使用其他属性取消设置 CONTACT 属性。

sql

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

• 单一 SQL 语句

• 调用存储过程

• 使用 Snowflake Scripting 的过程逻辑

  Note that currently, Snowsight does not support creating or modifying tasks to use Snowflake Scripting. Instead, use SnowSQL or another command-line client.

备注

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

WHEN boolean_expr

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

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

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

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

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

SYSTEM$STREAM_HAS_DATA

指明指定的流是否包含变更跟踪数据。如果任务未定义计划，则用于运行触发的任务。如果流不包含变更数据，您可以借此跳过当前任务运行。

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

SYSTEM$GET_PREDECESSOR_RETURN_VALUE

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

REMOVE WHEN

移除您已指定的 WHEN 条件。

EXECUTE AS USER user_name

代表指定的用户账户运行任务。运行命令的用户必须拥有使用 GRANT IMPERSONATE ON USER TO ROLE 命令授予的权限。

有关更多信息，请参阅 使用用户权限运行任务。

重命名任务¶

不支持重命名任务。相反，您可以克隆任务，然后删除旧任务；例如：

1. 暂停任务 (ALTER TASK task_old_name SUSPEND)。

2. 克隆任务，为其指定一个新名称 (CREATE TASK new_task_name CLONE old_task_name)。

3. 对于任务图，请查找引用旧任务名称的相关任务，然后将其更新为使用新名称：

1. 使用 TASK_DEPENDENTS ... RECURSIVE 函数查找直接相关的任务（即子任务和终结器任务，但不是子级任务）；例如：

   SELECT * FROM TABLE(INFORMATION_SCHEMA.TASK_DEPENDENTS('old_task_name', RECURSIVE => false));
   

   Copy

2. 更新每个相关任务以使用新的任务名称 (ALTER TASK child_task_1 ADD AFTER new_task_name)。

1. 删除任务的旧版本 (DROP TASK old_task_name)。

2. 恢复任务的新版本 (ALTER TASK new_task_name RESUME)。

使用说明¶

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

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

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

• Only the task owner --- that is, the role with the OWNERSHIP privilege on the task --- can set or unset properties on a task.

• 要更改默认 CONFIG，您必须提供整个替换 JSON 字符串。您无法更新单个键值对。要替换单次执行的默认配置，请使用 EXECUTE TASK。

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

• 您必须先暂停 任务图 中的根任务，然后才能修改任务图中的 任何 任务、暂停或恢复子任务或者添加子任务（使用 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;

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

ALTER TASK mytask UNSET WAREHOUSE;

ALTER TASK mytask SET USER_TASK_MANAGED_INITIAL_WAREHOUSE_SIZE = 'XSMALL';

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

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

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

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

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

ALTER TASK mytask REMOVE AFTER pred_task1, pred_task2;

ALTER TASK mytask ADD AFTER pred_task3;

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

ALTER TASK mytask MODIFY AS SELECT CURRENT_VERSION();

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

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

Update an existing task with new or replacement default configuration:

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

Remove the default configuration from an existing task:

ALTER TASK task_with_config UNSET CONFIG;