Inserir no Datawarehouse

O processador Inserir no Datawarehouse é o nó mais importante e central de escrita do HorusETL. Ele é o responsável por persistir os dados processados no ambiente do Horus, tornando-os disponíveis para consumo imediato em Dashboards (DataViz) ou armazenando-os para processamento em camadas posteriores.

Este processador oferece flexibilidade total para definir se o dado é um "Produto Final" ou uma "Etapa Intermediária" através de seus modos de operação.

Modos de Operação

O processador possui dois modos distintos, selecionados na configuração:

1. Datawarehouse (DataViz / Produto Final)

• Objetivo: Disponibilizar o dado para consumo imediato nos painéis e Dashboards do Horus DataViz
• Comportamento: Os dados são processados e otimizados para consulta rápida
• Uso Típico: A última etapa de um fluxo ETL, onde o dado já está tratado, limpo e pronto para o usuário final

2. Datalake (Cloud / Camadas)

• Objetivo: Armazenar o dado no Data Lake do Horus (Cloud Storage) para processamento posterior ou arquivamento
• Comportamento: Os dados são salvos em formatos otimizados para leitura em lote (Parquet), permitindo controle de versionamento, particionamento e upserts (atualização diferencial)
• Uso Típico: Construção de arquiteturas em camadas (Bronze -> Silver -> Gold). Este modo escreve dados que serão lidos posteriormente por outros fluxos usando o processador Leitura de Datalake

---

Configuração

Parâmetros Principais

Nome	Descrição
Modo	Define o destino do dado: Datawarehouse (Final) ou Datalake (Camadas).
Tabela	Seleciona a tabela de destino. Permite escolher uma tabela existente ou criar uma nova tabela diretamente pelo fluxo.
Nome da Tabela	(Apenas ao criar) Nome da nova tabela a ser criada. O sistema valida se o nome já existe.
Recriar Tabela	Se a estrutura dos dados (colunas/tipos) do fluxo for diferente da tabela existente, o sistema alerta e oferece um botão para recriar a tabela automaticamente ajustada aos novos dados.

Opções Específicas do Modo Datawarehouse

Quando o modo Datawarehouse está ativo, o comportamento de Upsert (inserir ou atualizar) é controlado pela definição da tabela, e não pelo processador.

IMPORTANT

Cargas Incrementais e Upsert no Datawarehouse Para garantir a unicidade dos registros e habilitar o comportamento de Upsert (manter apenas o registro mais recente) no modo Datawarehouse:

1. Após criar a tabela, clique no link (Editar tabela em nova janela) exibido no processador.
2. Na tela de modelagem da tabela, altere o "Modelo da Tabela" para Chave Única.
3. Selecione as colunas que compõem a chave única (ID, CPF).

Isso garante que, se o fluxo tentar inserir um registro com um ID já existente, o sistema atualizará o registro antigo com os dados novos, mantendo a integridade sem duplicatas.

TIP

Performance do Upsert: O Horus Lakehouse faz upsert nativo sem custo adicional de performance. Ou seja, uma carga com upsert não é mais lenta do que uma carga comum. Exemplo prático: se um registro teve uma coluna alterada na origem, o SELECT vai trazer esse registro, mas como ele já existe no Lakehouse, o sistema automaticamente atualiza ao invés de duplicar usando as chaves escolhidas.

Opções Específicas do Modo Datalake

Quando o modo Datalake está ativo, opções avançadas de gerenciamento de dados são exibidas:

Carga Diferencial (Use Delta)

Habilita o recurso de Upsert (Update + Insert). O sistema atualizará registros existentes e inserirá novos, evitando duplicidade.

• Chaves Primárias (Primary Keys): Quando a Carga Diferencial está ativa, você deve definir quais colunas formam a chave única do registro (ID, Codigo, Data). O sistema usa essas chaves para identificar se um registro deve ser atualizado ou inserido

Particionamento (Se não usar Delta)

Se a carga não for diferencial (apenas Append ou carga completa), é possível particionar fisicamente os arquivos para otimizar leituras futuras. Disponível quando o fluxo possui varáveis de carga temporal/incremental.

• Arquivo Único (NONE): Salva tudo em um bloco
• Por Ano (YEAR): Separa os dados em pastas por ano
• Por Mês (MONTH): Separa os dados em pastas por ano e mês

---

Detalhes Técnicos

• Validação de Estrutura: O processador compara automaticamente os tipos de dados e nomes de colunas do fluxo (Metadata) com a tabela de destino. Se houver divergência (coluna nova, tipo alterado), ele bloqueia a execução segura e solicita a recriação ou ajuste
• Performance (DW): No modo Datawarehouse, o sistema utiliza o motor de ingestão HorusParquet, otimizado para alta volumetria e indexação automática para o DataViz
• Performance (Datalake): No modo Datalake, utiliza o engine DeltaStore. O uso de Delta Lake garante transações ACID e histórico de versões
• Integração: Tabelas criadas no modo Datalake ("cloud tables") são visíveis apenas para processadores de leitura técnica (como o ExtractDatalake), enquanto tabelas Datawarehouse aparecem publicamente no módulo de DataViz

Exemplos de Uso

Cenário 1: Arquitetura em Camadas (Bronze -> Silver -> Gold)

1. Fluxo 1 (Ingestão): Lê dados crus de uma API e usa o Inserir no Datawarehouse (Modo Datalake) para salvar na tabela vendas_bronze.
2. Fluxo 2 (Tratamento): Usa o Leitura de Datalake para ler vendas_bronze, limpa os dados, remove duplicatas e salva usando Inserir no Datawarehouse (Modo Datalake) na tabela vendas_silver.
3. Fluxo 3 (Entrega): Lê vendas_silver, agrega os totais por mês e salva usando Inserir no Datawarehouse (Modo Datawarehouse) na tabela vendas_gold_bi.
   • Resultado: O usuário final acessa apenas vendas_gold_bi no Dashboard, mas o time de dados tem todo o histórico rastreável nas camadas anteriores

Cenário 2: Carga Incremental com Atualização (CDC)

• Configuração: Modo Datalake, Checkbox "Usar carga diferencial" ativado, Chave Primária = id_pedido
• Fluxo: O sistema recebe uma lista de pedidos do dia
• Resultado: Pedidos com id_pedido que já existiam são atualizados (status mudou de 'Pendente' para 'Pago'). Pedidos novos são inseridos. Isso mantém o Datalake sempre fiel ao estado atual sem duplicar dados