Execução e Agendamento

Uma vez que seu Dataflow esteja publicado em uma Mesa de Dados, você pode definir quando e como ele será executado.

---

▶️ Execução Manual (Forçar Carga)

Dispare uma execução manualmente a qualquer momento — ideal para cargas iniciais ou reprocessamento.

1. Na listagem da Mesa de Dados, clique no botão Executar ao lado do fluxo
2. O sistema apresentará opções dependendo de como o fluxo foi desenhado

Modos de Carga

Se o seu fluxo utiliza parâmetros temporais (variáveis {StartDate}, {EndDate}), o seletor de modo será exibido:

Modo	Descrição
Total	Executa o fluxo sem filtros de tempo. Ideal para carga histórica completa — apaga os dados antigos e recarrega tudo
Temporal	Permite definir um período específico: Dias Passados, Dias Futuros, Mês e Ano ou Ano
Incremental	Baseada em coluna de controle (updated_at), traz apenas registros novos ou alterados. O sistema guarda automaticamente o último datapoint processado

NOTE

Para que o modo Temporal funcione, seus nós (SQL Query, API Request) devem utilizar as variáveis {StartDate} e {EndDate}. Exemplo: DATA_EMISSAO BETWEEN '{StartDate}' AND '{EndDate}'

NOTE

Para que o modo Incremental funcione, seus nós devem utilizar a variável {LastDataPoint}. Exemplo: UPDATED_AT > '{LastDataPoint}'

---

⏰ Agendamentos

O Agendamento é o sistema de automação do Horus — ele dispara o fluxo automaticamente em intervalos definidos.

1. Acesse o menu Agendamentos (na barra lateral ou botão "Relógio" no card do fluxo)
2. Clique em Criar novo Agendamento
3. Configure a periodicidade ("Todo dia às 03:00 AM")
4. Vincule o fluxo que deve ser executado
5. Ative o agendamento

Status e Monitoramento

Na tela de Agendamentos, monitore as execuções:

Status	Indicador	Descrição
Sucesso	🟢	Terminou sem erros
Erro Parcial	🟡	Terminou, mas algumas linhas ou etapas falharam
Erro	🔴	O fluxo falhou e parou antes de concluir

Sequenciando Múltiplos Flows

Crie agendamentos com múltiplos flows em sequência para garantir a ordem de execução — essencial para arquiteturas em camadas:

1. Ao criar o agendamento, adicione os flows na ordem desejada
2. O sistema executa na sequência definida (RAW primeiro, depois Refined)
3. Se um flow anterior falhar, os posteriores não são executados

Exemplo de sequência típica:

1. raw_vendas — Extrai dados brutos do ERP
2. refined_vendas — Trata, remove duplicatas, aplica regras de negócio
3. gold_vendas — Gera agregações finais para dashboard

TIP

Configure o período de carga (últimos 30 dias) para cada flow, mantendo o mesmo período para flows do mesmo dado (vendas, por exemplo).

---

🔄 Gatilho por Mudança de Dados (CDC)

Em vez de rodar o flow por horário e só então descobrir, pela extração completa, que nada mudou, o gatilho Mudança de dados (CDC) faz o agente rodar uma consulta leve na origem a cada N segundos e dispara o agendamento só quando o valor devolvido muda. É a opção para origens sem CDC nativo acessível: Oracle, ODBC genérico, Firebird, Informix e IRIS.

NOTE

Este guia cobre a decisão de uso. Para o formato completo do YAML (campos, faixas, exemplo), veja Referência: Schedule.

Quando usar

Cenário	Recomendação
Tabela muda pouco, mas a extração dela é cara (join pesado, origem lenta, tabela grande)	CDC. A sonda é barata; a extração completa só roda quando compensa.
Origem não aguenta rodar o flow inteiro a cada minuto	CDC.
Extração já é barata e a mudança é rara	Agendamento comum por horário (Hour/Minute). Menos peça em movimento.

O que observar

A tela pergunta o que observar e escreve a consulta. Escolher a regra é escolher o que o gatilho enxerga:

