Jak spłaszczyć zagnieżdżony JSON do CSV: 5 strategii i macierz decyzji

Problem geometrii

Za każdym razem wpada się w tę samą ścianę. API zwraca zagnieżdżony JSON, a analityk na Slacku chce po prostu arkusza kalkulacyjnego. mongoexport produkuje opakowania $oid i trzy poziomy metadanych, a BigQuery oczekuje płaskiej tabeli. Spłaszczanie zagnieżdżonego JSON do CSV to nie problem składni. To problem geometrii. JSON jest drzewem, CSV — siatką, a drzewa nie da się przenieść w siatkę bez wybrania sposobu, w jaki zwiną się gałęzie.

Istnieje dokładnie pięć strategii zwijania. Wybór niewłaściwej oznacza wysłanie 200 kolumn do Excela, utratę precyzji ID z Twittera albo zerwanie pętli round-trip, na której opiera się pipeline. Wybór właściwej zamienia konwersję w jednoliniowiec.

Strategia	Jednoliniowiec	Najlepsza dla
Notacja kropkowa	customer.address.city	Analizy w Excelu/Sheets
Podkreślniki	customer_address_city	Kolumn przyjaznych SQL
Indeksowane tablice	items.0.sku, items.1.sku	Tablic o stałym rozmiarze
Eksplozja wierszy	Powtórz rodzica dla każdego dziecka	Analityki w Pandas/BigQuery
Stringify	"{\"city\":\"Seattle\"}" w jednej komórce	Bezstratnego round-trip

Ten przewodnik prowadzi przez każdą strategię, podaje macierz decyzji według odbiorcy (Excel, Pandas, BigQuery, Postgres) i pokazuje cztery prawdziwe payloady, w których właściwa strategia nie jest tą oczywistą. Jeśli potrzebny jest też ogólny przegląd dwukierunkowy (biblioteki parserów, strumieniowanie, pułapki kodowania), zobacz Konwersja CSV na JSON: metody, pułapki i przykłady kodu.

Dlaczego zagnieżdżony JSON nie mieści się w CSV

JSON niesie trzy rodzaje struktury, których CSV brakuje. Hierarchia to obiekt wewnątrz obiektu. Sekwencja to tablica. Mieszane to kombinacja: tablice obiektów, obiekty z tablicami, tablice tablic. Typowe zamówienie e-commerce ma wszystkie trzy naraz.

CSV ma dokładnie dwa wymiary: wiersze i kolumny. Nie ma trzeciej osi dla „ta kolumna trzyma troje dzieci”. Gdy żąda się siatki od drzewa, coś musi ustąpić. Albo rozłożyć dzieci na więcej kolumn (i żyć z nazwami w stylu items.0.options.0.value), albo rozłożyć je na więcej wierszy (pola rodzica się powtarzają), albo upchnąć je w jednej komórce jako tekst i przestać traktować je jak strukturę.

Każda strategia poniżej odpowiada na to pytanie inaczej. Niektóre zachowują czytelność, a tracą bezpieczeństwo round-trip. Inne — na odwrót. Żadna nie jest uniwersalna. Dopasuj odpowiedź do tego, kto przeczyta plik jako następny.

Porównanie 5 strategii spłaszczania

Strategia 1: notacja kropkowa (customer.address.city)

Notacja kropkowa wędruje od korzenia do liścia i używa . do łączenia kluczy. Każdy zagnieżdżony obiekt staje się jedną kolumną na liść, a ścieżka jest zakodowana w nazwie kolumny.

{ "customer": { "address": { "city": "Seattle" } }, "email": "alice@example.com" }

staje się

customer.address.city,email
Seattle,alice@example.com

W Pandas wystarczy jedna linia:

import pandas as pd

data = [{"customer": {"address": {"city": "Seattle"}}, "email": "alice@example.com"}]
df = pd.json_normalize(data, sep='.')
df.to_csv("out.csv", index=False)

