schedule

Tipo: Referência
Para: Desenvolvedor, Engenharia de dados

Um schedule roda um ou mais Dataflows, em sequência, nos horários dos seus gatilhos. O arquivo fica em schedules/<slug>--<id>.yaml. Como a execução e o agendamento funcionam no HorusETL está em HorusETL; o que cada contexto extrai, em tipos de carga.

bash

lumo new schedule --name "Vendas diário" --agent 41

Campos

fileName
string · opcional · valores: regex ^[a-z0-9-]+--\d+\.yaml$
header
object · obrigatório
header.id
integer · obrigatório · valores: ≥ 1
header.kind
string · obrigatório · valores: schedule (fixo)
header.lumo
string · obrigatório · valores: v2 (fixo)
header.tenantId
integer · obrigatório · valores: ≥ 1
header.appId
integer · opcional · valores: ≥ 1
header.dashboardId
integer · opcional · valores: ≥ 1
body
object · obrigatório
body.criado_em
string ou null · opcional · valores: regex ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$
Somente leitura: o servidor preenche.
body.criado_por
string ou integer ou null · opcional
Somente leitura: o servidor preenche.
body.publicado_em
string ou null · opcional · valores: regex ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$
Somente leitura: o servidor preenche.
body.publicado_por
string ou integer ou null · opcional
Somente leitura: o servidor preenche.
body.nome
string · obrigatório · valores: não vazio
body.ativo
boolean · obrigatório
body.timezone
string · obrigatório · valores: não vazio
Informational: the backend does not store it. HH:MM times (Day/Week/Month start_when, start_time, end_time) are Brasilia time (America/Sao_Paulo); ISO start_when values are absolute instants.
body.version
integer ou null · opcional · valores: ≥ 0
Somente leitura: o servidor preenche. Server-managed resource version.
body.parallel_lane
boolean · opcional
Runs the schedule outside the agent's normal concurrent-execution limit. Property of the schedule, applies to any trigger type, not just CDC.
body.tokenId
integer ou null · opcional
ETL agent the schedule runs on. Must be the agent of every flow in flows: the agent only runs the flows that are on it, and the server refuses a push that mixes them (SCHEDULE_AGENT_MISMATCH). lumo new schedule --agent <id> sets it at creation.
body.flows
array de object · obrigatório
body.flows[].flow_etl_id
integer · obrigatório · valores: ≥ 1
body.flows[].context
string · obrigatório · valores: Total, Incremental, Temporal, TemporalFuture, KeySweep; regex ^Temporal:(?:Days|Future):[0-9]+$; regex ^Temporal:Month:(?:0?[1-9]|1[0-2])-[0-9]{4}$; regex ^Temporal:Year:(?:[0-9]{4}|Current)$
How a scheduled flow runs. Total/Incremental/Temporal pick the extraction WINDOW; the flow's own load_type decides the DELETE predicate, so the two must agree (see the cross-reference rules in lumo lint). Temporal and TemporalFuture are the only short forms - the backend expands them with temporal_value into Temporal:Days:N / Temporal:Future:N. The four windowed forms are parsed by the agent: Days:N looks back N days, Future:N looks forward N days, Month:M-YYYY covers one calendar month, and Year:YYYY one calendar year (Year:Current resolves to the running year). Month and Year have no short form and must be written expanded. KeySweep is not a load at all: the agent runs only the flow's key_sweep query and marks as deleted, in the destination table, every key the source no longer returns - it requires load_type=Incremental and a configured key_sweep.
body.triggers
array de object · obrigatório
body.triggers[].type
string · obrigatório · valores: Hour, Minute, Day, Month, Week, CDC
body.triggers[].period
integer · obrigatório · valores: ≥ 1
Com type: Hour/Minute.
body.triggers[].period
integer · obrigatório · valores: ≥ 1, ≤ 31
Com type: Month. Day of month (treated as day-of-month, not interval count).
body.triggers[].period
integer · obrigatório · valores: ≥ 0, ≤ 6
Com type: Week. Day of week: 0=Sunday … 6=Saturday.
body.triggers[].period
integer · obrigatório · valores: ≥ 5, ≤ 3600
Com type: CDC. Probe interval in seconds. If config.timeout_seconds is left unset it defaults to 5 and must stay below period, so period: 5 with no explicit timeout_seconds is always rejected by the backend at push even though it satisfies this schema's minimum; either raise period or set a lower timeout_seconds.
body.triggers[].start_when
string · obrigatório · valores: regex ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$
Com type: Hour/Minute.
body.triggers[].start_when
string · obrigatório · valores: regex ^([01]?[0-9]|2[0-3]):[0-5][0-9]$
Com type: Day. HH:MM time-of-day. An edit takes effect the same day: a trigger changed at 13:00 to 23:59 fires that night.
body.triggers[].start_when
string · obrigatório · valores: regex ^([01]?[0-9]|2[0-3]):[0-5][0-9]$
Com type: Month. HH:MM time-of-day.
body.triggers[].start_when
string · obrigatório · valores: regex ^([01]?[0-9]|2[0-3]):[0-5][0-9]$
Com type: Week. HH:MM time-of-day.
body.triggers[].start_when
string · obrigatório · valores: regex ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$
Com type: CDC.
body.triggers[].start_time
string · obrigatório: sim, se type: Hour/Minute · valores: regex ^([01]\d|2[0-3]):[0-5]\d$
body.triggers[].end_time
string · obrigatório: sim, se type: Hour/Minute · valores: regex ^([01]\d|2[0-3]):[0-5]\d$
body.triggers[].config
object · obrigatório: sim, se type: CDC
body.triggers[].config.kind
string · obrigatório · valores: query-scalar
Detection mode. Only query-scalar today, new modes join this enum without a new trigger type.
body.triggers[].config.credential
string · obrigatório · valores: não vazio
Key of the etl credential the probe connects with. Does not have to match the credentials used by the flows.
body.triggers[].config.sql
string · obrigatório · valores: não vazio
Probe query. Must be a single statement starting with SELECT or WITH, returning exactly one row with 1 to 8 columns. With more than one column the probe fires when any of them changes: SELECT COUNT(*), MAX(changed_at) FROM t is the only rule that catches inserts, updates and deletes at once, and it needs two columns because concatenating them in SQL is dialect-specific. Requires agent 1.26.0 or newer. The backend validates this beyond size, the schema only bounds length.
body.triggers[].config.timeout_seconds
integer · opcional · valores: ≥ 1
Probe timeout in seconds. Must be lower than period. Defaults to 5.

