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

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

DataStore

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

from chdb.datastore import DataStore

Конструктор

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

Параметры:

Параметр	Тип	Описание
`data`	dict/list/DataFrame/DataStore	Входные данные
`columns`	list	Имена столбцов
`index`	Index	Индекс строк
`dtype`	dict	Типы данных столбцов
`copy`	bool	Копировать данные

Примеры:

# Из словаря
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()

Свойства

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

Подробности см. в разделе Методы-фабрики.

Методы запросов

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

Подробнее см. в разделе Построение запросов.

Методы, совместимые с 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()

Методы ввода-вывода

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

Подробнее см. в разделе Операции ввода-вывода.

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

Метод	Описание
`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 возвращается автоматически
col = ds['name']  # Возвращает ColumnExpr

Свойства

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

Аксессоры

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

См. Аксессоры для полной документации.

Арифметические операции

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]           # Больше
ds[ds['age'] >= 25]          # Больше или равно
ds[ds['age'] < 25]           # Меньше
ds[ds['age'] <= 25]          # Меньше или равно
ds[ds['name'] == 'Alice']    # Равно
ds[ds['name'] != 'Bob']      # Не равно

Логические операции

ds[(ds['age'] > 25) & (ds['city'] == 'NYC')]    # И
ds[(ds['age'] > 25) | (ds['city'] == 'NYC')]    # ИЛИ
ds[~(ds['status'] == 'inactive')]               # НЕ

Методы

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

Методы агрегации

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

LazyGroupBy

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

# LazyGroupBy возвращается автоматически
grouped = ds.groupby('category')  # Возвращает 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	Фильтрация групп

Выбор столбцов

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

Спецификации агрегирования

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

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

# Именованные агрегации
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.

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

Подробнее см. в разделе Агрегация.

Поле

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

from chdb.datastore import Field

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

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

CaseWhen

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

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

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

Window

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

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)

​DataStore

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

​Свойства

​Методы-фабрики

​Методы запросов

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

​Методы ввода-вывода

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

​Магические методы

​ColumnExpr

​Свойства

​Аксессоры

​Арифметические операции

​Операции сравнения

​Логические операции

​Методы

​Методы агрегации

​LazyGroupBy

​Методы

​Выбор столбцов

​Спецификации агрегирования

​LazySeries

​Свойства

​Методы

​Связанные классы

​F (Функции)

​Поле

​CaseWhen

​Window

DataStore

Конструктор

Свойства

Методы-фабрики

Методы запросов

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

Методы ввода-вывода

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

Магические методы

ColumnExpr

Свойства

Аксессоры

Арифметические операции

Операции сравнения

Логические операции

Методы

Методы агрегации

LazyGroupBy

Методы

Выбор столбцов

Спецификации агрегирования

LazySeries

Свойства

Методы

Связанные классы

F (Функции)

Поле

CaseWhen

Window