Inserir no DW

Tipo: Referência
Para: Engenharia de dados, Desenvolvedor
Na tela: HorusETL › Dataflows › editor do Dataflow

Para o dado chegar a um Dashboard, o Dataflow termina num nó DataWarehouse, que grava as linhas recebidas numa tabela do HorusDW. É no painel dele que se escolhe a tabela de destino, a Gravação (o que acontece com as linhas que já estão lá) e a chave da tabela.

Na biblioteca	`kind` no YAML	Grupo	Entradas
DataWarehouse	`InsertDatawarehouse`	Destinos	uma

Um Dataflow grava numa tabela só. Com um segundo nó de destino, a tela avisa: "Há dois destinos neste dataflow, e o servidor só considera um." Para gravar em outra tabela, crie outro Dataflow.

A Extração (o que o Dataflow pede à origem) e a Gravação formam um par, explicado em Cargas.

Destino

Na tela	No YAML	Onde fica	Regra
Destino	`Mode`	`options` do nó	Datawarehouse (padrão): tabela do BI, consultável pelos dashboards. O link Usar Datalake troca para Datalake. Trocar limpa a tabela escolhida
Tabela de destino, Escolher tabela	`TableID`	`options` do nó	A tabela que recebe as linhas. Obrigatória
Criar nova tabela, Nome da tabela	(cria a tabela e grava o `TableID`)		Cria uma tabela com as colunas que chegam ao nó
Editar tabela			Abre a tabela de destino no HorusDW, em outra aba

Sem tabela, o nó falha com "O nó InsertDatawarehouse está com TableID=0, ou seja, não está vinculado a nenhuma tabela do datawarehouse. Nada seria gravado." No Lumo CLI, lumo flow sync-table refaz o vínculo.

Estrutura da tabela

A seção Estrutura da tabela compara as colunas do Dataflow com as da tabela, lado a lado (Dataflow e Tabela), e mostra um de três estados:

Estado	Significa
Em dia	As colunas batem
Divergente	"As colunas do dataflow não batem com as da tabela de destino. Recrie a tabela para a carga não falhar."
Não verificada	O nó ainda não foi executado, ou a estrutura não carregou

Uma coluna da tabela que não chega do Dataflow falha a carga com "Coluna X não encontrada no dado a ser inserido." Recriar tabela apaga a tabela e a cria de novo com a estrutura do Dataflow.

Gravação

A Gravação fica na seção Carga do painel, ao lado da Extração. No YAML, as duas ficam no nível do Dataflow, fora do options do nó.

Na tela	No YAML (nível do Dataflow)	Regra
Extração	`load_type`	Total (`Total`), Janela (`Temporal`) ou Incremental (`Incremental`)
Gravação	`write_mode`	Veja a tabela abaixo. Vazio no YAML deriva da Extração e da chave da tabela
Coluna de janela (Janela) ou Coluna de corte (Incremental)	`load_type_column`	A coluna de data (ou de número, no Incremental) que recorta a carga
Ponto de corte		Só leitura. O valor que o próximo Incremental vai usar, lido da tabela

Gravação	`write_mode`	Com a Extração	O que acontece na tabela
Substituir tudo	`replace_all`	Total	Apaga da tabela tudo o que este Dataflow gravou antes, neste Agente ETL, e grava no lugar o que veio. O que outros Dataflows gravaram não é tocado, e por isso dois Dataflows podem alimentar a mesma tabela sem um apagar o outro. Veja Substituir tudo apaga só o que é do Dataflow
Substituir a janela	`replace_window`	Janela	Apaga as linhas cuja Coluna de janela, só a data, está entre `StartDate` e `EndDate`, e grava o que veio. Linha que chega com a data vazia ou fora da janela é descartada
Atualizar por chave	`upsert_by_key`	Janela ou Incremental	Linha com a mesma chave substitui a que existe; chave nova entra. Precisa de tabela com Chave Única; com Janela, também de Agente ETL 1.28.0 ou mais novo. Registro apagado na origem continua na tabela
Somente inserir	`insert_only`	Incremental	Só acrescenta linhas. Recusada em tabela com Chave Única, que já resolve pela chave

Os outros pares são recusados pela tela e pelo lumo lint, com o motivo. Total com Somente inserir, por exemplo, aparece na tela como "As mesmas linhas voltam a cada execução e entrariam de novo." Com write_mode vazio, vale: Total → Substituir tudo; Janela → Substituir a janela; Incremental → Atualizar por chave em tabela com Chave Única e Somente inserir nas outras.

