Salta ai contenuti

11. File grandi e streaming

  • Capire perché un JSON “classico” da 2 GB è un problema, e cosa cambia con JSON Lines.
  • Leggere una risposta HTTP riga per riga senza caricarla tutta (httpx.stream, for await in Node).
  • Usare un parser incrementale (ijson) su un array JSON gigante.
  • Sapere quale formato scegliere quando sei tu a produrre i dati.

json.loads / JSON.parse fanno due cose costose: leggono tutto il testo in memoria e costruiscono tutto l’albero di oggetti. Per un file da 50 MB va bene; per un log da 5 GB no, e non serve: quasi sempre vuoi elaborare un elemento alla volta.

La soluzione più usata è non produrre un documento ma un documento per riga:

{"id": 1, "title": "Il silenzio di Ustica", "price": 18.71}
{"id": 2, "title": "TypeScript e Ferrara", "price": 9.76}
{"id": 3, "title": "Il cervello e Matera", "price": 31.16}

Regole (jsonlines.org): codifica UTF-8, un valore JSON per riga, separatore \n, niente virgole tra le righe, niente [ ] intorno. Media type: application/x-ndjson (o application/jsonl). Estensioni: .ndjson, .jsonl.

Vantaggi: si legge riga per riga con memoria costante; si può appendere (>>) senza riscrivere il file; se una riga è corrotta perdi solo quella; grep, head, split funzionano. Svantaggio: non è un JSON valido nel suo insieme (jq . lo accetta comunque, un elemento alla volta).

Il server può iniziare a mandare la risposta prima di averla generata tutta (Transfer-Encoding: chunked). Il client, se legge in streaming, elabora i primi record mentre gli ultimi sono ancora in viaggio. È così che funziona GET /api/v1/export/books.ndjson.

Se il file è un array JSON classico e non puoi cambiarlo, un parser incrementale (SAX-like) emette gli elementi man mano che li incontra: ijson in Python, stream-json in Node.

terminale
curl -s -D - https://corso-api-json.giuseppebosi.com/api/v1/export/books.ndjson -o libri.ndjson
head -n 2 libri.ndjson | cut -c 1-120
wc -l libri.ndjson
-D -
dump headers: scrive gli header della risposta su stdout (-), separati dal corpo
-o libri.ndjson
output: salva il corpo nel file invece di stamparlo
head -n 2
prime 2 righe = primi 2 libri, perché un record = una riga
cut -c 1-120
taglia ogni riga ai primi 120 caratteri, solo per leggibilità qui
wc -l
conta le righe: 80 libri, senza aver fatto alcun parsing
HTTP/1.1 200 OK
content-type: application/x-ndjson
content-disposition: attachment; filename="books.ndjson"
transfer-encoding: chunked
{"id": 1, "title": "Il silenzio di Ustica", "isbn": "978-88-81482-001-1", "author_id": 19, "category_id": 2, "price": 18.71, …
{"id": 2, "title": "TypeScript e Ferrara", "isbn": "978-88-30379-002-3", "author_id": 11, "category_id": 9, "price": 9.76, …
80 libri.ndjson

Nota transfer-encoding: chunked e l’assenza di content-length: il server non sapeva in anticipo quanto sarebbe stata lunga la risposta, l’ha mandata a pezzi.

# pip install httpx ijson
import io, json
import httpx, ijson
BASE = "https://corso-api-json.giuseppebosi.com/api/v1"
# 1) NDJSON in streaming: memoria costante, un libro alla volta
tot, n = 0.0, 0
with httpx.stream("GET", f"{BASE}/export/books.ndjson") as r:
r.raise_for_status()
for riga in r.iter_lines(): # arriva riga per riga, mentre il server sta ancora inviando
if not riga:
continue # riga vuota finale
libro = json.loads(riga)
n += 1
tot += libro["price"]
print(n, round(tot / n, 2)) # 80 19.9
# 2) un array JSON classico letto in modo incrementale con ijson
r = httpx.get(f"{BASE}/books", params={"limit": 100})
for i, libro in enumerate(ijson.items(io.BytesIO(r.content), "items.item")):
if i < 2:
print(libro["title"], libro["price"])
# Il silenzio di Ustica 18.71
# TypeScript e Ferrara 9.76
# 3) scrivere NDJSON: una riga per record, append-friendly
with open("economici.ndjson", "a", encoding="utf-8") as f:
with httpx.stream("GET", f"{BASE}/export/books.ndjson") as r:
for riga in r.iter_lines():
if riga and json.loads(riga)["price"] < 10:
f.write(riga + "\n")

Cosa dovresti vedere:

80 19.9
Il silenzio di Ustica 18.71
TypeScript e Ferrara 9.76

"items.item" è il prefisso ijson: “gli elementi (item) dell’array sotto la chiave items”. Con un file su disco usi ijson.items(open("grande.json", "rb"), "item") per un array in radice. Nota che ijson restituisce i decimali come Decimal (precisione esatta): usa float(x) se ti serve un float.

Il browser scarica tutto e poi lo mostra, quindi qui non vedi lo streaming “dal vivo”, ma vedi il formato: una riga per libro, nessun array intorno.

GET/api/v1/export/books.ndjson— 80 libri in JSON Lines
GET/api/v1/export/books.csv— lo stesso export in CSV, per confronto

Provalo online, senza installare nulla:

Apri il notebook in Google Colab Apri il progetto TypeScript in StackBlitz

La richiesta GET diretta nel browser: https://corso-api-json.giuseppebosi.com/api/v1/export/books.ndjson

Python su Google Colab (serve un account Google gratuito per eseguire le celle); TypeScript su StackBlitz (si apre e parte da solo nel browser). Se l’API di prova è spenta, accendila da /api-attiva/.

Scrivi uno script che legge books.ndjson in streaming e produce per_categoria.ndjson: una riga per categoria con {"category": ..., "books": N, "max_price": X}. Deve funzionare anche se l’export avesse 10 milioni di righe (quindi: tieni in memoria solo l’aggregato per categoria, mai i libri).

Soluzione (Python)
import json, httpx
agg = {} # una voce per categoria: memoria proporzionale alle categorie, non ai libri
with httpx.stream("GET", "https://corso-api-json.giuseppebosi.com/api/v1/export/books.ndjson") as r:
for riga in r.iter_lines():
if not riga: continue
b = json.loads(riga)
a = agg.setdefault(b["category"], {"category": b["category"], "books": 0, "max_price": 0})
a["books"] += 1
a["max_price"] = max(a["max_price"], b["price"])
with open("per_categoria.ndjson", "w", encoding="utf-8") as f:
for a in agg.values():
f.write(json.dumps(a, ensure_ascii=False) + "\n")

Risultato: 10 righe, ad esempio {"category": "gialli", "books": 4, "max_price": 21.77}.

  • r.json() su una risposta NDJSON → JSONDecodeError: Extra data: non è un JSON, sono tanti.
  • for riga in r.text.splitlines() funziona ma ha già scaricato tutto: lo streaming vero è iter_lines() / for await.
  • Righe vuote o troncate (file in scrittura, ultima riga senza \n): salta le vuote e gestisci JSONDecodeError sull’ultima.
  • Accumulare tutti i record in una lista “per poi elaborarli”: è esattamente ciò che lo streaming voleva evitare.

JSON Lines + lettura riga per riga = memoria costante e pipeline componibili; ijson/stream-json salvano quando il file è un array classico. Prossimo capitolo: quanto costa davvero il parsing, e quando conviene una libreria più veloce.