title_wip

```
# Build query
query = ds.filter(...).groupby(...).agg(...)

# Check plan first
query.explain()

# If plan looks good, execute
result = query.to_df()
```

### 3. Profile Before Optimizing[​](#best-practice-3 "Direct link to 3. Profile Before Optimizing")

```
# Don't guess what's slow - measure it
config.enable_profiling()
result = your_pipeline()
get_profiler().report()
```

### 4. Check SQL When Results Are Wrong[​](#best-practice-4 "Direct link to 4. Check SQL When Results Are Wrong")

```
# View generated SQL
print(query.to_sql())

# Compare with expected SQL
# Run SQL directly in ClickHouse to verify
```

---

## Debugging Tools Summary[​](#summary "Direct link to Debugging Tools Summary")

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Tool Command Output|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Explain plan `ds.explain()` Execution steps + SQL|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Verbose explain `ds.explain(verbose=True)` + Metadata|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | View SQL `ds.to_sql()` SQL query string|  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Enable debug `config.enable_debug()` Detailed logs|  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Enable profiling `config.enable_profiling()` Timing data|  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | | Profiler report `get_profiler().report()` Performance summary|  |  |  | | --- | --- | --- | | Clear profiler `get_profiler().reset()` Clear timing data | | | | | | | | | | | | | | | | | | | | | | | |

---

## Next Steps[​](#next-steps "Direct link to Next Steps")

- [explain() Method](/docs/chdb/debugging/explain) - Detailed execution plan documentation
- [Profiling Guide](/docs/chdb/debugging/profiling) - Performance measurement
- [Logging Configuration](/docs/chdb/debugging/logging) - Log level and format setup

- [Debugging Tools Overview](#overview)- [Quick Decision Matrix](#decision-matrix)- [Quick Setup](#quick-setup)
      - [Enable All Debugging](#enable-all)- [explain() Method](#explain)- [Profiling](#profiling)- [Logging](#logging)- [Common Debugging Scenarios](#scenarios)
              - [1. Query Not Returning Expected Results](#scenario-wrong-results)- [2. Query Running Slowly](#scenario-slow)- [3. Understanding Engine Selection](#scenario-engine)- [4. Debugging Cache Issues](#scenario-cache)- [Best Practices](#best-practices)
                - [1. Debug in Development, Not Production](#best-practice-1)- [2. Use explain() Before Running Large Queries](#best-practice-2)- [3. Profile Before Optimizing](#best-practice-3)- [4. Check SQL When Results Are Wrong](#best-practice-4)- [Debugging Tools Summary](#summary)- [Next Steps](#next-steps)

Was this page helpful?