> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-home-button.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# DataStore: SQL 최적화가 적용된 Pandas 호환 API
> DataStore는 고성능 데이터 분석을 위한 SQL 최적화 기반의 Pandas 호환 API를 제공합니다
export const Image = ({img, alt, size}) => {
return
;
};
DataStore는 익숙한 Pandas DataFrame 인터페이스와 SQL 쿼리 최적화의 강점을 결합한 chDB의 Pandas 호환 API로, Pandas 스타일의 코드를 작성하면서도 ClickHouse의 성능을 활용할 수 있습니다.
## 주요 기능
* **Pandas 호환성**: 209개의 pandas DataFrame 메서드, 56개의 `.str` 메서드, 42개 이상의 `.dt` 메서드
* **SQL 최적화**: 연산이 자동으로 최적화된 SQL 쿼리로 컴파일됩니다
* **지연 평가**: 결과가 필요한 시점까지 연산이 지연됩니다
* **630개 이상의 API 메서드**: 데이터 조작을 위한 포괄적인 API 범위
* **ClickHouse 확장 기능**: pandas에서 제공하지 않는 추가 Accessor(`.arr`, `.json`, `.url`, `.ip`, `.geo`)
## 아키텍처
DataStore는 \*\*지연 평가(lazy evaluation)\*\*와 **이중 엔진 실행**을 사용합니다:
1. **지연 연산 체인**: 연산은 즉시 실행되지 않고 기록만 됩니다
2. **스마트 엔진 선택**: QueryPlanner가 각 세그먼트를 최적의 엔진으로 보냅니다(SQL은 chDB, 복잡한 연산은 Pandas)
3. **중간 결과 캐싱**: 빠른 반복 탐색을 위해 각 단계의 결과를 캐시합니다
자세한 내용은 [실행 모델](/ko/products/chdb/datastore/execution-model)을 참조하십시오.
## Pandas에서 한 줄로 마이그레이션
```python theme={null}
# 이전 (pandas)
import pandas as pd
df = pd.read_csv("data.csv")
result = df[df['age'] > 25].groupby('city')['salary'].mean()
# 이후 (DataStore) - import만 변경하면 됩니다!
from chdb import datastore as pd
df = pd.read_csv("data.csv")
result = df[df['age'] > 25].groupby('city')['salary'].mean()
```
기존 pandas 코드는 변경 없이 그대로 작동하지만, 이제 ClickHouse engine에서 실행됩니다.
## 성능 비교
DataStore는 pandas보다 전반적으로 성능이 크게 향상되며, 특히 집계와 복잡한 파이프라인에서 두드러집니다:
| Operation | Pandas | DataStore | Speedup |
| ---------------- | ------- | --------- | ---------- |
| GroupBy count | 347ms | 17ms | **19.93x** |
| Complex pipeline | 2,047ms | 380ms | **5.39x** |
| Filter+Sort+Head | 1,537ms | 350ms | **4.40x** |
| GroupBy agg | 406ms | 141ms | **2.88x** |
*1,000만 행을 기준으로 한 벤치마크입니다. 자세한 내용은 [벤치마크 스크립트](https://github.com/chdb-io/chdb/blob/main/refs/benchmark_datastore_vs_pandas.py)와 [성능 가이드](/ko/products/chdb/guides/pandas-performance)를 참조하십시오.*
## DataStore를 사용하는 경우
**다음과 같은 경우 DataStore를 사용하세요:**
* 대규모 데이터셋(수백만 개의 행)을 다룰 때
* 집계 및 groupby 연산을 수행할 때
* 파일, 데이터베이스 또는 클라우드 스토리지의 데이터를 쿼리할 때
* 복잡한 데이터 파이프라인을 구축할 때
* 더 나은 성능의 pandas API가 필요할 때
**다음과 같은 경우 raw SQL API를 사용하세요:**
* SQL을 직접 작성하는 방식을 선호할 때
* 쿼리 실행을 세밀하게 제어해야 할 때
* pandas API에서 제공되지 않는 ClickHouse 고유 기능을 사용해야 할 때
## 기능 비교
| 기능 | Pandas | Polars | DuckDB | DataStore |
| ------------------------ | ------ | ------ | ------ | ------------- |
| Pandas API 호환성 | - | 부분 지원 | 아니요 | **완전 지원** |
| 지연 평가 | 아니요 | 예 | 예 | **예** |
| SQL 쿼리 지원 | 아니요 | 예 | 예 | **예** |
| ClickHouse 함수 | 아니요 | 아니요 | 아니요 | **예** |
| String/DateTime Accessor | 예 | 예 | 아니요 | **예 + 추가 기능** |
| 배열/JSON/URL/IP/Geo | 아니요 | 부분 지원 | 아니요 | **예** |
| 파일 직접 쿼리 | 아니요 | 예 | 예 | **예** |
| 클라우드 스토리지 지원 | 아니요 | 제한적 | 예 | **예** |
## API 통계
| 범주 | 개수 | 지원 범위 |
| ---------------- | -------- | --------------------------- |
| DataFrame 메서드 | 209 | pandas 대비 100% |
| Series.str 접근자 | 56 | pandas 대비 100% |
| Series.dt 접근자 | 42+ | 100%+ (ClickHouse 추가 기능 포함) |
| Series.arr 접근자 | 37 | ClickHouse 전용 |
| Series.json 접근자 | 13 | ClickHouse 전용 |
| Series.url 접근자 | 15 | ClickHouse 전용 |
| Series.ip 접근자 | 9 | ClickHouse 전용 |
| Series.geo 접근자 | 14 | ClickHouse 전용 |
| **전체 API 메서드 수** | **630+** | - |
## 문서 탐색
### 시작하기
* [Quickstart](/ko/products/chdb/datastore/quickstart) - 설치 및 기본 사용법
* [Pandas 마이그레이션](/ko/products/chdb/guides/migration-from-pandas) - 단계별 마이그레이션 가이드
### API 참조
* [팩토리 메서드](/ko/products/chdb/datastore/factory-methods) - 다양한 소스에서 DataStore를 생성
* [쿼리 작성](/ko/products/chdb/datastore/query-building) - SQL 스타일 쿼리 작업
* [Pandas 호환성](/ko/products/chdb/datastore/pandas-compat) - pandas와 호환되는 209개 메서드
* [Accessor](/ko/products/chdb/datastore/accessors) - String, DateTime, 배열, JSON, URL, IP, Geo Accessor
* [집계](/ko/products/chdb/datastore/aggregation) - 집계 및 윈도우 함수
* [I/O 작업](/ko/products/chdb/datastore/io) - 데이터 읽기 및 쓰기
### 고급 주제
* [실행 모델](/ko/products/chdb/datastore/execution-model) - 지연 평가 및 캐싱
* [클래스 참조](/ko/products/chdb/datastore/class-reference) - 전체 API 참조
### 구성 및 디버깅
* [구성](/ko/products/chdb/configuration) - 모든 구성 옵션
* [성능 모드](/ko/products/chdb/configuration/performance-mode) - 최대 처리량을 위한 SQL 우선 모드
* [디버깅](/ko/products/chdb/debugging) - Explain, 프로파일링, 로깅
### Pandas 사용자 가이드
* [Pandas Cookbook](/ko/products/chdb/guides/pandas-cookbook) - 자주 쓰는 패턴
* [Key Differences](/ko/products/chdb/guides/pandas-differences) - Pandas와의 주요 차이점
* [성능 가이드](/ko/products/chdb/guides/pandas-performance) - 최적화 팁
* [SQL for Pandas Users](/ko/products/chdb/guides/pandas-to-sql) - Pandas 작업의 기반이 되는 SQL 이해하기
## 간단한 예시
```python theme={null}
from chdb import datastore as pd
# 다양한 소스에서 데이터 읽기
ds = pd.read_csv("sales.csv")
# 또는: ds = pd.DataStore.uri("s3://bucket/sales.parquet")
# 또는: ds = pd.DataStore.from_mysql("mysql://user:pass@host/db/table")
# 익숙한 pandas 연산 - 자동으로 SQL로 최적화됨
result = (ds
.filter(ds['amount'] > 1000) # WHERE amount > 1000
.groupby('region') # GROUP BY region
.agg({'amount': ['sum', 'mean']}) # SUM(amount), AVG(amount)
.sort_values('sum', ascending=False) # ORDER BY sum DESC
.head(10) # LIMIT 10
)
# 생성된 SQL 확인
print(result.to_sql())
# 실행 및 결과 가져오기
df = result.to_df() # pandas DataFrame 반환
```
## 다음 단계
* **DataStore가 처음이신가요?** [quickstart 가이드](/ko/products/chdb/datastore/quickstart)부터 시작하세요
* **pandas를 사용 중이신가요?** [마이그레이션 가이드](/ko/products/chdb/guides/migration-from-pandas)를 읽어보세요
* **더 알아보고 싶으신가요?** [API 참조](/ko/products/chdb/datastore/class-reference)를 살펴보세요