DataStore 클래스 참조

이 참조 문서에서는 DataStore API의 핵심 클래스를 설명합니다.

DataStore

데이터를 조작하는 데 사용하는 주요 DataFrame 유사 클래스입니다.

from chdb.datastore import DataStore

생성자

DataStore(data=None, columns=None, index=None, dtype=None, copy=None)

매개변수:

Parameter	유형	Description
`data`	dict/list/DataFrame/DataStore	입력 데이터
`columns`	list	컬럼 이름
`index`	Index	행 인덱스
`dtype`	dict	컬럼 데이터 타입
`copy`	bool	데이터 복사본

예시:

# From dictionary
ds = DataStore({'a': [1, 2, 3], 'b': ['x', 'y', 'z']})

# From pandas DataFrame
import pandas as pd

ds = DataStore(pd.DataFrame({'a': [1, 2, 3]}))

# Empty DataStore
ds = DataStore()

속성

속성	유형	설명
`columns`	Index	컬럼 이름
`dtypes`	Series	컬럼 데이터 타입
`shape`	tuple	(행 수, 컬럼 수)
`size`	int	전체 원소 수
`ndim`	int	차원 수 (2)
`empty`	bool	DataFrame이 비어 있는지 여부
`values`	ndarray	기반 데이터의 NumPy 배열
`index`	Index	행 인덱스
`T`	DataStore	전치
`axes`	list	축 목록

팩터리 메서드

Method	Description
`uri(uri)`	URI로부터 생성하는 공통 팩터리
`from_file(path, ...)`	파일에서 생성
`from_df(df)`	Pandas DataFrame에서 생성
`from_s3(url, ...)`	S3에서 생성
`from_gcs(url, ...)`	Google Cloud Storage에서 생성
`from_azure(url, ...)`	Azure Blob에서 생성
`from_mysql(...)`	MySQL에서 생성
`from_postgresql(...)`	PostgreSQL에서 생성
`from_clickhouse(...)`	ClickHouse에서 생성
`from_mongodb(...)`	MongoDB에서 생성
`from_sqlite(...)`	SQLite에서 생성
`from_iceberg(path)`	Iceberg 테이블에서 생성
`from_delta(path)`	Delta Lake에서 생성
`from_numbers(n)`	연속된 숫자로 생성
`from_random(rows, cols)`	무작위 데이터로 생성
`run_sql(query)`	SQL 쿼리에서 생성

자세한 내용은 팩터리 메서드를 참조하십시오.

쿼리 메서드

메서드	반환값	설명
`select(*cols)`	DataStore	컬럼 선택
`filter(condition)`	DataStore	행 필터링
`where(condition)`	DataStore	filter의 별칭
`sort(*cols, ascending=True)`	DataStore	행 정렬
`orderby(*cols)`	DataStore	sort의 별칭
`limit(n)`	DataStore	행 수 제한
`offset(n)`	DataStore	행 건너뛰기
`distinct(subset=None)`	DataStore	중복 제거
`groupby(*cols)`	LazyGroupBy	행 그룹화
`having(condition)`	DataStore	그룹 필터링
`join(right, ...)`	DataStore	DataStore 조인
`union(other, all=False)`	DataStore	DataStore 결합
`when(cond, val)`	CaseWhen	CASE WHEN

자세한 내용은 쿼리 작성을 참조하십시오.

Pandas 호환 메서드

209개 메서드의 전체 목록은 Pandas 호환성에서 확인하십시오.

인덱싱: head(), tail(), sample(), loc, iloc, at, iat, query(), isin(), where(), mask(), get(), xs(), pop()

집계: sum(), mean(), std(), var(), min(), max(), median(), count(), nunique(), quantile(), describe(), corr(), cov(), skew(), kurt()

조작: drop(), drop_duplicates(), dropna(), fillna(), replace(), rename(), assign(), astype(), copy()

정렬: sort_values(), sort_index(), nlargest(), nsmallest(), rank()

형태 변환: pivot(), pivot_table(), melt(), stack(), unstack(), transpose(), explode(), squeeze()

결합: merge(), join(), concat(), append(), combine(), update(), compare()

적용/변환: apply(), applymap(), map(), agg(), transform(), pipe(), groupby()

시계열: rolling(), expanding(), ewm(), shift(), diff(), pct_change(), resample()

I/O 메서드

