Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

DataStore I/O 작업

View as MarkdownEdit this pageReport an issueSet up docs MCP

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

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

# With options
ds = pd.read_csv(
    "data.csv",
    sep=";",                    # Custom delimiter
    header=0,                   # Header row index
    names=['a', 'b', 'c'],      # Custom column names
    usecols=['a', 'b'],         # Only read specific columns
    dtype={'a': 'Int64'},       # Specify dtypes
    nrows=1000,                 # Read only first 1000 rows
    skiprows=1,                 # Skip first row
    compression='gzip',         # Compressed file
    encoding='utf-8'            # Encoding
)

# From URL
ds = pd.read_csv("https://example.com/data.csv")

Parquet 파일

대규모 데이터셋에 권장됩니다 - 압축 효율이 더 높은 컬럼형 포맷입니다.

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

예시:

# Basic Parquet read
ds = pd.read_parquet("data.parquet")

# Read specific columns only (efficient - only reads needed data)
ds = pd.read_parquet("data.parquet", columns=['col1', 'col2', 'col3'])

# From S3
ds = pd.read_parquet("s3://bucket/data.parquet")

JSON 파일

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

예시:

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

# JSON Lines (newline-delimited)
ds = pd.read_json("data.jsonl", lines=True)

# JSON with specific orientation
ds = pd.read_json("data.json", orient='records')

Excel 파일

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

예시:

# Read first sheet
ds = pd.read_excel("data.xlsx")

# Read specific sheet
ds = pd.read_excel("data.xlsx", sheet_name="Sheet1")
ds = pd.read_excel("data.xlsx", sheet_name=2)  # Third sheet

# Read multiple sheets (returns dict)
sheets = pd.read_excel("data.xlsx", sheet_name=['Sheet1', 'Sheet2'])

SQL 데이터베이스

read_sql(sql, con, **kwargs)

예시:

# Read from SQL query
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")

# Fixed-width formatted
ds = pd.read_fwf("data.txt", widths=[10, 20, 15])

# HTML tables
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")

# Basic export
ds.to_csv("output.csv")

# With options
ds.to_csv(
    "output.csv",
    sep=";",                    # Custom delimiter
    index=False,                # Don't include index
    header=True,                # Include header
    na_rep='NULL',              # Represent NaN as 'NULL'
    compression='gzip'          # Compress output
)

# To string
csv_string = ds.to_csv()

to_parquet

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

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

예시:

# Basic export
ds.to_parquet("output.parquet")

# With compression options
ds.to_parquet("output.parquet", compression='gzip')
ds.to_parquet("output.parquet", compression='zstd')

# Partitioned output
ds.to_parquet(
    "output/",
    partition_cols=['year', 'month']
)

to_json

JSON 포맷으로 내보냅니다.

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

예시:

# Standard JSON (array of records)
ds.to_json("output.json", orient='records')

# JSON Lines (one JSON object per line)
ds.to_json("output.jsonl", lines=True)

# Different orientations
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}}

# To string
json_string = ds.to_json()

to_excel

Excel 포맷으로 내보냅니다.

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

예시:

# Single sheet
ds.to_excel("output.xlsx")
ds.to_excel("output.xlsx", sheet_name="Data", index=False)

# Multiple sheets
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)

예시:

# Generate SQL query (no execution)
sql = ds.to_sql()
print(sql)
# SELECT ...
# FROM ...
# WHERE ...

# Write to database
ds.to_sql("table_name", connection, if_exists='replace')

기타 내보내기 방법

# To pandas DataFrame
df = ds.to_df()
df = ds.to_pandas()

# To Arrow Table
table = ds.to_arrow()

# To NumPy array
arr = ds.to_numpy()

# To dictionary
d = ds.to_dict()
d = ds.to_dict(orient='records')  # List of dicts
d = ds.to_dict(orient='list')     # Dict of lists

# To records (list of tuples)
records = ds.to_records()

# To string
s = ds.to_string()
s = ds.to_string(max_rows=100)

# To Markdown
md = ds.to_markdown()

# To HTML
html = ds.to_html()

# To LaTeX
latex = ds.to_latex()

# To clipboard
ds.to_clipboard()

# To pickle
ds.to_pickle("output.pkl")

# To feather
ds.to_feather("output.feather")

파일 포맷 비교

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

권장 사항

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

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

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

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

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

    • 가장 빠른 직렬화
    • 타입 보존

압축 지원

압축 파일 읽기

# Auto-detect from extension
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")

# Explicit compression
ds = pd.read_csv("data.csv", compression='gzip')

압축 파일 쓰기

# CSV with compression
ds.to_csv("output.csv.gz", compression='gzip')
ds.to_csv("output.csv.bz2", compression='bz2')

# Parquet (always compressed)
ds.to_parquet("output.parquet", compression='snappy')  # Default
ds.to_parquet("output.parquet", compression='gzip')
ds.to_parquet("output.parquet", compression='zstd')    # Best ratio
ds.to_parquet("output.parquet", compression='lz4')     # Fastest

압축 옵션

압축 속도 압축률 사용 사례
snappy 매우 빠름 낮음 Parquet의 기본값
lz4 매우 빠름 낮음 속도 우선
gzip 중간 높음 호환성
zstd 빠름 매우 높음 가장 균형이 좋음
bz2 느림 매우 높음 최대 압축

스트리밍 I/O

메모리에 들어가지 않을 만큼 매우 큰 파일의 경우:

청크 단위로 읽기

# Read in chunks
for chunk in pd.read_csv("large.csv", chunksize=100000):
    # Process each chunk
    process(chunk)

# Using iterator
reader = pd.read_csv("large.csv", iterator=True)
chunk = reader.get_chunk(10000)

ClickHouse Streaming 사용

from chdb.datastore import DataStore

# Stream from file without loading all into memory
ds = DataStore.from_file("huge.parquet")

# Operations are lazy - only computes what's needed
result = ds.filter(ds['amount'] > 1000).head(100)

원격 데이터 원본

HTTP/HTTPS

# Read from 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

# Anonymous access
ds = DataStore.uri("s3://bucket/data.parquet?nosign=true")

# With credentials
ds = DataStore.from_s3(
    "s3://bucket/data.parquet",
    access_key_id="KEY",
    secret_access_key="SECRET"
)

GCS, Azure, HDFS

클라우드 스토리지 옵션은 팩토리 메서드에서 확인하십시오.

권장 사항

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

# Convert CSV to Parquet for better performance
ds = pd.read_csv("large.csv")
ds.to_parquet("large.parquet")

# Future reads are much faster
ds = pd.read_parquet("large.parquet")

2. 필요한 컬럼만 선택하기

# Efficient - only reads col1 and col2
ds = pd.read_parquet("data.parquet", columns=['col1', 'col2'])

# Inefficient - reads all columns then filters
ds = pd.read_parquet("data.parquet")[['col1', 'col2']]

3. 압축 사용하기

# Smaller file size, usually faster due to less I/O
ds.to_parquet("output.parquet", compression='zstd')

4. 배치 쓰기

# Write once, not in a loop
result = process_all_data(ds)
result.to_parquet("output.parquet")

# NOT this (inefficient)
for chunk in chunks:
    chunk.to_parquet(f"output_{i}.parquet")
Navigation