> ## 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: pandas-совместимый API с SQL-оптимизацией

> DataStore предоставляет pandas-совместимый API с 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](https://mintcdn.com/private-7c7dfe99/LCIbqddLfKHZZnfk/images/chdb/datastore_architecture.png?fit=max\&auto=format\&n=LCIbqddLfKHZZnfk\&q=85\&s=39e13b7a77b0f28d676648b855d60db0)

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

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

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

## Миграция из Pandas в одну строку

```python theme={null}
# 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, особенно при агрегации и в сложных конвейерах:

| Операция | Pandas | DataStore | Ускорение |
| - | - | - | - |
| GroupBy count | 347ms | 17ms | **19.93x** |
| Сложный конвейер | 2,047ms | 380ms | **5.39x** |
| Filter+Sort+Head | 1,537ms | 350ms | **4.40x** |
| GroupBy agg | 406ms | 141ms | **2.88x** |

*Бенчмарк на 10 млн строк. Подробности см. в [скрипте бенчмарка](https://github.com/chdb-io/chdb/blob/main/refs/benchmark_datastore_vs_pandas.py) и [руководстве по производительности](https://clickhouse.com/docs/ru/chdb/guides/pandas-performance.md).*

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

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

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

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

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

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

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

## Статистика API

| Категория | Количество | Покрытие |
| - | - | - |
| Методы DataFrame | 209 | 100% от pandas |
| Аксессор Series.str | 56 | 100% от pandas |
| Аксессор Series.dt | 42+ | 100%+ (включая дополнительные возможности ClickHouse) |
| Аксессор Series.arr | 37 | специфично для ClickHouse |
| Аксессор Series.json | 13 | специфично для ClickHouse |
| Аксессор Series.url | 15 | специфично для ClickHouse |
| Аксессор Series.ip | 9 | специфично для ClickHouse |
| Аксессор Series.geo | 14 | специфично для ClickHouse |
| **Всего методов API** | **630+** | - |

## Навигация по документации

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

* [Краткое руководство](https://clickhouse.com/docs/ru/chdb/datastore/quickstart.md) - Установка и базовое использование
* [Миграция из Pandas](https://clickhouse.com/docs/ru/chdb/guides/migration-from-pandas.md) - Пошаговое руководство по миграции

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

* [Фабричные методы](https://clickhouse.com/docs/ru/chdb/datastore/factory-methods.md) - Создание DataStore из различных источников
* [Построение запросов](https://clickhouse.com/docs/ru/chdb/datastore/query-building.md) - Операции с запросами в стиле SQL
* [Совместимость с pandas](https://clickhouse.com/docs/ru/chdb/datastore/pandas-compat.md) - Все 209 методов, совместимых с pandas
* [Аксессоры](https://clickhouse.com/docs/ru/chdb/datastore/accessors.md) - Аксессоры String, DateTime, Array, JSON, URL, IP и Geo
* [Агрегация](https://clickhouse.com/docs/ru/chdb/datastore/aggregation.md) - Агрегатные и оконные функции
* [Операции ввода-вывода](https://clickhouse.com/docs/ru/chdb/datastore/io.md) - Чтение и запись данных

### Дополнительные темы

* [Модель выполнения](https://clickhouse.com/docs/ru/chdb/datastore/execution-model.md) - Отложенные вычисления и кэширование
* [Справочник класса](https://clickhouse.com/docs/ru/chdb/datastore/class-reference.md) - Полное описание API

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

* [Конфигурация](https://clickhouse.com/docs/ru/chdb/configuration/index.md) - Все параметры
* [Режим производительности](https://clickhouse.com/docs/ru/chdb/configuration/performance-mode.md) - Режим с приоритетом SQL для максимальной пропускной способности
* [Отладка](https://clickhouse.com/docs/ru/chdb/debugging/index.md) - Explain, данные профилирования и логирование

### Руководства по Pandas

* [Pandas Cookbook](https://clickhouse.com/docs/ru/chdb/guides/pandas-cookbook.md) - Типовые приёмы
* [Ключевые различия](https://clickhouse.com/docs/ru/chdb/guides/pandas-differences.md) - Важные отличия от Pandas
* [Руководство по производительности](https://clickhouse.com/docs/ru/chdb/guides/pandas-performance.md) - Советы по оптимизации
* [SQL для пользователей Pandas](https://clickhouse.com/docs/ru/chdb/guides/pandas-to-sql.md) - Понимание SQL, лежащего в основе операций Pandas

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

```python theme={null}
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
```

## Дальнейшие шаги

* **Впервые работаете с DataStore?** Начните с [краткого руководства](https://clickhouse.com/docs/ru/chdb/datastore/quickstart.md)
* **Переходите с pandas?** Прочитайте [руководство по миграции](https://clickhouse.com/docs/ru/chdb/guides/migration-from-pandas.md)
* **Хотите узнать больше?** Ознакомьтесь с [справочником по API](https://clickhouse.com/docs/ru/chdb/datastore/class-reference.md)