> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# DataStore 클래스 참조

> DataStore, ColumnExpr, LazyGroupBy, LazySeries 클래스에 대한 전체 API 참조

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

## DataStore

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

```python theme={null}
from chdb.datastore import DataStore
```

### 생성자

```python theme={null}
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 | 데이터 복사본 |

**예시:**

```python theme={null}
# 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 쿼리에서 생성 |

자세한 내용은 [팩터리 메서드](https://clickhouse.com/docs/ko/chdb/datastore/factory-methods.md)를 참조하십시오.

### 쿼리 메서드

| 메서드 | 반환값 | 설명 |
| - | - | - |
| `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 |

자세한 내용은 [쿼리 작성](https://clickhouse.com/docs/ko/chdb/datastore/query-building.md)을 참조하십시오.

### Pandas 호환 메서드

209개 메서드의 전체 목록은 [Pandas 호환성](https://clickhouse.com/docs/ko/chdb/datastore/pandas-compat.md)에서 확인하십시오.

**인덱싱:**
`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 작업](https://clickhouse.com/docs/ko/chdb/datastore/io.md)을 참조하십시오.

### 디버깅 메서드

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

자세한 내용은 [디버깅](https://clickhouse.com/docs/ko/chdb/debugging/index.md)을 참조하십시오.

### 매직 메서드

| 메서드 | 설명 | |
| - | - | - |
| `__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

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

```python theme={null}
# 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](https://clickhouse.com/docs/ko/chdb/datastore/accessors.md)를 참조하십시오.

### 산술 연산

```python theme={null}
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
```

### 비교 연산

```python theme={null}
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
```

### 논리 연산

```python theme={null}
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입니다.

```python theme={null}
# 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 | 그룹 필터링 |

### 컬럼 선택

```python theme={null}
# Select column after groupby
grouped['amount'].sum()     # Returns DataStore
grouped[['a', 'b']].sum()   # Returns DataStore
```

### 집계 사양

```python theme={null}
# 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 함수의 네임스페이스입니다.

```python theme={null}
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')
```

자세한 내용은 [집계](https://clickhouse.com/docs/ko/chdb/datastore/aggregation.md#f-namespace)를 참고하십시오.

### 필드

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

```python theme={null}
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 표현식을 생성하는 빌더입니다.

```python theme={null}
# 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
```

### 윈도우

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

```python theme={null}
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)
```