> ## 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.

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

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

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

## Настройка Function Engine

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

### Настройка Function Engines

```python theme={null}
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
* Пользовательских операций со строками

### Пример

```python theme={null}
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 корректирует типы данных между движками.

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

```python theme={null}
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. **дата и время**: Различия в часовых поясах

### Пример

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

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

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

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

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

***

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

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

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

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

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

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

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

```python theme={null}
# Разработка: более мягкий режим
config.set_correction_level(CorrectionLevel.ALL)

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

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

```python theme={null}
# Тестирование с chdb
config.use_chdb()
result_chdb = process_data()

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

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