Regra	Pega	Não pega
Contagem e maior valor SELECT COUNT(*), MAX(col) FROM t	Inclusão, alteração e exclusão.	Nada; é a forma completa.
Só a contagem de linhas SELECT COUNT(*) FROM t	Inclusão e exclusão (a contagem muda nos dois casos).	Alteração de uma linha que já existia: a contagem não muda.
Só o maior valor de uma coluna SELECT MAX(col) FROM t	Inclusão e alteração.	Exclusão: a linha some da origem sem mexer no MAX.
Contadores internos da tabela (só PostgreSQL)	Inclusão, alteração e exclusão, sem ler a tabela.	Nada, desde que o servidor esteja com track_counts ligado.
Versão do Change Tracking (só SQL Server)	Qualquer mudança nas tabelas rastreadas, sem ler a tabela.	Distinguir qual tabela mudou: o número é do banco inteiro.

A regra completa usa duas colunas em vez de concatenar as duas consultas num valor só. Concatenar amarraria a sonda a um dialeto (|| no Oracle e no PostgreSQL, + no SQL Server, CONCAT no MySQL), e numa conexão ODBC o banco do outro lado nem é conhecido. Sonda de mais de uma coluna precisa do agente 1.26.0 ou mais novo.

As duas regras nativas aparecem na lista mesmo em conexões de outros bancos, em cinza e com o motivo, para ficar visível que existem.

TIP

As nativas são a melhor opção quando disponíveis: elas leem um contador que o próprio banco já mantém, então o tamanho da tabela deixa de importar. As genéricas dependem de índice (veja a seção seguinte).

WARNING

No SQL Server, com o Change Tracking desligado a função devolve vazio em vez de erro. Vazio é um valor perfeitamente estável, então a sonda ficaria verde e nunca dispararia. O botão Testar sonda acusa esse caso antes de salvar. No PostgreSQL o equivalente é o contador parado em zero, que costuma ser track_counts desligado no servidor.

IMPORTANT

Use uma credencial somente leitura para a sonda, no campo onde a credencial é escolhida. A validação que exige SELECT/WITH é textual (olha o texto da consulta), não é uma garantia de segurança: função com efeito colateral que não usa nenhuma palavra reconhecida como escrita (nextval, setval, lo_import e afins) passa por ela sem ser barrada. A defesa de verdade é a credencial só de leitura.

O custo mora no índice

Uma sonda roda a cada poucos segundos, não uma vez por dia. Se a coluna da consulta não tem índice, cada sondagem é uma varredura da tabela inteira, no banco de produção do cliente, repetida a cada 5, 10 ou 30 segundos. É o jeito mais fácil de transformar uma "consulta leve" numa fonte de lentidão para o cliente.

A tela de configuração do gatilho tem um botão Testar sonda, que roda a consulta de verdade contra a origem e mostra o tempo. Use antes de salvar: uma sondagem de poucos segundos já denuncia full scan.

O que acontece quando a carga falha

Se o flow disparado falhar (ou a execução for descartada), o valor observado não avança. Na sondagem seguinte, o valor antigo continua registrado, a mesma mudança é detectada de novo e o gatilho dispara outra vez. Nada se perde; o pior caso é reprocessar.

O que este gatilho não faz

• Detectar exclusão não é o mesmo que espelhar exclusão. As regras completas (contagem e maior valor, ou as nativas) detectam que uma linha sumiu e disparam o agendamento. Mas quem carrega é o flow, e uma carga Incremental só traz o que existe: a linha apagada continua no data warehouse. Se o requisito é espelhar exclusão, o gatilho é metade do caminho; a outra metade é a sincronização de exclusões ou uma carga Total.
• Não diz ao flow quais registros mudaram. O gatilho só dispara; o flow carrega do jeito que já carrega hoje (Total, Incremental ou Temporal), sem lista de registros alterados. Isso é uma decisão de desenho, não uma pendência — veja abaixo.

Por que o gatilho não passa a lista de registros alterados

A pergunta aparece sempre: se a sonda já sabe que algo mudou, por que não devolver quais linhas mudaram e entregar essa lista ao flow?

Tecnicamente seria fácil. O problema é de dono.

