定时任务

SCHEDULE，即定时任务，指按照预定的时间或事件自动执行特定的数据库任务。

KaiwuDB 支持授权用户根据需要执行以下定时任务相关操作：

• 通过 CREATE SCHEDULE 语句创建定时任务。
• 通过 SHOW SCHEDULE 语句查看创建的定时任务的调度周期、执行时间、执行状态等信息。
• 通过 SHOW JOBS FOR SCHEDULE 命令查看任务在历史和当前周期执行的开始时间、结束时间、执行进度、执行结果、错误信息等。更多信息，参见查看任务。
• 通过 ALTER SCHEDULE 语句修改调度周期、任务执行错误处理策略、或者前一次任务调度尚未执行完成的处理策略。
• 通过 PAUSE SCHEDULE 语句暂停后台计划任务的调度。
• 通过 RESUME SCHEDULE 语句恢复暂停的定时任务。
• 通过 DROP SCHEDULE 语句删除定时任务。

默认情况下，KaiwuDB 每 60 秒扫描一次定时任务列表，随机找出应该执行的 10 个定时任务，并执行相关联的任务。KaiwuDB 支持用户通过 SET CLUSTER SETTING <parameter> = <value> 语句修改以下实时参数关闭实时任务功能，修改扫描频率和每次执行的任务数：

• jobs.scheduler.enabled：开启或关闭定时任务功能。默认值为 TRUE，表示开启功能。
• jobs.scheduler.pace：扫描任务表 system.scheduled_jobs 的频率。默认值为 60 秒，设置值不能小于 60s。如果设置值小于 60s，将采用默认值 60s。
• jobs.scheduler.max_jobs_per_iteration：每次扫描执行的最大任务数。默认值为 10。取值为 0，表示无任务数限制。

创建定时任务

所需权限

• 非三权分立模式下，用户具有 Admin 角色。默认情况下，root 用户具有 Admin 角色。
• 三权分立模式下，用户是 sysadmin 角色的成员。默认情况下，sysroot 用户属于 sysadmin 角色。

语法格式

参数说明

参数	说明
IF NOT EXISTS	可选关键字。当使用 IF NOT EXISTS 关键字时，如果目标定时任务不存在，系统创建目标定时任务。如果目标定时任务存在，系统创建定时任务失败，但不会报错。当未使用 IF NOT EXISTS 关键字时，如果目标定时任务不存在，系统创建定时任务。如果目标定时任务存在，系统报错，提示目标定时任务已存在。
schedule_name	可选参数，待创建定时任务的名称。如未指定目标定时任务的名称，系统自动生成一个名称，例如 EXEC SQL 1718951529。定时任务名称必须唯一，支持字符串形式的名称，不支持数字形式的名称。如果使用 IF NOT EXISTS 关键字，则必须指定定时任务的名称。
sconst	指定的 SQL 语句。目前，只支持 INSERT、UPDATE、DELETE 语句。SQL 语句需要指定具体的数据库和表。
RECURRING crontab_expr	指定定时任务执行的时间点和周期，支持以下字段表达方式： - 7 字段表达式，即全字段表达式，字段之间使用空格分隔（<seconds> <minutes> <hours> <day-of-month> <month> <day-of-week> <year>）。其中 seconds 预设为 0，表示 0 秒执行。 - 6 字段表达式，字段之间使用空格分隔（<minutes> <hours> <day-of-month> <month> <day-of-week> <year>），其中，year 字段预设为 *，表示所有年份都适用。 - 5 字段表达式，字段之间使用空格分隔（<minutes> <hours> <day-of-month> <month> <day-of-week>）。 - 预定义表达式，具体包括 @annually（每年 1 月 1 日 0 点 0 分 0 秒运行一次）、@yearly（每年 1 月 1 日 0 点 0 分 0 秒运行一次，同@annually）、@monthly（每月 1 日 0 点 0 分 0 秒运行一次）、@weekly（每周日 0 点 0 分 0 秒运行一次）、@daily（每天 0 点 0 分 0 秒运行一次）、@hourly（每小时 0 分 0 秒开始时运行） 有关字段表达式的详细说明，参见字段表达式说明。
schedule_option	执行定时任务的选项，支持以下可选设置： first_run：指定在特定时间执行定时任务。如未指定，默认在下一个 RECURRING 时间执行定时任务，支持 TIMESTAMPTZ 类型和 NOW。 on_execution_failure：指定在执行过程中发生错误时应执行的操作。支持以下选项： - retry：立即重试执行定时任务。 - pause：表示暂停定时任务。暂停后，用户需要手动恢复定时任务。 - reschedule：（默认值）表示在下一个 RECURRING 时间执行重试执行定时任务。 on_previous_running：如果之前的定时任务仍在运行中，如何执行新的定时任务。支持以下选项： - start：立即执行新的定时任务。 - skip：不执行新的定时任务。 - wait：（默认值）等上一个定时任务完成后，再执行新的定时任务。

字段表达式说明

