How to Flatten the JSON Data: Explodir, Unir ou Deixar Aninhado (Guia 2026)

O que significa achatar dados JSON

CSV é plano: linhas e colunas, nada mais. JSON é uma árvore: objetos dentro de objetos, listas dentro de objetos, objetos dentro de listas. A expressão em inglês how to flatten the JSON data significa transformar essa árvore em uma tabela sem perder a informação de que você realmente precisa. Toda ferramenta de achatamento executa os mesmos três movimentos, e quando você consegue nomeá-los, toda ferramenta se torna previsível.

Os três movimentos são: objetos aninhados viram colunas com notação de ponto (customer vira customer.name e customer.city); listas de valores simples viram uma única célula unida (items vira book; pen); e listas que você precisa analisar viram uma linha por item, o que se chama explodir. Qual movimento se aplica a cada lista é toda a habilidade, e é uma decisão, não um padrão.

Uma distinção importa antes de qualquer outra coisa. Nosso guia anterior sobre como achatar JSON para CSV documenta exatamente o que o botão de achatamento do conversor deste site faz, célula por célula, incluindo seus casos extremos. Este guia trata do trabalho em si: você tem dados JSON aninhados, quer uma tabela plana e pode escolher como cada parte se achata, em qualquer ferramenta, incluindo as que não têm nenhum botão.

O exemplo resolvido: três pedidos aninhados

Todos os exemplos deste guia usam o mesmo exemplo pequeno, três pedidos com um objeto customer aninhado, uma lista items e uma lista vazia no terceiro pedido. Pequeno o suficiente para conferir à mão, aninhado o suficiente para mostrar cada decisão.

orders.json, o exemplo resolvido

[
  { "orderId": "A-101", "customer": { "name": "Ana", "city": "Madrid" }, "items": ["book", "pen"], "total": 19.99 },
  { "orderId": "A-102", "customer": { "name": "Ken", "city": "Osaka" }, "items": ["lamp"], "total": 42.50 },
  { "orderId": "A-103", "customer": { "name": "Lina", "city": "Berlin" }, "items": [], "total": 7.25 }
]

Passo 1: objetos aninhados viram colunas com notação de ponto

Um objeto aninhado tem campos com nomes, por isso achatá-lo é mecânico: desça pela árvore e una os nomes das chaves com pontos. customer.name guarda Ana, customer.city guarda Madrid, e o aninhamento original some, mas nada se perde, porque o nome com pontos registra o caminho completo de volta até a fonte.

Este é o movimento sobre o qual toda ferramenta concorda. O conversor online faz isso, o json_normalize do pandas faz isso, o jq faz isso quando você nomeia os caminhos explicitamente. A profundidade é o único julgamento: um ou dois níveis de pontos continuam legíveis, quatro níveis (a.b.c.d) geralmente significam que você está achatando uma estrutura que nunca foi pensada para ser uma linha de tabela, e esse é o assunto da seção sobre profundidade abaixo.

Passo 1 aplicado: objetos com ponto, listas unidas

orderId,customer.name,customer.city,items,total
A-101,Ana,Madrid,book; pen,19.99
A-102,Ken,Osaka,lamp,42.50
A-103,Lina,Berlin,,7.25

Passo 2: listas curtas viram uma única célula unida

Uma lista de valores simples, textos ou números sem aninhamento próprio, achata-se em uma única célula ao unir os valores com um separador. O conversor deste site une com ponto e vírgula seguido de espaço (book; pen). O ponto e vírgula é uma escolha deliberada: vírgulas colidiriam com o delimitador do CSV, enquanto um ponto e vírgula dentro de uma célula é inequívoco e sobrevive a uma ida e volta pelo Excel.

Unir mantém uma linha por registro, que é o que você quer quando a lista é contexto, não o assunto. Tags em um artigo, habilidades em um perfil, categorias em um produto: você vai lê-las, talvez filtrar por elas, mas não vai somar ou contar os valores individuais. Una essas listas.

Listas unidas: uma linha por pedido, listas em uma célula

orderId,items
A-101,book; pen
A-102,lamp
A-103,

Passo 3: explodir uma lista em uma linha por item