W JavaScripcie wystarczy mała funkcja rekurencyjna:

function flattenDot(obj, prefix = '', acc = {}) {
  for (const [k, v] of Object.entries(obj)) {
    const key = prefix ? `${prefix}.${k}` : k;
    if (v && typeof v === 'object' && !Array.isArray(v)) {
      flattenDot(v, key, acc);
    } else {
      acc[key] = v;
    }
  }
  return acc;
}

Zalety: czytelne dla człowieka, domyślne w Pandas, zachowuje oryginalną ścieżkę. Wady: nazwy kolumn potrafią rozciągać się w długość (specyfikacje Kubernetes produkują nazwy w stylu spec.template.spec.containers.0.resources.limits.memory), a kropka staje się dwuznaczna, jeśli prawdziwy klucz zawiera . (parametry zdarzeń Google Analytics 4 tak właśnie robią).

Strategia 2: notacja z podkreślnikami (customer_address_city)

Ten sam pomysł, inny separator. Zastąp . przez _, a wynik jest bezpieczny dla SQL: SELECT customer_address_city FROM events działa bez cytowania identyfikatora. BigQuery, Snowflake i Postgres wszystkie wolą tę formę.

import pandas as pd
df = pd.json_normalize(data, sep='_')

Wybór między kropką a podkreślnikiem dotyczy wyłącznie narzędzia odbierającego. Analitycy w Excelu naturalniej czytają kropkę; silniki SQL bez narzekania akceptują podkreślnik. Przełączenie to zmiana jednego argumentu.

Zalety: nazwy kolumn bezpieczne dla SQL, identyfikatory zgodne z BigQuery, bez konieczności cytowania. Wady: dwuznaczność pozostaje, jeśli klucz zawiera _ (rzadziej niż ., ale wciąż możliwe).

Strategia 3: indeksowane tablice (items.0.sku, items.1.sku)

Obiekty spłaszczają się czysto, bo klucze są unikalne. Tablice — nie, bo długość jest nieograniczona. Strategia indeksowana traktuje pozycje w tablicy jak segmenty ścieżki: items[0] staje się items.0.

{ "id": "ord-001", "items": [{"sku": "A"}, {"sku": "B"}] }

staje się

id,items.0.sku,items.1.sku
ord-001,A,B

To domyślne zachowanie trybu Flatten w naszym Konwerterze JSON na CSV. Każdy liść dostaje własną kolumnę; pozycja jest zapisana w nazwie.

Zalety: każda wartość dostaje własną komórkę, pozycja zachowana, bez duplikacji wierszy. Wady: liczba kolumn eksploduje (100 elementów = 100 kolumn); wiersze o różnych długościach tablic produkują postrzępione tabele; agregacja po stronie odbiorcy nie działa (nie ma SUM(items.*.qty)).

Strategia 4: eksplozja wierszy (tablica do wielu wierszy)

Zamiast poszerzać tabelę, by zmieściła tablicę, wydłuż ją. Powtórz pola rodzica raz na element tablicy i pozwól, by każdy element stał się własnym wierszem.

{ "order_id": "ord-001", "customer": "Alice", "items": [{"sku": "A", "qty": 2}, {"sku": "B", "qty": 1}] }

staje się

order_id,customer,items.sku,items.qty
ord-001,Alice,A,2
ord-001,Alice,B,1

W Pandas jedna linia załatwia i eksplozję, i normalizację:

import pandas as pd

orders = [{"order_id": "ord-001", "customer": "Alice",
           "items": [{"sku": "A", "qty": 2}, {"sku": "B", "qty": 1}]}]
df = pd.json_normalize(orders, record_path='items', meta=['order_id', 'customer'])
df.to_csv("orders.csv", index=False)

W SQL UNNEST robi to samo:

SELECT order_id, item.sku, item.qty FROM orders, UNNEST(items) AS item;

