Skip to main content
このガイドでは、chDB の Python 版を使い始める方法を説明します。 まず S3 上の JSON ファイルをクエリし、続いてその JSON ファイルを基に chDB でテーブルを作成して、データに対していくつかのクエリを実行します。 また、Apache Arrow や Panda を含むさまざまなフォーマットでクエリ結果を返す方法を確認し、最後に Pandas DataFrames をクエリする方法を学びます。

セットアップ

まずは仮想環境を作成します:
それでは、chDB をインストールします。 バージョンが 2.0.3 以降であることを確認してください。
それでは、ipython をインストールしましょう。
このガイドの以降のコマンドは ipython で実行します。次のコマンドで起動できます。
このガイドでは Pandas と Apache Arrow も使用するので、これらのライブラリもインストールしましょう。

S3 内の JSON ファイルをクエリする

それでは、S3 バケットに保存されている JSON ファイルをどのようにクエリするか見ていきましょう。 YouTube の低評価データセット には、2021 年までの YouTube 動画に対する低評価が 40 億行以上含まれています。 このデータセット内の JSON ファイルの 1 つを使って作業を進めます。 chdb をインポートします:
次のクエリを実行すると、JSONファイルの1つの構造を確認できます。
そのファイル内の行数を数えることもできます。
このファイルには、30万件を少し超えるレコードが含まれています。 chdb はまだクエリパラメータの受け渡しに対応していませんが、パスを取り出して f-string 経由で渡すことができます。
これはプログラム内で定義した変数に対して行う分には問題ありませんが、ユーザー入力に対しては行わないでください。そうしないと、クエリが SQL インジェクションの脆弱性を持つことになります。

出力フォーマットの設定

デフォルトの出力フォーマットは CSV ですが、output_format パラメータで変更できます。 chDB は ClickHouse のデータフォーマットに加えて、独自のフォーマット にも対応しており、その中には Pandas DataFrame を返す DataFrame も含まれます。
あるいは、Apache Arrowテーブルを取得するには、次のとおりです:

JSON ファイルからテーブルを作成する

次に、chDBでテーブルを作成する方法を見ていきましょう。 これには別のAPIを使用する必要があるため、まずそれをインポートします。
次に、セッションを初期化します。 セッションをディスクに永続化する場合は、ディレクトリ名を指定する必要があります。 空欄のままにすると、データベースはインメモリとなり、Python プロセスを終了するとすぐに失われます。
次に、データベースを作成します。
これで、CREATE...EMPTY AS を使って、JSON ファイルのスキーマに基づく dislikes テーブルを作成できます。 すべてのカラム型が Nullable にならないように、schema_inference_make_columns_nullable 設定を使用します。
次に、DESCRIBE 句を使用してスキーマを確認できます:
次に、そのテーブルにデータを挿入しましょう:
これら2つの手順は、CREATE...AS を使えば一度に実行することもできます。 では、その方法で別のテーブルを作成してみましょう。

テーブルにクエリを実行する

最後に、テーブルにクエリを実行してみましょう。
では次に、高評価と低評価の比率を計算するために、DataFrame にカラムを 1 つ追加するとしましょう。 次のようなコードを書けます。

Pandas DataFrame へのクエリ

次に、chDB からその DataFrame に対してクエリを実行できます。
Pandas DataFrames に対するクエリについて詳しくは、Pandas DataFrames をクエリする開発者ガイドも参照してください。

次のステップ

このガイドで、chDB の概要をつかんでいただけたなら幸いです。 使い方をさらに詳しく知りたい場合は、以下の開発者向けガイドを参照してください。
最終更新日 2026年7月23日