> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 실행 엔진 구성

> DataStore 실행 엔진 구성 - auto, chdb 또는 pandas

DataStore는 다양한 백엔드를 사용해 연산을 실행할 수 있습니다. 이 가이드에서는 실행 엔진 선택을 구성하고 최적화하는 방법을 설명합니다.

<div id="engines">
  ## 사용 가능한 엔진
</div>

| 엔진       | 설명                           | 가장 적합한 용도             |
| -------- | ---------------------------- | --------------------- |
| `auto`   | 작업별로 가장 적합한 엔진을 자동으로 선택합니다   | 일반 용도(기본값)            |
| `chdb`   | 모든 작업에 ClickHouse SQL을 사용합니다 | 대규모 데이터, 집계           |
| `pandas` | 모든 작업에 pandas를 사용합니다         | 호환성 테스트, pandas 전용 기능 |

<div id="setting">
  ## 엔진 설정
</div>

<div id="global">
  ### 전역 구성
</div>

```python theme={null}
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 강제 사용
```

<div id="checking">
  ### 현재 엔진 확인
</div>

```python theme={null}
print(config.execution_engine)  # 'auto', 'chdb', 또는 'pandas'
```

***

<div id="auto-mode">
  ## 자동 모드
</div>

`auto` 모드(기본값)에서는 DataStore가 각 연산에 가장 적합한 엔진을 선택합니다:

<div id="auto-chdb">
  ### chDB에서 실행되는 연산
</div>

* SQL 호환 필터링 (`filter()`, `where()`)
* 컬럼 선택 (`select()`)
* 정렬 (`sort()`, `orderby()`)
* 그룹화 및 집계 (`groupby().agg()`)
* 조인 (`join()`, `merge()`)
* 중복 제거 (`distinct()`, `drop_duplicates()`)
* 개수 제한 (`limit()`, `head()`, `tail()`)

<div id="auto-pandas">
  ### pandas에서 실행하는 작업
</div>

* 사용자 정의 apply 함수 (`apply(custom_func)`)
* 사용자 정의 집계를 사용하는 복잡한 피벗 테이블
* SQL로 표현할 수 없는 작업
* 입력이 이미 pandas DataFrame인 경우

<div id="auto-example">
  ### 예시
</div>

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

***

<div id="chdb-mode">
  ## chDB 모드
</div>

모든 작업을 ClickHouse SQL을 통해 수행하도록 강제합니다:

```python theme={null}
config.use_chdb()
```

<div id="chdb-when">
  ### 사용해야 하는 경우
</div>

* 대규모 데이터셋(수백만 개의 행) 처리
* 집계 중심 워크로드
* SQL 최적화를 최대한 활용하려는 경우
* 모든 작업에서 일관된 동작이 필요한 경우

<div id="chdb-performance">
  ### 성능 특성
</div>

| 작업 유형      | 성능                 |
| ---------- | ------------------ |
| GroupBy/집계 | 매우 우수함 (최대 20배 빠름) |
| 복잡한 필터링    | 매우 우수함             |
| 정렬         | 매우 우수              |
| 단순한 단일 필터  | 양호함 (약간의 오버헤드)     |

<div id="chdb-limitations">
  ### 제한 사항
</div>

* 사용자 정의 Python 함수는 지원되지 않을 수 있습니다.
* 일부 pandas 전용 기능은 변환이 필요할 수 있습니다.

***

<div id="pandas-mode">
  ## pandas 모드
</div>

모든 작업을 pandas를 통해 수행하도록 강제합니다:

```python theme={null}
config.use_pandas()
```

<div id="chdb-when">
  ### 사용해야 하는 경우
</div>

* pandas와의 호환성 테스트
* pandas 전용 기능 사용
* pandas 관련 문제 디버깅
* 데이터가 이미 pandas 포맷인 경우

<div id="chdb-performance">
  ### 성능 특성
</div>

| 작업 유형     | 성능         |
| --------- | ---------- |
| 단순 작업     | 양호         |
| 사용자 정의 함수 | 매우 우수      |
| 복잡한 집계    | chDB보다 느림  |
| 대규모 데이터셋  | 메모리 사용량이 큼 |

***

<div id="cross-datastore">
  ## Cross-DataStore 엔진
</div>

서로 다른 DataStore의 컬럼을 결합하는 작업에 사용할 엔진을 구성합니다:

```python theme={null}
# cross-DataStore 엔진 설정
config.set_cross_datastore_engine('auto')
config.set_cross_datastore_engine('chdb')
config.set_cross_datastore_engine('pandas')
```