Zalety: Pandas i BigQuery traktują ten kształt natywnie, agregacje działają (GROUP BY order_id), schemat pozostaje wąski. Wady: pola rodzica duplikują się w każdym wierszu-dziecku (przyrost pamięci), granica 1-do-wielu jest niejawna (potrzebny jest order_id), a dwie tablice na tym samym poziomie produkują iloczyn kartezjański, jeśli nie zrobi się UNNEST ostrożnie.

Strategia 5: stringify (JSON w komórce)

Opcja radykalna: nie spłaszczać wcale. Zserializuj całą zagnieżdżoną wartość jako string JSON i umieść ją w jednej komórce. Zewnętrzna tabela pozostaje płaska; struktura jest zachowana dosłownie w środku.

{ "id": "ord-001", "items": [{"sku": "A"}, {"sku": "B"}] }

staje się

id,items
ord-001,"[{""sku"":""A""},{""sku"":""B""}]"

To tryb Stringify w naszym Konwerterze JSON na CSV. Liczba kolumn nigdy nie eksploduje, oryginalny kształt jest zachowany bajt po bajcie, a podróż odwrotna rekonstruuje wejście dokładnie tak, jak wyglądało.

Zalety: 100% bezstratne, przewidywalna liczba kolumn, bezpieczny round-trip w parze z włączonym Infer types przy odwracaniu. Wady: użytkownicy Excela widzą escapowane cudzysłowy, silniki SQL potrzebują funkcji JSON, żeby odpytać wartość (JSON_EXTRACT_SCALAR w BigQuery, ->>'key' w Postgres), a formuły arkusza nie sięgają do wnętrza komórki.

5 strategii obok siebie

To samo wejście w pięciu wariantach: {"id":"ord-001","customer":{"name":"Alice"},"items":[{"sku":"A","qty":2},{"sku":"B","qty":1}]}.

Strategia	Kolumny	Bezpieczny round-trip	Najlepszy odbiorca
Notacja kropkowa	rośnie z tablicą	Nie	Analityk w Excelu
Podkreślniki	rośnie z tablicą	Nie	Hurtownia SQL
Indeksowane tablice	2 na slot tablicy	Nie (dwuznaczna przy odwracaniu)	Tablice o stałym rozmiarze
Eksplozja wierszy	wąskie, 1 wiersz na dziecko	Częściowo (potrzebny klucz)	Pandas / BigQuery
Stringify	stałe	Tak	Pipeline z round-trip

Macierz decyzji: która strategia dla którego odbiorcy

Najpierw znajdź odbiorcę, potem odczytaj rekomendowaną strategię.

Odbiorca	Rekomendowana strategia	Dlaczego
Excel / Sheets (analityk)	Kropka + Stringify dla dużych tablic	Czytelne nazwy kolumn; duże tablice nie rozsadzają arkusza
Excel-EU (DE/FR/IT/ES)	Kropka + ogranicznik ; + UTF-8 BOM	Średnik wymagany; BOM zapobiega przekłamaniom kodowania
Pandas (json_normalize + explode)	Podkreślniki + eksplozja wierszy	Kolumny przyjazne SQL; eksplozja dobrze gra z groupby
BigQuery / Snowflake	TSV + Stringify lub eksplozja	Tab unika pułapek z cudzysłowami; JSON_EXTRACT odpytuje komórkę
PostgreSQL COPY	RFC 4180 + Podkreślniki + płasko	Kolumny bezpieczne dla SQL; surowe cytowanie RFC
MongoDB → BigQuery ETL	Załaduj NDJSON bezpośrednio, omiń CSV	BigQuery ładuje NDJSON natywnie; CSV to objazd

Excel / Google Sheets: pułapka lokalizacji

Nazwy kolumn w Excelu nie mają praktycznego limitu długości. Prawdziwe pułapki są trzy.

