MaxCompute:Periodic tasks (invitational preview)

Syntax

CREATE TASK [IF NOT EXISTS] <task_name>
    SCHEDULE = "<num> [minute|minutes] | [second|seconds]"
    [TASKPROPERTIES("schedule_strategy"="<retries>",
                   "odps.namespace.schema"="true" ...)]
    [COMMENT task_comment]
    [WHEN <bool_expr>]
    AS <taskBody>;

Parameters

Example: create a task with a stream condition

This example creates a task that reads new rows from a Delta Table stream and inserts them into a destination table every 5 minutes. The task body runs only when the stream has new data.

Step 1: Create the destination Delta Table.

CREATE TABLE acid2_table_dest (
  pk BIGINT NOT NULL PRIMARY KEY,
  val BIGINT
) tblproperties ("transactional"="true");

Step 2: Create the source Delta Table and a stream on it.

-- Source Delta Table
CREATE TABLE delta_table_src (
  pk BIGINT NOT NULL PRIMARY KEY,
  val BIGINT
) tblproperties ("transactional"="true");

-- Stream on the source table (append mode, starting from version 1)
CREATE STREAM delta_table_stream
ON TABLE delta_table_src version as of 1
strmproperties('read_mode'='append')
comment 'stream demo';

Step 3: Create the periodic task.

SET odps.sql.periodic.task.enabled=true;

CREATE TASK IF NOT EXISTS periodic_task1
  SCHEDULE = '5 minutes'
  TASKPROPERTIES('schedule_strategy'='3')
  COMMENT 'task_comment'
  WHEN stream_has_data('delta_table_stream')
  AS INSERT INTO acid2_table_dest SELECT pk, val FROM delta_table_stream;

stream_has_data('delta_table_stream') is equivalent to running SELECT stream_has_data('delta_table_stream'); in MaxCompute. With schedule_strategy=3, the task retries up to 3 times if a scheduled run fails.

Step 4: Insert test data and verify the result.

-- Insert test data into the source table
INSERT INTO delta_table_src VALUES (1, 1), (2, 2);

-- After the next scheduled run, query the destination table
SELECT * FROM acid2_table_dest;

Expected output:

+------------+------------+
| pk         | val        |
+------------+------------+
| 1          | 1          |
| 2          | 2          |
+------------+------------+

Syntax

Modify schedule, properties, or comment:

ALTER TASK [IF EXISTS] <task_name>
    SET SCHEDULE = "<num> [minute|minutes] | [second|seconds]"
    [TASKPROPERTIES("schedule_strategy"="<retries>", ...)]
    [COMMENT task_comment];

Suspend or resume:

ALTER TASK [IF EXISTS] <task_name> resume | suspend;

Modify the WHEN condition:

ALTER TASK [IF EXISTS] <task_name> MODIFY WHEN <boolean_expr>;

Parameters

For SCHEDULE and TASKPROPERTIES, see Parameters in the Create a periodic task section.

Common scenarios

Suspend a task, update its schedule and retry count, then resume:

ALTER TASK periodic_task1 suspend;
ALTER TASK IF EXISTS periodic_task1 SET SCHEDULE = '6 minute';
ALTER TASK IF EXISTS periodic_task1 SET TASKPROPERTIES('schedule_strategy'='5');
ALTER TASK periodic_task1 resume;

Update the WHEN condition:

ALTER TASK IF EXISTS periodic_task1 MODIFY WHEN 1=1;

Add or update a comment:

ALTER TASK IF EXISTS periodic_task1 SET COMMENT 'comment2';

Syntax

SET odps.sql.periodic.task.enabled=true;

DROP TASK [IF EXISTS] <task_name>;

Parameters

Example

SET odps.sql.periodic.task.enabled=true;

DROP TASK periodic_task1;

Use commands

View basic information:

DESC TASK <task_name>;

View extended information:

DESC EXTENDED TASK <task_name>;

Example output for DESC TASK periodic_task1:

