> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-home-button.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Справочник по классу DataStore

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

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

<div id="datastore">
  ## DataStore
</div>

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

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

<div id="datastore-constructor">
  ### Конструктор
</div>

```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}
# Из словаря
ds = DataStore({'a': [1, 2, 3], 'b': ['x', 'y', 'z']})

# Из pandas DataFrame
import pandas as pd
ds = DataStore(pd.DataFrame({'a': [1, 2, 3]}))

# Пустой DataStore
ds = DataStore()
```

<div id="datastore-properties">
  ### Свойства
</div>

| Свойство  | Тип       | Описание                             |
| --------- | --------- | ------------------------------------ |
| `columns` | Index     | Имена столбцов                       |
| `dtypes`  | Series    | Типы данных столбцов                 |
| `shape`   | tuple     | (строки, столбцы)                    |
| `size`    | int       | Общее количество элементов           |
| `ndim`    | int       | Число измерений (2)                  |
| `empty`   | bool      | Пуст ли DataFrame                    |
| `values`  | ndarray   | Исходные данные в виде массива NumPy |
| `index`   | Index     | Индекс строк                         |
| `T`       | DataStore | Транспонированное представление      |
| `axes`    | list      | Список осей                          |

<div id="datastore-factory">
  ### Методы-фабрики
</div>

| Метод                     | Описание                           |
| ------------------------- | ---------------------------------- |
| `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-запроса             |

Подробности см. в разделе [Методы-фабрики](/ru/products/chdb/datastore/factory-methods).

<div id="datastore-query">
  ### Методы запросов
</div>

| Метод                         | Возвращает  | Описание                     |
| ----------------------------- | ----------- | ---------------------------- |
| `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   | Выполнить JOIN с DataStore   |
| `union(other, all=False)`     | DataStore   | Объединить объекты DataStore |
| `when(cond, val)`             | CaseWhen    | CASE WHEN                    |

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

<div id="datastore-pandas">
  ### Методы, совместимые с pandas
</div>

Полный список из 209 методов см. в разделе [Совместимость с pandas](/ru/products/chdb/datastore/pandas-compat).

**Индексация:**
`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()`

<div id="datastore-io">
  ### Методы ввода-вывода
</div>

| Метод                   | Описание                          |
| ----------------------- | --------------------------------- |
| `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    |
| `to_dict(orient)`       | Преобразование в словарь          |
| `to_records()`          | Преобразование в записи           |
| `to_numpy()`            | Преобразование в массив NumPy     |
| `to_sql()`              | Генерация SQL-строки              |
| `to_string()`           | Строковое представление           |
| `to_markdown()`         | Таблица Markdown                  |
| `to_html()`             | HTML-таблица                      |

Подробнее см. в разделе [Операции ввода-вывода](/ru/products/chdb/datastore/io).

<div id="datastore-debug">
  ### Методы отладки
</div>

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

Подробнее см. в разделе [Отладка](/ru/products/chdb/debugging).

<div id="datastore-magic">
  ### Магические методы
</div>

| Метод                     | Описание                                       |         |
| ------------------------- | ---------------------------------------------- | ------- |
| `__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)`                                      |         |

***

<div id="columnexpr">
  ## ColumnExpr
</div>

Представляет выражение столбца для отложенного вычисления. Возвращается при доступе к столбцу.

```python theme={null}
# ColumnExpr возвращается автоматически
col = ds['name']  # Возвращает ColumnExpr
```

<div id="datastore-properties">
  ### Свойства
</div>

| Свойство | Тип   | Описание    |
| -------- | ----- | ----------- |
| `name`   | str   | Имя столбца |
| `dtype`  | dtype | Тип данных  |

<div id="columnexpr-accessors">
  ### Аксессоры
</div>

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

См. [Аксессоры](/ru/products/chdb/datastore/accessors) для полной документации.

<div id="columnexpr-arithmetic">
  ### Арифметические операции
</div>

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

<div id="columnexpr-comparison">
  ### Операции сравнения
</div>

```python theme={null}
ds[ds['age'] > 25]           # Больше
ds[ds['age'] >= 25]          # Больше или равно
ds[ds['age'] < 25]           # Меньше
ds[ds['age'] <= 25]          # Меньше или равно
ds[ds['name'] == 'Alice']    # Равно
ds[ds['name'] != 'Bob']      # Не равно
```

<div id="columnexpr-logical">
  ### Логические операции
</div>

```python theme={null}
ds[(ds['age'] > 25) & (ds['city'] == 'NYC')]    # И
ds[(ds['age'] > 25) | (ds['city'] == 'NYC')]    # ИЛИ
ds[~(ds['status'] == 'inactive')]               # НЕ
```

<div id="columnexpr-methods">
  ### Методы
</div>

| Метод                        | Описание                     |
| ---------------------------- | ---------------------------- |
| `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)`                | Преобразовать значения       |

<div id="columnexpr-aggregation">
  ### Методы агрегации
</div>

| Method        | Description                           |
| ------------- | ------------------------------------- |
| `sum()`       | Сумма                                 |
| `mean()`      | Среднее                               |
| `avg()`       | Псевдоним mean                        |
| `min()`       | Минимум                               |
| `max()`       | Максимум                              |
| `count()`     | Количество значений, отличных от NULL |
| `nunique()`   | Количество уникальных значений        |
| `std()`       | Стандартное отклонение                |
| `var()`       | Дисперсия                             |
| `median()`    | Медиана                               |
| `quantile(q)` | Квантиль                              |
| `first()`     | Первое значение                       |
| `last()`      | Последнее значение                    |
| `any()`       | Хотя бы одно значение — true          |
| `all()`       | Все значения — true                   |

***

<div id="lazygroupby">
  ## LazyGroupBy
</div>

Представляет собой сгруппированный DataStore для операций агрегации.

```python theme={null}
# LazyGroupBy возвращается автоматически
grouped = ds.groupby('category')  # Возвращает LazyGroupBy
```

<div id="columnexpr-methods">
  ### Методы
</div>

| Метод             | Возвращает | Описание                                  |
| ----------------- | ---------- | ----------------------------------------- |
| `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  | Фильтрация групп                          |

