---
title: "Consultar archivos JSON y NDJSON con SQL | DuckLocal"
description: "Ejecuta SQL de DuckDB sobre archivos JSON, NDJSON y JSON Lines, comprimidos o no. Los objetos anidados se convierten en columnas que puedes filtrar, desplegar y unir con CSV y Parquet, en tu propio ordenador."
image: https://ducklocal.app/og-image.jpg?v=2
language: es
---

# 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.

- .json .ndjson .jsonl
- También .json.gz comprimido
- Campos anidados como columnas
- Vista rápida para JSON Lines

## 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](https://ducklocal.app/docs/es/cli#jsonl-and-nested-json) · [La referencia JSON de DuckDB](https://duckdb.org/docs/stable/data/json/overview)

```sql
-- 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](https://ducklocal.app/docs/es/data-sources#folders-and-patterns) · [Auditar registros de CloudTrail en local](https://ducklocal.app/docs/es/example-cloudtrail)

- 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](https://ducklocal.app/docs/es/data-sources#quick-look)

> **¿Quieres guardarlo como Parquet?** Exporta cualquier resultado de consulta a Parquet: archivos más pequeños, columnas con tipo y mucha más velocidad la próxima vez que lo leas. [Ver el visor de Parquet →](https://ducklocal.app/es/use-cases/parquet-viewer/)

## 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](https://ducklocal.app/docs/es/cli) · [SQL para agentes de IA](https://ducklocal.app/es/use-cases/ai-agent-sql/)

```bash
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.

Relacionado: [Consultar CSV con SQL](https://ducklocal.app/es/use-cases/query-csv-with-sql/) · [Consultar Excel con SQL](https://ducklocal.app/es/use-cases/query-excel-with-sql/) · [Visor de Parquet](https://ducklocal.app/es/use-cases/parquet-viewer/) · [Análisis de datos locales](https://ducklocal.app/es/use-cases/local-data-analysis/)

## Ejecuta SQL sobre tu propio JSON

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

## Enlaces

- [Descargar DuckLocal](https://github.com/JetSquirrel/DuckLocal/releases/latest)
- [Seguir el ejemplo de CloudTrail](https://ducklocal.app/docs/es/example-cloudtrail)
- [Instalar y ejecutar una primera consulta](https://ducklocal.app/docs/es/getting-started)

Source: https://ducklocal.app/es/use-cases/query-json-with-sql/