Explodir é o movimento que a maioria das pessoas perde, porque a maioria dos conversores nunca o oferece. Em vez de espremer uma lista em uma única célula, você cria uma linha por item e repete os campos do registro pai em cada linha. O pedido A-101, com dois itens, vira duas linhas: uma para book, outra para pen, cada uma carregando Ana, Madrid e 19.99. Três pedidos viram quatro linhas, porque a lista vazia em A-103 ainda gera uma linha com um item vazio, de modo que o pedido em si nunca é descartado em silêncio.

Exploda quando a lista é a unidade de análise: itens de linha que você vai somar, eventos que você vai contar, transações que você vai filtrar. Se você unir essas listas, os números por item ficam presos dentro de uma célula de texto, e nenhuma fórmula de planilha os recupera de forma limpa. A regra prática: se você algum dia for filtrar, contar ou somar valores individuais dentro da lista, exploda-a. Se a lista só for lida como um todo, una-a.

Explodido, o exemplo resolvido vira cinco linhas incluindo o cabeçalho: A-101 duas vezes (book, depois pen), A-102 uma vez (lamp), A-103 uma vez com um item vazio. Os campos do pedido se repetem em cada linha, o que parece redundante e é exatamente o ponto: cada linha agora é um fato analisável.

Explodir ou unir? Decida pelo significado da lista

A decisão entre explodir ou unir é o único ponto em que o achatamento dá errado em silêncio, porque as duas saídas parecem CSV válido. Uma lista unida de itens de linha abre bem no Excel, e nada avisa que os preços por item agora são texto irrecuperável. Faça uma pergunta por lista antes de achatá-la, e a escolha se faz sozinha.

Você vai filtrar, contar ou somar valores individuais dentro desta lista? Se sim, exploda-a. Itens de linha, eventos, transações e medições pertencem a este grupo.
A lista só é lida como um todo? Se sim, una-a. Tags, categorias, habilidades e rótulos pertencem a este grupo.
Está em dúvida? Exploda. Uma tabela explodida sempre pode ser agrupada de volta em células unidas, mas uma célula unida não pode ser dividida de volta em linhas com confiabilidade, porque o separador também pode aparecer dentro de um valor.
A lista contém objetos, não valores simples? Então nenhum movimento se aplica diretamente: uma lista de objetos vira uma célula de texto JSON quando unida, ou precisa ter seus campos com pontos antes de explodir. Veja a seção sobre profundidade para esse caso.

Até que profundidade achatar?

Achatar até as folhas parece completo, e produz as piores tabelas: dezenas de colunas com nomes de quatro níveis com pontos, a maioria vazia, nenhuma legível. Achate até a profundidade que você realmente vai usar. Se você vai filtrar ou ordenar por um campo, dê a ele uma coluna. Se você só vai lê-lo em contexto, deixe essa subárvore como uma única célula de texto JSON.

Uma regra prática de parada: achate dois a três níveis de profundidade e mantenha qualquer coisa mais profunda como texto JSON. Uma lista de rastreamento de objetos de envio, por exemplo, é dado real, mas raramente pertence a colunas: uma célula de rastreamento com o texto JSON mantém a tabela legível, e o arquivo JSON original mantém o detalhe completo. O CSV achatado é uma visão derivada dos seus dados, não um substituto dele, por isso guarde o arquivo JSON original.

Dados irregulares: chaves ausentes, listas vazias e nulos

JSON real é irregular: um registro tem um campo que o próximo não tem, uma lista está vazia, um valor é nulo. O achatamento trata os três com a mesma regra sem graça, e sem graça é o que você quer: a linha de cabeçalho é a união de todas as chaves encontradas em qualquer lugar dos dados, e qualquer registro sem uma chave ganha uma célula vazia ali. Nenhum erro, nenhuma linha descartada, apenas uma célula vazia que você pode ver.

Listas vazias e nulos seguem a mesma regra nos dois movimentos. Unida, uma lista vazia vira uma célula vazia. Explodida, uma lista vazia ainda gera uma linha com um item vazio, de modo que o registro pai sobrevive. Um nulo dentro de uma lista vira um segmento vazio entre os separadores: uma lista de mug, nulo e plate une-se em mug; ; plate, com a lacuna visível exatamente onde o nulo estava.

Nulos e segmentos vazios, verificados no mecanismo real

orderId,items
A-101,book; pen
A-103,mug; ; plate

Receita 1: Python, json_normalize mais explode

