Pular para o conteúdo
Atualizado em 2026-09-08

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

Passo a passo para depositar um arquivo na landing (push) e carregá-lo na camada Bronze, com opções de formato e saneamento automático.

Nesta página (14)

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.

CSV, JSON e Parquet só aceitam depósito. Não existe "nós buscamos" para formato de arquivo: para o Ingestia ir buscar arquivos numa pasta ou num bucket seu, o caminho são os conectores de object storage — Amazon S3, Google Cloud Storage, Azure Blob Storage e os compatíveis (MinIO, Wasabi, Cloudflare R2, Backblaze B2, DigitalOcean Spaces), além de SFTP, Google Drive, Dropbox, OneDrive/SharePoint e arquivo por HTTP. Todos estão em Acesso limitado: a liberação é conector a conector, depois de validada com uma credencial real da sua conta. Este tutorial cobre o depósito, 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):

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):

json
{"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 no Bronze com o tipo de cada coluna detectado pelos valores (número, data, texto) e os carimbos técnicos. Nenhuma linha é descartada no Bronze.
  • Atenção a identificadores só com dígitos (CPF sem pontuação, CEP, código de produto como 00123): a detecção os lê como número e o zero à esquerda se perde na Bronze. Envie esses campos com pontuação (071.518.203-05) ou com um caractere não numérico, e confira a coluna depois da primeira carga.
  • 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.

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#

SintomaCausa provávelO que fazer
Colunas todas numa sódelimitador errado no CSVSelecione o delimitador correto (; é comum no Brasil)
JSON não carregaformato marcado erradoAlterne entre Linhas (JSONL) e Array único
Invalid field namecabeçalho com acento/espaçoO saneamento recarrega sozinho; confira os nomes resultantes
CPF/CEP sem o zero à esquerdaa coluna só tem dígitos e foi lida como númeroEnvie o campo formatado (com pontos/hífen) e recrie a tabela; na Silver use LPAD(CAST(col AS STRING), 11, '0') para CPF

Solução de problemas#

  • 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#


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

Links relacionados