定时任务（Cron Job）-实时数仓 Hologres(Hologres)-阿里云帮助中心

背景信息

从 Hologres V4.2 版本起，Hologres 提供 Holo Cron 定时任务（Cron Job）功能。您可以通过 hologres.hg_register_cron_job 等系统函数，按照指定的 cron 表达式或调度间隔，定时自动执行 SQL 语句。该功能适用于以下典型场景：

数据定时导入：定时将业务数据从源表导入目标表。
数据定时清理：定时执行 TRUNCATE、DELETE 等操作清理过期数据。
数据定时计算：定时刷新汇总表、构建索引或更新物化视图等。

使用限制

暂不支持 DDL 和 DML 混合事务，一个定时任务中的 SQL 语句必须是纯 DDL 或纯 DML。
暂不支持查询语句（DQL），定时任务只能执行数据操作语句。
调度任务有最大并发数限制，默认最大 100 并发。同一时间产生的超过并发数限制的 task 可能会被延迟执行。
每个 task 运行时会占用 1 个对应 warehouse 上的连接数。
同一个 job 只会有一个 task 并发调度，如果 task 运行超过了原本应该下一次调度 task 的时间，下一次 task 会被跳过。
删除 Cron Job 后，正在运行的 task 会等待其跑完，不会被打断，但下一次不会再被调度。

权限说明

普通用户：仅能注册、管理、查看自己名下的定时任务。
Superuser：可以注册、管理、查看任意用户的定时任务。

命令参考

注册定时任务：hologres.hg_register_cron_job

使用 hologres.hg_register_cron_job 注册一个新的定时任务。语法如下：

SELECT hologres.hg_register_cron_job(
  job_name => '<job_name>',
  command => '<command>',
  [comment => '<comment>',]
  [schedule => '<schedule>',]
  [warehouse_id => '<warehouse_id>',]
  [db_name => '<db_name>',]
  [user_name => '<user_name>',]
  [retry_count => '<retry_count>',]
  [starts_time => '<starts_time>',]
  [ends_time => '<ends_time>',]
  [interval_text => '<interval_text>']
);

schedule 和 interval_text 两个参数必须至少指定其中一个，用于声明任务的调度计划。

参数详细说明请参见参数说明。

修改定时任务：hologres.hg_alter_cron_job

使用 hologres.hg_alter_cron_job 修改已注册的定时任务。语法如下：

SELECT hologres.hg_alter_cron_job(
  job_name => '<job_name>',
  command => '<command>',
  comment => '<comment>',
  schedule => '<schedule>',
  warehouse_id => '<warehouse_id>',
  db_name => '<db_name>',
  retry_count => '<retry_count>',
  active => '<active>',
  starts_time => '<starts_time>',
  ends_time => '<ends_time>',
  interval_text => '<interval_text>'
);

使用 hologres.hg_alter_cron_job 修改定时任务时，所有参数都是必填项，必须显式传入全部参数（包括与原任务相同的字段），否则会修改失败。如需将某个字段重置为默认值，请显式传入 NULL。

active 是 hologres.hg_alter_cron_job 独有的参数，用于控制定时任务是否启用。设置为 true 表示启用，false 表示暂停调度，但保留该任务的注册信息。其余参数含义与注册定时任务一致。

删除定时任务：hologres.hg_unregister_cron_job

使用 hologres.hg_unregister_cron_job 删除指定的定时任务。语法如下：

SELECT hologres.hg_unregister_cron_job('<job_name>');

删除 Cron Job 后，正在运行中的 task 会继续执行至完成，不会被中断；但删除完成后该 job 不会再被调度。

查看定时任务：hg_user_cron_jobs / hg_user_cron_tasks

查询当前定时任务列表（已注册但未执行的 job 信息），可以通过 hologres.hg_user_cron_jobs 视图：

SELECT * FROM hologres.hg_user_cron_jobs;

查询定时任务的历史执行记录及错误信息，可以通过 hologres.hg_user_cron_tasks 视图：

SELECT * FROM hologres.hg_user_cron_tasks;

普通用户仅能查看自己注册的 Cron Job 和 task 信息；Superuser 可以查看所有用户的 Cron Job 和 task 信息。

参数说明

下表列出了 hologres.hg_register_cron_job 和 hologres.hg_alter_cron_job 的参数说明。其中，active 仅 hologres.hg_alter_cron_job 支持。

