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.

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 · A referência de JSON do 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;

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 · Audite logs do CloudTrail localmente

  • 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

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 · 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"

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.

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.