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

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

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

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

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

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

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

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

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

Пример

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:

config.use_chdb()

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

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

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

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

Ограничения

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

Режим pandas

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

config.use_pandas()

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

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

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

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

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

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

# Set cross-DataStore engine
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")

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

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

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

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

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

См. Конфигурация функции для получения подробной информации.

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

Результаты бенчмарка на 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

config.use_auto()  # Let DataStore decide

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

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

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

# For heavy aggregation workloads
config.use_chdb()

# For pandas compatibility testing
config.use_pandas()

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

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()

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

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

# 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

# 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()

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

# 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()

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

Начало работы

Интеграции с языками программирования

DataStore

Конфигурация

Отладка

Руководства для разработчиков

Технический справочник

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

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