Tutorial — importar um arquivo (CSV, JSON ou Parquet)

Estado: Preview. A leitura de formato e o saneamento de carga são provados por teste; a carga real no datalake = NÃO MEDIDO (liberação em nuvem ainda não exercida). Exemplos sintéticos.

Leia antes: Como os dados fluem · Pipeline medalhão.

O que é#

Trazer um arquivo para o datalake pelo modo push ("Você deposita"): você envia o arquivo para a landing e o Ingestia carrega no Bronze automaticamente. Formatos suportados: CSV, JSON (linhas/JSONL ou array) e Parquet.

Arquivos também aceitam o modo pull (o Ingestia lê de um object storage). Object storage de terceiros: Azure Blob está em Preview; Amazon S3 e puxar bucket GCS do cliente são Roadmap (não implementados). Este tutorial cobre o push (upload), que é o caminho mais simples.

Para que serve#

Subir extrações pontuais, dumps ou planilhas exportadas sem configurar uma conexão de banco — ideal para começar rápido ou para dados que não vivem num sistema conectável.

Quando usar / quando não usar#

• Use quando: você tem um arquivo pronto (CSV/JSON/Parquet) e quer carregá-lo já.
• Não use quando: o dado se atualiza sozinho num banco/SaaS (prefira pull agendado) — o push é uma carga que você dispara.

Plano e permissões#

• Núcleo do produto · verificação de acesso · chave de desligamento execução de ingestão.

Pré-requisitos#

1. O arquivo em CSV, JSON ou Parquet.
2. Para CSV: saber o delimitador (vírgula, ponto e vírgula, tab ou pipe).
3. Para JSON: saber se é linhas (JSONL/ndjson) ou array único.
4. Parquet é auto-descritivo — sem opções de formato.

Passo a passo#

1. No console, vá em ETL/ELT → Conexões e escolha o formato: CSV, JSON ou Parquet (categoria Arquivos), no modo Você deposita (push).
2. Ajuste as opções de formato:
   • CSV → Delimitador: Vírgula (,), Ponto e vírgula (;), Tab ou Pipe (|).
   • JSON → Formato: Linhas (JSONL / ndjson) ou Array único.
   • Parquet → nada a configurar.
3. Use a área de upload para enviar o arquivo para a landing.
4. Dispare a carga em Tabelas do Bronze → Ingerir ao vivo (ou deixe o agendamento cuidar disso).
5. Acompanhe os passos ao vivo: validar → landing → bronze → registrar.

Exemplo (sintético)#

CSV de vendas com ponto e vírgula como delimitador (vendas.csv):

pedido_id;data_pedido;uf;categoria;preco_unitario;quantidade;status
P-1001;2026-01-03;SP;Bebidas;12,90;3;pago
P-1002;2026-01-03;RJ;Limpeza;29,90;1;pago
P-1003;2026-01-04;MG;Bebidas;12,90;2;cancelado

O mesmo dado em JSONL (uma linha por objeto):

{"pedido_id":"P-1001","data_pedido":"2026-01-03","uf":"SP","preco_unitario":"12,90","quantidade":"3","status":"pago"}
{"pedido_id":"P-1002","data_pedido":"2026-01-03","uf":"RJ","preco_unitario":"29,90","quantidade":"1","status":"pago"}

Resultado esperado#

• O arquivo chega à landing e é carregado verbatim no Bronze: cada linha entra como texto, com carimbos _ingest_at, _source, _row. Nenhuma linha é descartada no Bronze.
• O passo registrar atualiza o catálogo e a última sincronização.
• Depois, rode o pipeline para levar até Silver/Gold.

Saneamento automático (por que a carga não quebra por nome de coluna)#

Se um cabeçalho tiver acento, espaço ou vier vazio ("preço", "nome do cliente"), um load direto falharia (Invalid field name). Quando isso acontece, o Ingestia saneia o arquivo e recarrega: minúsculas, sem acento, _ no lugar de espaço; coluna vazia vira coluna; nome que começa com número vira col_.... Ele também explode envelopes ({meta..., data:[...]}) e converte array/pretty-JSON para NDJSON. Regra conservadora: linha não-parseável é mantida como está — o Ingestia nunca inventa dado.

Limites e custos#

• Carga para o Bronze: default batchSize 5.000, maxRows 200.000.
• A carga no datalake é cobrável. Custo faturado em BRL = NÃO MEDIDO.

Segurança#

• O arquivo vai para a landing do seu workspace (landing/{prefix}/...); nunca cruza com outro cliente.
• Não coloque segredos ou PII desnecessária no arquivo — colunas PII são mascaradas no profiling, mas o melhor é não trazer o que não precisa.

Erros comuns#

Diagnóstico#

• Verifique na tela de execução os passos validar → landing → bronze → registrar.
• Confira, na camada Bronze, o número de linhas ingeridas versus o do arquivo.

Relacionados#

• Construir Bronze/Silver/Gold
• Criar pipeline full
• Qualidade, deduplicação e rejeitados

Última revisão: 2026-09-08.