> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8c05c8a2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# explain() メソッド
> explain() メソッドで DataStore の実行計画を表示
`explain()` メソッドは、DataStore クエリの実行計画を表示し、どのような処理が実行され、どのような SQL が生成されるかを把握するのに役立ちます。
## 基本的な使い方
```python theme={null}
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()
```
## 構文
```python theme={null}
explain(verbose=False) -> None
```
**パラメータ:**
| パラメータ | 型 | デフォルト | 説明 |
| --------- | ---- | ------- | ------------- |
| `verbose` | bool | `False` | 追加のメタデータを表示する |
## 出力フォーマット
### 標準出力
```text theme={null}
================================================================================
実行計画 (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出力
```python theme={null}
query.explain(verbose=True)
```
verboseモードでは、各操作について追加情報が表示されます。これには、内部の行順序追跡メカニズムを含む完全なSQLクエリも含まれます。
***
## 3つの実行フェーズ
EXPLAIN の出力では、処理が次の3つのフェーズで示されます:
### フェーズ 1: SQLクエリの構築 (遅延評価)
SQLにコンパイルされる操作:
```text theme={null}
1. Source: file('sales.csv', 'CSVWithNames')
2. Filter: amount > 1000
3. GroupBy: region
4. Aggregate: sum(amount)
```
### フェーズ 2: 実行のタイミング
トリガーが発生すると:
```text theme={null}
5. Execute SQL -> DataFrame
Trigger: to_df() called
```
### フェーズ 3: DataFrame の処理
実行後の処理:
```text theme={null}
6. [pandas] pivot_table(...)
7. [pandas] apply(custom_func)
```
***
## 実行計画を理解する
### ソース情報
```text theme={null}
Source: file('sales.csv', 'CSVWithNames')
```
* `file()` - ClickHouseのfile()テーブル関数
* `'CSVWithNames'` - ヘッダー付きのファイルフォーマット
その他のソースタイプ:
```text theme={null}
Source: s3('bucket/data.parquet', ...)
Source: mysql('host', 'db', 'table', ...)
Source: __dataframe__ (pandas DataFrame input)
```
### フィルタ処理
```text theme={null}
Filter: amount > 1000 AND status = 'active'
```
適用される WHERE 句を表示します。
### GroupBy と集計
```text theme={null}
GroupBy: region, category
Aggregate: sum(amount), avg(amount), count(id)
```
GROUP BY のカラムと集計関数を表示します。
### ソート操作
```text theme={null}
Sort: sum DESC, region ASC
```
ORDER BY 句を示します。
### 操作の制限
```text theme={null}
Limit: 10
Offset: 100
```
LIMIT と OFFSET を表示します。
***
## エンジン情報
verbose モードを使用すると、どのエンジンが使用されるかを確認できます。
```text theme={null}
Filter: amount > 1000
- Engine: chdb
- Pushdown: Yes
Apply: custom_function
- Engine: pandas
- Pushdown: No
```
### プッシュダウン
* **はい**: 操作はデータソース (SQL) で実行されます
* **いいえ**: 操作の実行には pandas が必要です
***
## 例
### 基本的なクエリ
```python theme={null}
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()
```
```text theme={null}
================================================================================
実行計画 (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
================================================================================
```
### 複雑な集計
```python theme={null}
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()
```
```text theme={null}
================================================================================
実行計画 (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 に押し込めない場合、実行計画には複数のセグメントが表示されます。
```python theme={null}
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()
```
```text theme={null}
================================================================================
実行計画（実行順）
================================================================================
[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() を使ったデバッグ
### フィルタ条件の判定ロジックを確認する
```python theme={null}
# フィルターが正しいことを確認する
query = ds.filter((ds['age'] > 25) & (ds['city'] == 'NYC'))
query.explain()
# 出力例: Filter: age > 25 AND city = 'NYC'
```
### カラムの選択を確認する
```python theme={null}
# カラムのプルーニングを確認する
query = ds.select('name', 'age').filter(ds['age'] > 25)
query.explain()
# 出力: SELECT name, age FROM ... WHERE age > 25
```
### 集約を理解する
```python theme={null}
# 集計関数を確認する
query = ds.groupby('dept').agg({'salary': ['sum', 'mean', 'std']})
query.explain()
# 出力: SELECT dept, SUM(salary), AVG(salary), stddevPop(salary)
```
***
## ベストプラクティス
### 1. 大規模なクエリを実行する前の確認
```python theme={null}
# 大規模データの場合は常に最初にexplainを実行する
query = ds.complex_pipeline()
query.explain() # 実行計画を確認する
# 実行計画が正しければ
result = query.to_df() # 実行する
```
### 2. Verboseを使ってデバッグする
```python theme={null}
# 何かおかしいと思ったとき
query.explain(verbose=True)
# エンジンの選択とプッシュダウン情報を表示
```
### 3. `to_sql()` との比較
```python theme={null}
# explain() はプランを表示する
query.explain()
# to_sql() はSQLのみを表示する
print(query.to_sql())
# それぞれ異なる用途で役立つ
```
### 4. Pushdown の状態を確認する
```python theme={null}
# verboseモードでは、操作がプッシュダウンされているかどうかを確認できます
query.explain(verbose=True)
# プッシュダウンが「No」の場合、操作はpandasで実行されます
# パフォーマンス向上のため、クエリの構造を見直してください
```