Um Dataflow que passa a ser Incremental ao salvar precisa de tabela de destino com Chave Única. Sem ela, salvar falha com "A tabela ... não tem chave única: com carga Incremental, cada registro alterado entraria como linha nova em vez de substituir a anterior." Por isso Somente inserir só sobra para Dataflows que já eram Incremental.

Só Substituir tudo e Substituir a janela percebem registro apagado na origem. Para os outros casos, veja exclusões.

O Agente ETL confere as regras de novo na execução, porque a tabela pode ter mudado depois de o Dataflow ser salvo:

Atualizar por chave numa tabela sem Chave Única falha com "A Gravação "Atualizar por chave" exige que a tabela ... tenha chave única marcada".
Uma execução por janela num Dataflow sem Extração Janela, ou sem Coluna de janela, falha em vez de apagar a tabela inteira e regravar só a janela.
Substituir a janela sem StartDate e EndDate: "As variáveis StartDate e EndDate devem estar definidas para cargas temporais."

Chave da tabela

A chave é uma propriedade da tabela no HorusDW, editável no próprio painel em Chave da tabela.

Na tela	No YAML da tabela	Regra
Tipo de Chave	`key_type`	Chave Única (`unique`): casa pela chave e atualiza o registro que já existe. Chave Duplicada (`duplicate`): só ordena o armazenamento, e registro repetido entra de novo
Colunas Chave	`key_columns`	Ao menos uma. A ordem da chave é a ordem das colunas na tabela, e não a ordem em que você marca

WARNING

Mudar a chave e Recriar tabela apagam os dados da tabela. A tabela é recriada vazia e só volta a ter linhas na próxima execução do Dataflow. Num Dataflow Incremental, rode uma carga completa depois.

Os tipos de tabela e de chave estão em Tipos de tabela.

Execução

Executar inserção roda a gravação a partir do editor, com as linhas que o nó anterior entregou. Depois, a seção Metadados mostra as linhas gravadas e quando.

A contagem de linhas é a que o HorusDW confirmou ter gravado. Se o destino recusar parte das linhas, o log registra "ATENÇÃO: enviadas N linhas ao datawarehouse e confirmadas M."
O nó aceita uma entrada: "Apenas um dado de entrada pode ser inserido no processador InsertDatawarehouse".

Modo Datalake

Com Usar Datalake, o nó grava arquivos Parquet no armazenamento do Lumo, numa tabela do tipo Datalake, fora do banco do BI. Quem lê essas tabelas é o nó Extrair Datalake. Cada Agente ETL grava os próprios arquivos na tabela.

Nesse modo, quem decide a gravação é o Agente ETL, com estes campos:

Na tela	No YAML (`options`)	Padrão	Regra
Carga diferencial, Usar carga diferencial	ligado quando há `PrimaryKeys`	desligado	O Agente ETL compara pelas chaves e só grava o que mudou
chaves, Adicionar chave	`PrimaryKeys`	nenhuma	Até 6 colunas. Coluna que não existe na tabela é ignorada
Particionar	`PartitionType`	`NONE`	Arquivo único (`NONE`), Por ano (`YEAR`), Por mês (`MONTH`). Aparece sem carga diferencial, com Extração Janela ou Incremental por data

A Gravação Atualizar por chave não vale para tabela Datalake: a execução falha e sugere Substituir a janela. Para atualizar por chave num Datalake, use a carga diferencial.

Exemplo

Trecho do corpo do YAML de um Dataflow, depois do cabeçalho:

yaml

nome: Vendas diárias
load_type: Temporal
load_type_column: DATA_EMISSAO
write_mode: replace_window
nodes:
  Processors:
    - internalId: gravar_vendas
      kind: InsertDatawarehouse
      inputs: [sql_vendas]
      options:
        Mode: Datawarehouse
        TableID: 4821
  Connections:
    - from: sql_vendas
      to: gravar_vendas

Relacionado

Pelo Lumo CLI

O nó também pode ser escrito e versionado em YAML. Veja a referência de flow.

Inserir no DW ​

Destino ​

Estrutura da tabela ​

Gravação ​

Chave da tabela ​

Execução ​

Modo Datalake ​

Exemplo ​

Relacionado ​