JSON ファイルを SQL でクエリ

JSON、NDJSON、圧縮されたログファイルを DuckLocal にドロップすると、テーブルになります。ネストしたオブジェクトは列になり、絞り込み、展開、CSV や Parquet との結合ができます。jq のパイプラインを書く必要も、スクリプトを保守する必要もありません。

macOS、Windows、Linux 向けの無料オープンソース。ファイルはその場で読み込まれ、アップロードされることはありません。

JSON ファイルから結果まで

ファイルは元の場所のまま。DuckDB がクエリのたびにその場で読み込みます。

  1. ファイルをドロップ

    events.ndjson は events というビューに、logs.json.gz は logs になります。ファイルが配列か、単一のオブジェクトか、1 行 1 オブジェクトかは DuckDB が判断します。

  2. 構造を確認

    スキーマサイドバーには、ネストしたオブジェクトが STRUCT 列、配列が LIST 列として、フィールドとともに表示されます。概要タブでは結果の各列を分析できます。

  3. テーブルのようにクエリ

    ドット記法でネストしたフィールドを絞り込み、unnest で配列を展開し、開いているほかのファイルと結果を結合できます。

定型コードなしでネストしたフィールドを

明細の配列を持つ注文は、注文ごとに 1 行、items リスト付きになります。unnest でそのリストを明細ごとの行に変えれば、各明細のフィールドはドット 1 つで取り出せます。

レコードごとに形が違うデータには、json_extract_string(col, '$.a.b[0].c') がパスをたどってテキストを返します。値があってもなくても大丈夫です。

JSONL とネストした JSON · DuckDB の JSON リファレンス

-- 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;

ログ、エクスポート、API ダンプ

フォルダーや logs/2026-*/*.json.gz のようなパターンを指定すると、一致するものがすべてデータとして開きます。圧縮ファイルの展開は不要です。

CloudTrail の {"Records": [...]} のように、レコードを 1 つのオブジェクトで包むツールもあります。ducklocal schema はその形を見つけ、ヒントでレコードを行として読む SQL を示します。

フォルダーとパターン · CloudTrail ログをローカルで監査

  • JSON 配列、単一オブジェクト、JSON Lines
  • 圧縮ファイルをそのまま読み込み
  • フォルダーと glob パターン
  • CSV、Parquet、Excel のデータと結合
  • 結果を CSV や Parquet に書き出し

Finder の NDJSON ビューア

Mac で .jsonl や .ndjson ファイルを選んでスペースキーを押すと、DuckLocal の Quick Look プレビューが列と最初の 50 行を、文字の壁ではなく表で表示します。プレビューは書き込まず、ファイル全体を読まず、何もダウンロードしません。

Quick Look プレビュー

コマンドラインで JSON を扱う

同じ読み込みが画面なしでも使えます。ducklocal schema はネストしたものを含む JSON ファイルの列を表示し、--stats がそれを分析します。ducklocal query は 1 つの文を実行して型付きの JSON を出力するので、AI エージェントはフィールド名を推測せずにログをクエリできます。

CLI ガイドを読む · AI エージェントのための SQL

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"

JSON と SQL についての質問

DuckLocal はどの JSON 形式を開けますか?
JSON ドキュメント(.json)、改行区切りの JSON(.ndjson、.jsonl)、そして logs.json.gz のようなそれらの圧縮版です。各ファイルはファイル名のビューになります。
ネストしたオブジェクトはどう扱われますか?
DuckDB はネストしたオブジェクトを STRUCT 列、配列を LIST 列として推定します。ドット記法でアクセスし、unnest でリストを展開し、形が不規則なデータにはパスを指定した json_extract_string を使います。
CloudTrail ログのようにレコードが配列で包まれている場合は?
ducklocal schema は、ファイルがレコードのリストを包む 1 つのオブジェクトであることに気づき、ヒントでレコードを行として読む SQL を示します。ドキュメントの CloudTrail の例で手順を確認できます。
Mac 用の NDJSON ビューアはありますか?
あります。DuckLocal をインストールしたら、Finder で .jsonl か .ndjson ファイルを選んでスペースキーを押してください。アプリを開かなくても、Quick Look が列と最初の 50 行を表示します。
DuckLocal は JSON ファイルをアップロードしますか?
いいえ。ファイルはアプリ内の DuckDB がその場で読み込みます。サーバーへコピーされることはなく、アカウントもテレメトリーもありません。

自分の JSON に SQL を実行しよう

DuckLocal をダウンロードして、JSON ファイルやログのフォルダーをドロップし、最初の質問を投げかけましょう。