类别：: Information Schema、表函数

TASK_HISTORY¶

您可以使用此表函数查询指定日期范围内的任务使用历史记录。该函数会返回整个 Snowflake 账户、指定任务或任务图的任务使用历史记录。

语法¶

TASK_HISTORY(
      [ SCHEDULED_TIME_RANGE_START => <constant_expr> ]
      [, SCHEDULED_TIME_RANGE_END => <constant_expr> ]
      [, RESULT_LIMIT => <integer> ]
      [, TASK_NAME => '<string>' ]
      [, ERROR_ONLY => { TRUE | FALSE } ]
      [, ROOT_TASK_ID => '<string>'] )

Copy

实参¶

所有实参均为可选。

SCHEDULED_TIME_RANGE_START => constant_expr、. SCHEDULED_TIME_RANGE_END => constant_expr

过去 7 天内计划执行任务的时间范围（采用 TIMESTAMP_LTZ 格式）。如果时间范围不在最近 7 天内，则返回一条错误。

如果未指定 SCHEDULED_TIME_RANGE_END，该函数将返回那些已完成、当前正在运行或将来计划的任务。
如果 SCHEDULED_TIME_RANGE_END 为 CURRENT_TIMESTAMP，该函数将返回那些已完成或当前正在运行的任务。请注意，在当前时间之前立即执行的任务仍有可能被标识为计划任务。
要仅查询那些已完成或当前正在运行的任务，可以添加 WHERE query_id IS NOT NULL 作为筛选器。仅当任务开始运行时，才能填充 TASK_HISTORY 输出中的 QUERY_ID 列。

备注

如果未指定开始或结束时间，则返回最近的任务，不超过指定的 RESULT_LIMIT 值。

RESULT_LIMIT => integer

用于指定函数返回的行数上限的数字。

如果匹配的行数大于此限制，则返回具有最新时间戳的任务执行，直至达到指定的限制。

范围：1 至 10000

默认：100。

TASK_NAME => string

用于指定任务的不区分大小写的字符串。仅支持非限定任务名称。仅返回指定任务的执行。请注意，如果多个任务具有相同的名称，则该函数将返回每个任务的历史记录。

ERROR_ONLY => TRUE | FALSE

设置为 TRUE 时，此函数仅返回已失败或已取消的任务运行。

ROOT_TASK_ID =>string

任务图中根任务的唯一标识符。此 ID 与同一任务 SHOW TASKS 输出中的 ID 列值相匹配。指定 ROOT_TASK_ID 以显示根任务和任务图中任何子任务的历史记录。

使用说明¶

此函数仅返回 ACCOUNTADMIN 角色、任务所有者或具有全局 MONITOR EXECUTION 权限的角色的结果。请注意，除非具有该 MONITOR EXECUTION 权限的角色同时具有存储任务的数据库和架构的 USAGE 权限，否则输出中的 DATABASE_NAME 和 SCHEMA_NAME 值为 NULL。
此函数最多返回在 RESULT_LIMIT 实参值中设置的 10,000 行。默认值为 100。要避免此限制，请使用 TASK_HISTORY 视图 (Account Usage)。
请注意，查询 TASK_HISTORY 函数时，首先应用其任务名称、时间范围和结果限制实参，然后分别应用 WHERE 和 LIMIT 子句（如果已指定）。此外，TASK_HISTORY 函数还按 SCHEDULED_TIME 降序返回记录。处于 SUCCEEDED、FAILED 或 CANCELLED 状态的任务往往安排得较早，因此它们在搜索结果中通常较晚返回。
实际上，如果您的账户中正在运行许多任务，函数返回的结果可能包括少于预期的已完成任务或仅包含计划任务。要查询已运行任务的历史记录，可结合使用 SCHEDULED_TIME_RANGE_START => constant_expr 和 SCHEDULED_TIME_RANGE_END => constant_expr 实参。
当调用 Information Schema 表函数时，会话必须具有正在使用的 INFORMATION_SCHEMA 架构，或者函数名称必须为完全限定模式。有关更多信息，请参阅 Snowflake Information Schema。
此函数会返回过去 7 天内的所有执行运行或未来 8 天内的下一次计划执行。
云服务故障期间运行的任务可能会在此函数的结果中显示为重复条目。在云服务故障期间，Snowflake 可能会重新运行一个任务，导致该任务有两个不同任务 SCHEDULED_TIME 的 UUIDs。TASK_HISTORY 视图只显示重新运行任务的最终 UUID。
任务图运行中的所有任务都会显示相同的任务历史输出。

