Como preparar dados diversos para importação: CSV, XLSX, JSON e NDJSON

Quase todo problema de importação começa no arquivo: um separador diferente, uma data em formato local, um número com vírgula, uma coluna com nome trocado. Este guia passa pelos quatro formatos que o DeepMiner importa e mostra o que conferir em cada um antes de enviar.

Antes do arquivo, o schema

O schema diz quais campos o índice tem, qual o tipo de cada um e qual campo identifica o registro. Definir isso antes evita importar uma base que não serve para as perguntas que você vai fazer.

No DeepMiner, a forma mais rápida é colar um registro de exemplo em JSON e usar Inferir campos. Os tipos disponíveis são texto, número, data, booleano, objeto e lista. Revise o tipo de cada campo e marque o campo-chave: com ele, reimportar o mesmo registro atualiza em vez de duplicar. Campos já salvos ficam somente leitura, e campos novos podem ser acrescentados depois.

Os nomes das colunas do arquivo precisam ser iguais aos nomes dos campos do schema, com a mesma grafia. Nomes iniciados com sublinhado são reservados.

CSV

O CSV é o formato mais comum e o que mais varia. Confira:

• Cabeçalho na primeira linha, com os nomes dos campos.
• Um separador só: ponto e vírgula ou vírgula. Se o cabeçalho tiver ponto e vírgula, o DeepMiner usa ponto e vírgula para o arquivo inteiro.
• Nada de separador dentro dos valores. Um endereço com vírgula num CSV separado por vírgula quebra a linha em colunas a mais. Prefira ponto e vírgula como separador ou remova o caractere do valor.
• Uma linha por registro, sem quebras de linha dentro de um campo.
• Codificação UTF-8, para que acentos cheguem certos.

XLSX

A planilha resolve parte dos problemas do CSV, porque cada célula já é um valor separado. O cuidado está na estrutura: o DeepMiner lê a primeira aba, usa a primeira linha preenchida como cabeçalho e importa as linhas abaixo dela. Linhas totalmente vazias são ignoradas.

Antes de exportar, remova títulos, linhas de total e células mescladas acima do cabeçalho, e deixe os dados na primeira aba.

JSON e NDJSON

Quando o registro tem estrutura, como um cliente com uma lista de pedidos, JSON e NDJSON preservam essa estrutura sem achatar colunas. O schema do índice aceita objetos e listas de objetos, e os campos de dentro viram campos aninhados.

O JSON precisa ser um array de objetos, cada objeto um registro. O NDJSON tem um objeto completo por linha, sem vírgula entre as linhas e sem colchetes em volta. Se uma linha do NDJSON for inválida, a importação informa o número da linha.

Os dois formatos seguem as especificações públicas citadas nas fontes. Arquivos gerados por bibliotecas padrão costumam estar corretos. Os gerados à mão são os que mais falham.

Datas, números e booleanos

Os valores são validados pelo tipo do campo. Três formatos evitam a maior parte dos registros inválidos:

• Datas em AAAA-MM-DD, como 2025-01-31. Formatos locais podem ser lidos com dia e mês trocados.
• Números com ponto como separador decimal e sem separador de milhar: 1234.56.
• Booleanos como true ou false, 1 ou 0, sim ou não.

O registro com valor inválido num campo é importado com a marca de inválido e a mensagem do erro, para que você saiba qual campo corrigir. O campo-chave não pode ficar vazio.

Depois de importar

A tela de importação mostra o total de registros, os processados, as falhas e o status, com o progresso atualizando sozinho. O Histórico de Importação guarda cada arquivo, a origem (arquivo ou API) e o relatório de erros.

Confira alguns registros no índice antes de usar a base em fluxos. Se algo veio errado, corrija o arquivo e importe de novo: com o campo-chave, os registros são atualizados.

Quer importar uma amostra da sua base na demonstração? Agende e traga um arquivo com dados fictícios.