Python com pandas é o caminho mais tolerante, porque o json_normalize achata os objetos e o explode cuida das listas em duas linhas legíveis. Executado no exemplo de três pedidos, o json_normalize produziu as colunas orderId, items, total, customer.name e customer.city, e o explode em items transformou 3 linhas em 4, com a lista vazia deixando uma linha com um item vazio.

flatten.py, json_normalize mais explode (verificado)

import json
import pandas as pd

rows = json.load(open('orders.json'))
df = pd.json_normalize(rows)
flat = df.explode('items')
flat.to_csv('orders-flat.csv', index=False)

Se você quer o movimento de unir em vez de explodir, pule a linha do explode: o json_normalize deixa a lista como uma lista, e uma linha de união a transforma na célula separada por ponto e vírgula. O mesmo script, portanto, cobre as duas decisões, e é por isso que é a receita a procurar quando o achatamento não é algo único.

Receita 2: jq, explodir em um único comando

O jq explode uma lista em um único comando, sem arquivo de script e sem dependências além do próprio jq. A receita abaixo associa cada pedido a uma variável, verifica se sua lista items está vazia e emite uma linha com um item vazio ou uma linha por item. Executada no exemplo resolvido, ela produziu exatamente a saída de cinco linhas descrita na seção sobre explodir: A-101 duas vezes, A-102 uma vez, A-103 uma vez com um item vazio.

jq: explodir items em uma linha por item (verificado)

jq -r '. as $rows | (["orderId","name","city","item","total"] | @csv), ($rows[] | . as $o | if (.items | length) == 0 then [$o.orderId, $o.customer.name, $o.customer.city, "", $o.total] | @csv else (.items[] | [$o.orderId, $o.customer.name, $o.customer.city, ., $o.total] | @csv) end)' orders.json

O ramo da lista vazia é a parte que a maioria das receitas de explode em jq na internet omite, e é a parte que perde dados: sem ele, pedidos sem itens somem da saída por completo. Mantenha-o, mesmo quando seus dados atuais não têm listas vazias, porque o próximo arquivo terá.

Receita 3: Excel Power Query, sem código

Se o seu destino já é o Excel, o Power Query achata JSON sem nenhum código. Importe com Dados, depois Obter Dados, depois De Arquivo, depois De JSON, e o Power Query mostra cada registro como uma linha com as colunas aninhadas ainda dobradas. As duas operações de expansão correspondem exatamente aos dois movimentos de lista deste guia, e escolher a errada é o mesmo erro que em qualquer ferramenta.

Expanda uma coluna de registro (customer) com a seta de expansão e marque os campos que você quer: name e city viram colunas simples. Este é o Passo 1.
Expanda uma coluna de lista (items) com a seta de expansão e escolha Expandir para Novas Linhas para explodi-la: uma linha por item, campos do pai repetidos. Este é o Passo 3.
Expanda uma coluna de lista e escolha Extrair Valores, com um separador ponto e vírgula e espaço, para uni-la em uma única célula. Este é o Passo 2.
Repita para cada coluna aninhada até a tabela ficar plana na profundidade de que você precisa, depois Fechar e Carregar.

Receita 4: o conversor online une, mas nunca explode

O conversor gratuito deste site achata com o botão de achatamento ligado: objetos aninhados viram colunas com notação de ponto e listas unem-se em células separadas por ponto e vírgula, exatamente os Passos 1 e 2. Com o botão desligado, os valores aninhados ficam como texto JSON dentro de suas células, que é a opção de deixar aninhado do título. O que o conversor não faz é explodir: não há opção que transforme um pedido em uma linha por item.

Isso é uma limitação honesta, não um defeito. Explodir muda a contagem de linhas, o que é uma decisão de modelagem de dados, e um conversor de um clique não deveria tomá-la em silêncio. Se sua lista precisa ser explodida, use a receita em Python ou jq acima, e use o conversor para os muitos arquivos em que unir é a escolha certa.

Abrir o conversor gratuito de JSON para CSV

Dá para desfazer o achatamento?

Achatar é fácil de reverter para objetos e difícil de reverter exatamente para listas explodidas, por isso planeje-se para isso. Colunas com pontos dividem-se de volta em objetos aninhados com um pequeno script, e nada se perde, porque os pontos registraram o caminho completo. Linhas explodidas agrupam-se de volta com um agrupar por na chave pai, coletando os itens em uma lista de novo, mas a ordem original dos itens só sobrevive se você manteve um índice de linha, e as listas vazias originais são indistinguíveis das ausentes.

