clickhouse-local データベースの使用

clickhouse-local は、ClickHouse の組み込み版を搭載した CLI ツールです。 ClickHouse サーバーをインストールせずに、その機能を利用できます。 このガイドでは、chDB から clickhouse-local データベースを使用する方法を説明します。

セットアップ

まず仮想環境を作成します。

python -m venv .venv
source .venv/bin/activate

次に chDB をインストールします。 chDB のバージョンが 2.0.2 以上であることを確認してください。

pip install "chdb>=2.0.2"

それでは、ここで IPython をインストールします：

pip install ipython

このガイドでは、以降のコマンドを ipython を使って実行します。次のコマンドを実行して ipython を起動してください。

ipython

clickhouse-local のインストール

clickhouse-local のダウンロードとインストールは、ClickHouse のダウンロードとインストール と同じです。 次のコマンドを実行してください。

curl https://clickhouse.com/ | sh

データをディレクトリに永続化するように clickhouse-local を起動するには、--path オプションを指定する必要があります：

./clickhouse -m --path demo.chdb

clickhouse-local へのデータ取り込み

デフォルトのデータベースはメモリ上にのみデータを保存するため、取り込んだデータをディスクに永続的に保存できるよう、名前付きデータベースを作成する必要があります。

CREATE DATABASE foo;

テーブルを作成し、いくつかのランダムな数値を挿入してみましょう。

CREATE TABLE foo.randomNumbers
ORDER BY number AS
SELECT rand() AS number
FROM numbers(10_000_000);

どのようなデータがあるか確認するためのクエリを書きましょう：

SELECT quantilesExact(0, 0.5, 0.75, 0.99)(number) AS quants
FROM foo.randomNumbers

┌─quants────────────────────────────────┐
│ [69,2147776478,3221525118,4252096960] │
└───────────────────────────────────────┘

それが終わったら、必ず CLI で exit; を実行して終了してください。このディレクトリにロックを取得できるプロセスは 1 つだけです。 そうしないと、chDB からデータベースに接続しようとしたときに、次のエラーが発生します。

ChdbError: Code: 76. DB::Exception: ファイル demo.chdb/status をロックできません。同じディレクトリ内で別のサーバーインスタンスが既に実行中です。(CANNOT_OPEN_FILE)

clickhouse-local データベースへの接続

ipython シェルに戻り、chDB の session モジュールをインポートします。

from chdb import session as chs

demo..chdb を参照するセッションを初期化します:

sess = chs.Session("demo.chdb")

次に、同じクエリを実行して数値の分位数を取得できます：

sess.query("""
SELECT quantilesExact(0, 0.5, 0.75, 0.99)(number) AS quants
FROM foo.randomNumbers
""", "Vertical")

行 1:
──────
quants: [0,9976599,2147776478,4209286886]

また、chDB からこのデータベースにデータを挿入することもできます。

sess.query("""
INSERT INTO foo.randomNumbers
SELECT rand() AS number FROM numbers(10_000_000)
""")

Row 1:
──────
quants: [0,9976599,2147776478,4209286886]

その後、chDB または clickhouse-local から quantiles 関数のクエリを再実行できます。