DuckDBでParquetをPythonから分析する方法|読み込み・集計・書き出し

DuckDBとParquetでPythonデータを高速集計する入門 便利ツール

CSVを毎回読み込んで集計するPythonスクリプトが遅い。かといって、分析のためだけにデータベースサーバーを立てるのは重い。そんなときに候補になるのがDuckDBとParquetです。DuckDBはローカルのプロセス内でSQLを実行でき、Parquetをファイルのまま問い合わせられます。この記事では、数行のサンプルデータを作るところから、Parquetへの書き出し、複数ファイルの集計、読み取り量を減らす考え方までを一つの作業として追います。

ここでの目的は「DuckDBなら常に速い」という宣伝ではありません。ファイル数、列数、絞り込み条件、ストレージ、データの並び方によって結果は変わります。まず正しく動く最小構成を作り、実データで処理時間とメモリを比較できるようになることを目標にします。既にPolars LazyFrameを使っている人には、同じファイルをSQL中心に扱う別の選択肢として読むと役立ちます。

要点:Parquetは列単位で読み取れる形式で、DuckDBはread_parquet()から直接SQLを実行できます。必要な列と行を絞る書き方を先に考え、データを丸ごとPythonのリストやPandasへ戻すのは最後にしましょう。

DuckDBとParquetの処理経路

スポンサーリンク

DuckDBとParquetを組み合わせる理由

CSVは人が見やすく、ソフトウェア間の受け渡しにも便利です。一方で、ある月の売上と店舗だけが欲しいときでも、テキストを解釈して型を決める工程が発生します。日付や小数の形式が混ざると、読み込み時の確認も必要です。Parquetは列指向のバイナリ形式です。各列の型や統計情報を保持でき、必要な列だけを読む処理と相性が良くなります。

DuckDBはそのParquetを、まず自分のテーブルへ全件インポートすることなく直接問い合わせられます。公式ドキュメントにはSELECT ... FROM read_parquet('file.parquet')や、複数ファイルのglob、COPY ... TO ... (FORMAT parquet)が示されています。ファイルが分析の成果物であり、別のサービスへ読み込ませる前に手元で集計・検査したい場合に分かりやすい構成です。

ただし、Parquetそのものが万能な保存先ではありません。頻繁に一行ずつ更新する業務データ、複数人が同時にトランザクションを書き込む用途、厳密なアクセス制御をDB側で担いたい用途では、別のデータベースやレイクハウス設計を検討してください。DuckDBを使う理由は「SQLでローカル分析したい」「Parquetをそのまま扱いたい」という作業の形にあります。

この記事で作るもの

例として、注文ID・注文日・店舗・金額を持つ小さなordersテーブルを作り、Parquetへ書き出します。その後、PythonからDuckDBの接続を作って再び読み込み、店舗別の合計を求めます。実務ではCSVや既存Parquetを入力に置き換えるだけです。記事中のパスは自分の作業ディレクトリを基準にした相対パスです。COPYは既存ファイルへ書き込み得るため、既に同名のファイルがある場所で不用意に実行しないでください。

スポンサーリンク

まずはPythonで最小例を動かす

最初にPythonの仮想環境を用意し、DuckDBのPythonパッケージを導入します。既存プロジェクトなら、そのプロジェクトが採用している依存管理ツールに合わせてください。サンプルは外部のAPIやクラウドサービスへ接続しません。ファイルを書き出す前に作業フォルダを決め、既存データと混ぜないのが安全です。

python -m venv .venv
source .venv/bin/activate
python -m pip install duckdb

次のコードは一時的なフォルダにParquetを作り、同じプロセス内で再読込します。tempfile.TemporaryDirectory()を使うので、サンプル実行を終えれば生成ファイルは消えます。実務でファイルを残す場合は、明示的に決めたディレクトリへ置き換えてください。入力値はサンプル内の固定値で、SQLへ外部文字列を連結していません。

from pathlib import Path
from tempfile import TemporaryDirectory

import duckdb

with TemporaryDirectory() as directory:
    output = Path(directory) / "orders.parquet"
    connection = duckdb.connect()
    connection.execute("""
        CREATE TABLE orders AS
        SELECT * FROM (VALUES
            (1, DATE '2026-09-01', '東京', 1200),
            (2, DATE '2026-09-02', '大阪', 1800),
            (3, DATE '2026-09-03', '東京', 900)
        ) AS sample(order_id, order_date, shop, amount)
    """)
    connection.table("orders").to_parquet(str(output))
    rows = connection.execute(
        """
        SELECT shop, SUM(amount) AS total_amount
        FROM read_parquet(?)
        GROUP BY shop
        ORDER BY shop
        """,
        [str(output)],
    ).fetchall()
    print(rows)
    connection.close()

