thevar1able/ClickHouse

Fork 0

mirror of https://github.com/ClickHouse/ClickHouse.git synced 2024-12-13 09:52:38 +00:00

Miki Matsumoto 1e15312729 add translated Japanese docs

2024-11-18 11:58:58 +09:00

11 KiB

Raw Blame History

title

sidebar_label

slug

description

keywords

chDBの使い始め

使い始め

/ja/chdb/getting-started

chDBはClickHouseによってパワードされたプロセス内SQL OLAPエンジンです

chdb

embedded

clickhouse-lite

in-process

in process

chDBの使い始め

このガイドでは、chDBのPythonバリアントをセットアップしていきます。まず、S3上の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を起動できます:

ipython

さらに、PandasとApache Arrowを使用するので、それらのライブラリもインストールします:

pip install pandas pyarrow

S3上にあるJSONファイルにクエリ

次に、S3バケットに保存されているJSONファイルに対してクエリを行う方法を見てみましょう。YouTubeの非表示データセットには、2021年までのYouTube動画の非表示数が4億以上含まれています。このデータセットのJSONファイルの1つを使っていきます。

chdbをインポートします:

import chdb

次のクエリで、JSONファイルの構造を調べることができます:

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')
  """
)

:::warning これはプログラム内で定義された変数を使用する限りでは問題ありませんが、ユーザーから提供された入力で行うと、クエリがSQLインジェクションに対して脆弱になります。 :::

出力フォーマットの設定

デフォルトの出力フォーマットはCSVですが、output_formatパラメータを使って変更できます。chDBはClickHouseのデータフォーマットに加え、DataFrameなどchDB独自のフォーマットをサポートしており、Pandas 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")

次に、JSONファイルのスキーマに基づいてdislikesテーブルをCREATE...EMPTY AS技法を使って作成します。カラムの型をすべて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
  """
)

これらのステップを1回の操作で行うこともできます。CREATE...AS技法を使って異なるテーブルを作成してみます:

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
0                             Jeremih  139066569     812602         37842
1                     TheKillersMusic  109313116     529361         11931
2  LetsGoMartin- Canciones Infantiles  104747788     236615        141467
3                    Xiaoying Cuisine   54458335    1031525         37049
4                                Adri   47404537     279033         36583
5                  Diana and Roma IND   43829341     182334        148740
6                      ChuChuTV Tamil   39244854     244614        213772
7                            Cheez-It   35342270        108            27
8                            Anime Uz   33375618    1270673         60013
9                    RC Cars OFF Road   31952962     101503         49489

例えば、次にDataFrameにlikesとdislikesの比率を計算するカラムを追加する場合、次のコードを書くことができます:

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

Pandas DataFrameへのクエリ

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

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

                             uploader  likeDislikeRatio
0                             Jeremih         21.473548
1                     TheKillersMusic         44.368536
2  LetsGoMartin- Canciones Infantiles          1.672581
3                    Xiaoying Cuisine         27.842182
4                                Adri          7.627395
5                  Diana and Roma IND          1.225857
6                      ChuChuTV Tamil          1.144275
7                            Cheez-It          4.000000
8                            Anime Uz         21.173296
9                    RC Cars OFF Road          2.051021

Pandas DataFrameへのクエリについての詳細はQuerying Pandas developer guideで詳しく説明されています。

次のステップ

このガイドでchDBの概要が理解できたでしょうか。さらなる学習には、以下のデベロッパーガイドをご参照ください:

11 KiB Raw Blame History

chDBの使い始め

セットアップ

S3上にあるJSONファイルにクエリ

出力フォーマットの設定

JSONファイルからテーブルの作成

テーブルへのクエリ

Pandas DataFrameへのクエリ

次のステップ

11 KiB

Raw Blame History