> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# DataStore のデバッグ

> explain()、プロファイリング、ログを使用した DataStore 操作のデバッグ

DataStore には、データパイプラインの理解と最適化に役立つ包括的なデバッグツールが用意されています。

<div id="overview">
  ## デバッグツールの概要
</div>

| ツール         | 目的         | 使用する場面             |
| ----------- | ---------- | ------------------ |
| `explain()` | 実行計画を確認    | 実行される SQL の内容を把握する |
| プロファイラ      | パフォーマンスを測定 | 遅い処理を特定する          |
| ログ          | 実行の詳細を確認   | 想定外の動作をデバッグする      |

<div id="decision-matrix">
  ## クイック判断表
</div>

| 必要なもの       | ツール         | コマンド                        |
| ----------- | ----------- | --------------------------- |
| 実行計画を確認     | `explain()` | `ds.explain()`              |
| パフォーマンスを測定  | プロファイラ      | `config.enable_profiling()` |
| SQLクエリをデバッグ | ログ          | `config.enable_debug()`     |
| 上記すべて       | 組み合わせ       | 以下を参照                       |

<div id="quick-setup">
  ## クイックセットアップ
</div>

<div id="enable-all">
  ### すべてのデバッグ機能を有効にする
</div>

```python theme={null}
from chdb import datastore as pd
from chdb.datastore.config import config

# すべてのデバッグを有効化
config.enable_debug()        # 詳細ロギング
config.enable_profiling()    # パフォーマンス追跡

ds = pd.read_csv("data.csv")
result = ds.filter(ds['age'] > 25).groupby('city').agg({'salary': 'mean'})

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

# プロファイラレポートを取得
from chdb.datastore.config import get_profiler
profiler = get_profiler()
profiler.report()
```

***

<div id="explain">
  ## explain() メソッド
</div>

クエリを実行する前に、実行計画を確認できます。

```python title="Query" theme={null}
ds = pd.read_csv("data.csv")

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

# プランを表示
query.explain()
```

```text title="Response" theme={null}
Pipeline:
  Source: file('data.csv', 'CSVWithNames')
  Filter: amount > 1000
  GroupBy: region
  Aggregate: sum(amount), avg(amount)

Generated SQL:
SELECT region, SUM(amount) AS sum, AVG(amount) AS mean
FROM file('data.csv', 'CSVWithNames')
WHERE amount > 1000
GROUP BY region
```

詳しくは、[explain() のドキュメント](/ja/products/chdb/debugging/explain)を参照してください。

***

<div id="profiling">
  ## プロファイリング
</div>

各操作の実行時間を測定します。

```python title="Query" theme={null}
from chdb.datastore.config import config, get_profiler

# プロファイリングを有効化
config.enable_profiling()

# 操作を実行
ds = pd.read_csv("large_data.csv")
result = (ds
    .filter(ds['amount'] > 100)
    .groupby('category')
    .agg({'amount': 'sum'})
    .sort('sum', ascending=False)
    .head(10)
    .to_df()
)

# レポートを表示
profiler = get_profiler()
profiler.report(min_duration_ms=0.1)
```

```text title="Response" theme={null}
パフォーマンスレポート
==================
ステップ                          所要時間    呼び出し回数
----                          --------    -----
read_csv                      1.234s      1
filter                        0.002s      1
groupby                       0.001s      1
agg                           0.089s      1
sort                          0.045s      1
head                          0.001s      1
to_df (SQL execution)         0.567s      1
----                          --------    -----
合計                         1.939s      7
```

詳細については、[プロファイリングガイド](/ja/products/chdb/debugging/profiling)を参照してください。

***

<div id="logging">
  ## ログ
</div>

詳細な実行ログを確認します。

```python theme={null}
from chdb.datastore.config import config

# デバッグログを有効化
config.enable_debug()

# 操作を実行すると、以下がログに表示されます:
# - 生成されたSQLクエリ
# - 使用された実行エンジン
# - cacheのヒット/ミス
# - タイミング情報
```

ログ出力の例：

```text theme={null}
DEBUG - DataStore: Creating from file 'data.csv'
DEBUG - Query: SELECT region, SUM(amount) FROM ... WHERE amount > 1000 GROUP BY region
DEBUG - Engine: Using chdb for aggregation
DEBUG - Execution time: 0.089s
DEBUG - Cache: Storing result (key: abc123)
```