字段名称	取值范围	特殊字符	特殊字符说明
seconds	[0, 59]	星号（*） 逗号（,） 连字符（-） 斜线（/）	星号（*）：表示与字段的所有值匹配。例如，0 0 0 1 1 * * 表示每年的 1 月 1 日 0 点 0 分 0 秒运行一次。 逗号（,）：用于分割多个数值，表示任务将在数值对应的时间点执行。例如，10, 15, 30 在分钟字段表示在第 10 分钟、第 15 分钟和第 30 分钟执行任务。 连字符（-）：表示指定范围，例如，2000-2010 表示公元 2000 年至 2010 年之间的每一年，包括 2000 年和 2010 年。 斜线（/）：表示指定增量。例如，*/15 在分钟字段表示每 15 分钟执行一次任务。 字符 L：表示 last，在 day of month 字段中使用时表示一个月的最后一天，在 day of week 字段中使用时，允许指定月份的最后一个星期几，例如 5L 表示最后一个星期五。 字符 W：指定离给定日期最近的工作日（星期一至星期五）。15W 表示离指定月份第 15 日最近的工作日。如果 15 日是星期六，就会在 14 日星期五触发。如果 15 日是星期日，就会在 16 日星期一触发。如果 15 日是星期二，就会在 15 日星期二触发。W 字符可以与 L 组合，即 LW 表示一个月的最后一个工作日。注意：执行时不会跳过一个月的天数边界。如果设置为 1W，且第 1 天是星期六，则将在第 3 天的星期一触发。只有 day of month 字段的值是单个日期值，而不是一个日期范围或列表时，才能指定 W 字符。 井号（#）：表示指定增量。例如，用于 day of week 字段，后面必须跟一个 1 到 5 之间的数字。表示第几个特定星期几，例如，5#2 表示第二个星期五。
minutes	[0, 59]	星号（*） 逗号（,） 连字符（-） 斜线（/）
hour	[0, 23]	星号（*） 逗号（,） 连字符（-） 斜线（/）
day of month	[1, 31]	星号（*） 逗号（,） 连字符（-） 斜线（/） 字符 L 字符 W
month	[1,12]或者 JAN-DEC	星号（*） 逗号（,） 连字符（-） 斜线（/）
day of week	[0,7]或者 SUN-SAT。0 和 7 都表示星期日，兼容 linux 的 crontab。	星号（*） 逗号（,） 连字符（-） 斜线（/） 字符 L 井号（#）
year	[1970, 2099]	星号（*） 逗号（,） 连字符（-） 斜线（/）

语法示例

以下示例创建一个名为 s1 的定时任务，每小时将 tsdb.t1 表中的数据写入到 tsdb.t2 表中。

CREATE SCHEDULE s1 FOR SQL 'INSERT INTO tsdb.t2 SELECT * FROM tsdb.t1' RECURRING '@hourly' WITH SCHEDULE OPTIONS first_run=NOW;

查看定时任务

SHOW SCHEDULE 语句用于查看系统默认创建的以下定时任务：

• 表生命周期管理，任务名称为 scheduled_table_retention。
• 表压缩，任务名称为 scheduled_table_compress。

所需权限

• 非三权分立模式下，用户具有 Admin 角色。默认情况下，root 用户具有 Admin 角色。
• 三权分立模式下，用户是 sysadmin、secadmin 或 auditadmin 用户。

语法格式

参数说明

参数	说明
schedule_name	待查看定时任务的名称。

返回字段说明

参数	描述
id	定时任务 ID
name	定时任务名称
schedule_status	任务状态
next_run	下次执行时间
state	状态，显示空值或错误及建议处理措施。
recurrence	调度周期
jobsrunning	正在运行的任务
owner	创建用户
created	创建时间
command	执行的 SQL 命令

语法示例

• 查看系统创建的定时任务信息。

  show schedules;
          id         |              name          | schedule_status |         next_run          | state | recurrence | jobsrunning | owner |             created              |                                                 command
  ---------------------+----------------------------+-----------------+---------------------------+-------+------------+-------------+-------+----------------------------------+-----------------------------------------------------------------------------------------------------------
  958737479282262017 | scheduled_table_statistics | ACTIVE          | 2024-04-09 10:00:00+00:00 |       | @hourly    |           0 | root  | 2024-04-09 09:10:58.995182+00:00 | {"insert_statement": "INSERT INTO ts_table VALUES ('2023-07-13 14:06:32.272', 10.2, 219, 0.32, 1,1)"}
  (1 row)
  

• 查看指定的定时任务信息。

  show schedule scheduled_table_statistics;
          id         |              name          | schedule_status |         next_run          | state | recurrence | jobsrunning | owner |             created              |                                                 command
  ---------------------+----------------------------+-----------------+---------------------------+-------+------------+-------------+-------+----------------------------------+-----------------------------------------------------------------------------------------------------------
  958737479282262017 | scheduled_table_statistics | ACTIVE          | 2024-04-09 10:00:00+00:00 |       | @hourly    |           0 | root  | 2024-04-09 09:10:58.995182+00:00 | {"insert_statement": "INSERT INTO ts_table VALUES ('2023-07-13 14:06:32.272', 10.2, 219, 0.32, 1,1)"}
  (1 row)
  

修改定时任务

