Estágio 1 — Ingestão que dá origem à Landing

Objetivo da camada

A camada de ingestão é responsável por capturar dados das fontes e depositá-los de forma controlada, rastreável e temporária na Landing Zone.

Ela não deve ter como foco transformar dado para consumo analítico. O objetivo aqui é:

capturar, registrar, validar minimamente, organizar e preparar a entrada para o pipeline.

A Landing é uma área de passagem. Ela existe para receber os dados brutos vindos das fontes antes que eles sejam persistidos oficialmente na Bronze.

1. Papel da Landing na arquitetura

A Landing deve funcionar como uma zona transitória de entrada.

Ela recebe:

• arquivos brutos;

• payloads de APIs;

• extrações de bancos relacionais;

• eventos;

• dumps pontuais;

• cargas manuais controladas;

• arquivos de parceiros;

• respostas de integrações externas.

Ela não deve ser tratada como camada histórica definitiva.

A regra principal:

Landing não é camada analítica. Landing é área de recepção, inspeção e rastreabilidade inicial.

2. O que deve acontecer antes de gravar na Landing

Antes de qualquer dado entrar na Landing, o processo precisa executar uma validação inicial.

Validações mínimas

Para arquivos:

• verificar se o arquivo existe;

• verificar se está vazio;

• validar extensão esperada;

• validar encoding quando aplicável;

• validar delimitador quando for CSV;

• validar se o nome segue o padrão;

• validar se o schema esperado é compatível;

• validar se o arquivo já foi processado;

• gerar hash/checksum do arquivo;

• registrar tamanho, quantidade estimada de linhas e data de chegada.

Para APIs:

• validar status code;

• validar payload vazio;

• validar paginação;

• validar schema mínimo esperado;

• validar rate limit;

• registrar endpoint, parâmetros e janela consultada;

• persistir payload bruto ou resposta normalizada como arquivo bruto.

Para bancos de dados:

• validar conexão;

• validar query ou tabela origem;

• validar janela incremental;

• validar coluna de controle;

• registrar quantidade extraída;

• registrar watermark inicial e final;

• controlar duplicidade de janela.

Para eventos/streaming:

• validar tópico/fila/canal;

• validar payload mínimo;

• registrar offset/checkpoint;

• controlar replay;

• tratar eventos inválidos sem derrubar o fluxo inteiro.

3. Estrutura recomendada da Landing

A Landing precisa ser organizada por origem, domínio, entidade, data e lote.

Modelo genérico:

landing/
  source_system=<sistema_origem>/
    domain=<dominio>/
      entity=<entidade>/
        ingestion_date=YYYY-MM-DD/
          batch_id=<id_lote>/
            data/
              arquivo_original.ext
            metadata/
              manifest.json
              schema_snapshot.json
              validation_result.json
            errors/
              rejected_records.json

Exemplo:

landing/
  source_system=erp/
    domain=financeiro/
      entity=clientes/
        ingestion_date=2026-07-10/
          batch_id=20260710_001/
            data/
              clientes_20260710.csv
            metadata/
              manifest.json
              schema_snapshot.json
              validation_result.json
            errors/
              rejected_records.json

4. Retenção da Landing

A Landing deve ter retenção curta.

Recomendação:

Retenção máxima: 15 dias

Motivo:

• reduz custo;

• evita uso indevido como camada histórica;

• força a persistência correta na Bronze;

• simplifica governança;

• diminui risco de dados sensíveis ficarem expostos por muito tempo.

A regra ideal:

Se o dado foi aprovado, ele deve avançar para Bronze.Se foi rejeitado, deve ir para quarentena técnica ou área de erro controlada.Se expirou, deve ser limpo por política automática.

5. Contratos e metadados da ingestão

Essa camada deve ser orientada a metadados.

Cada fonte precisa ter um contrato de ingestão.

Exemplo de contrato lógico

source_system: erp
domain: financeiro
entity: clientes
source_type: database
load_type: incremental
expected_format: parquet
primary_key:
  - id_cliente
watermark_column: updated_at
required_columns:
  - id_cliente
  - nome
  - cpf_cnpj
  - updated_at
landing_retention_days: 15
bronze_target: bronze.financeiro.clientes
allow_schema_evolution: false
on_schema_drift: quarantine

Esse contrato orienta:

• como extrair;

• o que validar;

• onde gravar;

• como nomear;

• como reprocessar;

