CREATE TASK / ALTER TASK / DROP TASK / EXECUTE TASK / SHOW TASKS¶
Create, alter, drop, execute, and inspect MatrixOne SQL tasks. A SQL task is a named server-side job that runs a SQL body on a cron schedule or on demand, with optional WHEN gate, RETRY count, and TIMEOUT; run history is exposed via SHOW TASKS and SHOW TASK RUNS.
Description¶
A SQL task is a MatrixOne-managed scheduled job that runs a user-supplied SQL body. Tasks are owned by the account that created them; each task has an optional cron schedule, an optional WHEN gate that must evaluate truthy before a run is allowed, a retry limit, a timeout, and a SQL body placed between BEGIN and END.
Task runs can be triggered:
automatically by the scheduler whenever the cron expression fires, or
manually with
EXECUTE TASK.
Run history is persisted in mo_task.sql_task_run and is also exposed via SHOW TASK RUNS.
Syntax¶
CREATE TASK¶
CREATE TASK [IF NOT EXISTS] <task_name>
[SCHEDULE '<cron_expr>' [TIMEZONE '<tz_name>']]
[WHEN ( <gate_expr> )]
[RETRY <retry_limit>]
[TIMEOUT '<duration>']
AS BEGIN
<sql_statement>;
[<sql_statement>; ...]
END;
ALTER TASK¶
ALTER TASK <task_name> SUSPEND
ALTER TASK <task_name> RESUME
ALTER TASK <task_name> SET SCHEDULE '<cron_expr>' [TIMEZONE '<tz_name>']
ALTER TASK <task_name> SET WHEN ( <gate_expr> )
ALTER TASK <task_name> SET RETRY <retry_limit>
ALTER TASK <task_name> SET TIMEOUT '<duration>'
DROP TASK¶
DROP TASK [IF EXISTS] <task_name>
EXECUTE TASK¶
EXECUTE TASK <task_name>
SHOW TASKS / SHOW TASK RUNS¶
SHOW TASKS
SHOW TASK RUNS [FOR <task_name>] [LIMIT <n>]
Arguments¶
Parameter |
Description |
|---|---|
|
Identifier of the task. Unique per account. |
|
Cron expression parsed by the |
|
IANA time-zone name applied to the cron schedule (e.g. |
|
Optional gate expression re-evaluated at every run. The run body executes only when the expression converts to true; otherwise the run is recorded with |
|
Maximum number of extra retry attempts after a failing run. Default is |
|
Per-attempt body timeout. Go duration is parsed and truncated to whole seconds. Use |
|
SQL body. Each inner statement ends with |
|
Disable or re-enable scheduler firing for the task. |
Usage Notes¶
Name uniqueness.
CREATE TASKfails withsql task <name> already existswhen a task with the same name already exists for the account.IF NOT EXISTSturns re-creation into a no-op.Missing task.
ALTER TASK,DROP TASK, andEXECUTE TASKfail withsql task <name> not foundwhen the task does not exist.DROP TASK IF EXISTSturns this into a no-op.Non-overlapping runs. At most one run of a given task executes at a time;
EXECUTE TASKon a task that is already running fails withsql task is already running.Task service readiness. If the task service has not yet initialized on the current CN, the statement fails with
task service not ready yet, please try again later.and can be retried once the service comes up.Timeout precision. v4.2.5 stores whole seconds:
'500ms'becomes 0 (no body timeout),'1500ms'becomes 1 second. Zero sets no body timeout; negative and malformed durations are rejected.Gate semantics. The
WHENexpression is re-evaluated at every run. A skipped run is recorded with statusSKIPPED; it does not consume a retry attempt.SHOW TASKS columns.
task_name,schedule,enabled,gate_condition,retry_limit,timeout,created_at,last_run_status,last_run_time.SHOW TASK RUNS columns.
run_id,task_name,trigger_type,status,started_at,finished_at,duration,attempt,rows_affected,error_message.trigger_typeisMANUALforEXECUTE TASKandSCHEDULEDfor cron-fired runs.LIMIT ncaps the most recent rows;FOR task_namefilters by task.Manual and scheduled history share
mo_task.sql_task_run. Filter ontrigger_typeto distinguish them.
Examples¶
The task body is delimited by
BEGIN/ENDand contains embedded;terminators, so the statement cannot be sent through a plain;-delimited client without a custom delimiter. Treat the following SQL blocks as templates; in practice, use a client that supports a delimiter switch (for example themysqlclient’sDELIMITERcommand) to issue theCREATE TASKstatements.
Example 1 — scheduled task with a cron expression:
CREATE TASK IF NOT EXISTS <task_name>
SCHEDULE '0 0 0 1 1 *'
TIMEZONE 'UTC'
AS BEGIN
INSERT INTO <target_table>(<marker_col>) VALUES ('cron');
END;
Example 2 — manual-only task (no SCHEDULE), fired via EXECUTE TASK:
CREATE TASK IF NOT EXISTS <task_name>
AS BEGIN
INSERT INTO <target_table>
SELECT 1 WHERE NOT EXISTS (SELECT 1 FROM <target_table> WHERE id = 1);
END;
Example 3 — gated task with WHEN, retry, and per-run timeout:
CREATE TASK IF NOT EXISTS <task_name>
WHEN (EXISTS (SELECT 1 FROM <gate_table> WHERE id = 1))
RETRY 1
TIMEOUT '30s'
AS BEGIN
INSERT INTO <sink_table>
SELECT 'gate-ok'
WHERE NOT EXISTS (SELECT 1 FROM <sink_table> WHERE tag = 'gate-ok');
END;
Example 4 — alter, suspend, resume, execute, inspect, drop:
ALTER TASK <task_name> SET SCHEDULE '*/1 * * * * *' TIMEZONE 'UTC';
ALTER TASK <task_name> SET WHEN (EXISTS (SELECT 1 FROM <gate_table> WHERE id = 1));
ALTER TASK <task_name> SET RETRY 2;
ALTER TASK <task_name> SET TIMEOUT '1m';
ALTER TASK <task_name> SUSPEND;
ALTER TASK <task_name> RESUME;
EXECUTE TASK <task_name>;
SHOW TASKS;
SHOW TASK RUNS FOR <task_name> LIMIT 5;
DROP TASK IF EXISTS <task_name>;
Notes¶
SCHEDULEaccepts the 6-field cron form used byrobfig/cron/v3(including seconds); classic 5-field expressions may be rejected. UseTIMEZONEto anchor the schedule to a specific IANA zone.The SQL body runs with the creating user’s role and default database; cross-account access is not granted implicitly.
A
TIMEOUTthat elapses mid-run aborts the current statement and records the run as a timeout inmo_task.sql_task_run. Retries (if any) are performed up toRETRY retry_limitadditional attempts.Dropping a task removes its definition but does not delete rows already written to
mo_task.sql_task_run.
Execution and transaction boundaries¶
Manual EXECUTE TASK returns after execution finishes; scheduled runs execute through the background TaskService. SQL statements execute individually. BEGIN ... END does not provide whole-body atomicity: earlier successful writes can remain committed after a later failure. RETRY starts again at the beginning and may repeat writes; use idempotent business logic. See the runnable tutorial for a comparison with DML rollback inside a single SQL procedure.
Statuses, the UTC default, whole-second timeouts, and failure boundaries were checked against v4.2.5 source and single-CN runtime results on 2026-10-14.