Do arquivo JSON ao resultado
O arquivo fica onde está. O DuckDB o lê no lugar a cada consulta.
Solte o arquivo
events.ndjsonvira uma view chamadaevents, elogs.json.gzuma chamadalogs. O DuckDB descobre se o arquivo é um array, um único objeto ou um objeto por linha.Veja a estrutura
A barra lateral do esquema mostra objetos aninhados como colunas
STRUCTe arrays como colunasLIST, com seus campos. A aba Visão geral analisa cada coluna de um resultado.Consulte como uma tabela
Filtre por um campo aninhado com notação de ponto, expanda arrays com
unneste 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.
-- 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.
- 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.
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.
$ 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, comologs.json.gz. Cada arquivo vira uma view com o nome dele. - Como objetos aninhados são tratados?
- O DuckDB deduz objetos aninhados como colunas
STRUCTe arrays como colunasLIST. Acesse-os com notação de ponto, expanda listas comunnestou usejson_extract_stringcom um caminho para dados irregulares. - E se os registros vierem embrulhados em um array, como nos logs do CloudTrail?
ducklocal schemapercebe 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
.jsonlou.ndjsonno 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 · Consultar Excel com SQL · Visualizador de Parquet · Análise de dados locais
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.