Exemplo

yaml

# schedules/vendas-diario--3301.yaml
# yaml-language-server: $schema=https://docs.horusbi.com.br/schemas/v2/schedule.schema.json
id: 3301
kind: schedule
lumo: v2
tenantId: 1200
---
nome: Vendas diário
ativo: true
timezone: America/Sao_Paulo      # informativo: os horários HH:MM são de Brasília
tokenId: 41                      # o mesmo Agente ETL de todos os Dataflows abaixo
flows:                           # rodam em sequência
  - flow_etl_id: 5102            # dim_filiais
    context: Total
  - flow_etl_id: 5101            # fato_vendas
    context: "Temporal:Days:7"   # últimos 7 dias
triggers:
  - type: Day
    start_when: "06:00"          # uma vez por dia, às 6h

lumo scaffold schedule traz um exemplo de cada gatilho e de cada contexto, comentado.

Contexto de cada Dataflow

`context`	O que a execução extrai
`Total`	Tudo
`Incremental`	O que é novo desde a última execução
`Temporal:Days:7`	Os últimos 7 dias. A forma curta, `Temporal` com `temporal_value` igual a 7, grava o mesmo
`Temporal:Future:30`	Os próximos 30 dias, para datas futuras como agenda. Forma curta: `TemporalFuture`
`Temporal:Month:3-2026`, `Temporal:Year:2026`, `Temporal:Year:Current`	Um mês ou um ano do calendário. Não têm forma curta
`KeySweep`	Nada: só roda a consulta `key_sweep` do Dataflow e marca como apagado o que sumiu da origem

O contexto escolhe quanto extrair. O que acontece no destino é a Gravação do Dataflow (write_mode), na referência de flow.

Gatilhos

`type`	`period`	`start_when`
`Hour`	A cada N horas (1 a 24)	Data e hora ISO que fixam o minuto do disparo; use uma data no passado
`Minute`	A cada N minutos (1 a 60)	Igual ao `Hour`. Recusado se o Tenant estiver configurado para agendar só de hora em hora
`Day`	Não usa	`HH:MM`, uma vez por dia
`Week`	Dia da semana (0 = domingo a 6)	`HH:MM`
`Month`	Dia do mês (1 a 31)	`HH:MM`
`CDC`	Segundos entre consultas (5 a 3600)	Data e hora ISO, obrigatória

start_time e end_time (a janela do dia, em HH:MM) só valem para Hour, Minute e CDC, e são obrigatórios em Hour e Minute. O pull traz 07:00 e 19:00 em todo gatilho; nos outros tipos, deixe como veio.

Limites

Os Dataflows precisam estar publicados.
tokenId tem de ser o Agente ETL de todos os Dataflows da lista. O servidor recusa o push que mistura agentes (SCHEDULE_AGENT_MISMATCH). Copiar o YAML de outro agendamento copia o agente dele: confira com lumo info flow:<id>.
timezone é só informativo e não é gravado. Horários HH:MM são de Brasília; valores ISO são instantes absolutos (o Z é UTC).
No CDC, timeout_seconds vale 5 por padrão e precisa ficar abaixo de period. Por isso period: 5 sem timeout_seconds é recusado; o menor que funciona sem mexer em mais nada é 6. A consulta de sondagem tem no máximo 8 KB e devolve 1 linha com 1 a 8 colunas. Fora desse formato ela passa no push, mas não dispara e aparece como erro de configuração na execução; sondagem que estoura o tempo também não dispara e tenta de novo no ciclo seguinte. COUNT(*) sozinho não percebe alteração e MAX de uma data sozinho não percebe exclusão.
parallel_lane: true roda o agendamento fora do limite de execuções simultâneas do agente. Use só em agendamentos leves. O tamanho dessa pista é configurado no Agente ETL (padrão 4); com 0, ela fica desligada.
context: KeySweep exige Dataflow com load_type: Incremental, key_sweep preenchido e destino com key_type: unique.
lumo schedule run, pause e resume controlam a execução; lumo schedule logs lista as execuções, com --since para limitar o período.

schedule ​

Campos ​

Exemplo ​

Contexto de cada Dataflow ​

Gatilhos ​