chDBを使い始める

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

セットアップ

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

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

それでは、chDB をインストールしましょう。バージョン 2.0.3 以降であることを確認してください。

pip install "chdb>=2.0.2"

それでは、ipython をインストールしましょう。

pip install ipython

このガイドの以降では、コマンドの実行に ipython を使用します。起動するには、次を実行します。

ipython

このガイドでは Pandas と Apache Arrow も使用するので、これらのライブラリもインストールしましょう。

pip install pandas pyarrow

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

それでは、S3 バケットに保存されている JSON ファイルに対してクエリを実行する方法を見ていきましょう。 YouTube dislikes dataset には、2021 年までの YouTube 動画の低評価データが 40 億行以上含まれています。このデータセットに含まれる JSON ファイルの 1 つを使います。 chdb をインポートします:

import chdb

次のクエリを使用すると、JSONファイルの1つの構造を確認できます。

chdb.query(
  """
  DESCRIBE s3(
    's3://clickhouse-public-datasets/youtube/original/files/' ||
    'youtubedislikes_20211127161229_18654868.1637897329_vid.json.zst',
    'JSONLines'
  )
  SETTINGS describe_compact_output=1
  """
)

"id","Nullable(String)"
"fetch_date","Nullable(String)"
"upload_date","Nullable(String)"
"title","Nullable(String)"
"uploader_id","Nullable(String)"
"uploader","Nullable(String)"
"uploader_sub_count","Nullable(Int64)"
"is_age_limit","Nullable(Bool)"
"view_count","Nullable(Int64)"
"like_count","Nullable(Int64)"
"dislike_count","Nullable(Int64)"
"is_crawlable","Nullable(Bool)"
"is_live_content","Nullable(Bool)"
"has_subtitles","Nullable(Bool)"
"is_ads_enabled","Nullable(Bool)"
"is_comments_enabled","Nullable(Bool)"
"description","Nullable(String)"
"rich_metadata","Array(Tuple(
    call Nullable(String),
    content Nullable(String),
    subtitle Nullable(String),
    title Nullable(String),
    url Nullable(String)))"
"super_titles","Array(Tuple(
    text Nullable(String),
    url Nullable(String)))"
"uploader_badges","Nullable(String)"
"video_badges","Nullable(String)"

そのファイル内の行数を数えることもできます。

chdb.query(
  """
  SELECT count()
  FROM s3(
    's3://clickhouse-public-datasets/youtube/original/files/' ||
    'youtubedislikes_20211127161229_18654868.1637897329_vid.json.zst',
    'JSONLines'
  )"""
)

このファイルには30万件を少し超えるレコードが含まれています。 chdb ではまだクエリパラメータの受け渡しがサポートされていませんが、パスを取り出して f-String 経由で渡すことができます。

path = 's3://clickhouse-public-datasets/youtube/original/files/youtubedislikes_20211127161229_18654868.1637897329_vid.json.zst'

chdb.query(
  f"""
  SELECT count()
  FROM s3('{path}','JSONLines')
  """
)

これはプログラム内で定義した変数に対して行うのであれば問題ありませんが、ユーザー入力に対しては行わないでください。そうしないと、クエリがSQLインジェクションの対象になります。

出力フォーマットの設定

デフォルトの出力フォーマットは CSV ですが、output_format パラメーターで変更できます。 chDB は ClickHouse のデータフォーマットに加えて、独自のフォーマットもいくつかサポートしており、その中には Pandas の DataFrame を返す DataFrame も含まれます。

result = chdb.query(
  f"""
  SELECT is_ads_enabled, count()
  FROM s3('{path}','JSONLines')
  GROUP BY ALL
  """,
  output_format="DataFrame"
)

print(type(result))
print(result)

<class 'pandas.core.frame.DataFrame'>
   is_ads_enabled  count()
0           False   301125
1            True    35307

あるいは、Apache Arrowテーブルとして取得する場合:

result = chdb.query(
  f"""
  SELECT is_live_content, count()
  FROM s3('{path}','JSONLines')
  GROUP BY ALL
  """,
  output_format="ArrowTable"
)

print(type(result))
print(result)

<class 'pyarrow.lib.Table'>
pyarrow.Table
is_live_content: bool
count(): uint64 not null
----
is_live_content: [[false,true]]
count(): [[315746,20686]]

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

次に、chDBでテーブルを作成する方法を見ていきましょう。これには別のAPIを使う必要があるため、まずそれをインポートします。

from chdb import session as chs

次に、セッションを初期化します。セッションをディスクに永続化する場合は、ディレクトリ名を指定する必要があります。空のままにすると、データベースはメモリ上にのみ保持され、Python プロセスを終了した時点で失われます。

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

次に、データベースを作成します：

