explain() メソッド - ClickHouse Documentation

explain() メソッドは、DataStore クエリの実行計画を表示し、どのような処理が実行され、どのような SQL が生成されるかを把握するのに役立ちます。

基本的な使い方

from pathlib import Path
Path("sales.csv").write_text("""\
region,product,category,amount,quantity,price,date,order_id
East,Widget,Electronics,5200,10,120,2024-01-15,1001
West,Gadget,Electronics,800,5,160,2024-02-20,1002
East,Gizmo,Home,6500,3,100,2024-03-10,1003
North,Widget,Electronics,4500,6,150,2024-06-18,1004
West,Gadget,Electronics,2000,8,250,2024-09-14,1005
""")

from chdb import datastore as pd

ds = pd.read_csv("sales.csv")

query = (ds
    .filter(ds['amount'] > 1000)
    .groupby('region')
    .agg({'amount': ['sum', 'mean']})
    .sort('sum', ascending=False)
)

# 実行計画を表示
query.explain()

構文

explain(verbose=False) -> None

パラメータ:

パラメータ	型	デフォルト	説明
`verbose`	bool	`False`	追加のメタデータを表示する

出力フォーマット

標準出力

================================================================================
実行計画 (in execution order)
================================================================================

 [1] 📊 データソース: file('sales.csv', 'csv')

操作:
────────────────────────────────────────────────────────────────────────────────
    ️  Segment 1 [chDB] (from source): 操作 2-5
    ️  Note: SQL operations after Pandas ops use Python() table function

 [2] 🚀 [chDB] WHERE: "amount" > 1000
 [3] 🚀 [chDB] GROUP BY: region
 [4] 🚀 [chDB] AGGREGATE: sum(amount), avg(amount)
 [5] 🚀 [chDB] ORDER BY: sum DESC

────────────────────────────────────────────────────────────────────────────────
Final State: 📊 Pending (lazy, not yet executed)
             └─> Will execute when print(), .to_df(), .execute() is called

────────────────────────────────────────────────────────────────────────────────
Generated SQL Query:
────────────────────────────────────────────────────────────────────────────────

SELECT region, SUM(amount) AS sum, AVG(amount) AS mean
FROM file('sales.csv', 'csv')
WHERE "amount" > 1000
GROUP BY region
ORDER BY sum DESC

================================================================================

アイコンの凡例

アイコン	意味
📊	データソース
🚀	chDB (SQL) の操作
🐼	pandas の操作

verbose出力

query.explain(verbose=True)

verboseモードでは、各操作について追加情報が表示されます。これには、内部の行順序追跡メカニズムを含む完全なSQLクエリも含まれます。

3つの実行フェーズ

EXPLAIN の出力では、処理が次の3つのフェーズで示されます:

フェーズ 1: SQLクエリの構築 (遅延評価)

SQLにコンパイルされる操作:

Source: file('sales.csv', 'CSVWithNames')
Filter: amount > 1000      
GroupBy: region
Aggregate: sum(amount)

フェーズ 2: 実行のタイミング

トリガーが発生すると:

  5. Execute SQL -> DataFrame
     Trigger: to_df() called

フェーズ 3: DataFrame の処理

実行後の処理:

  6. [pandas] pivot_table(...)
  7. [pandas] apply(custom_func)

実行計画を理解する

ソース情報

Source: file('sales.csv', 'CSVWithNames')

file() - ClickHouseのfile()テーブル関数
'CSVWithNames' - ヘッダー付きのファイルフォーマット

その他のソースタイプ:

Source: s3('bucket/data.parquet', ...)
Source: mysql('host', 'db', 'table', ...)
Source: __dataframe__  (pandas DataFrame input)

フィルタ処理

Filter: amount > 1000 AND status = 'active'

適用される WHERE 句を表示します。

GroupBy と集計

GroupBy: region, category
Aggregate: sum(amount), avg(amount), count(id)

GROUP BY のカラムと集計関数を表示します。

ソート操作

Sort: sum DESC, region ASC

ORDER BY 句を示します。

操作の制限

Limit: 10
Offset: 100

LIMIT と OFFSET を表示します。

エンジン情報

verbose モードを使用すると、どのエンジンが使用されるかを確認できます。

Filter: amount > 1000
  - Engine: chdb
  - Pushdown: Yes

Apply: custom_function
  - Engine: pandas
  - Pushdown: No

プッシュダウン

はい: 操作はデータソース (SQL) で実行されます
いいえ: 操作の実行には pandas が必要です

例

基本的なクエリ

from pathlib import Path
Path("data.csv").write_text("""\
name,age,city,salary,department
Alice,25,NYC,55000,Engineering
Bob,30,LA,65000,Product
Charlie,35,NYC,80000,Engineering
Diana,28,SF,70000,Design
Eve,42,NYC,95000,Product
""")

ds = pd.read_csv("data.csv")
ds.filter(ds['age'] > 25).explain()

================================================================================
実行計画 (in execution order)
================================================================================

 [1] 📊 データソース: file('data.csv', 'csv')

操作:
────────────────────────────────────────────────────────────────────────────────
    ️  Segment 1 [chDB] (from source): 操作 2-2

 [2] 🚀 [chDB] WHERE: "age" > 25

────────────────────────────────────────────────────────────────────────────────
Generated SQL Query:
────────────────────────────────────────────────────────────────────────────────

SELECT * FROM file('data.csv', 'csv') WHERE "age" > 25