詳しくは、[ログ設定](/ja/products/chdb/debugging/logging)を参照してください。

***

<div id="scenarios">
  ## よくあるデバッグのシナリオ
</div>

<div id="scenario-wrong-results">
  ### 1. クエリが期待どおりの結果を返さない
</div>

```python theme={null}
# ステップ1: 実行計画を確認する
query = ds.filter(ds['age'] > 25).groupby('city').sum()
query.explain(verbose=True)

# ステップ2: SQLを確認するためにログを有効にする
config.enable_debug()

# ステップ3: 実行してログを確認する
result = query.to_df()
```

<div id="scenario-slow">
  ### 2. クエリの実行が遅い
</div>

```python theme={null}
# ステップ1: プロファイリングを有効にする
config.enable_profiling()

# ステップ2: クエリを実行する
result = process_data()

# ステップ3: プロファイラのレポートを確認する
profiler = get_profiler()
profiler.report()

# ステップ4: 遅い処理を特定して最適化する
```

<div id="scenario-engine">
  ### 3. Engine 選択を理解する
</div>

```python theme={null}
# 詳細ロギングを有効にする
config.enable_debug()

# 操作を実行する
result = ds.filter(ds['x'] > 10).apply(custom_func)

# ログには各操作で使用されたエンジンが表示される:
# DEBUG - filter: chdb エンジンを使用
# DEBUG - apply: pandas エンジンを使用（カスタム関数）
```

<div id="scenario-cache">
  ### 4. cache に関する問題のデバッグ
</div>

```python theme={null}
# キャッシュ操作を確認するためにデバッグを有効化
config.enable_debug()

# 初回実行
result1 = ds.filter(ds['x'] > 10).to_df()
# LOG: キャッシュミス、クエリを実行中

# 2回目の実行（cacheを使用するはず）
result2 = ds.filter(ds['x'] > 10).to_df()
# LOG: キャッシュヒット、キャッシュ済み結果を返却

# 期待通りにキャッシュされない場合は以下を確認:
# - 操作は同一か？
# - cacheは有効か？ config.cache_enabled
```

***

<div id="best-practices">
  ## ベストプラクティス
</div>

<div id="best-practice-1">
  ### 1. デバッグは本番環境ではなく開発環境で行う
</div>

```python theme={null}
# 開発環境
config.enable_debug()
config.enable_profiling()

# 本番環境
config.set_log_level(logging.WARNING)
config.set_profiling_enabled(False)
```

<div id="best-practice-2">
  ### 2. 大規模なクエリを実行する前に explain() を活用する
</div>

```python theme={null}
# クエリを構築する
query = ds.filter(...).groupby(...).agg(...)

# まず実行計画を確認する
query.explain()

# 実行計画に問題がなければ実行する
result = query.to_df()
```

<div id="best-practice-3">
  ### 3. 最適化の前にプロファイリングを行う
</div>

```python theme={null}
# 遅い箇所を推測せず、計測する
config.enable_profiling()
result = your_pipeline()
get_profiler().report()
```

<div id="best-practice-4">
  ### 4. 結果が正しくない場合は SQL を確認する
</div>

```python theme={null}
# 生成された SQL を表示する
print(query.to_sql())

# 期待される SQL と比較する
# ClickHouse で直接 SQL を実行して確認する
```

***

<div id="summary">
  ## デバッグツールのまとめ
</div>

| ツール            | コマンド                        | 出力           |
| -------------- | --------------------------- | ------------ |
| 実行プランの表示       | `ds.explain()`              | 実行ステップ + SQL |
| 詳細な実行プラン       | `ds.explain(verbose=True)`  | + メタデータ      |
| SQL の表示        | `ds.to_sql()`               | SQL クエリ文字列   |
| デバッグを有効にする     | `config.enable_debug()`     | 詳細なログ        |
| プロファイリングを有効にする | `config.enable_profiling()` | タイミングデータ     |
| プロファイラレポート     | `get_profiler().report()`   | パフォーマンスの概要   |
| プロファイラをクリア     | `get_profiler().reset()`    | タイミングデータをクリア |

***

<div id="next-steps">
  ## 次のステップ
</div>

* [explain() メソッド](/ja/products/chdb/debugging/explain) - 実行計画の詳細な解説
* [プロファイリングガイド](/ja/products/chdb/debugging/profiling) - パフォーマンス計測
* [ログ設定](/ja/products/chdb/debugging/logging) - ログレベルとフォーマットの設定