• qual regra aplicar em erro;

• qual destino posterior na Bronze.

6. Manifesto da carga

Toda ingestão precisa gerar um manifesto.

O manifesto é essencial para auditoria, rastreabilidade e reprocessamento.

Campos recomendados

batch_id
source_system
domain
entity
source_type
source_path_or_endpoint
target_landing_path
load_type
execution_id
trigger_type
started_at
finished_at
status
record_count
file_count
file_size_bytes
checksum
schema_hash
watermark_start
watermark_end
error_count
warning_count
reprocessable
parent_batch_id

O manifesto responde perguntas importantes:

• de onde veio;

• quando chegou;

• quem/processo carregou;

• qual lote gerou;

• qual schema foi recebido;

• qual arquivo foi processado;

• se pode ser reprocessado;

• se avançou ou não para Bronze.

7. Estados possíveis da carga

Toda carga precisa ter status operacional.

Sugestão:

RECEIVED
VALIDATING
LANDING_WRITTEN
FAILED_VALIDATION
QUARANTINED
READY_FOR_BRONZE
BRONZE_PROCESSED
EXPIRED
REPROCESS_REQUESTED
REPROCESSED

Isso evita depender apenas de logs soltos.

O pipeline deve conseguir responder:

Esse arquivo entrou?Foi validado?Foi para Landing?Foi para Bronze?Foi rejeitado?Pode ser reprocessado?Qual carga substituiu ou corrigiu essa?

8. Esteira de execução da ingestão

A execução ideal segue esta ordem:

1. Disparo da carga
2. Leitura do contrato da fonte
3. Identificação da origem
4. Extração ou recebimento dos dados
5. Validação inicial
6. Geração de metadados técnicos
7. Gravação na Landing
8. Geração do manifesto
9. Registro em tabela de controle
10. Classificação do status
11. Alerta em caso de falha
12. Liberação para processamento Bronze

Visualmente:

Fonte
  ↓
Contrato de ingestão
  ↓
Extração / coleta / recebimento
  ↓
Validação inicial
  ↓
Landing Zone
  ↓
Manifesto + metadados + tabela de controle
  ↓
Pronto para Bronze

9. O que pode reprovar na ingestão

A ingestão deve bloquear ou isolar problemas como:

• arquivo vazio;

• arquivo duplicado;

• schema incompatível;

• coluna obrigatória ausente;

• tipo de arquivo inesperado;

• encoding inválido;

• delimitador incorreto;

• API sem retorno;

• erro de paginação;

• falha de autenticação;

• janela incremental inválida;

• volume muito diferente do esperado;

• payload corrompido;

• arquivo parcialmente recebido.

Esses casos não devem simplesmente quebrar o pipeline inteiro sem registro.

Eles devem gerar:

status = FAILED_VALIDATION
ou
status = QUARANTINED

10. Quarentena técnica na ingestão

A quarentena técnica nasce justamente aqui.

Ela deve receber dados que não estão tecnicamente aptos para avançar.

Exemplos:

quarantine/
  technical/
    source_system=erp/
      domain=financeiro/
        entity=clientes/
          ingestion_date=2026-07-10/
            batch_id=20260710_001/
              data/
              metadata/
              error_report.json

A quarentena técnica precisa guardar:

• arquivo original;

• erro encontrado;

• schema recebido;

• schema esperado;

• data do erro;

• lote;

• origem;

• possibilidade de reprocessamento;

• responsável ou domínio afetado.

11. Reprocessamento na ingestão

O reprocessamento precisa ser previsto desde o início.

A ingestão deve permitir reprocessar por:

• batch_id;

• arquivo específico;

• data de ingestão;

• janela incremental;

• entidade;

• origem;

• domínio;

• status de erro;

• lista de arquivos;

• lote rejeitado.

Tipos de reprocessamento

Reprocessamento de arquivo

Usado quando um arquivo foi corrigido ou enviado novamente.

Reprocessar arquivo X do lote Y

Reprocessamento de janela

Usado para bancos ou APIs.

Reprocessar período de 2026-07-01 até 2026-07-10

Reprocessamento por lote

Usado quando uma execução inteira falhou.

Reprocessar batch_id = 20260710_001

Reprocessamento por quarentena

Usado quando dados rejeitados foram corrigidos ou liberados.

Reprocessar todos os registros em quarentena técnica já corrigidos

12. Idempotência na ingestão

