MaxCompute periodic task - MaxCompute: Central de Documentação do Alibaba Cloud

Visão geral do fluxo de trabalho

Fluxo de trabalho típico de ponta a ponta:

Ative as tarefas periódicas para a sessão definindo odps.sql.periodic.task.enabled=true.
Crie os objetos de suporte — Delta Tables e streams — caso sua tarefa leia dados de um stream.
Crie a tarefa com CREATE TASK, especificando o agendamento, a condição opcional WHEN e a estratégia de nova tentativa.
Verifique se a tarefa está ACTIVE usando DESC TASK.
Monitore o histórico de execução com SHOW HISTORY FOR TASK.
Modifique, suspenda ou exclua a tarefa conforme necessário com ALTER TASK ou DROP TASK.

Como funciona

Cada tarefa periódica executa uma instrução SQL em um intervalo fixo. Antes de cada execução, a tarefa avalia uma condição opcional WHEN. Se a condição retornar FALSE, a execução será ignorada. A tarefa não executa o corpo SQL, mas permanece agendada e reavalia a condição no próximo intervalo.

Esse padrão é útil para criar pipelines de dados que processam informações apenas quando novos dados estão disponíveis. Por exemplo, use WHEN stream_has_data('my_stream') para ignorar execuções quando o stream estiver vazio e evitar computação desnecessária. Por padrão, a tarefa gera automaticamente dados CDC incrementais em segundo plano.

Comportamentos principais:

WHEN atua como filtro, não como gatilho. A tarefa ainda dispara no agendamento fixo; WHEN apenas determina se o corpo SQL será executado.
A tarefa periódica inicia automaticamente após a criação. Seu status inicial é ACTIVE.
Para suspender ou retomar uma tarefa, use ALTER TASK ... suspend ou ALTER TASK ... resume.

Pré-requisitos

Antes de começar, certifique-se de ter:

Um projeto MaxCompute com o recurso de tarefas periódicas ativado (preview por convite).
Permissões para criar e gerenciar tarefas no projeto.
(Para acesso via console) A política AliyunMaxComputeReadOnlyAccess concedida ao seu usuário RAM. Para mais detalhes, consulte Permissões do RAM.

Observações de uso

Defina o seguinte parâmetro no nível da sessão antes de criar ou excluir tarefas periódicas. Sem ele, CREATE TASK e DROP TASK retornarão erro.

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

Criar uma tarefa periódica

Sintaxe

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

Parâmetros

Parâmetro	Obrigatório	Descrição
`IF NOT EXISTS`	Não	Caso já exista uma tarefa com o mesmo nome, a operação é concluída com sucesso e a tarefa existente não sofre alterações. Sem esta opção, criar uma tarefa com nome duplicado retorna erro.
`task_name`	Sim	Nome da tarefa periódica.
`SCHEDULE`	Sim	Intervalo de execução. Unidades suportadas: `second`/`seconds` (valor: 10–59) e `minute`/`minutes`. Para intervalos de 60 segundos ou mais, utilize minutos. Faixa de valores: de 10 a 3.540 segundos.
`TASKPROPERTIES`	Não	Parâmetros de execução para o corpo SQL. Configurações comuns: `schedule_strategy` (número de novas tentativas em caso de falha), `odps.stage.reducer.num` (número de instâncias de Reduce Task), `odps.sql.reducer.memory` (memória por instância de Reduce Task, em MB).
`COMMENT`	Não	Comentário para a tarefa. Comprimento máximo: 1.024 bytes.
`WHEN`	Não	Expressão booleana avaliada antes de cada execução agendada. O corpo da tarefa executa apenas quando esta expressão retorna TRUE. O padrão é TRUE se omitido. Suporta apenas funções escalares. Funções de janela, funções agregadas e subconsultas aninhadas não são suportadas. Para a lista completa de funções suportadas, consulte Lista de permissões de funções.
`AS <taskBody>`	Sim	Instrução SQL a ser executada. Suporta Linguagem de Manipulação de Dados (DML) e Linguagem de Consulta de Dados (DQL). Linguagem de Definição de Dados (DDL) e instruções SQL executadas a partir do editor de código não são suportadas.

Exemplo: criar uma tarefa com condição de stream

Este exemplo cria uma tarefa que lê novas linhas de um stream de Delta Table e as insere em uma tabela de destino a cada 5 minutos. O corpo da tarefa executa apenas quando o stream possui novos dados.

Etapa 1: Crie a Delta Table de destino.

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

Etapa 2: Crie a Delta Table de source e um stream associado a ela.

-- 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';

Etapa 3: Crie a tarefa periódica.

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') equivale a executar SELECT stream_has_data('delta_table_stream'); no MaxCompute. Com schedule_strategy=3 , a tarefa tenta novamente até 3 vezes se uma execução agendada falhar.

Etapa 4: Insira dados de teste e verifique o resultado.

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

Saída esperada:

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

Modificar uma tarefa periódica

Use ALTER TASK para atualizar o agendamento, as propriedades de execução, o comentário ou a condição WHEN de uma tarefa existente, bem como para suspendê-la ou retomá-la.

