DataStore I/O 작업

DataStore를 사용한 데이터 읽기 및 쓰기 - 지원되는 모든 포맷 및 대상

DataStore는 다양한 파일 포맷과 데이터 소스의 데이터를 읽고 쓸 수 있습니다.

​

데이터 읽기

​

CSV 파일

read_csv(filepath_or_buffer, sep=',', header='infer', names=None, 
         usecols=None, dtype=None, nrows=None, skiprows=None,
         compression=None, encoding=None, **kwargs)

예시:

from chdb import datastore as pd

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

# With options
ds = pd.read_csv(
    "data.csv",
    sep=";",                    # 사용자 정의 구분자
    header=0,                   # 헤더 행 인덱스
    names=['a', 'b', 'c'],      # 사용자 정의 컬럼 이름
    usecols=['a', 'b'],         # 특정 컬럼만 읽기
    dtype={'a': 'Int64'},       # 데이터 타입 지정
    nrows=1000,                 # 처음 1000개 행만 읽기
    skiprows=1,                 # 첫 번째 행 건너뛰기
    compression='gzip',         # 압축 파일
    encoding='utf-8'            # 인코딩
)

# URL에서 읽기
ds = pd.read_csv("https://example.com/data.csv")

​

Parquet 파일

대규모 데이터셋에 권장되며, 압축 효율이 더 좋은 컬럼형 포맷입니다.

read_parquet(path, columns=None, **kwargs)

예시:

# 기본 Parquet 읽기
ds = pd.read_parquet("data.parquet")

# 특정 컬럼만 읽기 (효율적 - 필요한 데이터만 읽음)
ds = pd.read_parquet("data.parquet", columns=['col1', 'col2', 'col3'])

# S3에서 읽기
ds = pd.read_parquet("s3://bucket/data.parquet")

​

JSON 파일

read_json(path_or_buf, orient=None, lines=False, **kwargs)

예시:

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

# JSON Lines (줄바꿈 구분)
ds = pd.read_json("data.jsonl", lines=True)

# 특정 방향(orientation)을 지정한 JSON
ds = pd.read_json("data.json", orient='records')

​

Excel 파일

read_excel(io, sheet_name=0, header=0, names=None, **kwargs)

예시:

# 첫 번째 시트 읽기
ds = pd.read_excel("data.xlsx")

# 특정 시트 읽기
ds = pd.read_excel("data.xlsx", sheet_name="Sheet1")
ds = pd.read_excel("data.xlsx", sheet_name=2)  # 세 번째 시트

# 여러 시트 읽기 (dict 반환)
sheets = pd.read_excel("data.xlsx", sheet_name=['Sheet1', 'Sheet2'])

​

SQL 데이터베이스

read_sql(sql, con, **kwargs)

예시:

# SQL 쿼리에서 읽기
ds = pd.read_sql("SELECT * FROM users", connection)
ds = pd.read_sql("SELECT * FROM orders WHERE date > '2024-01-01'", connection)

​

기타 포맷

# Feather (Arrow)
ds = pd.read_feather("data.feather")

# ORC
ds = pd.read_orc("data.orc")

# Pickle
ds = pd.read_pickle("data.pkl")

# 고정 너비 형식
ds = pd.read_fwf("data.txt", widths=[10, 20, 15])

# HTML 테이블
ds = pd.read_html("https://example.com/table.html")[0]

---

​

데이터 쓰기

​

to_csv

CSV 포맷으로 내보냅니다.

to_csv(path_or_buf=None, sep=',', na_rep='', header=True, 
       index=True, mode='w', compression=None, **kwargs)

예시:

ds = pd.read_parquet("data.parquet")

# 기본 내보내기
ds.to_csv("output.csv")

# With options
ds.to_csv(
    "output.csv",
    sep=";",                    # 사용자 지정 구분자
    index=False,                # 인덱스 미포함
    header=True,                # 헤더 포함
    na_rep='NULL',              # NaN을 'NULL'로 표시
    compression='gzip'          # 출력 압축
)

