Buscar K
Aparência
Tipos de carga
- Tipo
- Conceito
- Para
- Engenharia de dados
Toda carga de um Dataflow responde a duas perguntas separadas: quanto pedir da origem e o que fazer, no destino, com o que chegou. A primeira resposta se chama Extração; a segunda, Gravação. As duas ficam na seção Carga do editor do Dataflow.
Errar a escolha não gera erro. A carga termina com sucesso e a tabela fica com linha duplicada ou faltando, e isso só aparece num total que não fecha.
Extração: quanto pedir da origem
| Extração | O que pede | Precisa de |
|---|---|---|
| Total | a origem inteira, a cada execução | nada |
| Janela | um intervalo de datas | uma coluna de data, a coluna de janela |
| Incremental | o que mudou desde a última carga | uma coluna que só cresce, a coluna de corte |
Na Janela, o Agente ETL entrega à consulta as duas pontas do intervalo, {StartDate} e {EndDate}. O tamanho do intervalo vem de quem dispara a execução: o agendamento ou a execução manual dizem "últimos 30 dias" ou "mês 10/2026".
Na Incremental, o Agente entrega {LastDataPoint}, o maior valor que a coluna de corte já atingiu na tabela de destino. Na primeira execução o destino está vazio e o ponto de corte volta vazio (01/01/1901, se a coluna de corte é data), então a carga traz tudo.
sql
-- Janela
SELECT * FROM vendas WHERE data_emissao BETWEEN '{StartDate}' AND '{EndDate}'
-- Incremental
SELECT * FROM pedidos WHERE atualizado_em > '{LastDataPoint}'Rode as consultas abaixo para ver o que cada Extração traz da mesma origem:
A consulta de cada ExtraçãoDuckDB
A tabela titulos é a origem em 31/10. Em cada aba, as variáveis já vêm trocadas pelo valor que o Agente ETL entrega; mude as datas e rode de novo.
Schema
A Extração só recorta a origem se a consulta usar essas variáveis no WHERE. Sem elas, o Dataflow lê a base inteira toda vez, e o recorte acontece tarde demais ou nunca. No editor, a Extração aparece como Janela; no YAML, na execução manual e no agendamento, o mesmo valor se chama Temporal.
Gravação: o que fazer no destino
| Gravação | O que acontece com o que já estava no destino |
|---|---|
| Substituir tudo | o que aquele Dataflow gravou antes sai, e entra o que chegou |
| Substituir a janela | as linhas do Dataflow dentro da janela saem, e entra o que chegou |
| Atualizar por chave | nada sai; a linha que chega toma o lugar da que tem a mesma chave |
| Somente inserir | nada sai e nada é substituído; tudo entra como linha nova |
As duas primeiras apagam antes de inserir, e por isso refletem um registro excluído na origem: ele não vem na consulta e o que estava no destino já saiu. As duas últimas nunca apagam. Um registro excluído na origem continua no destino até que algo o tire de lá, assunto da página Exclusões na origem.
Substituir tudo apaga só o que é do Dataflow
A Gravação Substituir tudo apaga as linhas que aquele Dataflow, rodando naquele Agente ETL, gravou antes. Quando dois Dataflows alimentam a mesma tabela, cada um substitui só a própria parte, e a carga Total de um não apaga o que o outro trouxe.
Quando a tabela tem um único Dataflow que grava nela (contando os pausados), rodando no mesmo Agente ETL, a troca é da tabela inteira. Nesse caso saem também linhas que nenhum Dataflow reconhece mais, como as que sobraram de um Dataflow já excluído.
Atualizar por chave depende da tabela
Atualizar por chave funciona porque a tabela de destino deduplica: com Chave Única marcada, o banco analítico guarda uma linha só por chave, e a última que chegou vence. A chave fica na própria tabela, em Chave da tabela, com o Tipo de Chave e as Colunas Chave. Sem Chave Única, ou com Chave Única e nenhuma coluna marcada, o mesmo registro alterado entraria como linha nova a cada carga, e o Lumo recusa essa combinação. Ela também só existe para tabela do Datawarehouse; numa tabela Datalake, o equivalente é a carga diferencial do próprio nó, em Inserir no DW.
A chave precisa conter todas as colunas que distinguem uma linha da outra. Com chave incompleta, duas linhas diferentes viram uma só, e o sintoma é o total bater na prévia do Dataflow e não bater no Dashboard. Os tipos de tabela e o modelo de chave estão em Tipos de tabela.
As cinco combinações
Das doze combinações possíveis, cinco valem. As outras sete duplicariam dado, apagariam histórico, deixariam no destino o que sumiu da origem ou pediriam uma janela que a Extração não tem. A tela mostra essas opções desabilitadas, com o motivo. Total com Atualizar por chave, por exemplo, aparece com "A origem inteira já veio. Quem sumiu de lá continuaria vivo no destino."
| Extração | Gravação | Pré-condição | Para que serve |
|---|---|---|---|
| Total | Substituir tudo | nenhuma | dimensão e cadastro pequenos, tabela sem coluna de controle |
| Janela | Substituir a janela | coluna de janela que nunca muda | fato grande com data de nascimento: venda, emissão, movimento |
| Janela | Atualizar por chave | Chave Única no destino e Agente ETL 1.28.0 ou mais novo | registro que interessa por várias datas: título a pagar e a receber |
| Incremental | Atualizar por chave | Chave Única no destino | registro que muda e tem updated_at ou ID crescente |
| Incremental | Somente inserir | destino sem deduplicação | log que nasce e nunca muda; só em Dataflow que já era Incremental |
O simulador abaixo roda a mesma origem nos cinco pares. Os sete pares recusados aparecem riscados, com a mensagem da tela.
A tabela de títulos foi carregada inteira em 10/10. Até a execução de 31/10, a origem mudou em cinco linhas. A janela desta execução é outubro; o ponto de corte do Incremental é 10/10.
Extração
Gravação
- Substituir a janela: Não existe janela para substituir. Só a Extração Janela define uma.
- Atualizar por chave: A origem inteira já veio. Quem sumiu de lá continuaria vivo no destino.
- Somente inserir: As mesmas linhas voltam a cada execução e entrariam de novo.
Origem em 31/10
| Título | Emissão | Valor | O que mudou |
|---|---|---|---|
| 1 | 15/08 | 150 | alterada, fora da janela |
| 2 | 03/10 | 250 | alterada, na janela |
| 3 | 20/08 | 300 | excluída, fora da janela |
| 4 | 06/10 | 400 | excluída, na janela |
| 5 | 08/10 | 500 | sem mudança |
| 6 | 25/10 | 600 | nova |
Em negrito e marcadas à esquerda, as 4 linhas que a consulta traz.
Destino depois de 31/10
| Título | Emissão | Valor | Situação |
|---|---|---|---|
| 1 | 15/08 | 150 | atualizada |
| 2 | 03/10 | 250 | atualizada |
| 5 | 08/10 | 500 | igual à origem |
| 6 | 25/10 | 600 | nova |
| 3 | 20/08 | 300 | saiu, como na origem |
| 4 | 06/10 | 400 | saiu, como na origem |
O destino ficou igual à origem.
Quando a Gravação não está declarada (Dataflow anterior a ela, ou write_mode vazio no YAML), o Lumo deriva uma: Total vira Substituir tudo, Janela vira Substituir a janela, e Incremental vira Atualizar por chave se o destino tem Chave Única, ou Somente inserir se não tem.
Janela com Atualizar por chave é a única combinação que um Agente ETL antigo executaria errado: ele não conhece a Gravação, vê a Extração Janela e apaga a janela no destino. Por isso o Lumo recusa a execução num Agente anterior ao 1.28.0, com "Este dataflow usa a Gravação "Atualizar por chave" com Extração "Janela", que exige Agente ETL 1.28.0 ou mais novo." As outras quatro rodam em qualquer versão. Para atualizar, veja Manter o Agente ETL.
A coluna de janela precisa ficar parada
Substituir a janela apaga no destino as linhas cuja coluna de janela cai no intervalo e insere o que a consulta trouxe. Isso só fecha se a consulta devolver exatamente o que existe naquele intervalo, pela mesma coluna. O que ela lê é livre: um cálculo pode ler cinco anos de vendas (data_venda <= '{EndDate}') para produzir as linhas do mês, desde que devolva só linhas com a coluna de janela dentro do intervalo.
Uma data que muda ao longo da vida do registro quebra o acordo. Um título com data_vencimento em outubro e prorrogado para novembro sai da consulta de outubro, mas a linha antiga continua no destino com outubro. Na carga de novembro ele entra de novo, e a tabela passa a ter duas linhas para o mesmo título. data_emissao e created_at servem; data_vencimento e data_alteracao não.
Para recortar por uma data que muda, use Janela com Atualizar por chave. Como essa combinação não apaga nada, a consulta pode filtrar por várias datas ao mesmo tempo, e a chave resolve as repetições:
sql
SELECT * FROM titulos
WHERE data_pagamento BETWEEN '{StartDate}' AND '{EndDate}'
OR data_vencimento BETWEEN '{StartDate}' AND '{EndDate}'
OR data_emissao BETWEEN '{StartDate}' AND '{EndDate}'Na Incremental, a coluna de corte pode mudar no mesmo registro, desde que só cresça: um atualizado_em que sobe a cada alteração é o caso típico.
A janela de cada execução
A Extração define a regra; a janela concreta chega com a execução, e ela se chama contexto. Um mesmo Dataflow de Janela pode rodar com os últimos 3 dias num agendamento e os últimos 90 em outro.
O contexto Total vale para qualquer Dataflow e sempre faz a troca completa da parte do Dataflow, mesmo quando a Gravação é Atualizar por chave ou Somente inserir. Num Dataflow de Janela, ele abre o intervalo de 01/01/1910 a 01/01/2100. É assim que se faz a primeira carga de um Dataflow de Janela, que de outro modo traria só o período do agendamento.
Quando apaga por janela (Substituir a janela, ou o contexto Total num Dataflow de Janela), o Agente também descarta na inserção as linhas cuja coluna de janela chega vazia ou cai fora do intervalo. Por isso a coluna de janela precisa vir sempre preenchida da origem. Em Janela com Atualizar por chave, fora do contexto Total, nada é descartado.
Onde isso aparece
- No editor do Dataflow, na seção Carga, com Extração, Gravação, Coluna de janela ou Coluna de corte e Tabela de destino.
- Na execução manual e no agendamento, onde se escolhe o contexto. Ver Agendar um Dataflow.
- No YAML do Lumo CLI, nas chaves
load_type,load_type_columnewrite_mode. Ver Modos de carga. - Para escolher entre as combinações a partir da sua origem, ver Escolher a carga de uma tabela.