Interroga file JSON con SQL

Trascina in DuckLocal un file JSON, NDJSON o un log compresso e diventa una tabella. Gli oggetti annidati diventano colonne da filtrare, espandere e unire con CSV e Parquet. Nessuna pipeline jq da scrivere, nessuno script da mantenere.

Gratuito e open source per macOS, Windows e Linux. I file vengono letti sul posto e mai caricati.

Dal file JSON al risultato

Il file resta dov’è. DuckDB lo legge sul posto a ogni query.

  1. Trascina il file

    events.ndjson diventa una vista chiamata events, e logs.json.gz una chiamata logs. DuckDB capisce da solo se il file è un array, un singolo oggetto o un oggetto per riga.

  2. Guarda la struttura

    La barra laterale dello schema mostra gli oggetti annidati come colonne STRUCT e gli array come colonne LIST, con i loro campi. La scheda Panoramica analizza ogni colonna di un risultato.

  3. Interrogalo come una tabella

    Filtra su un campo annidato con la notazione a punto, espandi gli array con unnest e unisci il risultato a qualsiasi altro file aperto.

Campi annidati senza codice ripetitivo

Un ordine con un array di righe diventa una riga per ordine con una lista items. unnest trasforma quella lista in una riga per articolo, e i campi di ogni articolo sono a un punto di distanza.

Per dati la cui forma cambia da un record all’altro, json_extract_string(col, '$.a.b[0].c') segue un percorso e restituisce testo, che il valore ci sia o no.

JSONL e JSON annidato · Il riferimento JSON di DuckDB

-- orders.ndjson: one order per line,
-- each with an items array
WITH lines AS (
  SELECT order_id, unnest(items) AS item
  FROM orders
)
SELECT item.sku,
       sum(item.qty) AS units
FROM lines
GROUP BY item.sku
ORDER BY units DESC;

Log, esportazioni e dump di API

Indica a DuckLocal una cartella o un pattern come logs/2026-*/*.json.gz e ogni corrispondenza si apre come dati. I file compressi non vanno decompressi.

Alcuni strumenti avvolgono i record in un unico oggetto, come il {"Records": [...]} di CloudTrail. ducklocal schema riconosce questa forma e il suo suggerimento fornisce l’SQL che legge i record come righe.

Cartelle e pattern · Verificare i log di CloudTrail in locale

  • Array JSON, oggetti singoli e JSON Lines
  • File compressi letti direttamente
  • Cartelle e pattern glob
  • Join con dati CSV, Parquet ed Excel
  • Risultati esportati in CSV o Parquet

Un visualizzatore NDJSON nel Finder

Su Mac, seleziona un file .jsonl o .ndjson e premi la barra spaziatrice. L’anteprima di Visualizzazione rapida di DuckLocal mostra le colonne e le prime 50 righe come tabella, invece di un muro di testo. L’anteprima non scrive mai, non legge mai l’intero file e non scarica nulla.

Anteprime di Visualizzazione rapida

JSON dalla riga di comando

La stessa lettura funziona senza interfaccia. ducklocal schema mostra le colonne di un file JSON, comprese quelle annidate, e --stats le analizza. ducklocal query esegue un’istruzione e stampa JSON tipizzato, così un agente IA può interrogare i log senza indovinare i nomi dei campi.

Leggi la guida della CLI · SQL per agenti IA

Terminal
$ ducklocal schema events.jsonl
$ ducklocal query --sql \
  "SELECT json_extract_string(event,
            '$.payload.items[0].sku') AS sku,
          count(*) AS n
   FROM read_ndjson_objects('events.jsonl')
   GROUP BY 1 ORDER BY n DESC"

Domande su JSON e SQL

Quali formati JSON apre DuckLocal?
Documenti JSON (.json), JSON delimitato per righe (.ndjson, .jsonl) e le loro versioni compresse come logs.json.gz. Ogni file diventa una vista con il suo nome.
Come vengono gestiti gli oggetti annidati?
DuckDB deduce gli oggetti annidati come colonne STRUCT e gli array come colonne LIST. Raggiungili con la notazione a punto, espandi le liste con unnest oppure usa json_extract_string con un percorso per dati irregolari.
E se i record sono avvolti in un array, come nei log di CloudTrail?
ducklocal schema si accorge che il file è un oggetto che avvolge una lista di record, e il suo suggerimento fornisce l’SQL che legge i record come righe. L’esempio CloudTrail nella documentazione mostra tutti i passaggi.
Esiste un visualizzatore NDJSON per Mac?
Sì. Con DuckLocal installato, seleziona un file .jsonl o .ndjson nel Finder e premi la barra spaziatrice: Visualizzazione rapida mostra le colonne e le prime 50 righe senza aprire l’app.
DuckLocal carica i miei file JSON da qualche parte?
No. I file vengono letti sul posto da DuckDB, dentro l’app. Nulla viene copiato su un server, e non ci sono account né telemetria.

Esegui SQL sul tuo JSON

Scarica DuckLocal, trascina un file JSON o una cartella di log e fai la tua prima domanda.