Po pierwsze, podział lokalizacyjny. Europejski Excel (Niemcy, Francja, Włochy, Hiszpania) oczekuje ; jako ogranicznika, ponieważ , jest separatorem dziesiętnym. CSV z przecinkami otwiera się z każdym wierszem zwiniętym w kolumnę A. Preset Excel w naszym narzędziu json-na-csv jednym kliknięciem przełącza na ; + CRLF + UTF-8 BOM.

Po drugie, notacja naukowa. Excel widzi 9007199254740993 i renderuje 9.00719925474E+15. Trzymaj duże liczby całkowite jako stringi w źródłowym JSON i włącz BOM, żeby Excel zachował komórkę jako tekst. Nasz konwerter wykrywa duże liczby całkowite automatycznie.

Po trzecie, praktyczny limit kolumn. Excel teoretycznie obsługuje 16 384 kolumn, ale powyżej ~500 robi się to nie do opanowania. Stringify ciężkie poddrzewa albo wyciągnij interesujące pola przez jq przed konwersją.

Pandas: json_normalize + explode

Standardowy wzorzec dla zagnieżdżonych tablic to record_path + meta w jednym przejściu:

import pandas as pd

orders = [{
    "order_id": "ord-001",
    "customer": {"name": "Alice", "city": "Seattle"},
    "items": [{"sku": "SKU-100", "qty": 2}, {"sku": "SKU-205", "qty": 1}]
}]

df = pd.json_normalize(orders, record_path='items',
    meta=['order_id', ['customer', 'name'], ['customer', 'city']], sep='_')
df.to_csv("orders.csv", index=False)

Wynik to jeden wiersz na element z powtórzonymi order_id, customer_name i customer_city. To bije uruchamianie explode najpierw, a json_normalize potem: record_path pomija pośrednią kolumnę obiektu, a meta pozwala kontrolować, które pola rodzica się propagują. Dla wejść, gdzie elementy tablicy zawierają zagnieżdżone obiekty, ustaw max_level=, by ograniczyć głębokość.

BigQuery / Snowflake: TSV + JSON w komórce

LOAD DATA w BigQuery jest surowe, jeśli chodzi o cytowanie CSV, i często źle parsuje pliki z przecinkami wewnątrz cytowanego tekstu. TSV jest bezpieczniejsze, bo taby prawie nigdy nie pojawiają się w polach tekstowych:

bq load --source_format=CSV --field_delimiter='\t' \
  dataset.orders gs://bucket/orders.tsv \
  order_id:STRING,customer:STRING,items:STRING

Gdy załaduje się zagnieżdżone dane jako Stringified JSON w pojedynczej kolumnie, BigQuery wciąż odpytuje je przez JSON_EXTRACT_SCALAR:

SELECT order_id, JSON_EXTRACT_SCALAR(items, '$[0].sku') AS first_sku
FROM dataset.orders;

Snowflake oferuje tę samą możliwość przez VARIANT, z zapytaniami po ścieżce w stylu items:0.sku::STRING. W obu silnikach Stringify + zapytania po ścieżce JSON biją pełne spłaszczanie, gdy zagnieżdżone tablice są duże lub o zmiennej długości.

PostgreSQL COPY: surowy RFC 4180

COPY ... FROM ... WITH (FORMAT csv, HEADER true) to najsurowszy czytnik RFC 4180, jaki spotyka się na co dzień. Dwa zachowania zwykle podcinają.

Po pierwsze, COPY nie akceptuje UTF-8 BOM. Znacznik kolejności bajtów staje się dosłownym prefiksem pierwszej nazwy kolumny (id zamiast id), a każde zapytanie odwołujące się do id cicho się wywala. Wyłącz BOM dla celów Postgres.

Po drugie, COPY nie potrafi natywnie parsować zagnieżdżonych danych. Albo rozłóż tablice na wiele wierszy przed załadowaniem, albo zdefiniuj cel jako jsonb i zserializuj zagnieżdżoną wartość:

CREATE TABLE orders (order_id text PRIMARY KEY, customer text, items jsonb);
COPY orders FROM '/tmp/orders.csv' WITH (FORMAT csv, HEADER true);
SELECT order_id, items->0->>'sku' AS first_sku FROM orders;