输出¶

该函数返回以下列：

列名称	数据类型	描述
QUERY_ID	TEXT	任务执行的 SQL 语句的 ID。可以与 QUERY_HISTORY 视图联接，以获取有关语句或存储过程执行的其他详细信息。
NAME	TEXT	任务的名称。
DATABASE_NAME	TEXT	包含任务的数据库的名称。
SCHEMA_NAME	TEXT	包含任务的架构的名称。
QUERY_TEXT	TEXT	SQL 语句的文本。
CONDITION_TEXT	TEXT	任务在确定是否运行时评估的 WHEN 条件的文本。
STATE	TEXT	任务状态： `SCHEDULED`：计划执行。 `EXECUTING`：当前正在执行。 `SUCCEEDED`：执行成功。 `FAILED`：执行失败。 FAILED_AND_AUTO_SUSPENDED：任务失败，并已自动暂停。 `CANCELLED`：已取消执行。 `SKIPPED`：指示任务运行开始，但任务定义中的可选 `WHEN` 参数返回 FALSE 值；因此，运行不会恢复仓库（如果任务使用客户管理的计算资源），也不会执行任务定义中的 SQL 代码。
ERROR_CODE	NUMBER	错误代码（如果语句返回错误）。
ERROR_MESSAGE	TEXT	错误消息（如果语句返回错误）。
SCHEDULED_TIME	TIMESTAMP_LTZ	任务计划开始运行的时间。注意，我们会尽最大努力确保绝对精度，但仅保证任务不会在计划时间之前执行。
QUERY_START_TIME	TIMESTAMP_LTZ	任务定义中的查询开始运行的时间；如果 SCHEDULED_TIME 是将来的时间，或当前计划的运行尚未开始，则值为 NULL。此时间戳与 QUERY_HISTORY 返回的查询的开始时间一致。
NEXT_SCHEDULED_TIME	TIMESTAMP_LTZ	独立任务或根任务（在任务的任务图中）下次计划开始运行的时间，假设在 SCHEDULED_TIME 时间开始的独立任务或任务图的当前运行及时完成。
COMPLETED_TIME	TIMESTAMP_LTZ	任务完成的时间；如果 SCHEDULED_TIME 是将来的时间或者任务仍在运行，则值为 NULL。
ROOT_TASK_ID	TEXT	任务图中根任务的唯一标识符。此 ID 与同一任务的 SHOW TASKS 输出中的 ID 列值匹配。
GRAPH_VERSION	NUMBER	整数，用于识别已运行或计划运行的任务图版本。该值的每个增量增加表示对任务图中的任务的一个或多个修改。如果重新创建根任务（使用 CREATE OR REPLACE TASK），则版本号从 1 重新开始。
RUN_ID	NUMBER	任务图中的独立任务或根任务最初计划开始运行的时间。格式是纪元时间（以毫秒为单位）。. . 最初计划时间是指系统可能会将同一任务重新计划为在不同时间运行以重试或重新平衡负载的罕见情况。如果发生这种情况，RUN_ID 会显示最初计划运行时间，SCHEDULED_TIME 则会显示重新计划的运行时间。. . 注意，在重试之前，RUN_ID 可能不是当前任务/图形运行的唯一标识符。您可以使用 GRAPH_RUN_GROUP_ID 列来代替 RUN_ID。
RETURN_VALUE	TEXT	任务图中的前置任务值集。由前置任务通过调用 SYSTEM$SET_RETURN_VALUE 函数显式设置返回值。
SCHEDULED_FROM	TEXT	其中之一： `SCHEDULE`：任务计划正常运行，如 CREATE TASK 中的 SCHEDULE 或 AFTER 子句所述。 `EXECUTE TASK`：计划使用 EXECUTE TASK 运行此任务。 `MANUAL RETRY`：计划使用 EXECUTE TASK ...RETRY LAST 运行此任务。对于任务图中子任务的运行，该列返回与根任务运行相同的值。
ATTEMPT_NUMBER	NUMBER	整数表示尝试运行此任务的次数。最初的一次。
CONFIG	TEXT	如果为根任务设置了图形级别配置，则显示图形级别配置，否则显示 NULL。
QUERY_HASH	TEXT	根据规范化 SQL 文本计算的哈希值。
QUERY_HASH_VERSION	NUMBER	用于计算 `QUERY_HASH` 的逻辑版本。
QUERY_PARAMETERIZED_HASH	TEXT	根据参数化查询计算的哈希值。
QUERY_PARAMETERIZED_HASH_VERSION	NUMBER	用于计算 `QUERY_PARAMETERIZED_HASH` 的逻辑版本。
GRAPH_RUN_GROUP_ID	NUMBER	图形运行标识符。当图形运行有多个任务运行时，每个任务运行将显示相同的 GRAPH_RUN_GROUP_ID。GRAPH_RUN_GROUP_ID 和 ATTEMPT_NUMBER 的组合可用于对图形运行进行唯一标识。
BACKFILL_INFO	OBJECT	保留以供将来使用。所有行的返回值均为 NULL。

