---
title: "Consulte arquivos JSON e NDJSON com SQL | DuckLocal"
description: "Execute SQL do DuckDB em arquivos JSON, NDJSON e JSON Lines, compactados ou não. Objetos aninhados viram colunas que você pode filtrar, expandir e juntar com CSV e Parquet, no seu próprio computador."
image: https://ducklocal.app/og-image.jpg?v=2
language: pt
---

# Consulte arquivos JSON com SQL

Solte um arquivo JSON, NDJSON ou um log compactado no DuckLocal e ele vira uma tabela. Objetos aninhados viram colunas que você pode filtrar, expandir e juntar com CSV e Parquet. Sem pipeline de `jq` para escrever e sem script para manter.

Gratuito e de código aberto para macOS, Windows e Linux. Os arquivos são lidos no lugar e nunca enviados.

- .json .ndjson .jsonl
- Também .json.gz compactado
- Campos aninhados como colunas
- Visualização Rápida para JSON Lines

## Do arquivo JSON ao resultado

O arquivo fica onde está. O DuckDB o lê no lugar a cada consulta.

1. **Solte o arquivo.** `events.ndjson` vira uma view chamada `events`, e `logs.json.gz` uma chamada `logs`. O DuckDB descobre se o arquivo é um array, um único objeto ou um objeto por linha.
2. **Veja a estrutura.** A barra lateral do esquema mostra objetos aninhados como colunas `STRUCT` e arrays como colunas `LIST`, com seus campos. A aba Visão geral analisa cada coluna de um resultado.
3. **Consulte como uma tabela.** Filtre por um campo aninhado com notação de ponto, expanda arrays com `unnest` e junte o resultado com qualquer outro arquivo aberto.

## Campos aninhados sem código repetitivo

Um pedido com um array de itens vira uma linha por pedido com uma lista `items`. `unnest` transforma essa lista em uma linha por item, e os campos de cada item ficam a um ponto de distância.

Para dados cujo formato muda de registro para registro, `json_extract_string(col, '$.a.b[0].c')` percorre um caminho e devolve texto, exista ou não algo ali.

[JSONL e JSON aninhado](https://ducklocal.app/docs/pt/cli#jsonl-and-nested-json) · [A referência de JSON do 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;
```

## Logs, exportações e dumps de API

Aponte o DuckLocal para uma pasta ou um padrão como `logs/2026-*/*.json.gz` e cada correspondência abre como dados. Arquivos compactados não precisam ser descompactados.

Algumas ferramentas embrulham os registros em um único objeto, como o `{"Records": [...]}` do CloudTrail. `ducklocal schema` percebe esse formato e a dica dele traz o SQL que lê os registros como linhas.

[Pastas e padrões](https://ducklocal.app/docs/pt/data-sources#folders-and-patterns) · [Audite logs do CloudTrail localmente](https://ducklocal.app/docs/pt/example-cloudtrail)

- Arrays JSON, objetos únicos e JSON Lines
- Arquivos compactados lidos diretamente
- Pastas e padrões glob
- Junções com dados CSV, Parquet e Excel
- Resultados exportados para CSV ou Parquet

## Um visualizador de NDJSON no Finder

No Mac, selecione um arquivo `.jsonl` ou `.ndjson` e pressione a barra de espaço. A pré-visualização da Visualização Rápida do DuckLocal mostra as colunas e as primeiras 50 linhas como uma tabela, em vez de um paredão de texto. A pré-visualização nunca grava, nunca lê o arquivo inteiro e não baixa nada.

[Pré-visualizações da Visualização Rápida](https://ducklocal.app/docs/pt/data-sources#quick-look)

> **Quer guardar como Parquet?** Exporte qualquer resultado de consulta para Parquet: arquivos menores, colunas tipadas e leitura muito mais rápida da próxima vez. [Veja o visualizador de Parquet →](https://ducklocal.app/pt/use-cases/parquet-viewer/)

## JSON na linha de comando

A mesma leitura funciona sem interface. `ducklocal schema` mostra as colunas de um arquivo JSON, inclusive as aninhadas, e `--stats` as analisa. `ducklocal query` executa uma instrução e imprime JSON tipado, então um agente de IA pode consultar logs sem adivinhar nomes de campos.

[Leia o guia da CLI](https://ducklocal.app/docs/pt/cli) · [SQL para agentes de IA](https://ducklocal.app/pt/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"
```

## Perguntas sobre JSON e SQL

**Quais formatos JSON o DuckLocal abre?** Documentos JSON (`.json`), JSON delimitado por linha (`.ndjson`, `.jsonl`) e versões compactadas deles, como `logs.json.gz`. Cada arquivo vira uma view com o nome dele.

**Como objetos aninhados são tratados?** O DuckDB deduz objetos aninhados como colunas `STRUCT` e arrays como colunas `LIST`. Acesse-os com notação de ponto, expanda listas com `unnest` ou use `json_extract_string` com um caminho para dados irregulares.

**E se os registros vierem embrulhados em um array, como nos logs do CloudTrail?** `ducklocal schema` percebe que o arquivo é um objeto que envolve uma lista de registros, e a dica dele traz o SQL que lê os registros como linhas. O exemplo do CloudTrail na documentação mostra o passo a passo.

**Existe um visualizador de NDJSON para Mac?** Sim. Com o DuckLocal instalado, selecione um arquivo `.jsonl` ou `.ndjson` no Finder e pressione a barra de espaço: a Visualização Rápida mostra as colunas e as primeiras 50 linhas sem abrir o app.

**O DuckLocal envia meus arquivos JSON para algum lugar?** Não. Os arquivos são lidos no lugar pelo DuckDB dentro do app. Nada é copiado para um servidor, e não há conta nem telemetria.

Relacionados: [Consultar CSV com SQL](https://ducklocal.app/pt/use-cases/query-csv-with-sql/) · [Consultar Excel com SQL](https://ducklocal.app/pt/use-cases/query-excel-with-sql/) · [Visualizador de Parquet](https://ducklocal.app/pt/use-cases/parquet-viewer/) · [Análise de dados locais](https://ducklocal.app/pt/use-cases/local-data-analysis/)

## Execute SQL no seu próprio JSON

Baixe o DuckLocal, solte um arquivo JSON ou uma pasta de logs e faça sua primeira pergunta.

## Links

- [Baixar o DuckLocal](https://github.com/JetSquirrel/DuckLocal/releases/latest)
- [Siga o exemplo do CloudTrail](https://ducklocal.app/docs/pt/example-cloudtrail)
- [Instale e execute uma primeira consulta](https://ducklocal.app/docs/pt/getting-started)

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