Dla pipeline’ów, które i tak mówią JSON od końca do końca, omiń CSV i użyj COPY ... FROM ... WITH (FORMAT text) z wejściem po jednej linii JSON.

Przejścia przez prawdziwe payloady

Przejście 1: zamówienia e-commerce (klient + tablica items)

Typowe zamówienie łączy zagnieżdżone informacje o kliencie z tablicą items o zmiennej długości:

[{ "id": "ord-001",
   "customer": { "name": "Alice", "address": {"city": "Seattle", "country": "US"} },
   "items": [{"sku": "SKU-100", "qty": 2}, {"sku": "SKU-205", "qty": 1}] }]

Właściwa strategia zależy od tego, kto czyta plik. Finansy chcą jednego wiersza na element, by policzyć przychód na SKU; to strategia eksplozji, produkująca dwa wiersze z powtórzonymi id i customer.name. Operacje chcą jednego wiersza na zamówienie do dashboardów realizacji; to notacja kropkowa ze Stringifiedowanym items, żeby tablica nie rozsadziła liczby kolumn. To samo wejście, dwa wyjścia, oba poprawne dla swojego odbiorcy.

Wypróbuj bezpośrednio: wklej payload do naszego Konwertera JSON na CSV i przełączaj Flatten kontra Stringify w opcji Nested. Przykład „Nested E-commerce Orders” ładuje ten sam kształt.

Przejście 2: GitHub Issues API (tablica labels + obiekt user)

Endpoint /repos/{owner}/{repo}/issues zwraca mieszany zagnieżdżony kształt:

[{ "id": 1001, "title": "Bug: login 404", "state": "open",
   "labels": ["bug", "priority:high"], "user": {"login": "alice"} }]

user to obiekt z jednym przydatnym polem; labels to tablica stringów o nieograniczonej długości. Pragmatyczne spłaszczenie jest hybrydowe: notacja kropkowa na user (interesuje tylko user.login) i inline-join na labels do pojedynczej komórki rozdzielonej przez ;:

id,title,state,labels,user.login
1001,Bug: login 404,open,bug;priority:high,alice

Nie da się objąć jednocześnie „złącz tablice w komórkę” i „spłaszcz obiekty z kropkami” w jednej strategii. Nasz konwerter automatycznie obsługuje spłaszczanie obiektów; przetwórz labels wstępnie przez jq (map(.labels = (.labels | join(";")))) lub zaakceptuj domyślne stringifyowanie tablic.

Przejście 3: MongoDB mongoexport ($oid + metadane)

mongoexport --jsonArray produkuje opakowania Extended JSON:

[{ "_id": {"$oid": "6634a1b2c3d4e5f600000001"},
   "email": "alice@example.com",
   "metadata": { "signupDate": "2026-01-15T10:30:00Z",
                 "preferences": {"newsletter": true, "theme": "dark"} } }]

Opakowanie $oid produkuje kolumnę dosłownie nazwaną _id.$oid, którą większość silników SQL odrzuca. Przetwórz wstępnie przez jq, żeby je odpakować:

mongoexport --collection=users --jsonArray | jq 'map(._id = ._id."$oid")' > users.json

Dla głęboko zagnieżdżonego bloku metadata.preferences wybór zależy od odbiorcy. Eksport dla analityka: spłaszcz całość kropkami; metadata.preferences.theme czyta się dobrze. Round-trip pipeline’u: zserializuj metadata, żeby zachować nietkniętą strukturę. Pełne wzorce jq, które łączą się z pipeline’ami CSV, znajdziesz w naszym jq Cheat Sheet.

Przejście 4: Kubernetes Pod Spec (głęboko zagnieżdżone)

