Consultar archivos JSON con SQL

Suelta un archivo JSON, NDJSON o un registro comprimido en DuckLocal y se convierte en una tabla. Los objetos anidados pasan a ser columnas que puedes filtrar, desplegar y unir con CSV y Parquet. Sin canalizaciones de jq que escribir ni scripts que mantener.

Gratis y de código abierto para macOS, Windows y Linux. Los archivos se leen en su sitio y nunca se suben.

Del archivo JSON al resultado

El archivo se queda donde está. DuckDB lo lee en su sitio cada vez que consultas.

  1. Suelta el archivo

    events.ndjson se convierte en una vista llamada events, y logs.json.gz en una llamada logs. DuckDB detecta si el archivo es un array, un único objeto o un objeto por línea.

  2. Mira la estructura

    La barra lateral del esquema muestra los objetos anidados como columnas STRUCT y los arrays como columnas LIST, con sus campos. La pestaña Resumen perfila cada columna de un resultado.

  3. Consúltalo como una tabla

    Filtra por un campo anidado con notación de punto, despliega arrays con unnest y une el resultado con cualquier otro archivo que tengas abierto.

Campos anidados sin código repetitivo

Un pedido con un array de líneas se convierte en una fila por pedido con una lista items. unnest transforma esa lista en una fila por artículo, y los campos de cada artículo están a un punto de distancia.

Para datos cuya forma cambia de un registro a otro, json_extract_string(col, '$.a.b[0].c') recorre una ruta y devuelve texto, haya o no algo ahí.

JSONL y JSON anidado · La referencia JSON de 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;

Registros, exportaciones y volcados de API

Indica a DuckLocal una carpeta o un patrón como logs/2026-*/*.json.gz y cada coincidencia se abre como datos. Los archivos comprimidos no necesitan descomprimirse.

Algunas herramientas envuelven sus registros en un único objeto, como el {"Records": [...]} de CloudTrail. ducklocal schema detecta esa forma y su pista da el SQL que lee los registros como filas.

Carpetas y patrones · Auditar registros de CloudTrail en local

  • Arrays JSON, objetos únicos y JSON Lines
  • Archivos comprimidos leídos directamente
  • Carpetas y patrones glob
  • Uniones con datos CSV, Parquet y Excel
  • Resultados exportados a CSV o Parquet

Un visor de NDJSON en el Finder

En un Mac, selecciona un archivo .jsonl o .ndjson y pulsa la barra espaciadora. La vista previa de Vista rápida de DuckLocal muestra sus columnas y sus primeras 50 filas como una tabla en lugar de un muro de texto. La vista previa nunca escribe, nunca lee el archivo completo y no descarga nada.

Vistas previas con Vista rápida

JSON desde la línea de comandos

La misma lectura funciona sin interfaz. ducklocal schema muestra las columnas de un archivo JSON, incluidas las anidadas, y --stats las perfila. ducklocal query ejecuta una instrucción e imprime JSON con tipos, así que un agente de IA puede consultar registros sin adivinar nombres de campo.

Leer la guía de la CLI · SQL para agentes de 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"

Preguntas sobre JSON y SQL

¿Qué formatos JSON abre DuckLocal?
Documentos JSON (.json), JSON delimitado por líneas (.ndjson, .jsonl) y sus versiones comprimidas, como logs.json.gz. Cada archivo se convierte en una vista con su nombre.
¿Cómo se tratan los objetos anidados?
DuckDB deduce los objetos anidados como columnas STRUCT y los arrays como columnas LIST. Accede a ellos con notación de punto, despliega listas con unnest o usa json_extract_string con una ruta para datos irregulares.
¿Y si los registros vienen envueltos en un array, como en los registros de CloudTrail?
ducklocal schema se da cuenta de que el archivo es un objeto que envuelve una lista de registros, y su pista da el SQL que lee los registros como filas. El ejemplo de CloudTrail de la documentación lo recorre paso a paso.
¿Hay un visor de NDJSON para Mac?
Sí. Con DuckLocal instalado, selecciona un archivo .jsonl o .ndjson en el Finder y pulsa la barra espaciadora: Vista rápida muestra sus columnas y sus primeras 50 filas sin abrir la aplicación.
¿DuckLocal sube mis archivos JSON?
No. DuckDB, dentro de la aplicación, lee los archivos en su sitio. Nada se copia a un servidor, y no hay cuenta ni telemetría.

Ejecuta SQL sobre tu propio JSON

Descarga DuckLocal, suelta un archivo JSON o una carpeta de registros y haz tu primera pregunta.