Перейти к основному содержимому
Перейти к основному содержимому

DataStore: API chDB, совместимый с pandas и оптимизированный для SQL

DataStore — это API chDB, совместимый с pandas, который сочетает привычный интерфейс pandas DataFrame с мощью оптимизации SQL‑запросов и позволяет писать код в стиле pandas, получая производительность ClickHouse.

Ключевые возможности​

  • Совместимость с pandas: 209 методов pandas DataFrame, 56 методов .str, более 42 методов .dt
  • Оптимизация SQL: операции автоматически компилируются в оптимизированные SQL-запросы
  • Ленивые вычисления: выполнение операций откладывается до момента, когда требуются результаты
  • Более 630 методов API: обширный API для работы с данными
  • Расширения ClickHouse: дополнительные аксессоры (.arr, .json, .url, .ip, .geo), недоступные в pandas

Архитектура​

Архитектура DataStore

DataStore использует отложенные вычисления с двухдвижковой архитектурой выполнения:

  1. Отложенная цепочка операций: операции записываются, но не выполняются немедленно
  2. Интеллектуальный выбор движка: QueryPlanner направляет каждый сегмент в оптимальный движок (chDB для SQL, Pandas для сложных операций)
  3. Промежуточное кэширование: результаты кэшируются на каждом шаге для быстрого итеративного исследования данных

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

Миграция из Pandas одной строкой​

# Before (pandas)
import pandas as pd
df = pd.read_csv("data.csv")
result = df[df['age'] > 25].groupby('city')['salary'].mean()

# After (DataStore) - just change the import!
from chdb import datastore as pd
df = pd.read_csv("data.csv")
result = df[df['age'] > 25].groupby('city')['salary'].mean()

Ваш существующий код pandas работает без изменений, но теперь выполняется поверх движка ClickHouse.

Сравнение производительности​

DataStore обеспечивает значительный прирост производительности по сравнению с pandas, особенно для агрегаций и сложных пайплайнов:

ОперацияPandasDataStoreУскорение
GroupBy count347ms17ms19.93x
Complex pipeline2,047ms380ms5.39x
Filter+Sort+Head1,537ms350ms4.40x
GroupBy agg406ms141ms2.88x

Бенчмарк на 10M строк. Подробности см. в скрипте бенчмарка и руководстве по производительности.

Когда использовать DataStore​

Используйте DataStore, когда:

  • Работаете с большими наборами данных (миллионы строк)
  • Выполняете агрегирование и операции groupby
  • Выполняете запросы к данным из файлов, баз данных или облачных хранилищ
  • Строите сложные конвейеры обработки данных
  • Вам нужен API pandas с более высокой производительностью

Используйте raw SQL API, когда:

  • Вы предпочитаете писать SQL напрямую
  • Вам нужен точный контроль над выполнением запроса
  • Работаете с функциями ClickHouse, которые недоступны через API pandas

Сравнение возможностей​

ВозможностьPandasPolarsDuckDBDataStore
Совместимость с API Pandas-ЧастичнаяНетПолная
Отложенные вычисленияНетДаДаДа
Поддержка SQL-запросовНетДаДаДа
Функции ClickHouseНетНетНетДа
Методы доступа к строкам/DateTimeДаДаНетДа + дополнительные возможности
Array/JSON/URL/IP/GeoНетЧастичноНетДа
Прямые запросы к файламНетДаДаДа
Поддержка облачных хранилищНетОграниченная поддержкаДаДа

Статистика API​

КатегорияКоличествоПокрытие
Методы DataFrame209100% API pandas
Аксессор Series.str56100% API pandas
Аксессор Series.dt42+100%+ (включая дополнительные возможности ClickHouse)
Аксессор Series.arr37Специфичный для ClickHouse
Аксессор Series.json13Специфичный для ClickHouse
Аксессор Series.url15Специфичный для ClickHouse
Аксессор Series.ip9Специфичный для ClickHouse
Аксессор Series.geo14Специфичный для ClickHouse
Всего методов API630+-

Начало работы​

Справочник по API​

  • Factory Methods - Фабричные методы для создания DataStore из различных источников
  • Query Building - Операции построения запросов в стиле SQL
  • Pandas Compatibility - Все 209 методов, совместимых с pandas
  • Accessors - аксессоры для String, DateTime, Array, JSON, URL, IP, Geo
  • Aggregation - агрегатные и оконные функции
  • I/O Operations - чтение и запись данных

Продвинутые темы​

Конфигурация и отладка​

Руководства для пользователей pandas​

  • Pandas Cookbook - Распространённые приёмы
  • Key Differences - Важные отличия от pandas
  • Performance Guide - Руководство по оптимизации производительности
  • SQL for Pandas Users - Понимание SQL, лежащего в основе операций pandas

Краткий пример​

from chdb import datastore as pd

# Read data from various sources
ds = pd.read_csv("sales.csv")
# or: ds = pd.DataStore.uri("s3://bucket/sales.parquet")
# or: ds = pd.DataStore.from_mysql("mysql://user:pass@host/db/table")

# Familiar pandas operations - automatically optimized to SQL
result = (ds
    .filter(ds['amount'] > 1000)           # WHERE amount > 1000
    .groupby('region')                      # GROUP BY region
    .agg({'amount': ['sum', 'mean']})       # SUM(amount), AVG(amount)
    .sort_values('sum', ascending=False)    # ORDER BY sum DESC
    .head(10)                               # LIMIT 10
)

# View the generated SQL
print(result.to_sql())

# Execute and get results
df = result.to_df()  # Returns pandas DataFrame

Следующие шаги​