Odpowiedź kubectl get pod -o json to najgorszy przypadek dla płaskich strategii. Struktura rutynowo schodzi sześć poziomów w głąb (spec.template.spec.containers.0.resources.limits.memory). Naiwne spłaszczanie kropkami produkuje nazwy kolumn przekraczające 70 znaków i ponad 200 kolumn wyjścia. Działają dwie strategie.

Wstępna projekcja przez kubectl jsonpath. Wybierz tylko te pola, których naprawdę potrzebujesz:

kubectl get pods -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.containers[0].image}{"\t"}{.status.phase}{"\n"}{end}' > pods.tsv

Zserializuj spec, spłaszcz metadata. Trzymaj metadata (name, namespace, labels) płasko, a spec zserializuj w pojedynczą komórkę:

kubectl get pods -o json | jq 'map({name: .metadata.name, namespace: .metadata.namespace, spec: (.spec | tostring)})'

Potem wklej do konwertera w trybie Flatten. Kolumna spec staje się jedną komórką JSON; kolumny metadata pozostają czytelne. Unikaj antywzorca kubectl get pod -o json | json-to-csv flatten bez wstępnej projekcji. Liczba kolumn będzie nie do opanowania.

Bezpieczeństwo round-trip: spłaszczanie jest stratne, Stringify bezstratny

Oto twierdzenie, które konkurencyjne przewodniki pomijają. Notacja kropkowa, notacja z podkreślnikami, indeksowane tablice i eksplozja wierszy to wszystko jednokierunkowe projekcje. Po spłaszczeniu którąkolwiek z nich oryginalny JSON nie da się idealnie zrekonstruować z samego CSV.

Kontrprzykłady łatwo skonstruować. Kolumna nazwana customer.address.city jest dwuznaczna między {"customer": {"address": {"city": "..."}}} a {"customer": {"address.city": "..."}}. Indeksowane tablice wyglądają na odwracalne, ale CSV nie potrafi powiedzieć, czy items.0.sku powinno zrekonstruować się do tablicy, czy do obiektu z kluczem liczbowym. Eksplozja wierszy wymaga klucza grupującego; bez order_id nie da się powiedzieć, które wiersze należały do tego samego rodzica.

Tylko Stringify przeżywa round-trip. Zagnieżdżona wartość jest zachowana dosłownie jako string JSON, więc konwerter odwrotny czyta komórkę, parsuje ją i wstawia oryginał nietknięty. Skonwertuj ze Stringify, zapisz CSV, wklej do naszego Konwertera CSV na JSON, włącz Infer types i otrzymasz bajty identyczne z wejściem.

Reguła praktyczna: round-trip pipeline’u → Stringify. Jednorazowa analiza lub raportowanie → kropka, podkreślniki lub eksplozja w zależności od odbiorcy.

Robienie tego w naszym narzędziu przeglądarkowym

Konwerter JSON na CSV udostępnia dwie z pięciu strategii bezpośrednio: Flatten (łączące notację kropkową i indeksowane tablice) oraz Stringify (zachowujące strukturę wewnątrz komórki). Pozostałe trzy (podkreślniki, eksplozja wierszy, presety pod cel SQL) są o jeden krok preprocessingu dalej.

Typowa sesja zajmuje pięć kliknięć:

1. Zwaliduj wejście naszym Formatowaniem JSON, żeby błędy składni nie zamieniły się w ciche porażki konwersji.
2. Wklej JSON do Konwertera JSON na CSV. Konwersja uruchamia się natychmiast.
3. Ustaw Nested na Flatten dla kluczy kropkowych i indeksowanych albo na Stringify, by trzymać tablice i obiekty w pojedynczych komórkach.
4. Wybierz preset: RFC 4180 dla pipeline’ów, Excel dla arkuszy EU, TSV dla hurtowni, Pipe dla tekstu pełnego przecinków.
5. Kliknij Swap direction i użyj Konwertera CSV na JSON z włączonym Infer types, żeby zweryfikować round-trip Stringify.