<div id="lazygroupby-columns">
  ### Выбор столбцов
</div>

```python theme={null}
# Выбор столбца после groupby
grouped['amount'].sum()     # Возвращает DataStore
grouped[['a', 'b']].sum()   # Возвращает DataStore
```

<div id="lazygroupby-agg">
  ### Спецификации агрегирования
</div>

```python theme={null}
# Одиночная агрегация
grouped.agg({'amount': 'sum'})

# Несколько агрегаций для столбца
grouped.agg({'amount': ['sum', 'mean', 'count']})

# Именованные агрегации
grouped.agg(
    total=('amount', 'sum'),
    average=('amount', 'mean'),
    count=('id', 'count')
)
```

***

<div id="lazyseries">
  ## LazySeries
</div>

Представляет собой ленивый объект Series (один столбец).

<div id="datastore-properties">
  ### Свойства
</div>

| Свойство | Тип   | Описание   |
| -------- | ----- | ---------- |
| `name`   | str   | Имя серии  |
| `dtype`  | dtype | Тип данных |

<div id="columnexpr-methods">
  ### Методы
</div>

Наследует большинство методов класса `ColumnExpr`. Основные методы:

| Метод            | Описание                  |
| ---------------- | ------------------------- |
| `value_counts()` | Частоты значений          |
| `unique()`       | Уникальные значения       |
| `nunique()`      | Число уникальных значений |
| `mode()`         | Наиболее частое значение  |
| `to_list()`      | Преобразовать в список    |
| `to_numpy()`     | Преобразовать в массив    |
| `to_frame()`     | Преобразовать в DataStore |

***

<div id="related">
  ## Связанные классы
</div>

<div id="f-class">
  ### F (Функции)
</div>

Пространство имен функций ClickHouse.

```python theme={null}
from chdb.datastore import F, Field

# Агрегации
F.sum(Field('amount'))
F.avg(Field('price'))
F.count(Field('id'))
F.quantile(Field('value'), 0.95)

# Условные
F.sum_if(Field('amount'), Field('status') == 'completed')
F.count_if(Field('active'))

# Оконные
F.row_number().over(order_by='date')
F.lag('price', 1).over(partition_by='product', order_by='date')
```

Подробнее см. в разделе [Агрегация](/ru/products/chdb/datastore/aggregation#f-namespace).

<div id="field-class">
  ### Поле
</div>

Ссылка на столбец по его имени.

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

# Создание ссылки на поле
amount = Field('amount')
price = Field('price')

# Использование в выражениях
F.sum(Field('amount'))
F.avg(Field('price'))
```

<div id="casewhen-class">
  ### CaseWhen
</div>

Конструктор выражений CASE WHEN.

```python theme={null}
# Создать выражение case-when
result = (ds
    .when(ds['score'] >= 90, 'A')
    .when(ds['score'] >= 80, 'B')
    .when(ds['score'] >= 70, 'C')
    .otherwise('F')
)

# Присвоить столбцу
ds['grade'] = result
```

<div id="window-class">
  ### Window
</div>

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

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

# Создание окна
window = F.window(
    partition_by='category',
    order_by='date',
    rows_between=(-7, 0)
)

# Использование с агрегацией
ds['rolling_avg'] = F.avg('price').over(window)
```