このコードはDuckDBのPython Relational APIにあるto_parquet()で書き出し、read_parquet()で再読込しています。読み取りパスはパラメータで渡し、ユーザー入力をSQL文字列へ直接連結しません。Python環境で実際に使うDuckDBのバージョンを確認してください。後述のSQL例では、読みやすさのためにファイル名をリテラルで記します。

結果は店舗ごとの合計になります。東京は2件で2,100、大阪は1件で1,800です。初めに小さな入力で期待値を手計算し、コードの集計結果と照合するのが大切です。大きなファイルへ進む前に、金額の欠損値、返品、通貨違いなど、自分のデータに必要な定義も決めましょう。

read_parquet()とテーブルへの取り込みは別

read_parquet()はParquetファイルを読み取るテーブル関数です。クエリのFROMで使えば、DuckDBの永続テーブルを作らずに内容を参照できます。一方、CREATE TABLE orders AS SELECT ... FROM read_parquet(...)はDuckDB側へコピーを作ります。後者は繰り返しアクセスや更新のために意図して行う操作で、元ファイルと自動同期するわけではありません。

ファイルの内容が更新されたときに、いつのデータを見ているのか混乱しないようにしてください。ビューを作る方法もありますが、ビューは参照先のファイルが移動したり削除されたりすると読めなくなります。再現性が重要なら、入力ファイル名、生成日時、件数、スキーマを処理ログに残す方が確実です。

複数のParquetファイルを一度に読む

日ごとや月ごとにファイルが分かれているときは、globまたはパスのリストを渡せます。公式ドキュメントはread_parquet('orders/*.parquet')と、複数の具体的なファイルを渡す形の両方を示しています。globは便利ですが、思っていたより広い範囲を拾うことがあります。最初の検査ではfilename列も見て、実際にどのファイルが対象になったか確認しましょう。

SELECT filename, COUNT(*) AS rows_in_file
FROM read_parquet('orders/*.parquet')
GROUP BY filename
ORDER BY filename;

新しいDuckDBではParquetのfilenameが仮想列として使えます。古い環境の挙動を前提にしないため、導入しているバージョンを確認してください。データセットを別の人へ渡すときは、globの文字列だけでなく、対象ディレクトリの構成と除外すべき一時ファイルも共有しておくと再現しやすくなります。

ファイルごとに列の順序や列名が違う場合、単純にまとめて読むと失敗したり、意図しない型の統一が起きたりします。DuckDBにはunion_by_nameという選択肢がありますが、それはスキーマ差異を解決したことと同義ではありません。欠けた列が何になるか、同名列の型が揃うか、古いデータをどう扱うかを確認してください。データを静かに「読めた」状態にすることより、期待した意味で集計できたかが重要です。

Hive形式のフォルダ分割

件数が増えたデータでは、year=2026/month=09/part-001.parquetのように、列名と値をフォルダ名へ含める構成があります。DuckDBの公式資料ではHive partitioningとして説明されています。hive_partitioning = trueを付けて読むと、yearやmonthを列として扱えます。年と月を絞るクエリでは、対象外フォルダのファイルを読まない最適化につながる場合があります。

SELECT shop, SUM(amount) AS total_amount
FROM read_parquet('orders/*/*/*.parquet', hive_partitioning = true)
WHERE year = 2026 AND month = 9
GROUP BY shop;

日付フォルダを細かく切れば必ず速くなるわけではありません。数千個の小さなファイルを作ると、一覧取得やファイルを開くコストが増えることもあります。まずは検索に本当に使うキーを選び、実データでファイル数、サイズ、集計時間を測ります。月単位が合うか日単位が合うかは、データ量とアクセスの傾向によって変わります。

Parquetの分割と絞り込み

なぜ必要な列だけにするのか

Parquetは列指向です。SELECT *を使うと、表示に不要な列まで結果へ含めます。一方、店舗名と金額だけが必要な集計なら、その2列に絞るクエリを書けます。DuckDBの公式資料は、Parquetスキャンに対するprojection pushdownとfilter pushdownを説明しています。前者は必要な列だけを読み、後者は条件を読み取り側へ押し込む最適化です。

SELECT shop, SUM(amount) AS total_amount
FROM read_parquet('orders/*.parquet')
WHERE order_date >= DATE '2026-09-01'
GROUP BY shop;

ただし、WHEREを書けば必ず該当行だけを一件ずつピンポイントに読み込めるという意味ではありません。Parquetのrow groupや統計情報、ファイル内のデータの並び方に依存します。たとえば日付が無秩序に混ざっているファイルでは、条件に関係するrow groupが多数残る可能性があります。「理論上はpushdownできる」と「このファイルで十分に速くなる」を分けて考えます。

最初はSELECT *で内容を確かめ、安定したら列を列挙する、という進め方で構いません。分析結果を本番のレポートへ使う段階では、列の追加や順序変更に影響されないよう、必要な列と出力名を明記します。SELECT *を長く残すと、入力スキーマの変更が結果の構造を変えても気付きにくくなります。

Pythonに戻すタイミングを決める

