title_wip

**Key insights:**

- chDB excels at aggregations and complex pipelines
- pandas is slightly faster for simple single operations
- Use `auto` mode to get the best of both

---

## Best Practices[​](#best-practices "Direct link to Best Practices")

### 1. Start with Auto Mode[​](#start-with-auto-mode "Direct link to 1. Start with Auto Mode")

```
config.use_auto()  # Let DataStore decide
```

### 2. Profile Before Forcing[​](#profile-before-forcing "Direct link to 2. Profile Before Forcing")

```
config.enable_profiling()
# Run your workload
# Check profiler report to see where time is spent
```

### 3. Force Engine for Specific Workloads[​](#force-engine-for-specific-workloads "Direct link to 3. Force Engine for Specific Workloads")

```
# For heavy aggregation workloads
config.use_chdb()

# For pandas compatibility testing
config.use_pandas()
```

### 4. Use explain() to Understand Execution[​](#use-explain-to-understand-execution "Direct link to 4. Use explain() to Understand Execution")

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

# See what SQL will be generated
query.explain()
```

---

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

### Issue: Operation slower than expected[​](#issue-operation-slower "Direct link to Issue: Operation slower than expected")

```
# Check current engine
print(config.execution_engine)

# Enable debug to see what's happening
config.enable_debug()

# Try forcing specific engine
config.use_chdb()  # or config.use_pandas()
```

### Issue: Unsupported operation in chdb mode[​](#issue-unsupported-operation "Direct link to Issue: Unsupported operation in chdb mode")

```
# Some pandas operations aren't supported in SQL
# Solution: use auto mode
config.use_auto()

# Or explicitly convert to pandas first
df = ds.to_df()
result = df.some_pandas_specific_operation()
```

### Issue: Memory issues with large data[​](#issue-memory-issues "Direct link to Issue: Memory issues with large data")

```
# Use chdb engine to avoid loading all data into memory
config.use_chdb()

# Filter early to reduce data size
result = ds.filter(ds['date'] >= '2024-01-01').to_df()

# For maximum throughput on large datasets, use performance mode
# which enables parallel Parquet reading and single-SQL aggregation
config.use_performance_mode()
```

Performance Mode

If you are running heavy aggregation workloads and don't need exact pandas output compatibility (row order, MultiIndex, dtype corrections), consider using [Performance Mode](/docs/chdb/configuration/performance-mode). It automatically sets the engine to `chdb` and removes all pandas compatibility overhead.

- [Available Engines](#engines)- [Setting the Engine](#setting)
    - [Global Configuration](#global)- [Checking Current Engine](#checking)- [Auto Mode](#auto-mode)
      - [Operations Executed in chDB](#auto-chdb)- [Operations Executed in pandas](#auto-pandas)- [Example](#auto-example)- [chDB Mode](#chdb-mode)
        - [When to Use](#chdb-when)- [Performance Characteristics](#chdb-performance)- [Limitations](#chdb-limitations)- [pandas Mode](#pandas-mode)
          - [When to Use](#pandas-when)- [Performance Characteristics](#pandas-performance)- [Cross-DataStore Engine](#cross-datastore)
            - [Example](#cross-example)- [Engine Selection Logic](#selection-logic)
              - [Auto Mode Decision Tree](#decision-tree)- [Function-Level Override](#function-override)- [Performance Comparison](#performance-comparison)- [Best Practices](#best-practices)
                  - [1. Start with Auto Mode](#start-with-auto-mode)- [2. Profile Before Forcing](#profile-before-forcing)- [3. Force Engine for Specific Workloads](#force-engine-for-specific-workloads)- [4. Use explain() to Understand Execution](#use-explain-to-understand-execution)- [Troubleshooting](#troubleshooting)
                    - [Issue: Operation slower than expected](#issue-operation-slower)- [Issue: Unsupported operation in chdb mode](#issue-unsupported-operation)- [Issue: Memory issues with large data](#issue-memory-issues)

Was this page helpful?