A regra prática decorre disso: nunca trate o CSV achatado como sua única cópia. Guarde o arquivo JSON original, trate o CSV como uma visão derivada construída para uma análise, e achate de novo a partir do JSON quando a análise mudar. Armazenamento é barato, e derivar de novo a partir da fonte supera depurar um CSV que perdeu estrutura em silêncio.

Checklist de achatamento

Antes de achatar qualquer arquivo JSON, passe por estas seis verificações. Elas levam um minuto e pegam todos os modos de falha deste guia.

Nomeie a unidade de análise primeiro: uma linha por pedido, por item ou por evento? Essa resposta escolhe explodir ou unir para cada lista.
Achate objetos até a profundidade em que você vai filtrar ou ordenar, e deixe subárvores mais profundas como texto JSON.
Verifique cada lista: valores simples unem ou explodem de forma limpa, mas uma lista de objetos precisa ter seus campos com pontos antes de qualquer movimento fazer sentido.
Espere dados irregulares: chaves ausentes viram células vazias, listas vazias viram uma linha vazia ou célula vazia, nulos viram segmentos vazios.
Cuidado com pontos dentro de nomes de chaves: uma chave como version.2 colide com um caminho aninhado do mesmo nome, e uma delas vence em silêncio.
Guarde o JSON original. O CSV achatado é uma visão derivada, não a fonte da verdade.

Guias relacionados

Perguntas frequentes

O que significa achatar dados JSON?

Significa transformar uma árvore JSON aninhada em uma tabela plana de linhas e colunas. Objetos aninhados viram colunas com notação de ponto (customer.name), listas de valores simples unem-se em uma única célula (book; pen) ou explodem em uma linha por item, e qualquer coisa que você não achatar fica como texto JSON em uma célula.

Devo achatar JSON aninhado antes de converter para CSV?

Sim, a menos que você queira texto JSON dentro das células do seu CSV. CSV não tem aninhamento, por isso dados aninhados precisam achatar, unir ou ficar como texto. Achatar com o botão ligado dá colunas reais que você pode filtrar e ordenar; deixá-lo desligado mantém os valores aninhados como texto JSON legível em células únicas.

Como explodir um array JSON em linhas, uma por item?

Exploda-o. Em Python: pd.json_normalize(rows) e depois df.explode('items'). Em jq: associe cada registro a uma variável e emita uma linha por item, com um ramo explícito para listas vazias, para que registros sem itens não sejam descartados. As duas receitas estão neste guia e foram verificadas no exemplo resolvido.

Como achatar JSON em Python?

Use pandas: carregue o arquivo com json.load, use pd.json_normalize(rows) para achatar objetos aninhados em colunas com notação de ponto e depois una as colunas de lista com um separador ou use df.explode('items') para obter uma linha por item. Para objetos aninhados sem pandas, uma pequena função recursiva de achatamento que constrói chaves com pontos faz o mesmo trabalho.

Como achatar JSON no Excel?

Use o Power Query: Dados, Obter Dados, De Arquivo, De JSON. Expanda colunas de registro para achatar objetos aninhados e expanda colunas de lista com Expandir para Novas Linhas para explodir ou Extrair Valores para unir. Repita por coluna aninhada e depois Fechar e Carregar.

O que acontece com listas vazias e nulos ao achatar JSON?

Eles viram células vazias ou segmentos vazios, nunca erros. Uma chave ausente dá uma célula vazia, uma lista vazia une-se em uma célula vazia ou explode em uma linha com um item vazio, um nulo vira uma célula vazia e um nulo dentro de uma lista vira um segmento vazio entre separadores (mug; ; plate).

Posso achatar JSON online sem instalar nada?

Sim. Cole JSON ou envie um arquivo para um conversor online gratuito com o achatamento ligado: objetos aninhados viram colunas com notação de ponto e listas unem-se em uma única célula. Se você precisa explodir uma lista em uma linha por item, use a receita em Python ou jq deste guia, porque conversores online unem listas e não as explodem.

JSON aninhado? Achate no navegador, grátis

Cole JSON ou envie um arquivo: objetos aninhados achatam-se em colunas com notação de ponto, listas unem-se em células limpas e o download é UTF-8 simples. Grátis, sem cadastro, roda totalmente no seu navegador.

Abrir o conversor de JSON para CSV

Todos os guias