定時任務（Cron Job）

背景資訊

從 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
);