Um agendamento tem vários flows, e a sonda é uma consulta só. As chaves que ela observa descrevem uma tabela. Os outros flows leem outras tabelas, às vezes de outras origens: a mesma lista seria verdadeira para um e sem sentido para os demais.

O flow já resolve isso, e com uma granularidade que a sonda não tem. Numa carga Incremental o ponto de corte vem do destino, não da sonda: cada flow consulta a própria tabela no data warehouse e a própria coluna incremental. É por flow, por tabela, por coluna.

Quem	Decide
Gatilho CDC (agendamento)	Quando rodar
Tipo de carga (flow)	O que trazer

Juntar os dois criaria duas fontes de verdade para a mesma pergunta: a lista da sonda e o ponto de corte do destino.

E quando eu precisar de alteração e exclusão?

Essa é uma escolha de tipo de carga, e depende de o que a origem oferece.

Com coluna de alteração na origem e destino de chave única, alteração já está resolvida. Uma tabela do data warehouse com chave unique substitui a linha pela chave na inserção. Então uma carga Incremental por atualizado_em traz só o delta e sobrescreve o que mudou, sem duplicar. É o par que o gatilho CDC pede: sonda barata e carga barata.

WARNING

Confira o tipo de chave da tabela de destino antes de montar essa carga. Com chave duplicate não existe substituição: a mesma configuração acrescenta uma cópia da linha a cada alteração, sem erro nenhum. duplicate é o padrão e ainda é a maioria das tabelas.

Sem coluna de alteração na origem, o caminho é Temporal. Existem bancos em que não há atualizado_em nem chave incremental utilizável, e ali o Incremental é impossível por desenho da origem. O Temporal apaga a janela no destino e a reinsere, então tudo que mudou dentro dela é refletido, inclusive exclusão. Em camadas ele fica barato e atual ao mesmo tempo: a cada 10 minutos as vendas de hoje, a cada hora as do mês, a cada 6 horas os últimos seis meses, uma vez por dia o total.

IMPORTANT

A coluna da janela precisa ser uma data que nasce com o registro e nunca muda. O predicado de exclusão roda no destino usando essa mesma coluna: se o valor mudar, a linha antiga fica fora da janela que vai ser apagada, a nova é inserida ao lado, e a partir daí existem duas.

data_vencimento de um título é o exemplo clássico de escolha ruim, porque uma prorrogação move o registro de janela. Data de emissão, de criação ou de movimento servem.

Exclusão fora de janela tem recurso próprio: a sincronização de exclusões. Uma linha apagada não aparece em delta nenhum, por definição, então nenhum predicado na origem alcança o que não está mais lá. A saída é inverter a pergunta: em vez de perguntar o que mudou, perguntar o que ainda existe. O dataflow guarda uma consulta que devolve só as chaves vivas na origem, um agendamento roda essa consulta no contexto Sincronizar exclusões, e tudo que não veio é marcado como excluído no destino.

Ela exige load_type: Incremental e tabela de destino com chave única. Onde isso não valer, as alternativas continuam sendo:

• Exclusão lógica na origem (uma coluna de status ou data de exclusão) com destino de chave única: a exclusão entra no delta como uma alteração comum. A linha continua no data warehouse marcada como excluída, então os relatórios precisam filtrar por essa coluna.
• Carga Total, quando a tabela couber nisso.
• Nó Configurador Python gerando a variável DeletePredicate, quando a origem apaga de verdade e recarregar tudo não é opção. O nó calcula quais chaves sumiram (comparando a origem com o destino, ou lendo uma tabela de eventos da origem) e gera essa variável, que vira o WHERE do delete executado antes da inserção. É mecanismo existente, não recurso de tela: exige código próprio em cada flow, e o predicado é uma cláusula SQL, então a lista de chaves tem um teto prático de tamanho.

Como diagnosticar

Onde	O que mostra
Indicador no detalhe do agendamento	Badge CDC com a vida da sonda (sondando, parada, com erro).
Valor observado	O último valor que a sonda leu, para conferir se a consulta está mesmo enxergando a mudança esperada.
Coluna de motivo no log de execuções	De onde para onde o valor mudou na execução que disparou, por exemplo MAX(UPDATED_AT): 14:03:11 → 14:22:04.