# 문자열로 변환
csv_string = ds.to_csv()

​

to_parquet

Parquet 포맷으로 내보냅니다(대용량 데이터에 권장됨).

to_parquet(path, engine='pyarrow', compression='snappy', **kwargs)

예시:

# 기본 내보내기
ds.to_parquet("output.parquet")

# 압축 옵션 사용
ds.to_parquet("output.parquet", compression='gzip')
ds.to_parquet("output.parquet", compression='zstd')

# 파티션된 출력
ds.to_parquet(
    "output/",
    partition_cols=['year', 'month']
)

​

to_json

JSON 포맷으로 내보냅니다.

to_json(path_or_buf=None, orient='records', lines=False, **kwargs)

예시:

# 표준 JSON (레코드 배열)
ds.to_json("output.json", orient='records')

# JSON Lines (한 줄에 JSON 객체 하나)
ds.to_json("output.jsonl", lines=True)

# 다양한 orient 옵션
ds.to_json("output.json", orient='split')    # {columns, data, index}
ds.to_json("output.json", orient='records')  # [{col: val}, ...]
ds.to_json("output.json", orient='columns')  # {col: {idx: val}}

# 문자열로 변환
json_string = ds.to_json()

​

to_excel

Excel 포맷으로 내보냅니다.

to_excel(excel_writer, sheet_name='Sheet1', index=True, **kwargs)

예시:

# 단일 시트
ds.to_excel("output.xlsx")
ds.to_excel("output.xlsx", sheet_name="Data", index=False)

# 여러 시트
with pd.ExcelWriter("output.xlsx") as writer:
    ds1.to_excel(writer, sheet_name="Sales")
    ds2.to_excel(writer, sheet_name="Inventory")

​

to_sql

SQL 데이터베이스로 내보내거나 SQL 문자열을 만듭니다.

to_sql(name=None, con=None, schema=None, if_exists='fail', **kwargs)

예시:

# SQL 쿼리 생성 (실행 없음)
sql = ds.to_sql()
print(sql)
# SELECT ...
# FROM ...
# WHERE ...

# 데이터베이스에 쓰기
ds.to_sql("table_name", connection, if_exists='replace')

​

기타 내보내기 방법

# pandas DataFrame으로 변환
df = ds.to_df()
df = ds.to_pandas()

# Arrow Table로 변환
table = ds.to_arrow()

# NumPy 배열로 변환
arr = ds.to_numpy()

# 딕셔너리로 변환
d = ds.to_dict()
d = ds.to_dict(orient='records')  # 딕셔너리의 리스트
d = ds.to_dict(orient='list')     # 리스트의 딕셔너리

# 레코드로 변환 (튜플의 리스트)
records = ds.to_records()

# 문자열로 변환
s = ds.to_string()
s = ds.to_string(max_rows=100)

# Markdown으로 변환
md = ds.to_markdown()

# HTML로 변환
html = ds.to_html()

# LaTeX로 변환
latex = ds.to_latex()

# 클립보드로 복사
ds.to_clipboard()

# pickle로 저장
ds.to_pickle("output.pkl")

# feather로 저장
ds.to_feather("output.feather")

---

​

파일 포맷 비교

포맷	읽기 속도	쓰기 속도	파일 크기	스키마	가장 적합한 용도
Parquet	빠름	빠름	작음	있음	대규모 데이터셋, 분석
CSV	보통	빠름	큼	없음	호환성, 단순한 데이터
JSON	느림	보통	큼	부분 지원	API, 중첩 데이터
Excel	느림	느림	보통	부분 지원	비기술 사용자와 공유
Feather	매우 빠름	매우 빠름	보통	있음	프로세스 간 데이터 교환, pandas

​

권장 사항