A ingestão deve ser idempotente.

Ou seja:

Executar o mesmo processo mais de uma vez não pode gerar duplicidade nem inconsistência.

Para isso, usar:

• batch_id;

• source_file_name;

• source_file_hash;

• source_path;

• watermark_start;

• watermark_end;

• execution_id;

• controle de status;

• tabela de manifesto;

• chaves naturais da origem quando existirem.

Regra prática:

Mesmo arquivo + mesmo hash + mesma origem = não reprocessar automaticamente

A menos que exista uma ordem explícita de reprocessamento.

13. Tabela de controle da ingestão

Uma tabela operacional mínima deveria ter esta estrutura lógica:

control_ingestion_batches

Campos sugeridos:

batch_id
execution_id
source_system
domain
entity
source_type
load_type
status
landing_path
quarantine_path
file_name
file_hash
schema_hash
record_count
error_count
warning_count
watermark_start
watermark_end
started_at
finished_at
duration_seconds
created_by
reprocess_flag
reprocess_reason
parent_batch_id

Essa tabela vira a base do controle operacional.

14. Separação por tipo de origem

A arquitetura deve prever estratégias diferentes para cada tipo de fonte.

Arquivos

Fonte → Validação de arquivo → Landing → Manifesto → Bronze

Melhor para:

• CSV;

• JSON;

• XML;

• Excel;

• Parquet;

• arquivos de parceiros.

Banco de dados

Fonte → Extração full/incremental/CDC → Landing → Manifesto → Bronze

Melhor para:

• SQL Server;

• MySQL;

• PostgreSQL;

• Oracle;

• bancos transacionais.

API

Fonte → Requisição paginada → Persistência do payload → Landing → Manifesto → Bronze

Melhor para:

• REST;

• GraphQL;

• SaaS;

• webhooks.

Streaming/Eventos

Fonte → Fila/tópico → Checkpoint/offset → Landing ou Bronze direto → Manifesto

Melhor para:

• eventos;

• logs;

• IoT;

• integrações quase real-time.

15. O que não deve acontecer nessa camada

A camada de ingestão não deve:

• aplicar regra complexa de negócio;

• criar indicadores;

• fazer join analítico;

• sobrescrever histórico sem controle;

• corrigir dado silenciosamente;

• descartar erro sem registro;

• misturar domínios sem necessidade;

• gravar direto na Silver sem validação intermediária;

• depender só de logs técnicos sem tabela de controle.

A responsabilidade dela é garantir entrada confiável, não modelagem analítica.

16. Critérios para avançar da Landing para Bronze

Um lote só deve avançar se:

status = READY_FOR_BRONZE

Condições mínimas:

• extração concluída;

• arquivo/payload persistido;

• schema mínimo validado;

• manifesto criado;

• metadados registrados;

• ausência de erro bloqueante;

• controle operacional atualizado.

Se falhar:

status = FAILED_VALIDATION
ou
status = QUARANTINED

17. Resultado esperado da camada

Ao final da ingestão, devemos ter:

Landing organizada
Manifesto criado
Tabela de controle atualizada
Metadados capturados
Status definido
Erros isolados
Alertas emitidos
Lote pronto ou bloqueado para Bronze

A entrega da camada é:

dado bruto recebido com rastreabilidade, controle e condição explícita de avanço.

18. Resumo visual do estágio

FONTES
  ↓
CONTRATOS / METADADOS
  ↓
INGESTÃO POR TIPO DE FONTE
  ↓
VALIDAÇÃO INICIAL
  ↓
LANDING ZONE
  ↓
MANIFESTO + CONTROLE OPERACIONAL
  ↓
READY_FOR_BRONZE

Em caso de falha:

VALIDAÇÃO INICIAL
  ↓
QUARENTENA TÉCNICA
  ↓
CORREÇÃO
  ↓
REPROCESSAMENTO
  ↓
LANDING / BRONZE

Definição final do estágio

A camada de Ingestão → Landing deve ser desenhada como uma área operacional, temporária e auditável, responsável por receber dados de diferentes origens, aplicar validações iniciais, registrar metadados, controlar status, permitir reprocessamento e preparar os dados para entrada segura na Bronze.

Ela é o primeiro ponto onde a arquitetura deixa de ser apenas “copiar dados” e passa a operar com contratos, rastreabilidade, idempotência, qualidade inicial e governança operacional.