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

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

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

​

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

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

​

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

​

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

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

​

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

print(config.execution_engine)  # 'auto', 'chDB' или 'pandas'

---

​

Автоматический режим

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

​

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

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

​

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

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

​

Пример

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)

---

​

Режим chDB

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

config.use_chdb()

​

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

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

​

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

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

​

Ограничения

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

---

​

Режим pandas

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

config.use_pandas()

​

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

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

​

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

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

---

​

Движок Cross-DataStore

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

# Установить движок cross-DataStore
config.set_cross_datastore_engine('auto')
config.set_cross_datastore_engine('chdb')
config.set_cross_datastore_engine('pandas')

​

Пример

ds1 = pd.read_csv("sales.csv")
ds2 = pd.read_csv("inventory.csv")

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

---

​

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

​

Дерево решений для автоматического режима

Operation requested
    │
    ├─ Can be expressed in SQL?
    │      │
    │      ├─ Yes → Use chDB
    │      │
    │      └─ No → Use pandas
    │
    └─ Cross-DataStore operation?
           │
           └─ Use cross_datastore_engine setting

​

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

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

from chdb.datastore.config import function_config

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

Подробнее см. в разделе Конфигурация функции.

---

​

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

Результаты бенчмарка на 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, чтобы получить преимущества обоих вариантов

---

​

Рекомендации

​

1. Начните с автоматического режима

config.use_auto()  # Позвольте DataStore решить

​

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

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

​

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

# Для задач с интенсивной агрегацией
config.use_chdb()

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

​

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

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

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

---

​

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

​

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

# Проверить текущий движок
print(config.execution_engine)

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

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

​

Проблема: Неподдерживаемая операция в режиме chDB

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

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

​

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

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

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

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

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

Если вы выполняете ресурсоёмкие задачи агрегации и вам не нужна точная совместимость вывода с pandas (порядок строк, MultiIndex, исправления dtype), рассмотрите возможность использования режима производительности. Он автоматически устанавливает движок chdb и устраняет все накладные расходы, связанные с совместимостью с pandas.