sess.query("CREATE DATABASE IF NOT EXISTS youtube")

これで、CREATE...EMPTY AS を使って、JSONファイルのスキーマに基づく dislikes テーブルを作成できます。すべてのカラムの型が Nullable にならないよう、schema_inference_make_columns_nullable 設定を使用します。

sess.query(f"""
  CREATE TABLE youtube.dislikes
  ORDER BY fetch_date 
  EMPTY AS 
  SELECT * 
  FROM s3('{path}','JSONLines')
  SETTINGS schema_inference_make_columns_nullable=0
  """
)

次に、DESCRIBE 句を使用してスキーマを確認できます：

sess.query(f"""
   DESCRIBE youtube.dislikes
   SETTINGS describe_compact_output=1
   """
)

"id","String"
"fetch_date","String"
"upload_date","String"
"title","String"
"uploader_id","String"
"uploader","String"
"uploader_sub_count","Int64"
"is_age_limit","Bool"
"view_count","Int64"
"like_count","Int64"
"dislike_count","Int64"
"is_crawlable","Bool"
"is_live_content","Bool"
"has_subtitles","Bool"
"is_ads_enabled","Bool"
"is_comments_enabled","Bool"
"description","String"
"rich_metadata","Array(Tuple(
    call String,
    content String,
    subtitle String,
    title String,
    url String))"
"super_titles","Array(Tuple(
    text String,
    url String))"
"uploader_badges","String"
"video_badges","String"

次に、そのテーブルにデータを挿入します。

sess.query(f"""
  INSERT INTO youtube.dislikes
  SELECT * 
  FROM s3('{path}','JSONLines')
  SETTINGS schema_inference_make_columns_nullable=0
  """
)

CREATE...AS 手法を使えば、これら2つの手順をまとめて一度に実行することもできます。その手法を使って、別のテーブルを作成してみましょう。

sess.query(f"""
  CREATE TABLE youtube.dislikes2
  ORDER BY fetch_date 
  AS 
  SELECT * 
  FROM s3('{path}','JSONLines')
  SETTINGS schema_inference_make_columns_nullable=0
  """
)

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

最後に、テーブルにクエリを実行してみましょう。

df = sess.query("""
  SELECT uploader, sum(view_count) AS viewCount, sum(like_count) AS likeCount, sum(dislike_count) AS dislikeCount
  FROM youtube.dislikes
  GROUP BY ALL
  ORDER BY viewCount DESC
  LIMIT 10
  """,
  "DataFrame"
)
df

                             uploader  viewCount  likeCount  dislikeCount
                           Jeremih  139066569     812602         37842
                   TheKillersMusic  109313116     529361         11931
LetsGoMartin- Canciones Infantiles  104747788     236615        141467
                  Xiaoying Cuisine   54458335    1031525         37049
                              Adri   47404537     279033         36583
                Diana and Roma IND   43829341     182334        148740
                    ChuChuTV Tamil   39244854     244614        213772
                          Cheez-It   35342270        108            27
                          Anime Uz   33375618    1270673         60013
                  RC Cars OFF Road   31952962     101503         49489

次に、likes と dislikes の比率を計算するため、DataFrame にカラムを 1 つ追加するとします。その場合、次のようなコードを書けます。

df["likeDislikeRatio"] = df["likeCount"] / df["dislikeCount"]

PandasのDataFrameをクエリする

続いて、chDB からそのDataFrameに対してクエリを実行できます。

chdb.query(
  """
  SELECT uploader, likeDislikeRatio
  FROM Python(df)
  """,
  output_format="DataFrame"
)

                             uploader  likeDislikeRatio
                           Jeremih         21.473548
                   TheKillersMusic         44.368536
LetsGoMartin- Canciones Infantiles          1.672581
                  Xiaoying Cuisine         27.842182
                              Adri          7.627395
                Diana and Roma IND          1.225857
                    ChuChuTV Tamil          1.144275
                          Cheez-It          4.000000
                          Anime Uz         21.173296
                  RC Cars OFF Road          2.051021

Pandas DataFrame へのクエリについて詳しくは、Pandas DataFrame へのクエリに関する開発者ガイドもご覧ください。

次のステップ

このガイドで、chDB の概要を把握できたなら幸いです。使い方についてさらに詳しく知るには、以下の開発者向けガイドを参照してください。

Get started

DataStore

Configuration

Debugging

セットアップ

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

出力フォーマットの設定

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

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

PandasのDataFrameをクエリする

次のステップ

​セットアップ

​S3 内の JSON ファイルにクエリを実行する

​出力フォーマットの設定

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

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

​PandasのDataFrameをクエリする

​次のステップ

セットアップ

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

出力フォーマットの設定

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

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

PandasのDataFrameをクエリする

次のステップ