> ## 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 보정이 포함됩니다.

## 함수 엔진 구성

특정 함수의 실행 엔진을 재정의합니다.

### 함수 엔진 설정

```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에서만 사용할 수 있습니다.

| 범주 | 함수 |
| - | - |
| **배열** | `arraySum`, `arrayAvg`, `arraySort`, `arrayDistinct`, `groupArray`, `arrayElement` |
| **JSON** | `JSONExtractString`, `JSONExtractInt`, `JSONExtractFloat`, `JSONHas` |
| **URL** | `domain`, `path`, `protocol`, `extractURLParameter` |
| **IP** | `IPv4StringToNum`, `IPv4NumToString`, `isIPv4String` |
| **Geo** | `greatCircleDistance`, `geoDistance`, `geoToH3` |
| **해시** | `cityHash64`, `xxHash64`, `sipHash64`, `MD5`, `SHA256` |
| **조건부** | `sumIf`, `countIf`, `avgIf`, `minIf`, `maxIf` |

이 함수들은 구성과 관계없이 자동으로 chdb 엔진을 사용합니다.

***

## pandas 전용 함수

일부 함수는 pandas에서만 사용할 수 있습니다:

| 범주 | 함수 |
| - | - |
| **Apply** | 사용자 지정 람다 함수, 사용자 정의 함수 |
| **복잡한 피벗** | 사용자 지정 집계를 사용하는 피벗 테이블 |
| **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와 ClickHouse의 NULL
4. **Boolean**: 불리언 표현 방식이 다를 때
5. **DateTime**: 시간대 차이

### 예시

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

***

## Function 구성 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}
# engine 매개변수 사용(지원되는 경우)
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)
```