PythonからDuckDBを使うと、SQL結果をfetchall()やDataFrameとして受け取れます。しかし大きな元データを全件Pythonへ戻すと、Parquetを直接SQLで集計する利点を失います。まずWHERE、GROUP BY、LIMITで必要な結果を小さくし、最後にPythonへ渡しましょう。グラフを描く場合も、何百万行ものイベントを描画ライブラリへ渡すより、日別・店舗別の集計結果を渡す方が読みやすい図になります。

前述の小さな例ではfetchall()で十分です。実際のデータが大きい場合は、結果の行数、列数、メモリを見積もります。集計後も大量の行が残るなら、結果を再びParquetへ書き出す、ページ単位で読む、分析粒度を見直すなどの選択肢があります。どれを選ぶかは、後続処理が本当に必要とする情報で決めます。

Polars LazyFrameとの使い分けも同じ観点で考えられます。Pythonの式で変換を組み立てたいならPolars、既存のSQL資産や集計クエリを中心に使いたいならDuckDBが分かりやすいことがあります。速さはデータとクエリごとに計測するのが妥当です。既に動いている処理を、名前だけで置き換える必要はありません。

ファイルへの書き出しと共有

集計結果を保存したいとき、DuckDBのCOPYでParquetへ書き出せます。公式資料にはCOPY (SELECT ...) TO 'result.parquet' (FORMAT parquet)が掲載されています。レポート用なら、出力のスキーマと期間を先に固定すると、毎回同じ意味の成果物になります。

COPY (
    SELECT shop, SUM(amount) AS total_amount
    FROM read_parquet('orders/*.parquet')
    GROUP BY shop
) TO 'result.parquet' (FORMAT parquet);

上書きや途中失敗に備え、実務では一時ファイルに書いて検証した後、正式な名前へ切り替える運用が有効です。件数が期待値と一致するか、金額が欠損していないか、集計対象の日付範囲が合うかを確認してから配布します。Parquetは人がテキストエディタで直接読む形式ではないので、受け渡し先に列の意味や単位を書いた小さな説明も添えると誤用を防げます。

圧縮方式やrow group sizeも指定できますが、最初から細かく調整する必要はありません。ファイルサイズと読み込み時間の両方を測った後に選びます。圧縮率だけを最適化しても、読み取り側のCPU負荷やファイル数が増えて全体が遅くなる場合があります。まずは標準設定と、現実のワークロードを基準にした比較です。

エラーが出たときの確認順

「ファイルが見つからない」場合は、Pythonの現在の作業ディレクトリとSQLに渡したパスを確認します。ノートブック、IDE、定期実行で作業ディレクトリが異なることは珍しくありません。絶対パスを一時的にログへ出して確認しても、個人情報を含むディレクトリ名を公開ログへ流さないよう注意してください。

「型が違う」場合は、まず対象ファイルのスキーマを調べます。DESCRIBE SELECT * FROM read_parquet('file.parquet')は公式ドキュメントにも示された確認方法です。複数ファイルで問題が起きるなら、一つずつ読めるかを確認し、型や列名の差を調べます。数値に見える文字列を黙って変換する前に、変換できなかった値がどう扱われるかを決めてください。

「思ったより遅い」場合は、データが実際にどれだけ広がっているかを調べます。globが余分なファイルを含んでいないか、SELECT *で大きな列を読んでいないか、日付条件がフォルダやrow groupを絞れているかを見ます。公式のParquet TipsとPerformance Guideにはファイルサイズやrow groupの考え方がありますが、推奨値を丸写しにせず、自分の規模で測定してください。

結果が合わないときは、速度調整より先に定義を確認します。返品を負の金額として含むか、タイムゾーンをどう切るか、重複した注文IDをどう数えるかで、同じSQLでも値が変わります。サンプルの3件のように手計算できる検査データを用意し、その期待値をテストに残します。

実運用前のチェックリスト

  • □ 対象ファイルの範囲と作業ディレクトリを確認した
  • □ filenameでglobが拾ったファイルを確認した
  • □ 必要な列と期間をSQLで明示した
  • □ Parquetの列名・型・欠損の扱いを確認した
  • □ 集計の期待値を小さな検査データで確かめた
  • □ 大量行をPythonへ戻す前に結果サイズを見積もった
  • □ 書き出し先に既存ファイルがないか確認した
  • □ 処理時間とメモリを実データで測った

まとめ

DuckDBとParquetは、ローカルでSQLを使ってファイルを分析するための組み合わせです。read_parquet()で直接読み、必要な列と行だけを選び、集計した結果をPythonへ渡すところから始めてください。複数ファイルやHive形式のフォルダに進むときは、対象範囲とスキーマを先に確認します。速度向上は仕組みから期待できますが、実際の効果はファイル構成とクエリによって変わるため、測って判断しましょう。

関連記事

公式資料

コメント

タイトルとURLをコピーしました