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

> Полный справочник API для классов DataStore, ColumnExpr, LazyGroupBy и LazySeries

В этом справочнике описаны основные классы API DataStore.

## DataStore

Основной класс для работы с данными, аналогичный DataFrame.

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

### Конструктор

```python theme={null}
DataStore(data=None, columns=None, index=None, dtype=None, copy=None)
```

**Параметры:**

| Параметр | Тип | Описание |
| - | - | - |
| `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 | Список осей |

### Фабричные методы

| Метод | Описание |
| - | - |
| `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/ru/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 с помощью JOIN |
| `union(other, all=False)` | DataStore | Объединить DataStore |
| `when(cond, val)` | CaseWhen | CASE WHEN |

Подробнее см. в разделе [Построение запросов](https://clickhouse.com/docs/ru/chdb/datastore/query-building.md).

### Методы, совместимые с pandas

Полный список всех 209 методов см. в разделе [Совместимость с pandas](https://clickhouse.com/docs/ru/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/ru/chdb/datastore/io.md).

### Методы отладки

| Метод | Описание |
| - | - |
| `explain(verbose=False)` | Показать план выполнения |
| `clear_cache()` | Очистить кэшированные результаты |

Подробности см. в разделе [Отладка](https://clickhouse.com/docs/ru/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 | Тип данных |

### Аксессоры

| Аксессор | Описание | Методы |
| - | - | - |
| `.str` | Строковые операции | 56 методов |
| `.dt` | Операции с датой и временем | 42+ методов |
| `.arr` | Операции с массивами | 37 методов |
| `.json` | Разбор JSON | 13 методов |
| `.url` | Разбор URL | 15 методов |
| `.ip` | Операции с IP-адресами | 9 методов |
| `.geo` | Геопространственные операции и операции с расстояниями | 14 методов |

См. [Аксессоры](https://clickhouse.com/docs/ru/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)` | Привести к типу |
| `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 | Название серии |
| `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/ru/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
```

### Window

Спецификация окна для оконных функций.

```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)
```