메서드	설명
`to_csv(path, ...)`	CSV로 내보내기
`to_parquet(path, ...)`	Parquet로 내보내기
`to_json(path, ...)`	JSON으로 내보내기
`to_excel(path, ...)`	Excel로 내보내기
`to_df()`	Pandas DataFrame으로 변환
`to_pandas()`	to_df의 별칭
`to_arrow()`	Arrow Table로 변환
`to_dict(orient)`	딕셔너리로 변환
`to_records()`	레코드로 변환
`to_numpy()`	NumPy 배열로 변환
`to_sql()`	SQL 문자열 생성
`to_string()`	문자열 표현
`to_markdown()`	Markdown 테이블
`to_html()`	HTML 테이블

자세한 내용은 I/O 작업을 참조하십시오.

디버깅 메서드

메서드	설명
`explain(verbose=False)`	실행 계획 표시
`clear_cache()`	캐시된 결과 삭제

자세한 내용은 디버깅을 참조하십시오.

매직 메서드

메서드	설명
`__getitem__(key)`	`ds['col']`, `ds[['a', 'b']]`, `ds[condition]`
`__setitem__(key, value)`	`ds['col'] = value`
`__delitem__(key)`	`del ds['col']`
`__len__()`	`len(ds)`
`__iter__()`	`for col in ds`
`__contains__(key)`	`'col' in ds`
`__repr__()`	`repr(ds)`
`__str__()`	`str(ds)`
`__eq__(other)`	`ds == other`
`__ne__(other)`	`ds != other`
`__lt__(other)`	`ds < other`
`__le__(other)`	`ds <= other`
`__gt__(other)`	`ds > other`
`__ge__(other)`	`ds >= other`
`__add__(other)`	`ds + other`
`__sub__(other)`	`ds - other`
`__mul__(other)`	`ds * other`
`__truediv__(other)`	`ds / other`
`__floordiv__(other)`	`ds // other`
`__mod__(other)`	`ds % other`
`__pow__(other)`	`ds ** other`
`__and__(other)`	`ds & other`
`__or__(other)`	`ds	other`
`__invert__()`	`~ds`
`__neg__()`	`-ds`
`__pos__()`	`+ds`
`__abs__()`	`abs(ds)`

ColumnExpr

지연 평가에 사용되는 컬럼 표현식을 나타냅니다. 컬럼에 액세스하면 반환됩니다.

# ColumnExpr is returned automatically
col = ds['name']  # Returns ColumnExpr

속성

속성	유형	설명
`name`	str	컬럼 이름
`dtype`	dtype	데이터 타입

Accessors

Accessor	설명	메서드
`.str`	String 연산	56개 메서드
`.dt`	DateTime 연산	42개 이상의 메서드
`.arr`	배열 연산	37개 메서드
`.json`	JSON 파싱	13개 메서드
`.url`	URL 파싱	15개 메서드
`.ip`	IP 주소 연산	9개 메서드
`.geo`	Geo/거리 연산	14개 메서드

전체 문서는 Accessors를 참조하십시오.

산술 연산

ds['total'] = ds['price'] * ds['quantity']
ds['profit'] = ds['revenue'] - ds['cost']
ds['ratio'] = ds['a'] / ds['b']
ds['squared'] = ds['value'] ** 2
ds['remainder'] = ds['value'] % 10

비교 연산

ds[ds['age'] > 25]           # Greater than
ds[ds['age'] >= 25]          # Greater or equal
ds[ds['age'] < 25]           # Less than
ds[ds['age'] <= 25]          # Less or equal
ds[ds['name'] == 'Alice']    # Equal
ds[ds['name'] != 'Bob']      # Not equal

논리 연산

ds[(ds['age'] > 25) & (ds['city'] == 'NYC')]    # AND
ds[(ds['age'] > 25) | (ds['city'] == 'NYC')]    # OR
ds[~(ds['status'] == 'inactive')]               # NOT

메서드

메서드	설명
`as_(alias)`	별칭 설정
`cast(dtype)`	지정한 유형으로 CAST
`astype(dtype)`	cast의 별칭
`isnull()`	NULL 여부
`notnull()`	NULL이 아님
`isna()`	isnull의 별칭
`notna()`	notnull의 별칭
`isin(values)`	값 목록에 포함됨
`between(low, high)`	두 값 사이
`fillna(value)`	NULL 채우기
`replace(to_replace, value)`	값 대체
`clip(lower, upper)`	값 클리핑
`abs()`	절댓값
`round(decimals)`	값 반올림
`floor()`	내림
`ceil()`	올림
`apply(func)`	함수 적용
`map(mapper)`	값 매핑

