Справочник по классам 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	Копирование данных

Примеры:

# 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-запроса

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

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

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

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

Методы, совместимые с 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	Тип данных

Аксессоры

Аксессор	Описание	Методы
`.str`	Строковые операции	56 методов
`.dt`	Операции с датой и временем	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]           # 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)`	Привести к типу
`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	Название серии
`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

Window

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

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)

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

DataStore

Конструктор

Свойства

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

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

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

Методы I/O

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

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

ColumnExpr

Свойства

Аксессоры

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

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

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

Методы

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

LazyGroupBy

Методы

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

Спецификации агрегации

LazySeries

Свойства

Методы

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

F (Функции)

Поле

CaseWhen

Window