Uma tarefa periódica inicia automaticamente após a criação com status ACTIVE. Para pausá-la, use ALTER TASK ... suspend . Para retorná-la ao status ACTIVE, use ALTER TASK ... resume . Verifique o status atual com DESC TASK .

Sintaxe

Modificar agendamento, propriedades ou comentário:

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

Suspender ou retomar:

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

Modificar a condição WHEN:

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

Parâmetros

Parâmetro	Obrigatório	Descrição
`IF EXISTS`	Não	Se a tarefa não existir, a operação é ignorada e uma mensagem de sucesso é retornada. Sem esta opção, modificar uma tarefa inexistente retorna erro.
`boolean_expr`	Sim (para `MODIFY WHEN`)	Nova expressão booleana para a condição de acionamento da tarefa.

Para SCHEDULE e TASKPROPERTIES, consulte Parâmetros na seção Create a periodic task.

Cenários comuns

Suspender uma tarefa, atualizar agendamento e contagem de novas tentativas e depois retomar:

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;

Atualizar a condição WHEN:

ALTER TASK IF EXISTS periodic_task1 MODIFY WHEN 1=1;

Adicionar ou atualizar um comentário:

ALTER TASK IF EXISTS periodic_task1 SET COMMENT 'comment2';

Excluir uma tarefa periódica

Sintaxe

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

DROP TASK [IF EXISTS] <task_name>;

Parâmetros

Parâmetro	Obrigatório	Descrição
`IF EXISTS`	Não	Se a tarefa não existir, a operação é ignorada e uma mensagem de sucesso é retornada. Sem esta opção, excluir uma tarefa inexistente retorna erro.
`task_name`	Sim	Nome da tarefa periódica a ser excluída.

Exemplo

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

DROP TASK periodic_task1;

Visualizar informações da tarefa

Usar comandos

Visualizar informações básicas:

DESC TASK <task_name>;

Visualizar informações estendidas:

DESC EXTENDED TASK <task_name>;

Exemplo de saída para 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:                                                                           |
+------------------------------------------------------------------------------------+

Usar o console

Faça login no console do MaxCompute e selecione uma região.Console do MaxCompute
No painel de navegação à esquerda, escolha Manage Configurations > Projects.
Na página Projects, localize o projeto desejado e clique em Manage na coluna Actions.
Na página Project Settings, selecione a aba Periodic Task para visualizar todas as tarefas periódicas do projeto.
Clique em Details na coluna Actions da tarefa desejada.
Na caixa de diálogo View Periodic Task, revise o Task Name, Task Status, Scheduling Cycle e Execution Log.
Clique em um Instance ID para abrir a página Job Insights e visualizar logs detalhados de execução.

Listar todas as tarefas periódicas

SHOW TASKS;

Exemplo de saída:

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

SHOW TASKS lista todas as tarefas no projeto atual. Para filtrar por nome de tarefa, utilize a aba Periodic Task no console do MaxCompute.

Visualizar histórico de execução

SHOW HISTORY FOR TASK retorna o InstanceId, CreateTime, EndTime e Status de cada execução agendada.

Para visualizar logs detalhados de uma execução específica, use WAIT para obter a URL do Logview e abra-a em um navegador:

WAIT <InstanceId>;
-- Example: WAIT 2024082309000177gq71ut9****;

Sintaxe

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

Parâmetros

Parâmetro	Obrigatório	Descrição
`task_name`	Sim	Nome da tarefa periódica.
`limit_value`	Não	Número de registros a serem retornados. Deve ser maior que 0. Se omitido, retorna o máximo de registros possível. Exemplo: `LIMIT 50` retorna 50 registros.
`offset_value`	Não	Número de registros a pular a partir do mais recente. `OFFSET 0` começa pelo registro mais recente.

Exemplos

Visualizar todo o histórico de periodic_task1:

SHOW HISTORY FOR TASK periodic_task1;

Saída:

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

Visualizar as 6 execuções mais recentes:

SHOW HISTORY FOR TASK periodic_task1 LIMIT 6 OFFSET 0;

Ignorar as 5 execuções mais recentes e visualizar o rest:

SHOW HISTORY FOR TASK periodic_task1 OFFSET 5;

Lista de permissões de funções

A condição WHEN suporta apenas funções escalares. Funções de janela, funções agregadas e subconsultas aninhadas não são suportadas. As seguintes funções estão disponíveis. Para detalhes sobre cada função, consulte Funções integradas (ordem alfabética).

Data e hora

DATEADD, DATEDIFF, DATEPART, DATETRUNC, DATE_FORMAT, FROM_UNIXTIME, GETDATE, ISDATE, LASTDAY, LAST_DAY, UNIX_TIMESTAMP, 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

Matemática

ABS, ROUND

String

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

Condicional e JSON

COALESCE, IF, SPLIT, SPLIT_PART, FROM_JSON

Tabela e partição

MAX_PT, TABLE_EXISTS, PARTITION_EXISTS, GET_LATEST_VERSION, GET_LATEST_TIMESTAMP, STREAM_HAS_DATA, TABLE_NEED_CDC_BUILD