집계 메서드

메서드	설명
`sum()`	합계
`mean()`	평균
`avg()`	mean의 별칭
`min()`	최솟값
`max()`	최댓값
`count()`	NULL이 아닌 값 개수
`nunique()`	고유값 개수
`std()`	표준 편차
`var()`	분산
`median()`	중앙값
`quantile(q)`	분위수
`first()`	첫 번째 값
`last()`	마지막 값
`any()`	하나라도 true
`all()`	모두 true

LazyGroupBy

집계 작업을 위한 그룹화된 DataStore입니다.

# LazyGroupBy is returned automatically
grouped = ds.groupby('category')  # Returns LazyGroupBy

메서드

메서드	반환값	설명
`agg(spec)`	DataStore	집계
`aggregate(spec)`	DataStore	`agg`의 별칭
`sum()`	DataStore	그룹별 합계
`mean()`	DataStore	그룹별 평균
`count()`	DataStore	그룹별 개수
`min()`	DataStore	그룹별 최솟값
`max()`	DataStore	그룹별 최댓값
`std()`	DataStore	그룹별 표준 편차
`var()`	DataStore	그룹별 분산
`median()`	DataStore	그룹별 중앙값
`nunique()`	DataStore	그룹별 고유값 개수
`first()`	DataStore	그룹별 첫 번째 값
`last()`	DataStore	그룹별 마지막 값
`nth(n)`	DataStore	그룹별 n번째 값
`head(n)`	DataStore	그룹별 처음 n개
`tail(n)`	DataStore	그룹별 마지막 n개
`apply(func)`	DataStore	그룹별 함수 적용
`transform(func)`	DataStore	그룹별 변환
`filter(func)`	DataStore	그룹 필터링

컬럼 선택

# Select column after groupby
grouped['amount'].sum()     # Returns DataStore
grouped[['a', 'b']].sum()   # Returns DataStore

집계 사양

# Single aggregation
grouped.agg({'amount': 'sum'})

# Multiple aggregations per column
grouped.agg({'amount': ['sum', 'mean', 'count']})

# Named aggregations
grouped.agg(
    total=('amount', 'sum'),
    average=('amount', 'mean'),
    count=('id', 'count')
)

LazySeries

지연 실행되는 Series(단일 컬럼)를 나타냅니다.

속성

속성	유형	설명
`name`	str	Series 이름
`dtype`	dtype	데이터 타입

메서드

ColumnExpr의 대부분의 메서드를 상속받습니다. 주요 메서드는 다음과 같습니다:

메서드	설명
`value_counts()`	값별 빈도
`unique()`	고유값
`nunique()`	고유값 수
`mode()`	최빈값
`to_list()`	리스트로 변환
`to_numpy()`	배열로 변환
`to_frame()`	DataStore로 변환

F (함수)

ClickHouse 함수의 네임스페이스입니다.

from chdb.datastore import F, Field

# Aggregations
F.sum(Field('amount'))
F.avg(Field('price'))
F.count(Field('id'))
F.quantile(Field('value'), 0.95)

# Conditional
F.sum_if(Field('amount'), Field('status') == 'completed')
F.count_if(Field('active'))

# Window
F.row_number().over(order_by='date')
F.lag('price', 1).over(partition_by='product', order_by='date')

자세한 내용은 집계를 참고하십시오.

필드

이름으로 컬럼을 참조합니다.

from chdb.datastore import Field

# Create field reference
amount = Field('amount')
price = Field('price')

# Use in expressions
F.sum(Field('amount'))
F.avg(Field('price'))

CaseWhen

CASE WHEN 표현식을 생성하는 빌더입니다.

# Create case-when expression
result = (ds
    .when(ds['score'] >= 90, 'A')
    .when(ds['score'] >= 80, 'B')
    .when(ds['score'] >= 70, 'C')
    .otherwise('F')
)

# Assign to column
ds['grade'] = result

윈도우

윈도우 함수에 사용할 윈도우 사양입니다.

from chdb.datastore import F

# Create window
window = F.window(
    partition_by='category',
    order_by='date',
    rows_between=(-7, 0)
)

# Use with aggregation
ds['rolling_avg'] = F.avg('price').over(window)