1. 분석 워크로드용: Parquet를 사용합니다

   • 컬럼형 포맷이므로 필요한 컬럼만 읽을 수 있습니다
   • 압축 효율이 뛰어납니다
   • 데이터 타입이 유지됩니다

2. 데이터 교환용: CSV 또는 JSON을 사용합니다

   • 범용 호환성이 높습니다
   • 사람이 읽기 쉽습니다

3. pandas 상호 운용용: Feather 또는 Arrow를 사용합니다

   • 직렬화가 가장 빠릅니다
   • 타입이 유지됩니다

---

​

압축 지원

​

압축 파일 읽기

# 확장자에서 자동 감지
ds = pd.read_csv("data.csv.gz")
ds = pd.read_csv("data.csv.bz2")
ds = pd.read_csv("data.csv.xz")
ds = pd.read_csv("data.csv.zst")

# 명시적 압축
ds = pd.read_csv("data.csv", compression='gzip')

​

압축 파일 쓰기

# 압축을 사용하는 CSV
ds.to_csv("output.csv.gz", compression='gzip')
ds.to_csv("output.csv.bz2", compression='bz2')

# Parquet (항상 압축됨)
ds.to_parquet("output.parquet", compression='snappy')  # 기본값
ds.to_parquet("output.parquet", compression='gzip')
ds.to_parquet("output.parquet", compression='zstd')    # 최고 압축률
ds.to_parquet("output.parquet", compression='lz4')     # 가장 빠름

​

압축 옵션

압축	속도	압축률	사용 사례
snappy	매우 빠름	낮음	Parquet 기본값
lz4	매우 빠름	낮음	속도 우선
gzip	보통	높음	호환성
zstd	빠름	매우 높음	가장 뛰어난 균형
bz2	느림	매우 높음	최대 압축

---

​

스트리밍 I/O

메모리에 모두 올릴 수 없을 만큼 큰 파일의 경우:

​

청크 단위 읽기

# 청크 단위로 읽기
for chunk in pd.read_csv("large.csv", chunksize=100000):
    # 각 청크 처리
    process(chunk)

# 이터레이터 사용
reader = pd.read_csv("large.csv", iterator=True)
chunk = reader.get_chunk(10000)

​

ClickHouse Streaming 사용

from chdb.datastore import DataStore

# 파일에서 스트리밍 - 전체를 메모리에 로드하지 않음
ds = DataStore.from_file("huge.parquet")

# 연산은 지연 실행 방식 - 필요한 것만 계산
result = ds.filter(ds['amount'] > 1000).head(100)

---

​

원격 데이터 소스

​

HTTP/HTTPS

# URL에서 읽기
ds = pd.read_csv("https://example.com/data.csv")
ds = pd.read_parquet("https://example.com/data.parquet")

​

S3

from chdb.datastore import DataStore

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

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

​

GCS, Azure, HDFS

클라우드 스토리지 옵션은 팩토리 메서드 문서를 참조하십시오.

---

​

권장 사항

​

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

# 성능 향상을 위해 CSV를 Parquet으로 변환
ds = pd.read_csv("large.csv")
ds.to_parquet("large.parquet")

# 이후 읽기 속도가 훨씬 빠름
ds = pd.read_parquet("large.parquet")

​

2. 필요한 컬럼만 선택

# 효율적 - col1과 col2만 읽기
ds = pd.read_parquet("data.parquet", columns=['col1', 'col2'])

# 비효율적 - 모든 컬럼을 읽은 후 필터링
ds = pd.read_parquet("data.parquet")[['col1', 'col2']]

​

3. 압축 사용하기

# 파일 크기가 작아지고, I/O가 줄어들어 대개 더 빠릅니다
ds.to_parquet("output.parquet", compression='zstd')

​

4. 배치 쓰기

# 루프 대신 한 번에 쓰기
result = process_all_data(ds)
result.to_parquet("output.parquet")

# 이렇게 하지 마세요 (비효율적)
for chunk in chunks:
    chunk.to_parquet(f"output_{i}.parquet")