参数	类型	是否必填	说明
job_name	text	是	任务名称。最长 128 字节，仅支持字母、数字、下划线。禁止注册重复 `job_name` 的任务。
command	text	是	欲执行的 SQL 命令。建议使用 `$$` 包裹，例如 `$$INSERT INTO tbl VALUES(1)$$`，避免转义问题。支持多条语句，但不支持 DDL 和 DML 混合，也不支持 DQL，否则会报错。
comment	text	否	任务描述。默认值为 `NULL`。
schedule	text	否	cron 表达式。无效的 cron 表达式会在真正调度时报错 `invalid cron expression`。默认值为 `NULL`，此时会尝试用 `interval_text` 字段来指定调度间隔时间。`schedule` 和 `interval_text` 必须至少指定其中一个。表达式格式详见Cron 表达式说明。
warehouse_id	int	否	期望执行 `command` 时连接的 warehouse id。需要注意 warehouse 的权限。默认值为 `-1`，表示实例级别的 default warehouse。非 warehouse 实例忽略该参数。
db_name	text	否	执行 `command` 的 database。必须是实例已存在的 database，否则报错。默认值为当前 database。
user_name	text	否	执行 `command` 时使用的 user。普通用户仅能注册 user_name 为当前用户的 job；Superuser 可以注册任意 user 的 job。默认值为当前用户。仅 `hologres.hg_register_cron_job` 支持。
retry_count	int	否	定时任务执行失败时的最大重试次数。范围是 0 到 10。默认值为 `0`。
active	boolean	是（仅 hg_alter_cron_job 必填）	控制定时任务是否启用。`true` 表示启用，`false` 表示暂停调度，但保留任务注册信息。仅 `hologres.hg_alter_cron_job` 支持。
starts_time	text	否	指定定时任务调度的开始时间。调度时刻早于 `starts_time` 的 job 将被跳过。默认值为 `NULL`，表示不限制开始时间，第一次调度从当前时间开始。
ends_time	text	否	指定定时任务调度的结束时间。调度时刻晚于 `ends_time` 的 job 将被跳过。默认值为 `NULL`，表示不限制结束时间。
interval_text	text	否	当 `schedule` 为 `NULL` 时，使用该字段指定调度间隔时间。格式为「数字 + 时间单位」，支持 `minute/minutes/hour/hours`。例如 `1 hour`、`35 minutes` 都是合法值。默认值为 `NULL`。

使用示例

示例 1：每 5 分钟执行一次数据导入

从当前时间开始，每 5 分钟从 a 表导入数据到 b 表。可以使用 schedule 或 interval_text 两种方式实现。

方式一：使用 schedule（cron 表达式）

SELECT hologres.hg_register_cron_job(
  job_name => 'job_import_data',
  command => 'INSERT INTO b SELECT * FROM a;',
  schedule => '0 */5 * * * ?'
);

方式二：使用 interval_text

SELECT hologres.hg_register_cron_job(
  job_name => 'job_import_data',
  command => 'INSERT INTO b SELECT * FROM a;',
  interval_text => '5 minutes'
);

示例 2：指定时间范围内每小时执行 TRUNCATE

在 2026 年 4 月期间，每小时整点对 test_db 中的 tbl 表执行 TRUNCATE，使用 warehouse 1 上的资源执行，失败时最多重试 5 次。

SELECT hologres.hg_register_cron_job(
  job_name => 'job_truncate_tbl',
  comment => '定时TRUNCATE',
  schedule => '0 0 */1 * * ?',
  command => $$TRUNCATE tbl$$,
  warehouse_id => 1,
  db_name => 'test_db',
  retry_count => 5,
  starts_time => '2026-04-01 00:00:00+08',
  ends_time => '2026-04-30 23:59:59+08'
);

Cron 表达式说明

schedule 参数使用标准的 cron 表达式，Hologres 采用 7 段式格式（含秒和年），与常见的 5 段式 unix cron 不同。表达式各字段含义如下：

秒  分  时  日  月  星期  年（年可选）

Hologres 的 cron 表达式遵循 Java（Quartz）风格，与 unix 5 段式 cron（分时日月星期）不同，多了「秒」和「年」字段。如果使用在线 cron 表达式生成器，请明确选择 Java（Quartz）格式以避免格式不兼容。

常用 cron 表达式示例：

表达式	说明
`0 0 * * * ?`	每小时执行一次。
`0 0 0 * * ?`	每天 0 点执行一次。
`0 0 0 * * 1`	每周一 0 点执行一次。
`0 0 0 1 * ?`	每月 1 日 0 点执行一次。
`0 /5 * * ?`	每 5 分钟执行一次。

您可以使用在线工具辅助生成 cron 表达式，请选择 Java（Quartz）格式。

常见问题

定时任务执行失败如何排查？

查询 hologres.hg_user_cron_tasks 视图，查看历史执行记录及错误信息。
检查 SQL 语句是否存在语法错误。
检查 user_name 指定的执行用户是否具有相应权限。

定时任务错过调度怎么办？

当并发调度资源耗尽，或 task 运行时间过长导致下一次调度被跳过时，可以采取以下措施：

调整调度间隔，避免任务堆积。
优化 SQL 执行性能，缩短单次执行时间。
合理评估并发任务规模，避免超出默认 100 并发上限。

如何暂停定时任务？

使用 hologres.hg_alter_cron_job，将 active 参数设置为 false 即可暂停定时任务。再次启用时，将 active 设置为 true 即可。

由于 hologres.hg_alter_cron_job 要求所有参数必填，暂停时需要传入该任务的全部参数（包括与原任务相同的字段），不能仅传 active。

SELECT hologres.hg_alter_cron_job(
  job_name => 'job_import_data',
  command => 'INSERT INTO b SELECT * FROM a;',
  comment => '数据导入任务',
  schedule => '0 */5 * * * ?',
  warehouse_id => -1,
  db_name => 'mydb',
  retry_count => 0,
  active => false,
  starts_time => NULL,
  ends_time => NULL,
  interval_text => NULL
);