> ## 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 — auto, chDB или pandas

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

<div id="engines">
  ## Доступные движки
</div>

| Engine   | Description                                                   | Best For                                       |
| -------- | ------------------------------------------------------------- | ---------------------------------------------- |
| `auto`   | Автоматически выбирает оптимальный движок для каждой операции | Общее применение (по умолчанию)                |
| `chDB`   | Принудительно направляет все операции через ClickHouse SQL    | Большие датасеты, агрегации                    |
| `pandas` | Принудительно направляет все операции через pandas            | Тестирование совместимости, возможности pandas |

<div id="setting">
  ## Настройка движка
</div>

<div id="global">
  ### Глобальная конфигурация
</div>

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

# Вариант 1: Использование метода set
config.set_execution_engine('auto')    # По умолчанию
config.set_execution_engine('chdb')    # Принудительно ClickHouse
config.set_execution_engine('pandas')  # Принудительно pandas

# Вариант 2: Использование сокращённых методов
config.use_auto()     # Автоматический выбор
config.use_chdb()     # Принудительно ClickHouse
config.use_pandas()   # Принудительно pandas
```

<div id="checking">
  ### Проверка текущего движка
</div>

```python theme={null}
print(config.execution_engine)  # 'auto', 'chDB' или 'pandas'
```

***

<div id="auto-mode">
  ## Автоматический режим
</div>

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

<div id="auto-chdb">
  ### Операции, выполняемые в chDB
</div>

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

<div id="auto-pandas">
  ### Операции, выполняемые в pandas
</div>

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

<div id="auto-example">
  ### Пример
</div>

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

config.use_auto()  # По умолчанию

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

# Используется chDB (SQL)
result = (ds
    .filter(ds['amount'] > 100)   # SQL: WHERE
    .groupby('region')            # SQL: GROUP BY
    .agg({'amount': 'sum'})       # SQL: SUM()
)

# Используется pandas (пользовательская функция)
result = ds.apply(lambda row: complex_calculation(row), axis=1)
```

***

<div id="chdb-mode">
  ## Режим chDB
</div>

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

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

<div id="chdb-when">
  ### Когда использовать
</div>

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

<div id="chdb-performance">
  ### Характеристики производительности
</div>

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

<div id="chdb-limitations">
  ### Ограничения
</div>

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

***

<div id="pandas-mode">
  ## Режим pandas
</div>

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

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

<div id="chdb-when">
  ### Когда использовать
</div>

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

<div id="chdb-performance">
  ### Характеристики производительности
</div>

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

***

<div id="cross-datastore">
  ## Движок Cross-DataStore
</div>

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

```python theme={null}
# Установить движок cross-DataStore
config.set_cross_datastore_engine('auto')
config.set_cross_datastore_engine('chdb')
config.set_cross_datastore_engine('pandas')
```

<div id="auto-example">
  ### Пример
</div>

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

# Эта операция затрагивает два DataStore
result = ds1.join(ds2, on='product_id')
# Использует настройку cross_datastore_engine
```

***

<div id="selection-logic">
  ## Логика выбора движка
</div>

<div id="decision-tree">
  ### Дерево решений для автоматического режима
</div>

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

<div id="function-override">
  ### Переопределение на уровне функций
</div>

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

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

# Принудительно задать конкретный движок для конкретных функций
function_config.use_chdb('length', 'substring')
function_config.use_pandas('upper', 'lower')
```

Подробнее см. в разделе [Конфигурация функции](/ru/products/chdb/configuration/function-config).

***

<div id="performance-comparison">
  ## Сравнение производительности
</div>

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

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

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

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

***

<div id="best-practices">
  ## Рекомендации
</div>

<div id="start-with-auto-mode">
  ### 1. Начните с автоматического режима
</div>

```python theme={null}
config.use_auto()  # Позвольте DataStore решить
```

<div id="profile-before-forcing">
  ### 2. Сначала профилируйте, потом принудительно задавайте
</div>

```python theme={null}
config.enable_profiling()
# Запустите рабочую нагрузку
# Проверьте отчёт профилировщика, чтобы узнать, где тратится время
```

<div id="force-engine-for-specific-workloads">
  ### 3. Явно задавайте движок для конкретных рабочих нагрузок
</div>

```python theme={null}
# Для задач с интенсивной агрегацией
config.use_chdb()

# Для тестирования совместимости с pandas
config.use_pandas()
```

<div id="use-explain-to-understand-execution">
  ### 4. Используйте explain(), чтобы понять выполнение запроса
</div>

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

# Посмотреть, какой SQL будет сгенерирован
query.explain()
```

***

<div id="troubleshooting">
  ## Устранение неполадок
</div>

<div id="issue-operation-slower">
  ### Проблема: Операция выполняется медленнее, чем ожидалось
</div>

```python theme={null}
# Проверить текущий движок
print(config.execution_engine)

# Включить отладку для диагностики
config.enable_debug()

# Попробовать принудительно задать конкретный движок
config.use_chdb()  # или config.use_pandas()
```

<div id="issue-unsupported-operation">
  ### Проблема: Неподдерживаемая операция в режиме chDB
</div>

```python theme={null}
# Некоторые операции pandas не поддерживаются в SQL
# Решение: использовать режим auto
config.use_auto()

# Или сначала явно преобразовать в pandas
df = ds.to_df()
result = df.some_pandas_specific_operation()
```

<div id="issue-memory-issues">
  ### Проблема: нехватка памяти при работе с большими объёмами данных
</div>

```python theme={null}
# Используйте движок chdb, чтобы не загружать все данные в память
config.use_chdb()

# Фильтруйте данные заранее, чтобы уменьшить их объём
result = ds.filter(ds['date'] >= '2024-01-01').to_df()

# Для максимальной пропускной способности при работе с большими датасетами используйте режим производительности,
# который включает параллельное чтение Parquet и агрегацию в одном SQL-запросе
config.use_performance_mode()
```

<Tip>
  **Режим производительности**

  Если вы выполняете ресурсоёмкие задачи агрегации и вам не нужна точная совместимость вывода с pandas (порядок строк, MultiIndex, исправления dtype), рассмотрите возможность использования [режима производительности](/ru/products/chdb/configuration/performance-mode). Он автоматически устанавливает движок `chdb` и устраняет все накладные расходы, связанные с совместимостью с pandas.
</Tip>