DataStore 빠른 시작

DataStore 시작하기 - 설치, pandas에서 한 줄로 마이그레이션, 기본 사용법

몇 분이면 DataStore를 시작할 수 있습니다. 이 가이드에서는 설치, pandas에서 마이그레이션하는 방법, 그리고 기본 사용법을 설명합니다.

​

설치

pip를 사용하여 chDB를 설치합니다:

pip install "chdb>=4.0"

선택적 종속성의 경우:

# pandas DataFrame 지원을 위한 패키지
pip install "chdb[pandas]>=4.0"

# PyArrow 지원을 위한 패키지
pip install "chdb[arrow]>=4.0"

# 모든 선택적 의존성 패키지
pip install "chdb[all]>=4.0"

​

설치 확인

import chdb
print(chdb.__version__)  # 4.x.x 이상이 출력되어야 합니다

from chdb import datastore as pd
print("DataStore ready!")

​

Pandas에서 한 줄로 마이그레이션

DataStore를 가장 간단하게 사용하기 시작하는 방법은 import 문을 바꾸는 것입니다:

# 변경 전 (pandas)
import pandas as pd

# 변경 후 (DataStore)
from chdb import datastore as pd

이제 끝입니다! 기존 pandas 코드는 이제 DataStore를 사용하게 되며, SQL 최적화의 이점도 누릴 수 있습니다.

​

마이그레이션 예시

from pathlib import Path
Path("employees.csv").write_text("""\
name,age,city,salary,department,dept_id,status,email
Alice,28,NYC,75000,Engineering,1,active,[e-mail]
Bob,35,LA,85000,Engineering,1,active,[e-mail]
Charlie,52,NYC,95000,Product,2,active,[e-mail]
Diana,32,SF,70000,Design,3,active,[e-mail]
Eve,23,LA,48000,Product,2,inactive,[e-mail]
""")

# 기존 pandas 코드
import pandas as pd

df = pd.read_csv("employees.csv")
result = (df[df['salary'] > 50000]
          .groupby('department')['salary']
          .agg(['mean', 'count'])
          .sort_values('mean', ascending=False))
print(result)

# DataStore 버전 - import만 변경하면 됩니다!
from chdb import datastore as pd

df = pd.read_csv("employees.csv")
result = (df[df['salary'] > 50000]
          .groupby('department')['salary']
          .agg(['mean', 'count'])
          .sort_values('mean', ascending=False))
print(result)  # 동일한 결과, 더 빠른 실행!

​

기본 사용법

​

DataStore 생성하기

from chdb import datastore as pd

# 딕셔너리에서 생성
ds = pd.DataFrame({
    'name': ['Alice', 'Bob', 'Charlie'],
    'age': [25, 30, 35],
    'city': ['NYC', 'LA', 'NYC']
})

# pandas DataFrame에서 생성
import pandas
pdf = pandas.DataFrame({'a': [1, 2, 3], 'b': [4, 5, 6]})
ds = pd.DataFrame(pdf)

# CSV 파일에서 생성
ds = pd.read_csv("data.csv")

# Parquet 파일에서 생성 (대용량 데이터셋에 권장)
ds = pd.read_parquet("data.parquet")

​

데이터 필터링

from chdb import datastore as pd

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

# 단일 조건
senior = ds[ds['age'] > 30]

# 여러 조건 사용(AND)
senior_nyc = ds[(ds['age'] > 30) & (ds['city'] == 'NYC')]

# 여러 조건 사용(OR)
young_or_senior = ds[(ds['age'] < 25) | (ds['age'] > 50)]

# filter 메서드 사용(SQL 스타일)
result = ds.filter(ds['salary'] > 50000)

​

컬럼 선택

# Pandas 스타일
subset = ds[['name', 'age']]

# SQL 스타일
subset = ds.select('name', 'age')

​

정렬

# Pandas 스타일
sorted_ds = ds.sort_values('salary', ascending=False)

# SQL 스타일
sorted_ds = ds.sort('salary', ascending=False)

​

그룹화와 집계

from pathlib import Path
Path("sales.csv").write_text("""\
region,product,category,amount,quantity,price,date,order_id
East,Widget,Electronics,5200,10,120,2024-01-15,1001
West,Gadget,Electronics,800,5,160,2024-02-20,1002
East,Gizmo,Home,6500,3,100,2024-03-10,1003
North,Widget,Electronics,4500,6,150,2024-06-18,1004
West,Gadget,Electronics,2000,8,250,2024-09-14,1005
""")

from chdb import datastore as pd

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

# 단일 컬럼으로 그룹화
by_region = ds.groupby('region')['amount'].sum()

# 여러 컬럼으로 그룹화
by_region_product = ds.groupby(['region', 'product']).agg({
    'amount': ['sum', 'mean'],
    'quantity': 'sum'
})

# 여러 집계 연산
summary = ds.groupby('category').agg({
    'price': ['min', 'max', 'mean'],
    'quantity': 'sum'
})

​

DataStore 조인하기

