Настройка на уровне функций

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

DataStore позволяет тонко управлять выполнением на уровне функций, включая выбор движка и коррекцию Dtype.

​

Настройка Function Engine

Переопределите движок выполнения для отдельных функций.

​

Настройка Function Engines

from chdb.datastore.config import function_config

# Принудительно использовать chdb для указанных функций
function_config.use_chdb('length', 'substring', 'concat')

# Принудительно использовать pandas для указанных функций
function_config.use_pandas('upper', 'lower', 'capitalize')

# Установить предпочтение по умолчанию
function_config.prefer_chdb()    # По умолчанию chdb
function_config.prefer_pandas()  # По умолчанию pandas

# Сбросить в автоматический режим
function_config.reset()

​

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

Принудительно использовать chdb для:

• Функций, которые работают быстрее в ClickHouse
• Функций, выигрывающих от SQL-оптимизации
• Масштабных операций со строками и датой/временем

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

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

​

Пример

from chdb import datastore as pd
from chdb.datastore.config import function_config

# Настройка движков функций
function_config.use_chdb('length', 'substring')
function_config.use_pandas('upper')

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

# length() будет использовать chdb
ds['name_len'] = ds['name'].str.len()

# substring() будет использовать chdb  
ds['prefix'] = ds['name'].str.slice(0, 3)

# upper() будет использовать pandas
ds['name_upper'] = ds['name'].str.upper()

---

​

Общие функции

Более 159 функций доступны в обоих движках — chdb и pandas:

Категория	Функции
Строки	length, upper, lower, trim, ltrim, rtrim, concat, substring, replace, reverse, contains, startswith, endswith
Математика	abs, round, floor, ceil, exp, log, log10, sqrt, pow, sin, cos, tan
Дата и время	year, month, day, hour, minute, second, dayofweek, dayofyear, quarter
Агрегация	sum, avg, min, max, count, std, var, median

Для общих функций движок выбирается на основе:

1. Явной конфигурации функции (если задана)
2. Глобальной настройки execution_engine
3. Автоматического выбора по контексту

---

​

Функции, доступные только в chdb

Некоторые функции доступны только через ClickHouse:

Категория	Функции
Array	arraySum, arrayAvg, arraySort, arrayDistinct, groupArray, arrayElement
JSON	JSONExtractString, JSONExtractInt, JSONExtractFloat, JSONHas
URL	domain, path, protocol, extractURLParameter
IP	IPv4StringToNum, IPv4NumToString, isIPv4String
Geo	greatCircleDistance, geoDistance, geoToH3
Hash	cityHash64, xxHash64, sipHash64, MD5, SHA256
Conditional	sumIf, countIf, avgIf, minIf, maxIf

Эти функции автоматически используют движок chdb независимо от конфигурации.

---

​

Функции, доступные только в pandas

Некоторые функции доступны только через pandas:

Категория	Функции
Apply	Собственные лямбда-функции, пользовательские функции
Complex Pivot	Сводные таблицы с пользовательскими агрегациями
Stack/Unstack	Сложные операции преобразования формы данных
Interpolate	Методы интерполяции временных рядов

Эти функции автоматически используют движок pandas независимо от конфигурации.

---

​

Коррекция dtype

Настройте, как DataStore корректирует типы данных между движками.

​

Уровни коррекции

from chdb.datastore.dtype_correction.config import CorrectionLevel
from chdb.datastore.config import config

# Без коррекции
config.set_correction_level(CorrectionLevel.NONE)

# Только критические типы (обработка NULL, булевы значения)
config.set_correction_level(CorrectionLevel.CRITICAL)

# Высокий приоритет (по умолчанию) — распространённые несоответствия типов
config.set_correction_level(CorrectionLevel.HIGH)

# Средний — более агрессивная коррекция
config.set_correction_level(CorrectionLevel.MEDIUM)

# Все — коррекция всех возможных типов
config.set_correction_level(CorrectionLevel.ALL)

​

Подробное описание уровней коррекции

Уровень	Описание	Исправляемые типы
NONE	Без автоматических исправлений	Нет
CRITICAL	Критически важные исправления	обработка NULL, преобразование булевых значений
HIGH (по умолчанию)	Распространённые исправления	точность целых чисел и чисел с плавающей точкой, дата и время, кодировка строк
MEDIUM	Дополнительные исправления	точность Decimal, обработка часовых поясов
ALL	Максимальный уровень исправления	Все различия в типах

​

Когда требуется корректировка типов

Различия в типах могут возникать в следующих случаях:

1. ClickHouse → pandas: Разный размер целочисленных типов (Int64 vs int64)
2. pandas → ClickHouse: Преобразование объектов Python в SQL-типы
3. Обработка NULL: pandas NA vs ClickHouse NULL
4. булевый: Различные представления логических значений
5. дата и время: Различия в часовых поясах

​

Пример

from chdb.datastore.dtype_correction.config import CorrectionLevel
from chdb.datastore.config import config

# Строгий режим — ожидаются точные соответствия типов
config.set_correction_level(CorrectionLevel.NONE)

# Мягкий режим — автоматическое исправление несоответствий типов
config.set_correction_level(CorrectionLevel.ALL)

---

​

API конфигурации функции

​

Объект function_config

from chdb.datastore.config import function_config

# Принудительно задать движок для функций
function_config.use_chdb(*function_names)
function_config.use_pandas(*function_names)

# Задать предпочтение по умолчанию
function_config.prefer_chdb()
function_config.prefer_pandas()

# Сбросить до значения по умолчанию (авто)
function_config.reset()

# Проверить конфигурацию
function_config.get_engine('length')  # Возвращает 'chdb', 'pandas' или 'auto'

​

Переопределение на уровне отдельного вызова

Некоторые методы поддерживают переопределение движка на уровне отдельного вызова:

# Использование параметра движка (где поддерживается)
ds['result'] = ds['col'].str.upper(engine='pandas')

---

​

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

​

1. Начните с настроек по умолчанию

# Используйте автоматический режим, пусть DataStore решит самостоятельно
config.use_auto()

​

2. Настройте для конкретных рабочих нагрузок

# Для обработки строк, оптимизированной под ClickHouse
function_config.use_chdb('length', 'substring', 'concat')

# Для поведения строк, совместимого с pandas
function_config.use_pandas('upper', 'lower')

​

3. Выберите подходящий уровень коррекции

# Разработка: более мягкий режим
config.set_correction_level(CorrectionLevel.ALL)

# Продакшн: более строгий режим
config.set_correction_level(CorrectionLevel.HIGH)

​

4. Протестируйте оба движка

# Тестирование с chdb
config.use_chdb()
result_chdb = process_data()

# Тестирование с pandas
config.use_pandas()
result_pandas = process_data()

# Сравнение результатов
assert result_chdb.equals(result_pandas)