+------------------------------------------------------------------------------------+
| Owner:                    ALIYUN$odps****@aliyun.com                               |
| Project:                  sql_odps2                                                |
| Schema:                                                                            |
| Task:                     periodic_task1                                           |
+------------------------------------------------------------------------------------+
| CreateTime:               2024-08-23 11:05:46                                      |
| LastModifiedTime:         2024-08-23 11:05:46                                      |
+------------------------------------------------------------------------------------+
| ScheduleText:             '5 minute'                                               |
| TaskType:                 SQL                                                      |
| Query:                    insert into acid2_table_dest select pk, val from acid_stream; |
| Condition:                stream_has_data('acid_stream')                           |
| Status:                   ACTIVE                                                   |
| Comment:                                                                           |
+------------------------------------------------------------------------------------+

Use the console

1. Log on to the MaxCompute console and select a region.MaxCompute console

2. In the left navigation pane, choose Manage Configurations > Projects.

3. On the Projects page, find the target project and click Manage in the Actions column.

4. On the Project Settings page, select the Periodic Task tab to view all periodic tasks in the project.

5. Click Details in the Actions column of the target task.

6. In the View Periodic Task dialog box, review the Task Name, Task Status, Scheduling Cycle, and Execution Log.

7. Click an Instance ID to open the Job Insights page and view detailed execution logs.

Syntax

SHOW HISTORY FOR TASK <task_name> [[LIMIT <limit_value>] OFFSET <offset_value>];

Parameters

Examples

View all history for periodic_task1:

SHOW HISTORY FOR TASK periodic_task1;

Output:

+---------------------------------------------------------------------------------------------------+
| Project:                  muze_demo                                                               |
| Schema:                                                                                           |
| Task:                     periodic_task1                                                          |
+---------------------------------------------------------------------------------------------------+
| History:                                                                                          |
+---------------------------------------------------------------------------------------------------+
| InstanceId                       | CreateTime             | EndTime                | Status       |
+---------------------------------------------------------------------------------------------------+
| 202506130710002599mhgq4****      | 2025-06-13 15:10:00    | 2025-06-13 15:10:00    | Terminated   |
| 2025061307050039g47jzzs1****     | 2025-06-13 15:05:00    | 2025-06-13 15:05:00    | Terminated   |
| 2025061307000030o9vh1l1****      | 2025-06-13 15:00:00    | 2025-06-13 15:00:00    | Terminated   |
| 2025061306550032l84ahcr4****     | 2025-06-13 14:55:00    | 2025-06-13 14:55:00    | Terminated   |
| 2025061306500043cthoc62****      | 2025-06-13 14:50:00    | 2025-06-13 14:50:00    | Terminated   |
| 20250613064500324fkhaz1****      | 2025-06-13 14:45:00    | 2025-06-13 14:45:00    | Terminated   |
| 2025061306400048194cx8g****      | 2025-06-13 14:40:00    | 2025-06-13 14:40:00    | Terminated   |
| 20250613063500351g99kf2****      | 2025-06-13 14:35:00    | 2025-06-13 14:35:00    | Terminated   |
| 2025061306300084qkbtk9****       | 2025-06-13 14:30:00    | 2025-06-13 14:30:00    | Terminated   |
| 20250613062501711nswoio****      | 2025-06-13 14:25:01    | 2025-06-13 14:25:01    | Terminated   |
| 2025061306200129vln5ncr4****     | 2025-06-13 14:20:01    | 2025-06-13 14:20:01    | Terminated   |
| 2025061306150119yhlkmbo****      | 2025-06-13 14:15:00    | 2025-06-13 14:15:01    | Terminated   |
| 2025061306100139uemvy7r6****     | 2025-06-13 14:10:00    | 2025-06-13 14:10:01    | Terminated   |
+---------------------------------------------------------------------------------------------------+

View the 6 most recent runs:

SHOW HISTORY FOR TASK periodic_task1 LIMIT 6 OFFSET 0;

Skip the 5 most recent runs and view the rest:

SHOW HISTORY FOR TASK periodic_task1 OFFSET 5;