示例¶

检索账户中最近的 100 个任务执行（已完成、仍在运行或将来计划）。注意，默认情况下，函数返回的最大行数限制为 100 行：

SELECT *
  FROM TABLE(INFORMATION_SCHEMA.TASK_HISTORY())
  ORDER BY SCHEDULED_TIME;

Copy

检索过去 7 天内在指定 30 分钟时间段内账户中任务的执行历史记录：

SELECT *
  FROM TABLE(INFORMATION_SCHEMA.TASK_HISTORY(
    SCHEDULED_TIME_RANGE_START=>TO_TIMESTAMP_LTZ('2018-11-9 12:00:00.000 -0700'),
    SCHEDULED_TIME_RANGE_END=>TO_TIMESTAMP_LTZ('2018-11-9 12:30:00.000 -0700')));

Copy

检索过去一小时内计划的指定任务（已完成、仍在运行或将来计划）的最近 10 次执行：

SELECT *
  FROM TABLE(INFORMATION_SCHEMA.TASK_HISTORY(
    SCHEDULED_TIME_RANGE_START=>DATEADD('hour',-1,current_timestamp()),
    RESULT_LIMIT => 10,
    TASK_NAME=>'mytask'));
Copy
备注

要仅检索已完成或仍在运行的任务，请使用 WHERE query_id IS NOT NULL 筛选查询。请注意，在 RESULT_LIMIT 已减少返回的结果:emph:`之后`应用此筛选器，因此，如果计划了 1 个任务但尚未启动，则查询可能会返回 9 个任务。

检索指定根任务的任务图中所有任务的执行历史记录。

SELECT *
  FROM TABLE(INFORMATION_SCHEMA.TASK_HISTORY(ROOT_TASK_ID=>'d4b89013-c942-465c-bcb8-e7037a932b04'));

Copy

检索最近查询的根任务的任务图中所有任务的执行历史记录：

DESC TASK my_task
SET task_id=(SELECT "id" FROM TABLE(RESULT_SCAN(LAST_QUERY_ID())));
SELECT *
  FROM TABLE(INFORMATION_SCHEMA.TASK_HISTORY(ROOT_TASK_ID=>$task_id));

Copy