> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Настройка движка выполнения

> Настройка движка выполнения DataStore: auto, chDB или pandas

DataStore может выполнять операции с помощью разных движков. В этом руководстве показано, как настроить и оптимизировать выбор движка.

## Доступные движки

| Движок | Описание | Лучше всего подходит для |
| - | - | - |
| `auto` | Автоматически выбирает оптимальный движок для каждой операции | Для общего использования (по умолчанию) |
| `chdb` | Выполняет все операции через ClickHouse SQL | Крупные датасеты, агрегации |
| `pandas` | Выполняет все операции через pandas | Проверка совместимости, возможности pandas |

## Настройка движка

### Глобальная конфигурация

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

# Option 1: Using set method
config.set_execution_engine('auto')    # Default
config.set_execution_engine('chdb')    # Force ClickHouse
config.set_execution_engine('pandas')  # Force pandas

# Option 2: Using shortcuts
config.use_auto()     # Auto-select
config.use_chdb()     # Force ClickHouse
config.use_pandas()   # Force pandas
```

### Проверка текущего движка

```python theme={null}
print(config.execution_engine)  # 'auto', 'chdb', or 'pandas'
```

***

## Режим Auto

В режиме `auto` (по умолчанию) DataStore выбирает для каждой операции оптимальный движок:

### Операции, выполняемые в chDB

* SQL-совместимая фильтрация (`filter()`, `where()`)
* Выбор столбцов (`select()`)
* Сортировка (`sort()`, `orderby()`)
* Группировка и агрегация (`groupby().agg()`)
* Соединение (`join()`, `merge()`)
* Удаление дубликатов (`distinct()`, `drop_duplicates()`)
* Ограничение (`limit()`, `head()`, `tail()`)

### Операции, выполняемые в pandas

* Пользовательские apply-функции (`apply(custom_func)`)
* Сложные сводные таблицы с пользовательскими агрегациями
* Операции, которые невозможно выразить в SQL
* Если на входе уже pandas DataFrame

### Пример

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

config.use_auto()  # Default

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

# This uses chDB (SQL)
result = (ds
    .filter(ds['amount'] > 100)   # SQL: WHERE
    .groupby('region')            # SQL: GROUP BY
    .agg({'amount': 'sum'})       # SQL: SUM()
)

# This uses pandas (custom function)
result = ds.apply(lambda row: complex_calculation(row), axis=1)
```

***

## Режим chDB

Принудительно выполняйте все операции через ClickHouse SQL:

```python theme={null}
config.use_chdb()
```

### Когда использовать

* Обработка больших наборов данных (миллионы строк)
* Ресурсоёмкие рабочие нагрузки агрегации
* Когда нужна максимальная SQL-оптимизация
* Единообразное поведение во всех операциях

### Характеристики производительности

| Тип операции | Производительность |
| - | - |
| GroupBy/агрегация | Отличная (до 20 раз быстрее) |
| Сложная фильтрация | Отличная |
| Сортировка | Очень хорошая |
| Простые фильтры по одному условию | Хорошая (небольшие накладные расходы) |

### Ограничения

* Пользовательские функции Python могут не поддерживаться
* Для некоторых возможностей, специфичных для pandas, требуется преобразование

***

## Режим pandas

Принудительно выполняйте все операции через pandas:

```python theme={null}
config.use_pandas()
```

### Когда использовать pandas

* Тестирование совместимости с pandas
* Использование возможностей pandas
* Отладка проблем, связанных с pandas
* Когда данные уже представлены в формате pandas

### Характеристики производительности

| Тип операции | Производительность |
| - | - |
| Простые отдельные операции | Хорошая |
| Пользовательские функции | Отличная |
| Сложные агрегации | Медленнее, чем chDB |
| Крупные датасеты | Требуют много памяти |

***

## Движок для операций между DataStore

Настройте движок для операций, объединяющих столбцы из разных DataStore:

```python theme={null}
# Set cross-DataStore engine
config.set_cross_datastore_engine('auto')
config.set_cross_datastore_engine('chdb')
config.set_cross_datastore_engine('pandas')
```

### Пример

```python theme={null}
ds1 = pd.read_csv("sales.csv")
ds2 = pd.read_csv("inventory.csv")

# This operation involves two DataStores
result = ds1.join(ds2, on='product_id')
# Uses cross_datastore_engine setting
```

***

## Логика выбора движка

### Дерево решений для режима Auto

```text theme={null}
Operation requested
    │
    ├─ Can be expressed in SQL?
    │      │
    │      ├─ Yes → Use chDB
    │      │
    │      └─ No → Use pandas
    │
    └─ Cross-DataStore operation?
           │
           └─ Use cross_datastore_engine setting
```

### Переопределение на уровне функции

Для некоторых функций можно явно задать движок:

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

# Force specific functions to use specific engine
function_config.use_chdb('length', 'substring')
function_config.use_pandas('upper', 'lower')
```

См. [Конфигурация функции](https://clickhouse.com/docs/ru/chdb/configuration/function-config.md) для получения подробной информации.

***

## Сравнение производительности

Результаты бенчмарка на 10 млн строк:

| Операция | pandas (ms) | chdb (ms) | Ускорение |
| - | - | - | - |
| GroupBy count | 347 | 17 | 19.93x |
| Комбинированные операции | 1,535 | 234 | 6.56x |
| Сложный конвейер | 2,047 | 380 | 5.39x |
| Filter+Sort+Head | 1,537 | 350 | 4.40x |
| GroupBy agg | 406 | 141 | 2.88x |
| Одиночный фильтр | 276 | 526 | 0.52x |

**Ключевые выводы:**

* chDB особенно хорошо показывает себя в агрегациях и сложных конвейерах
* pandas немного быстрее при простых одиночных операциях
* Используйте режим `auto`, чтобы получить лучшее из обоих вариантов

***

## Лучшие практики

### 1. Начните с режима Auto

```python theme={null}
config.use_auto()  # Let DataStore decide
```

### 2. Сначала профилируйте, потом применяйте принудительно

```python theme={null}
config.enable_profiling()
# Run your workload
# Check profiler report to see where time is spent
```

### 3. Явно задавайте движок для конкретных рабочих нагрузок

```python theme={null}
# For heavy aggregation workloads
config.use_chdb()

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

### 4. Используйте explain(), чтобы понять выполнение

```python theme={null}
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()
```

***

## Устранение неполадок

### Проблема: операция выполняется медленнее, чем ожидалось

```python theme={null}
# 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()
```

### Проблема: операция не поддерживается в режиме chDB

```python theme={null}
# 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()
```

### Проблема: нехватка памяти при больших объёмах данных

```python theme={null}
# 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()
```

> [!TIP]
>
> **Режим производительности**
>
> Если вы работаете с ресурсоёмкими агрегациями и вам не нужна полная совместимость вывода с pandas (порядок строк, MultiIndex, корректировка dtype), рассмотрите возможность использования [режима производительности](https://clickhouse.com/docs/ru/chdb/configuration/performance-mode.md). Он автоматически переключает движок на `chdb` и устраняет все накладные расходы, связанные с совместимостью с pandas.