Wszystko działa w przeglądarce. PII, wewnętrzne eksporty i sekrety produkcyjne nie opuszczają strony; po jej załadowaniu konwerter nie wysyła żadnego żądania sieciowego. Dzięki temu narzędzie nadaje się do wrażliwych danych w sytuacjach, w których wgrywanie do serwisu trzeciej strony nie wchodzi w grę.

Częste pułapki

Sześć trybów porażki powraca raz za razem.

1. Eksplozja nazw kolumn. Specyfikacje Kubernetes i wątki review PR-ów na GitHubie produkują setki ścieżek liści. Lekarstwo: wstępna projekcja przez jq lub kubectl jsonpath albo stringify ciężkich poddrzew przy spłaszczaniu metadanych.
2. Niezgodność długości tablic. Wiersz 1 ma 3 elementy, wiersz 2 ma 5 elementów. Indeksowane tablice produkują puste komórki w items.3.sku i items.4.sku dla wiersza 1. Lekarstwo: przełącz na eksplozję wierszy.
3. Klucze indeksów traktowane jako stringi przy odwracaniu. Gdy CSV-na-JSON widzi items.0.sku, 0 to technicznie klucz stringowy. Niektóre konwertery odwrotne rekonstruują {"0": {"sku": "A"}} zamiast [{"sku": "A"}]. Lekarstwo: użyj Stringify dla round-tripów.
4. Klucze już zawierające separator. Zdarzenia GA4 mają klucze typu event_params.key zawierające dosłowne kropki; spłaszczanie przez . produkuje dwuznaczne ścieżki. Lekarstwo: użyj podkreślnika lub zmień nazwy problematycznych kluczy. Zobacz nasz przewodnik JSON5 i JSONC, gdzie znajdziesz tło formatów JSON z rozszerzonym wsparciem dla kluczy.
5. Typy mieszane na różnych poziomach. Niektóre wiersze mają address jako obiekt, inne jako null. Spłaszczanie produkuje puste komórki tam, gdzie obiekt był null. Ostrzeżenie o uwagach do schematu na naszym konwerterze sygnalizuje to, żeby można było zweryfikować odbiorcę.
6. Duże liczby całkowite obcięte przez Excela. $oid Long, Twitterowy snowflake ID albo resourceVersion z K8s przekracza bezpieczny zakres JavaScriptu (2^53 - 1) i jest po cichu zaokrąglany. Excel renderuje je potem jako 9.00719925474E+15. Lekarstwo: trzymaj ID jako stringi w źródłowym JSON, włącz BOM i użyj presetu Excel.

FAQ

Jaki jest najlepszy sposób spłaszczania zagnieżdżonego JSON do CSV?

Najlepszy sposób spłaszczania zagnieżdżonego JSON do CSV zależy od odbiorcy. Użyj notacji kropkowej dla Excela lub Google Sheets. Użyj eksplozji wierszy, gdy Pandas lub BigQuery będą agregować dane. Użyj Stringify, gdy CSV musi wrócić do JSON bez utraty danych. Dopasuj strategię do następnego czytelnika.

Jak skonwertować tablicę JSON na wiele wierszy CSV?

Skonwertuj tablicę JSON na wiele wierszy CSV za pomocą strategii eksplozji: zduplikuj pola rodzica raz na element tablicy, żeby każdy stał się własnym wierszem. W Pandas pd.json_normalize(data, record_path='items', meta=['order_id']) robi to jednym wywołaniem. W SQL UNNEST(items) produkuje ten sam kształt. Klucze rodzica powtarzają się między wybuchniętymi wierszami.

Czy mogę zrobić round-trip CSV z powrotem do oryginalnego zagnieżdżonego JSON?

Round-trip CSV z powrotem do oryginalnego zagnieżdżonego JSON działa tylko z trybem Stringify. Notacja kropkowa, podkreślniki, indeksowane tablice i eksplozja wierszy to stratne jednokierunkowe projekcje; konwerter odwrotny nie potrafi idealnie zrekonstruować drzewa. Stringify zachowuje tablice i obiekty jako JSON wewnątrz pojedynczej komórki, więc pełny round-trip jest identyczny bajtowo, gdy Infer types jest włączony.

