All Products
Search

This Product

    MaxCompute:Periodic tasks (invitational preview)

    Document Center

    MaxCompute:Periodic tasks (invitational preview)

    Last Updated:Oct 20, 2025

    The MaxCompute periodic task feature lets you use SQL statements to customize scheduling and computing logic. This helps you manage scheduled tasks efficiently and flexibly. This feature provides shorter scheduling cycles, high-efficiency execution, and low-cost schedule management.

    Features

    MaxCompute periodic tasks allow you to flexibly customize task scheduling policies and run SQL computing logic. This automatically builds data pipelines and simplifies extract, transform, and load (ETL) workflows. You can also combine tasks with table data changes and stream reading to create continuous ETL workflows that process recently changed data. This feature has the following attributes:

    • SQL support: Manage all scheduled tasks using simple SQL statements.

    • Full lifecycle management: Create, modify, delete, and view tasks. You can also view task lists and task execution instance lists.

    • Second-level scheduling: Supports timed scheduling with a minimum interval of 10 seconds.

    • Built-in scheduling service: A more efficient and cost-effective service built into MaxCompute.

    • Conditional execution: Configure a `WHEN` expression as the instance startup condition to implement complex conditional logic.

    • Seamless integration: Works with objects within the platform. For example, it provides an efficient built-in scheduling service for objects that require regular refreshes, such as Delta Table change data capture (CDC) and Object Tables.

    • Automatic incremental data: By default, incremental CDC data is automatically generated in the background.

    This feature is in invitational preview. For more information, see Usage notes.

    Notes

    Before you create or delete a periodic task, you must set the SET odps.sql.periodic.task.enabled=true; parameter at the session level. This enables the periodic task feature. If you do not set this parameter, you cannot create or delete periodic tasks.

    Create a periodic task

    Syntax

    CREATE TASK [IF NOT EXISTS] <task_name>
    SCHEDULE = "<num> [minute|minutes] | [second|seconds]"
    [TASKPROPERTIES("schedule_strategy"="3",--Specify the number of retries for the scheduled task.
               "odps.namespace.schema"="true" ....];
    [COMMENT task_comment]
    [WHEN <bool_expr>]
    AS <taskBody>;

    Parameters

    Parameter

    Required

    Description

    IF NOT EXISTS

    No

    When you create a task:

    • If you specify this option, the statement returns a success message even if a task with the same name exists. The existing task is not affected.

    • If you do not specify this option, an error is returned if a task with the same name exists.

    task_name

    Yes

    The name of the periodic task.

    SCHEDULE = "<num> [minute|minutes] | [second|seconds]"

    Yes

    The execution interval. The supported units are minutes and seconds. The value must be in the range of 10 seconds to 3,540 seconds.

    Note

    The value for seconds must be between 10 and 59. For intervals of 60 seconds or more, use minutes as the unit.

    TASKPROPERTIES("schedule_strategy"="3","odps.namespace.schema"="true" ....]

    No

    Parameters to specify when the scheduled task executes the SQL statement. A common parameter is schedule_strategy, which specifies the number of retries for the scheduled task. Examples of SQL statements for scheduled task execution are as follows:

    • taskproperties('odps.stage.reducer.num'='100'): The number of Reduce Task instances for the automatically started task is 100.

    • taskproperties('odps.sql.reducer.memory'='2048'): The memory size of each Reduce Task instance for the automatically started task is 2048 MB.

    COMMENT task_comment

    No

    The comment for the periodic task. The comment must be a valid string of no more than 1,024 bytes. Otherwise, an error is returned.

    WHEN

    No

    Specifies a Boolean expression. The subsequent SQL statement is triggered only when this expression returns TRUE. If you do not configure this parameter, the default value is TRUE. Only specific functions are supported in the conditional statement.

    Note

    • Common scalar functions are supported in the Boolean expression. Window functions, aggregate functions, and nested subqueries are not supported.

    • You can use scalar functions such as `CURRENT_TIMESTAMP`, `GETDATE`, and `WEEKDAY` to get dates. You can use `TO_DATE`, `CONCAT`, `LENGTH`, `REGEXP_REPLACE`, `UPPER`, and `SPLIT` to perform conversions, calculations, and replacements. You can also use `MAX_PT`, `TABLE_EXISTS`, `PARTITION_EXISTS`, `STREAM_HAS_DATA`, and `TABLE_NEED_CDC_BUILD` to get table and partition information. For a list of supported functions, see Function whitelist.

    AS <taskBody>

    Yes

    The SQL task to execute. Statements that run in the code editor are not supported. Common Data Manipulation Language (DML) and Data Query Language (DQL) syntax is supported. Data Definition Language (DDL) is not supported.

    Example

    This example creates a scheduled task named periodic_task1. The task is scheduled to run every 5 minutes and retries up to three times if it fails. The SQL statement INSERT INTO acid2_table_dest SELECT pk, val FROM acid_stream is executed only if the conditional expression stream_has_data('delta_table_stream') returns TRUE.

    1. Create a Delta Table as the destination table.

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

    2. Create a Delta Table as the source table and create a stream associated with it.

      -- Create a Delta Table as the source table.
CREATE TABLE delta_table_src (
  pk bigint NOT NULL PRIMARY KEY,
  val bigint
) tblproperties ("transactional"="true");

-- Create a stream associated with the Delta Table.
CREATE STREAM delta_table_stream 
ON TABLE delta_table_src version as of 1 
strmproperties('read_mode'='append') 
comment 'stream demo';

    3. Create a periodic task named periodic_task1.

      --Enable automatic incremental updates for the 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;
      Note

      The conditional expression stream_has_data('delta_table_stream') is equivalent to running the SELECT stream_has_data('delta_table_stream'); command in MaxCompute.

    4. Insert data into the source Delta Table, wait for the schedule to complete, and then view the data in the destination table.

      -- Insert data into the source Delta Table.
INSERT INTO delta_table_src VALUES (1, 1), (2, 2);

-- Wait for the schedule to complete, and then view the data in the destination table.
SELECT * FROM acid2_table_dest;

      The following result indicates that the data was successfully written to the `acid2_table_dest` table.

      --Two records are returned.
+------------+------------+
| pk         | val        |
+------------+------------+
| 1          | 1          |
| 2          | 2          |
+------------+------------+

    Modify a periodic task

    Syntax

    • You can modify the schedule (execution interval), SQL parameters (such as the number of retries), and comments of a periodic task.

      ALTER TASK [IF EXISTS] <task_name>
    SET SCHEDULE = "<num> [minute|minutes] | [second|seconds]"
    [TASKPROPERTIES("schedule_strategy"="3",--Specify the number of retries for the scheduled task.
               "odps.namespace.schema"="true" ....];
    [COMMENT task_comment];

    • You can resume or suspend a periodic task.

      Note

      A periodic task starts automatically after it is created. If a task is paused due to an issue or a manual `suspend` operation, you can use the `resume` operation to restart it. After the task is resumed, its status changes to `ACTIVE`. You can verify the status by running the DESC command.

      ALTER TASK [IF EXISTS] task_name resume | suspend;

    • You can modify the WHEN expression for the trigger condition of a recurring scheduled task. Use this syntax to modify the expression after the task is created.

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

    Parameters

    Parameter

    Required

    Description

    IF EXISTS

    No

    When you modify a periodic task:

    • If you specify this option, the operation is skipped and a success message is returned if the specified periodic task does not exist. The specified task is modified if it exists.

    • If you do not specify this option, an error is returned if the specified periodic task does not exist.

    boolean_expr

    Yes

    The WHEN expression that specifies the trigger condition for a recurring schedule task.

    For more information about the other parameters, see Parameters.

    Examples

    • Example 1: Resume a periodic task

      ALTER TASK periodic_task1 resume;

    • Example 2: Suspend a periodic task

      ALTER TASK periodic_task1 suspend;

    • Example 3: Change the scheduling interval to 6 minutes

      ALTER TASK IF EXISTS periodic_task1 SET schedule = '6 minute';

    • Example 4: Add a comment

      ALTER TASK IF EXISTS periodic_task1 SET comment 'comment2';

    • Example 5: Set the number of retries for the periodic task to 5

      ALTER TASK IF EXISTS periodic_task1 SET taskproperties('schedule_strategy'='5');

    • Example 6: Modify the task trigger condition WHEN expression

      ALTER TASK IF EXISTS periodic_task1 MODIFY WHEN 1=1;

    View information about a periodic task

    Syntax

    • You can view information about a periodic task.

      DESC task <task_name>;

    • You can view information and extended information about a periodic task.

      DESC extended task <task_name>;

    Parameters

    task_name: The name of the periodic task.

    Example

    View information about the `periodic_task1`.

    DESC task periodic_task1;

    The following is a sample result:

    +------------------------------------------------------------------------------------+
| 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:                                                                           |
+------------------------------------------------------------------------------------+

    Delete a periodic task

    Syntax

    DROP TASK [IF EXISTS] <task_name>;

    Parameters

    Parameter

    Required

    Description

    IF EXISTS

    No

    When you delete a periodic task:

    • If you specify this option, the operation is skipped and a success message is returned if the specified periodic task does not exist. The specified task is deleted if it exists.

    • If you do not specify this option, an error is returned if the specified periodic task does not exist.

    task_name

    Yes

    The name of the periodic task to delete.

    Example

    To delete the `periodic_task1` task, run the following command:

    DROP TASK periodic_task1;

    View a list of all periodic tasks

    You can use the following SQL statement to view all periodic tasks in the current MaxCompute project.

    Syntax

    SHOW TASKS;

    Example

    You can view the created periodic tasks.

    SHOW TASKS;

    The following is a sample result:

    +--------------------------------------------------------------------------------------------------------------------------------+
| Project:                  openmronlot_daily_arm_src3_xr                                                                        |
| Schema:                                                                                                                        |
+--------------------------------------------------------------------------------------------------------------------------------+
| Tasks:                                                                                                                         |
+--------------------------------------------------------------------------------------------------------------------------------+
| Name                      | Owner                             | CreateTime             | LastModifiedTime       | Status       |
+--------------------------------------------------------------------------------------------------------------------------------+
| periodic_task1            | ALIYUN$odpst****@aliyun.com       | 2024-07-26 16:19:06    | 2024-07-26 16:19:06    | ACTIVE       |
| periodic_task2            | ALIYUN$odpst****@aliyun.com       | 2024-07-26 16:19:28    | 2024-07-26 16:19:28    | ACTIVE       |
| periodic_task3            | ALIYUN$odpst****@aliyun.com       | 2024-07-26 16:20:45    | 2024-07-26 16:20:45    | ACTIVE       |
| periodic_task6            | ALIYUN$odpst****@aliyun.com       | 2024-08-15 11:09:55    | 2024-08-15 11:09:55    | ACTIVE       |
| periodic_task_alter1      | ALIYUN$odpst****@aliyun.com       | 2024-07-26 16:17:40    | 2024-07-26 16:17:40    | ACTIVE       |
+--------------------------------------------------------------------------------------------------------------------------------+

    View the history of automatically scheduled instances for a periodic task

    You can view the InstanceId, CreateTime, EndTime, and Status of automatically scheduled instances for a periodic task.

    Note

    To view the detailed log of an automatically scheduled instance, run the WAIT <InstanceId>; command. For example, run WAIT 2024082309000177gq71ut9****; to obtain the MaxCompute Logview URL. You can then copy the Logview URL to a browser to view the detailed log.

    Syntax

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

    Parameters

    Parameter

    Required

    Description

    task_name

    Yes

    The name of the periodic task.

    limit_value

    No

    The number of records to display. For example, LIMIT 50 displays only 50 records.

    The value of limit_value must be greater than 0. Otherwise, an error is returned. If you do not specify this parameter, as many records as possible are displayed.

    offset_value

    No

    The starting position. This specifies the number of records to skip. A value of 0 indicates that the starting position is the latest task record.

    Examples

    • Example 1: View the history of automatically scheduled instances for the `periodic_task1` task. Run the following command:

      SHOW HISTORY FOR TASK periodic_task1;

      The following is a sample result:

      +---------------------------------------------------------------------------------------------------+
| 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   |
+---------------------------------------------------------------------------------------------------+

    • Example 2: View the history of automatically scheduled instances for the `periodic_task1` task. Set the starting position to the latest record and display six records.

      SHOW HISTORY FOR TASK periodic_task1 LIMIT 6 OFFSET 0;

      The following is a sample result:

      +---------------------------------------------------------------------------------------------------+
| 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   |
| 2025061306500043ethoc62****      | 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   |
+---------------------------------------------------------------------------------------------------+

    • Example 3: View the history of automatically scheduled instances for the `periodic_task1` task. Skip the first five records by setting the starting position to the sixth record.

      SHOW HISTORY FOR TASK periodic_task1 OFFSET 5;

      The following is a sample result:

      +---------------------------------------------------------------------------------------------------+
| Project:                  muze_demo                                                              |
| Schema:                                                                                           |
| Task:                     periodic_task1                                                          |
+---------------------------------------------------------------------------------------------------+
| History:                                                                                          |
+---------------------------------------------------------------------------------------------------+
| InstanceId                       | CreateTime             | EndTime                | Status       |
+---------------------------------------------------------------------------------------------------+
| 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   |
+---------------------------------------------------------------------------------------------------+

    Function whitelist

    When you create a periodic task, you can configure a Boolean expression. The conditional statement supports only the following functions. For more information about these functions, see Built-in functions (alphabetical order).

    • DATEADD

    • DATEDIFF

    • DATEPART

    • DATETRUNC

    • DATE_FORMAT

    • FROM_UNIXTIME

    • GETDATE

    • ISDATE

    • LASTDAY

    • LAST_DAY

    • UNIX_TIMESTAMP

    • WEEKDAY

    • WEEKDAY

    • WEEKOFYEAR

    • TO_DATE

    • TO_CHAR

    • YEAR

    • QUARTER

    • MONTH

    • DAY

    • DAYOFMONTH

    • HOUR

    • MINUTE

    • SECOND

    • CURRENT_TIMESTAMP

    • FROM_UTC_TIMESTAMP

    • ADD_MONTHS

    • NEXT_DAY

    • MONTHS_BETWEEN

    • TO_MILLIS

    • ABS

    • ROUND

    • CONCAT

    • CONCAT_WS

    • GET_JSON_OBJECT

    • INSTR

    • LENGTH

    • LENGTHB

    • REGEXP_EXTRACT

    • REGEXP_REPLACE

    • REGEXP_INSTR

    • REGEXP_SUBSTR

    • REGEXP_COUNT

    • REVERSE

    • SUBSTR

    • TOLOWER

    • TOUPPER

    • TRIM

    • LTRIM

    • RTRIM

    • REPLACE

    • SIZE

    • FIELD

    • COALESCE

    • IF

    • SPLIT

    • SPLIT_PART

    • FROM_JSON

    • MAX_PT

    • TABLE_EXISTS

    • PARTITION_EXISTS

    • GET_LATEST_VERSION

    • GET_LATEST_TIMESTAMP