================================================================================

複雑な集計

query = (ds
    .filter(ds['date'] >= '2024-01-01')
    .filter(ds['amount'] > 100)
    .select('region', 'category', 'amount')
    .groupby('region', 'category')
    .agg({
        'amount': ['sum', 'mean', 'count']
    })
    .sort('sum', ascending=False)
    .limit(20)
)
query.explain()

================================================================================
実行計画 (in execution order)
================================================================================

 [1] 📊 データソース: file('sales.csv', 'csv')

操作:
────────────────────────────────────────────────────────────────────────────────
    ️  Segment 1 [chDB] (from source): 操作 2-8

 [2] 🚀 [chDB] WHERE: "date" >= '2024-01-01'
 [3] 🚀 [chDB] WHERE: "amount" > 100
 [4] 🚀 [chDB] SELECT: region, category, amount
 [5] 🚀 [chDB] GROUP BY: region, category
 [6] 🚀 [chDB] AGGREGATE: sum(amount), avg(amount), count(amount)
 [7] 🚀 [chDB] ORDER BY: sum DESC
 [8] 🚀 [chDB] LIMIT: 20

────────────────────────────────────────────────────────────────────────────────
Generated SQL Query:
────────────────────────────────────────────────────────────────────────────────

SELECT region, category, 
       SUM(amount) AS sum, 
       AVG(amount) AS mean, 
       COUNT(amount) AS count
FROM file('sales.csv', 'csv')
WHERE "date" >= '2024-01-01' AND "amount" > 100
GROUP BY region, category
ORDER BY sum DESC
LIMIT 20

================================================================================

SQL と pandas の併用

処理を完全に SQL に押し込めない場合、実行計画には複数のセグメントが表示されます。

query = (ds
    .filter(ds['age'] > 25)           # SQL
    .groupby('city')                   # SQL
    .agg({'salary': 'mean'})           # SQL
    .apply(lambda x: x * 1.1)          # pandas（セグメントの分割をトリガー）
    .filter(ds['mean'] > 50000)        # SQL（新しいセグメント）
)
query.explain()

================================================================================
実行計画（実行順）
================================================================================

 [1] 📊 データソース: file('data.csv', 'csv')

操作:
────────────────────────────────────────────────────────────────────────────────
    ️  セグメント 1 [chDB] (ソースから): 操作 2-4
    ️  セグメント 2 [Pandas] (DataFrame上): 操作 5
    ️  セグメント 3 [chDB] (DataFrame上): 操作 6
    ️  注意: Pandas操作後のSQL操作にはPython()テーブル関数が使用されます

 [2] 🚀 [chDB] WHERE: "age" > 25
 [3] 🚀 [chDB] GROUP BY: city
 [4] 🚀 [chDB] AGGREGATE: avg(salary)
 [5] 🐼 [Pandas] APPLY: lambda
 [6] 🚀 [chDB] WHERE: "mean" > 50000

================================================================================

explain() を使ったデバッグ

フィルタ条件の判定ロジックを確認する

# フィルターが正しいことを確認する
query = ds.filter((ds['age'] > 25) & (ds['city'] == 'NYC'))
query.explain()
# 出力例: Filter: age > 25 AND city = 'NYC'

カラムの選択を確認する

# カラムのプルーニングを確認する
query = ds.select('name', 'age').filter(ds['age'] > 25)
query.explain()
# 出力: SELECT name, age FROM ... WHERE age > 25

集約を理解する

# 集計関数を確認する
query = ds.groupby('dept').agg({'salary': ['sum', 'mean', 'std']})
query.explain()
# 出力: SELECT dept, SUM(salary), AVG(salary), stddevPop(salary)

ベストプラクティス

1. 大規模なクエリを実行する前の確認

# 大規模データの場合は常に最初にexplainを実行する
query = ds.complex_pipeline()
query.explain()  # 実行計画を確認する

# 実行計画が正しければ
result = query.to_df()  # 実行する

2. Verboseを使ってデバッグする

# 何かおかしいと思ったとき
query.explain(verbose=True)
# エンジンの選択とプッシュダウン情報を表示

3. `to_sql()` との比較

# explain() はプランを表示する
query.explain()

# to_sql() はSQLのみを表示する
print(query.to_sql())

# それぞれ異なる用途で役立つ

4. Pushdown の状態を確認する

# verboseモードでは、操作がプッシュダウンされているかどうかを確認できます
query.explain(verbose=True)

# プッシュダウンが「No」の場合、操作はpandasで実行されます
# パフォーマンス向上のため、クエリの構造を見直してください

​基本的な使い方

​構文

​出力フォーマット

​標準出力

​アイコンの凡例

​verbose出力

​3つの実行フェーズ

​フェーズ 1: SQLクエリの構築 (遅延評価)

​フェーズ 2: 実行のタイミング

​フェーズ 3: DataFrame の処理

​実行計画を理解する

​ソース情報

​フィルタ処理

​GroupBy と集計

​ソート操作

​操作の制限

​エンジン情報

​プッシュダウン

​例

​基本的なクエリ

​複雑な集計

​SQL と pandas の併用

​explain() を使ったデバッグ

​フィルタ条件の判定ロジックを確認する

​カラムの選択を確認する

​集約を理解する

​ベストプラクティス

​1. 大規模なクエリを実行する前の確認

​2. Verboseを使ってデバッグする

​3. to_sql() との比較

​4. Pushdown の状態を確認する