ALTER SCHEDULE 语句用于修改数据库中已存在的定时任务。修改将在下一个调度时间生效，不影响正在执行的任务和定时任务的状态。

所需权限

• 非三权分立模式下，用户具有 Admin 角色。默认情况下，root 用户具有 Admin 角色。
• 三权分立模式下，用户是 sysadmin 角色的成员。默认情况下，sysroot 用户属于 sysadmin 角色。

语法格式

参数说明

参数	说明
schedule_name	待修改的定时任务的名称。
RECURRING crontab_expr	指定定时任务执行的时间点和周期，支持以下字段表达方式： - 7 字段表达式，即全字段表达式，字段之间使用空格分隔（<seconds> <minutes> <hours> <day-of-month> <month> <day-of-week> <year>）。 - 6 字段表达式，字段之间使用空格分隔（<minutes> <hours> <day-of-month> <month> <day-of-week> <year>）。其中 seconds 预设为 0，表示 0 秒执行。 - 5 字段表达式，字段之间使用空格分隔（<minutes> <hours> <day-of-month> <month> <day-of-week>），其中，year 字段预设为 *，表示所有年份都适用。 - 预定义表达式，具体包括 @annually（每年 1 月 1 日 0 点 0 分 0 秒运行一次）、@yearly（每年 1 月 1 日 0 点 0 分 0 秒运行一次，同@annually）、@monthly（每月 1 日 0 点 0 分 0 秒运行一次）、@weekly（每周日 0 点 0 分 0 秒运行一次）、@daily（每天 0 点 0 分 0 秒运行一次）、@hourly（每小时 0 分 0 秒开始时运行） 有关字段表达式的详细说明，参见字段表达式说明。
schedule_option	定时任务相关的执行选项，支持以下可选设置： - first_run：指定未来时间的执行计划。如未指定，默认根据下一个 RECURRING 时间执行计划，支持 TIMESTAMPTZ 类型和 NOW。 - on_execution_failure：指定在执行过程中发生错误时应执行的操作。默认值是 reschedule，表示根据 RECURRING 表达式重新安排下一次时间来重试执行。也支持设置为 pause，表示暂停定时任务。暂停后，用户需要手动恢复任务。 - on_previous_running：如果按计划启动的上一次任务仍在运行应执行的操作。默认值为 skip，表示跳过新的执行，然后根据 RECURRING 表达式安排下一次运行。

语法示例

以下示例每小时执行一次定时任务。

ALTER SCHEDULE scheduled_table_statistics RECURRING '@hourly';

暂停定时任务

系统在进行导入大量数据等高负载工作时，为了避免进一步加重系统负载或干扰关键任务，可以暂停预定的定时任务。暂停命令会在下一个调度时间生效，不影响当前正在执行的任务或定时任务的状态。

PAUSE SCHEDULE 语句用于暂停已创建的定时任务。

所需权限

• 非三权分立模式下，用户具有 Admin 角色。默认情况下，root 用户具有 Admin 角色。
• 三权分立模式下，用户是 sysadmin 角色的成员。默认情况下，sysroot 用户属于 sysadmin 角色。

语法格式

参数说明

参数	说明
schedule_name	待暂停的定时任务名称，任务状态必须是 running。

语法示例

以下示例暂停指定的定时任务。

PAUSE SCHEDULE scheduled_table_statistics;

恢复定时任务

RESUME SCHEDULE 语句用于恢复已暂停的定时任务。

所需权限

• 非三权分立模式下，用户具有 Admin 角色。默认情况下，root 用户具有 Admin 角色。
• 三权分立模式下，用户是 sysadmin 角色的成员。默认情况下，sysroot 用户属于 sysadmin 角色。

语法格式

参数说明

参数	说明
schedule_name	待恢复的定时任务的名称，任务状态必须是 paused。

语法示例

以下示例恢复指定的定时任务。

RESUME SCHEDULE scheduled_table_statistics;

删除定时任务

DROP SCHEDULE 语句用于删除定时任务。目前，不支持删除系统创建的 scheduled_table_compress、scheduled_table_retention 默认定时任务。

所需权限

• 非三权分立模式下，用户具有 Admin 角色。默认情况下，root 用户具有 Admin 角色。
• 三权分立模式下，用户是 sysadmin 角色的成员。默认情况下，sysroot 用户属于 sysadmin 角色。

语法格式

参数说明

参数	说明
IF EXISTS	可选关键字。当使用 IF EXISTS 关键字时，如果目标定时任务存在，系统删除目标定时任务。如果目标定时任务不存在，系统删除定时任务失败，但不会报错。当未使用 IF EXISTS 关键字时，如果目标定时任务存在，系统删除目标定时任务。如果目标定时任务不存在，系统报错，提示目标定时任务不存在。
schedule_name	待删除定时任务的名称。
select_stmt	选择查询子句，返回待删除定时任务的名称。

语法示例

• 删除单个定时任务。

  DROP SCHEDULE s1;
  

• 使用 SELECT 子句查询定时任务名称并删除目标定时任务。

  DROP SCHEDULES SELECT name FROM [SHOW SCHEDULES] WHERE schedule_status='PAUSED';