Dlaczego Excel pokazuje mój spłaszczony JSON jako jedną długą kolumnę?

Excel pokazuje spłaszczony JSON jako jedną długą kolumnę, gdy znajdujesz się w europejskiej lokalizacji (Niemcy, Francja, Włochy, Hiszpania), w której przecinek jest zarezerwowany dla liczb dziesiętnych i Excel oczekuje średnika jako ogranicznika. Preset Excel w narzędziu json-na-csv jednym kliknięciem przełącza na ; + CRLF + UTF-8 BOM.

Czy używać notacji kropkowej, czy podkreślników do nazw kolumn?

Użyj notacji kropkowej, gdy celem jest Excel, Google Sheets lub Pandas; kropki są domyślne w json_normalize i czytają się naturalnie. Użyj podkreślników, gdy celem jest SQL: Postgres, BigQuery i Snowflake wymagają cytowania wokół identyfikatorów zawierających kropki, podczas gdy podkreślniki są akceptowane bez cytowania wszędzie.

Jak pandas json_normalize obsługuje tablice obiektów?

Pandas json_normalize obsługuje tablice obiektów przez argumenty record_path i meta. pd.json_normalize(data, record_path='items', meta=['order_id']) rozkłada items na jeden wiersz na element z powtórzonym order_id. Dla zagnieżdżonych obiektów bez tablic prostsze pd.json_normalize(data, sep='_') produkuje nazwy kolumn rozdzielone podkreślnikami w stylu customer_address_city. Użyj max_level=, by ograniczyć głębokość na głębokich drzewach.

Jaki jest limit kolumn przy spłaszczaniu głęboko zagnieżdżonego JSON?

Limit kolumn przy spłaszczaniu głęboko zagnieżdżonego JSON to 16 384 w Excelu i praktycznie nieograniczony w samym CSV, ale powyżej 500 kolumn wyjście robi się nie do opanowania. Specyfikacje Pod w Kubernetes albo odpowiedzi GraphQL łatwo to przekraczają. Zserializuj ciężkie poddrzewa przez Konwerter JSON na CSV albo zrób wstępną projekcję przez jq lub kubectl jsonpath.

Czy jq to dobre narzędzie do spłaszczania JSON przed konwersją na CSV?

Tak, jq to właściwe narzędzie do spłaszczania JSON przed konwersją na CSV. Obsługuje wstępną projekcję (map({id, name})), wstępną eksplozję (.[] | {id, item: .items[]}) i normalizację kształtu w jednej linii. Pipeline jq działa przed krokiem CSV i kontroluje dokładnie, które pola docierają do konwertera. Zobacz nasz jq Cheat Sheet, żeby zobaczyć wzorce.

Podsumowanie

Pięć wniosków:

1. JSON-na-CSV to problem geometrii, nie składni. Drzewo nie zmieści się w siatce bez wyboru, jak zwiną się gałęzie.
2. Pięć strategii pokrywa praktyczny wszechświat (kropka, podkreślniki, indeksowane tablice, eksplozja wierszy, Stringify). Wybierz według odbiorcy.
3. Stringify to jedyna bezstratna ścieżka. Użyj jej do round-tripów pipeline’u.
4. Excel-EU i BigQuery mają presety nie bez powodu. Korzystaj z nich.
5. Prawdziwe payloady (mongoexport, specyfikacje Kubernetes, odpowiedzi GitHub) zwykle wymagają najpierw kroku wstępnej projekcji przez jq lub kubectl jsonpath.

Wypróbuj własny payload w Konwerterze JSON na CSV. Działa lokalnie, obsługuje wszystkie pięć strategii i robi bezstratny round-trip w trybie Stringify. Konwersja odbywa się w przeglądarce, bez rejestracji i bez wysyłania pliku na serwer.