<div id="auto-example">
  ### 예시
</div>

```python theme={null}
ds1 = pd.read_csv("sales.csv")
ds2 = pd.read_csv("inventory.csv")

# 이 작업은 두 개의 DataStore를 포함합니다
result = ds1.join(ds2, on='product_id')
# cross_datastore_engine 설정을 사용합니다
```

***

<div id="selection-logic">
  ## 엔진 선택 로직
</div>

<div id="decision-tree">
  ### 자동 모드 의사결정 트리
</div>

```text theme={null}
작업 요청
    │
    ├─ SQL로 표현 가능?
    │      │
    │      ├─ 예 → chDB 사용
    │      │
    │      └─ 아니오 → pandas 사용
    │
    └─ Cross-DataStore 작업?
           │
           └─ cross_datastore_engine 설정 사용
```

<div id="function-override">
  ### 함수 수준 재정의
</div>

일부 함수는 사용할 엔진을 명시적으로 지정할 수 있습니다:

```python theme={null}
from chdb.datastore.config import function_config

# 특정 함수가 특정 엔진을 사용하도록 강제 지정
function_config.use_chdb('length', 'substring')
function_config.use_pandas('upper', 'lower')
```

자세한 내용은 [Function Config](/ko/products/chdb/configuration/function-config)를 참고하십시오.

***

<div id="performance-comparison">
  ## 성능 비교
</div>

1,000만 행 기준 벤치마크 결과:

| 연산               | pandas (ms) | chdb (ms) | 속도 향상  |
| ---------------- | ----------- | --------- | ------ |
| 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` 모드를 사용하세요

***

<div id="best-practices">
  ## 권장 사항
</div>

<div id="start-with-auto-mode">
  ### 1. 자동 모드부터 시작하세요
</div>

```python theme={null}
config.use_auto()  # DataStore가 자동으로 결정
```

<div id="profile-before-forcing">
  ### 2. 강제 적용 전 프로파일링
</div>

```python theme={null}
config.enable_profiling()
# 워크로드를 실행하세요
# 프로파일러 보고서를 확인하여 시간이 소요되는 부분을 파악하세요
```

<div id="force-engine-for-specific-workloads">
  ### 3. 특정 워크로드에 엔진 강제 지정
</div>

```python theme={null}
# 대용량 집계 워크로드의 경우
config.use_chdb()

# pandas 호환성 테스트의 경우
config.use_pandas()
```

<div id="use-explain-to-understand-execution">
  ### 4. `explain()`을 사용해 실행 과정 이해하기
</div>

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

# 생성될 SQL 확인
query.explain()
```

***

<div id="troubleshooting">
  ## 문제 해결
</div>

<div id="issue-operation-slower">
  ### 문제: 작업 속도가 예상보다 느림
</div>

```python theme={null}
# 현재 엔진 확인
print(config.execution_engine)

# 디버그를 활성화하여 상황 확인
config.enable_debug()

# 특정 엔진 강제 지정 시도
config.use_chdb()  # or config.use_pandas()
```

<div id="issue-unsupported-operation">
  ### 문제: chdb 모드에서 지원되지 않는 작업
</div>

```python theme={null}
# 일부 pandas 연산은 SQL에서 지원되지 않습니다
# 해결 방법: auto 모드 사용
config.use_auto()

# 또는 먼저 pandas로 명시적으로 변환
df = ds.to_df()
result = df.some_pandas_specific_operation()
```

<div id="issue-memory-issues">
  ### 문제: 대용량 데이터 처리 시 메모리 문제
</div>

```python theme={null}
# 모든 데이터를 메모리에 로드하지 않도록 chdb 엔진을 사용합니다
config.use_chdb()

# 데이터 크기를 줄이기 위해 초기에 필터링합니다
result = ds.filter(ds['date'] >= '2024-01-01').to_df()

# 대용량 데이터셋의 최대 처리량을 위해 성능 모드를 사용합니다
# 성능 모드는 병렬 Parquet 읽기와 단일 SQL 집계를 활성화합니다
config.use_performance_mode()
```

<Tip>
  **성능 모드**

  집계 부하가 큰 워크로드를 실행 중이며 pandas 출력과의 완전한 호환성(행 순서, MultiIndex, dtype 보정)이 필요하지 않다면 [성능 모드](/ko/products/chdb/configuration/performance-mode) 사용을 고려하십시오. 이 모드는 엔진을 자동으로 `chdb`로 설정하고 pandas 호환성으로 인한 모든 오버헤드를 제거합니다.
</Tip>