From 6a958f2a4661a5318790adcdef8e124ea1a08f18 Mon Sep 17 00:00:00 2001 From: BohuTANG Date: Tue, 18 Nov 2025 20:34:08 +0800 Subject: [PATCH] docs: add show tasks doc and task history examples --- .../00-ddl/04-task/01-ddl-create_task.md | 17 ++++- .../00-ddl/04-task/05-show-tasks.md | 64 +++++++++++++++++++ .../10-sql-commands/00-ddl/04-task/index.md | 4 +- .../00-ddl/04-task/01-ddl-create_task.md | 15 +++++ .../00-ddl/04-task/05-show-tasks.md | 64 +++++++++++++++++++ .../10-sql-commands/00-ddl/04-task/index.md | 2 + 6 files changed, 164 insertions(+), 2 deletions(-) create mode 100644 docs/cn/sql-reference/10-sql-commands/00-ddl/04-task/05-show-tasks.md create mode 100644 docs/en/sql-reference/10-sql-commands/00-ddl/04-task/05-show-tasks.md diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/04-task/01-ddl-create_task.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/04-task/01-ddl-create_task.md index 4c68bc7187..4dea8b8afc 100644 --- a/docs/cn/sql-reference/10-sql-commands/00-ddl/04-task/01-ddl-create_task.md +++ b/docs/cn/sql-reference/10-sql-commands/00-ddl/04-task/01-ddl-create_task.md @@ -208,4 +208,19 @@ AS GROUP BY product_category; ``` -本例创建名为 `cache_enabled_task` 的任务，带启用查询结果缓存的**会话参数**，每 **5 分钟**运行一次，使用 **analytics** 计算集群。会话参数 **`enable_query_result_cache = 1`** 与 **`query_result_cache_min_execute_secs = 5`** 置于所有其他参数之后，为执行时间 ≥5 秒的查询启用缓存，若底层数据未变，可**提升**后续执行的**性能**。 \ No newline at end of file +本例创建名为 `cache_enabled_task` 的任务，带启用查询结果缓存的**会话参数**，每 **5 分钟**运行一次，使用 **analytics** 计算集群。会话参数 **`enable_query_result_cache = 1`** 与 **`query_result_cache_min_execute_secs = 5`** 置于所有其他参数之后，为执行时间 ≥5 秒的查询启用缓存，若底层数据未变，可**提升**后续执行的**性能**。 + +### 查看任务运行历史 + +使用 `TASK_HISTORY()` 表函数查看任务何时、如何运行： + +```sql +SELECT * +FROM TASK_HISTORY( + TASK_NAME => 'daily_sales_summary', + RESULT_LIMIT => 20 +) +ORDER BY scheduled_time DESC; +``` + +更多参数（如按时间范围或 DAG 的根任务 ID 过滤）参见 [TASK HISTORY](../../../20-sql-functions/17-table-functions/task_histroy.md)。 diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/04-task/05-show-tasks.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/04-task/05-show-tasks.md new file mode 100644 index 0000000000..dc6edc2395 --- /dev/null +++ b/docs/cn/sql-reference/10-sql-commands/00-ddl/04-task/05-show-tasks.md @@ -0,0 +1,64 @@ +--- +title: SHOW TASKS +sidebar_position: 5 +--- +import FunctionDescription from '@site/src/components/FunctionDescription'; + + + +列出当前角色可见的任务。 + +**注意：** 该命令默认仅在 Databend Cloud 可用；自建部署需配置 Cloud Control 才能查询任务。 + +## 语法 + +```sql +SHOW TASKS [LIKE '' | WHERE ] +``` + +| 参数 | 说明 | +|-----------|-------------| +| LIKE | 使用区分大小写的模式匹配（含 `%` 通配符）过滤任务名。 | +| WHERE | 对输出列使用表达式过滤结果。 | + +### 输出列 + +`SHOW TASKS` 返回以下列： + +- `created_on`: 任务创建时间戳。 +- `name`: 任务名称。 +- `id`: 内部任务 ID。 +- `owner`: 拥有该任务的角色。 +- `comment`: 可选备注。 +- `warehouse`: 关联的计算集群。 +- `schedule`: 间隔或 CRON 调度（如有）。 +- `state`: 当前状态（`Started` 或 `Suspended`）。 +- `definition`: 任务执行的 SQL。 +- `condition_text`: 任务的 WHEN 条件。 +- `after`: DAG 中上游任务的逗号分隔列表。 +- `suspend_task_after_num_failures`: 连续失败多少次后自动挂起。 +- `error_integration`: 失败通知使用的集成名称。 +- `next_schedule_time`: 下一次计划运行的时间戳。 +- `last_committed_on`: 任务定义上次更新的时间戳。 +- `last_suspended_on`: 上次挂起时间（如有）。 +- `session_parameters`: 任务运行时应用的会话参数。 + +## 示例 + +列出当前角色可见的全部任务： + +```sql +SHOW TASKS; ++----------------------------+---------------+------+---------------+---------+-----------+---------------------------------+----------+-------------------------------------------+------------------------+---------+-------------------------------------+-------------------+----------------------------+----------------------------+----------------------------+---------------------------------------------------+ +| created_on | name | id | owner | comment | warehouse | schedule | state | definition | condition_text | after | suspend_task_after_num_failures | error_integration | next_schedule_time | last_committed_on | last_suspended_on | session_parameters | ++----------------------------+---------------+------+---------------+---------+-----------+---------------------------------+----------+-------------------------------------------+------------------------+---------+-------------------------------------+-------------------+----------------------------+----------------------------+----------------------------+---------------------------------------------------+ +| 2024-07-01 08:00:00.000000 | ingest_sales | 101 | ACCOUNTADMIN | NULL | etl_wh | CRON 0 5 * * * * TIMEZONE UTC | Started | COPY INTO sales FROM @stage PATTERN '.*' | STREAM_STATUS('s1') | | 3 | slack_errors | 2024-07-01 08:05:00.000000 | 2024-07-01 08:00:00.000000 | NULL | {"enable_query_result_cache":"1"} | +| 2024-07-01 09:00:00.000000 | hourly_checks | 102 | SYSADMIN | health | etl_wh | INTERVAL 3600 SECOND | Suspended | CALL run_health_check() | | ingest_sales | NULL | NULL | 2024-07-01 10:00:00.000000 | 2024-07-01 09:05:00.000000 | 2024-07-01 09:10:00.000000 | {"query_result_cache_min_execute_secs":"5"} | ++----------------------------+---------------+------+---------------+---------+-----------+---------------------------------+----------+-------------------------------------------+------------------------+---------+-------------------------------------+-------------------+----------------------------+----------------------------+----------------------------+---------------------------------------------------+ +``` + +仅展示名称以 `ingest_` 开头的任务： + +```sql +SHOW TASKS LIKE 'ingest_%'; +``` diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/04-task/index.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/04-task/index.md index 80ede81196..e3f407bca6 100644 --- a/docs/cn/sql-reference/10-sql-commands/00-ddl/04-task/index.md +++ b/docs/cn/sql-reference/10-sql-commands/00-ddl/04-task/index.md @@ -17,8 +17,10 @@ title: 任务（Task） | 命令 | 描述 | |---------|-------------| +| [SHOW TASKS](05-show-tasks.md) | 查看当前角色可见的任务 | +| [TASK HISTORY](../../../20-sql-functions/17-table-functions/task_histroy.md) | 查看一个或多个任务的运行历史 | | [TASK ERROR INTEGRATION PAYLOAD](10-task-error-integration-payload.md) | 显示任务错误通知的错误载荷格式 | :::note Databend 中的任务允许您安排和自动化 SQL 命令在指定间隔执行。 -::: \ No newline at end of file +::: diff --git a/docs/en/sql-reference/10-sql-commands/00-ddl/04-task/01-ddl-create_task.md b/docs/en/sql-reference/10-sql-commands/00-ddl/04-task/01-ddl-create_task.md index 318214584a..5bf270efc3 100644 --- a/docs/en/sql-reference/10-sql-commands/00-ddl/04-task/01-ddl-create_task.md +++ b/docs/en/sql-reference/10-sql-commands/00-ddl/04-task/01-ddl-create_task.md @@ -210,3 +210,18 @@ AS ``` In this example, a task named `cache_enabled_task` is created with **session parameters** that enable query result caching. The task is scheduled to run **every 5 minutes** and uses the **analytics** warehouse. The session parameters **`enable_query_result_cache = 1`** and **`query_result_cache_min_execute_secs = 5`** are specified **after all other task parameters**, enabling the query result cache for queries that take at least 5 seconds to execute. This can **improve performance** for subsequent executions of the same task if the underlying data hasn't changed. + +### View Task Run History + +Use the `TASK_HISTORY()` table function to see when and how tasks ran: + +```sql +SELECT * +FROM TASK_HISTORY( + TASK_NAME => 'daily_sales_summary', + RESULT_LIMIT => 20 +) +ORDER BY scheduled_time DESC; +``` + +See [TASK HISTORY](../../../20-sql-functions/17-table-functions/task_histroy.md) for all options, including filtering by time range or root task ID in a DAG. diff --git a/docs/en/sql-reference/10-sql-commands/00-ddl/04-task/05-show-tasks.md b/docs/en/sql-reference/10-sql-commands/00-ddl/04-task/05-show-tasks.md new file mode 100644 index 0000000000..a83c044c67 --- /dev/null +++ b/docs/en/sql-reference/10-sql-commands/00-ddl/04-task/05-show-tasks.md @@ -0,0 +1,64 @@ +--- +title: SHOW TASKS +sidebar_position: 5 +--- +import FunctionDescription from '@site/src/components/FunctionDescription'; + + + +Lists the tasks that are visible to the current role. + +**NOTICE:** This command works out of the box only in Databend Cloud. For self-hosted deployments, configure Cloud Control to query tasks. + +## Syntax + +```sql +SHOW TASKS [LIKE '' | WHERE ] +``` + +| Parameter | Description | +|-----------|-------------| +| LIKE | Filters task names using case-sensitive pattern matching with the `%` wildcard. | +| WHERE | Filters the result set using an expression on the output columns. | + +### Output + +`SHOW TASKS` returns the following columns: + +- `created_on`: Timestamp when the task was created. +- `name`: Task name. +- `id`: Internal task identifier. +- `owner`: Role that owns the task. +- `comment`: Optional comment. +- `warehouse`: Warehouse assigned to the task. +- `schedule`: Interval or CRON schedule, when present. +- `state`: Current status (`Started` or `Suspended`). +- `definition`: SQL the task runs. +- `condition_text`: WHEN condition for the task. +- `after`: Comma-separated list of upstream tasks in a DAG. +- `suspend_task_after_num_failures`: Number of consecutive failures before suspension. +- `error_integration`: Notification integration for failures. +- `next_schedule_time`: Timestamp of the next scheduled run. +- `last_committed_on`: Timestamp when the task definition was last updated. +- `last_suspended_on`: Timestamp when the task was last suspended, if any. +- `session_parameters`: Session parameters applied when the task runs. + +## Examples + +List all tasks available to the current role: + +```sql +SHOW TASKS; ++----------------------------+---------------+------+---------------+---------+-----------+---------------------------------+----------+-------------------------------------------+------------------------+---------+-------------------------------------+-------------------+----------------------------+----------------------------+----------------------------+---------------------------------------------------+ +| created_on | name | id | owner | comment | warehouse | schedule | state | definition | condition_text | after | suspend_task_after_num_failures | error_integration | next_schedule_time | last_committed_on | last_suspended_on | session_parameters | ++----------------------------+---------------+------+---------------+---------+-----------+---------------------------------+----------+-------------------------------------------+------------------------+---------+-------------------------------------+-------------------+----------------------------+----------------------------+----------------------------+---------------------------------------------------+ +| 2024-07-01 08:00:00.000000 | ingest_sales | 101 | ACCOUNTADMIN | NULL | etl_wh | CRON 0 5 * * * * TIMEZONE UTC | Started | COPY INTO sales FROM @stage PATTERN '.*' | STREAM_STATUS('s1') | | 3 | slack_errors | 2024-07-01 08:05:00.000000 | 2024-07-01 08:00:00.000000 | NULL | {"enable_query_result_cache":"1"} | +| 2024-07-01 09:00:00.000000 | hourly_checks | 102 | SYSADMIN | health | etl_wh | INTERVAL 3600 SECOND | Suspended | CALL run_health_check() | | ingest_sales | NULL | NULL | 2024-07-01 10:00:00.000000 | 2024-07-01 09:05:00.000000 | 2024-07-01 09:10:00.000000 | {"query_result_cache_min_execute_secs":"5"} | ++----------------------------+---------------+------+---------------+---------+-----------+---------------------------------+----------+-------------------------------------------+------------------------+---------+-------------------------------------+-------------------+----------------------------+----------------------------+----------------------------+---------------------------------------------------+ +``` + +Show only tasks whose names start with `ingest_`: + +```sql +SHOW TASKS LIKE 'ingest_%'; +``` diff --git a/docs/en/sql-reference/10-sql-commands/00-ddl/04-task/index.md b/docs/en/sql-reference/10-sql-commands/00-ddl/04-task/index.md index e6ced214ca..6b171eecca 100644 --- a/docs/en/sql-reference/10-sql-commands/00-ddl/04-task/index.md +++ b/docs/en/sql-reference/10-sql-commands/00-ddl/04-task/index.md @@ -17,6 +17,8 @@ This page provides a comprehensive overview of task operations in Databend, orga | Command | Description | |---------|-------------| +| [SHOW TASKS](05-show-tasks.md) | Lists tasks visible to the current role | +| [TASK HISTORY](../../../20-sql-functions/17-table-functions/task_histroy.md) | Shows run history for one or more tasks | | [TASK ERROR INTEGRATION PAYLOAD](10-task-error-integration-payload.md) | Shows the error payload format for task error notifications | :::note