from pathlib import Path
Path("departments.csv").write_text("""\
dept_id,department_name
1,Engineering
2,Product
3,Design
""")

from chdb import datastore as pd

employees = pd.read_csv("employees.csv")
departments = pd.read_csv("departments.csv")

# 내부 조인(Inner join)
result = employees.join(departments, on='dept_id', how='inner')

# 왼쪽 조인(Left join)
result = employees.join(departments, on='dept_id', how='left')

# 머지 사용 (pandas 스타일)
result = pd.merge(employees, departments, on='dept_id')

​

결과 확인하기

DataStore는 지연 평가를 사용하므로 결과가 실제로 필요해질 때까지 작업이 실행되지 않습니다.

​

실행 시작하기

# 자동 트리거
print(ds)           # 결과 표시
len(ds)             # 행 수 조회
ds.columns          # 속성 접근
list(ds)            # 리스트로 변환

# 명시적 변환
df = ds.to_df()     # pandas DataFrame으로 변환
df = ds.to_pandas() # to_df()와 동일

​

생성된 SQL 확인하기

Query

# DataStore가 실행할 SQL 확인
query = ds.filter(ds['age'] > 25).groupby('city').agg({'salary': 'mean'})
print(query.to_sql())

Response

SELECT city, AVG(salary) AS mean
FROM file('data.csv', 'CSVWithNames')
WHERE age > 25
GROUP BY city

​

다양한 데이터 소스 사용하기

​

로컬 파일

from chdb import datastore as pd

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

# Parquet (최고 성능)
ds = pd.read_parquet("data.parquet")

# JSON
ds = pd.read_json("data.json")

​

클라우드 저장소

from chdb.datastore import DataStore

# S3 (익명)
ds = DataStore.uri("s3://bucket/data.parquet?nosign=true")

# S3 (자격 증명 사용)
ds = DataStore.from_s3(
    "s3://bucket/data.parquet",
    access_key_id="KEY",
    secret_access_key="SECRET"
)

# HTTP/HTTPS
ds = DataStore.uri("https://example.com/data.csv")

​

데이터베이스

from chdb.datastore import DataStore

# MySQL
ds = DataStore.from_mysql(
    host="localhost",
    database="mydb",
    table="users",
    user="root",
    password="pass"
)

# PostgreSQL
ds = DataStore.from_postgresql(
    host="localhost",
    database="mydb",
    table="users",
    user="postgres",
    password="pass"
)

# URI 사용
ds = DataStore.uri("mysql://user:pass@localhost:3306/mydb/users")

​

문자열 및 DateTime 연산

​

문자열 연산

# 모든 pandas .str 메서드가 작동합니다
ds['name_upper'] = ds['name'].str.upper()
ds['name_len'] = ds['name'].str.len()
ds['has_a'] = ds['name'].str.contains('a')

​

DateTime 연산

# 모든 pandas .dt 메서드가 작동합니다
ds['year'] = ds['date'].dt.year
ds['month'] = ds['date'].dt.month
ds['day_of_week'] = ds['date'].dt.dayofweek

​

ClickHouse 확장 기능

# URL 파싱 (pandas에서는 사용 불가!)
ds['domain'] = ds['url'].url.domain()

# JSON 추출
ds['user_name'] = ds['json_data'].json.get_string('name')

# IP 주소 연산
ds['is_ipv4'] = ds['ip_addr'].ip.is_ipv4_string()

​

권장 사항

​

1. 대용량 파일에는 Parquet를 사용하세요

# CSV - 느림, 전체 파일 읽기
ds = pd.read_csv("large_data.csv")

# Parquet - 빠름, 컬럼형 포맷, 필요한 컬럼만 읽기
ds = pd.read_parquet("large_data.parquet")

​

2. 초기 단계에서 필터링하기

# 좋음 - 먼저 필터링한 다음 집계
result = (ds
    .filter(ds['date'] >= '2024-01-01')
    .groupby('category')['amount'].sum()
)

# 덜 최적임 - 먼저 집계
result = ds.groupby('category')['amount'].sum()

​

3. 필요한 컬럼만 선택

# 좋음 - 특정 컬럼만 선택
result = ds.select('name', 'age', 'city').filter(ds['age'] > 25)

# 비효율적 - 모든 컬럼 사용
result = ds.filter(ds['age'] > 25)

​

4. 복잡한 작업에는 SQL 사용

# 복잡한 쿼리는 SQL을 직접 사용하세요
ds = DataStore()
result = ds.sql("""
    SELECT category, 
           SUM(amount) as total,
           COUNT(*) as count,
           AVG(amount) as avg
    FROM file('sales.csv', 'CSVWithNames')
    WHERE date >= '2024-01-01'
    GROUP BY category
    HAVING total > 10000
    ORDER BY total DESC
    LIMIT 10
""")

​

다음 단계

• DataStore를 생성하는 모든 팩토리 메서드를 알아보세요
• SQL 스타일 작업을 위한 쿼리 작성을 살펴보세요
• 문자열, datetime 등과 관련된 Accessor를 확인해 보세요
• 최적화 팁은 성능 가이드를 참고하세요