> ## 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.

# Миграция с pandas

> Пошаговое руководство по миграции с pandas на DataStore

Это руководство поможет вам перевести существующий код на pandas на DataStore, чтобы повысить производительность, сохранив совместимость.

## Миграция одной строкой

Самый простой вариант — заменить import:

```python theme={null}
# Before (pandas)
import pandas as pd

# After (DataStore)
from chdb import datastore as pd
```

Вот и всё! Большая часть кода pandas работает без изменений.

## Пошаговая миграция

**1. Установите chDB**

```bash theme={null}
pip install "chdb>=4.0"
```

**2. Измените импорт**

```python theme={null}
# Измените это:
import pandas as pd

# На это:
from chdb import datastore as pd
```

**3. Проверьте свой код**

Запустите существующий код. Большинство операций работают без изменений:

```python theme={null}
from chdb import datastore as pd

# Всё это работает одинаково
df = pd.read_csv("data.csv")
result = df[df['age'] > 25]
grouped = df.groupby('city')['salary'].mean()
df.to_csv("output.csv")
```

**4. Учтите различия**

Некоторые операции работают иначе. См. раздел [Ключевые различия](#differences) ниже.

***

## Что остается без изменений

### Загрузка данных

```python theme={null}
# All these work the same
df = pd.read_csv("data.csv")
df = pd.read_parquet("data.parquet")
df = pd.read_json("data.json")
df = pd.read_excel("data.xlsx")
```

### Фильтрация

```python theme={null}
# Boolean indexing
df[df['age'] > 25]
df[(df['age'] > 25) & (df['city'] == 'NYC')]

# query() method
df.query('age > 25 and salary > 50000')
```

### Выборка

```python theme={null}
# Column selection
df['name']
df[['name', 'age']]

# Row selection
df.head(10)
df.tail(10)
df.iloc[0:100]
```

### GroupBy и агрегирование

```python theme={null}
# GroupBy
df.groupby('city')['salary'].mean()
df.groupby(['city', 'dept']).agg({'salary': ['sum', 'mean']})
```

### Сортировка

```python theme={null}
df.sort_values('salary', ascending=False)
df.sort_values(['city', 'age'])
```

### Операции со строками

```python theme={null}
df['name'].str.upper()
df['name'].str.contains('John')
df['name'].str.len()
```

### Operations с типом «дата и время»

```python theme={null}
df['date'].dt.year
df['date'].dt.month
df['date'].dt.dayofweek
```

### Операции ввода-вывода

```python theme={null}
df.to_csv("output.csv")
df.to_parquet("output.parquet")
df.to_json("output.json")
```

***

## Основные различия

### 1. Отложенное вычисление

Операции DataStore выполняются отложенно — они не запускаются, пока не понадобятся результаты.

**pandas:**

```python theme={null}
# Executes immediately
result = df[df['age'] > 25]
print(type(result))  # pandas.DataFrame
```

**DataStore:**

```python theme={null}
# Builds query, doesn't execute yet
result = ds[ds['age'] > 25]
print(type(result))  # DataStore (lazy)

# Executes when you need the data
print(result)        # Triggers execution
df = result.to_df()  # Triggers execution
```

### 2. Возвращаемые типы

| Операция | pandas возвращает | DataStore возвращает |
| - | - | - |
| `df['col']` | Series | ColumnExpr (с отложенным выполнением) |
| `df[['a', 'b']]` | DataFrame | DataStore (с отложенным выполнением) |
| `df[condition]` | DataFrame | DataStore (с отложенным выполнением) |
| `df.groupby('x')` | GroupBy | LazyGroupBy |

### 3. Параметр inplace не поддерживается

DataStore не поддерживает `inplace=True`. Всегда используйте возвращаемое значение:

**pandas:**

```python theme={null}
df.drop(columns=['col'], inplace=True)
```

**DataStore:**

```python theme={null}
ds = ds.drop(columns=['col'])  # Assign the result
```

### 4. Сравнение объектов DataStore

pandas не распознаёт объекты DataStore, поэтому для сравнения используйте `to_pandas()`:

```python theme={null}
# This may not work as expected
df == ds  # pandas doesn't know DataStore

# Do this instead
df.equals(ds.to_pandas())
```

### 5. Порядок строк

DataStore может не сохранять порядок строк для файловых источников данных (например, SQL-баз данных). Используйте явную сортировку:

```python theme={null}
# pandas preserves order
df = pd.read_csv("data.csv")

# DataStore - use sort for guaranteed order
ds = pd.read_csv("data.csv")
ds = ds.sort('id')  # Explicit ordering
```

***

## Сценарии миграции

### Шаблон 1: чтение, анализ, запись

```python theme={null}
# pandas
import pandas as pd
df = pd.read_csv("data.csv")
result = df[df['amount'] > 100].groupby('category')['amount'].sum()
result.to_csv("output.csv")

# DataStore - same code works!
from chdb import datastore as pd
df = pd.read_csv("data.csv")
result = df[df['amount'] > 100].groupby('category')['amount'].sum()
result.to_csv("output.csv")
```

### Шаблон 2: DataFrame с операциями в pandas

Если вам нужны возможности, специфичные для pandas, выполните преобразование в конце:

```python theme={null}
from chdb import datastore as pd

# Fast DataStore operations
ds = pd.read_csv("large_data.csv")
ds = ds.filter(ds['date'] >= '2024-01-01')
ds = ds.filter(ds['amount'] > 100)

# Convert to pandas for specific features
df = ds.to_df()
df_pivoted = df.pivot_table(...)  # pandas-specific
```

### Сценарий 3: Смешанный процесс работы

```python theme={null}
from chdb import datastore as pd
import pandas

# Start with DataStore for fast filtering
ds = pd.read_csv("huge_file.csv")  # 10M rows
ds = ds.filter(ds['year'] == 2024)  # Fast SQL filter
ds = ds.select('col1', 'col2', 'col3')  # Column pruning

# Convert for pandas-specific operations
df = ds.to_df()  # Now only ~100K rows
result = df.apply(complex_custom_function)  # pandas
```

***

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

DataStore работает значительно быстрее на больших наборах данных:

| Операция | pandas | DataStore | Ускорение |
| - | - | - | - |
| Подсчёт в GroupBy | 347ms | 17ms | **19.93x** |
| Сложный конвейер | 2,047ms | 380ms | **5.39x** |
| Фильтрация+сортировка+head | 1,537ms | 350ms | **4.40x** |
| Агрегация GroupBy | 406ms | 141ms | **2.88x** |

*Бенчмарк на 10 млн строк*

***

## Устранение неполадок при миграции

### Проблема: Операция не работает

Некоторые операции pandas могут не поддерживаться. Проверьте следующее:

1. Есть ли эта операция в [списке совместимости](https://clickhouse.com/docs/ru/chdb/datastore/pandas-compat.md)?
2. Попробуйте сначала преобразовать данные в pandas: `ds.to_df().operation()`

### Проблема: Разные результаты

Включите отладочное журналирование, чтобы понять, что происходит:

```python theme={null}
from chdb.datastore.config import config
config.enable_debug()

# View the SQL being generated
ds.filter(ds['x'] > 10).explain()
```

### Проблема: Низкая производительность

Проверьте, как выполняется процесс:

```python theme={null}
# Bad: Multiple small executions
for i in range(1000):
    result = ds.filter(ds['id'] == i).to_df()

# Good: Single execution
result = ds.filter(ds['id'].isin(ids)).to_df()
```

### Проблема: несоответствие типов

DataStore может по-разному определять типы:

```python theme={null}
# Check types
print(ds.dtypes)

# Force conversion
ds['col'] = ds['col'].astype('int64')
```

***

## Стратегия поэтапной миграции

### Неделя 1: Проверка совместимости

```python theme={null}
# Keep both imports
import pandas as pd
from chdb import datastore as ds

# Compare results
pdf = pd.read_csv("data.csv")
dsf = ds.read_csv("data.csv")

# Verify they match
assert pdf.equals(dsf.to_pandas())
```

### Неделя 2: Переведите простые скрипты

Начните со скриптов, которые:

* Читают большие файлы
* Выполняют фильтрацию и агрегацию
* Не используют пользовательские функции apply

### Неделя 3: Разбор сложных случаев

Для скриптов с пользовательскими функциями:

```python theme={null}
from chdb import datastore as pd

# Let DataStore handle the heavy lifting
ds = pd.read_csv("data.csv")
ds = ds.filter(ds['year'] == 2024)  # SQL

# Convert for custom work
df = ds.to_df()
result = df.apply(my_custom_function)
```

### Неделя 4: Полная миграция

Переведите все скрипты на импорт из DataStore.

***

## FAQ

### Можно ли использовать и pandas, и DataStore?

Да! Вы можете свободно преобразовывать их друг в друга:

```python theme={null}
from chdb import datastore as ds
import pandas as pd

# DataStore to pandas
df = ds_result.to_pandas()

# pandas to DataStore  
ds = ds.DataFrame(pd_result)
```

### Будут ли мои тесты по-прежнему проходить?

Большинство тестов должно проходить. Для тестов на сравнение преобразуйте данные в pandas:

```python theme={null}
def test_my_function():
    result = my_function()
    expected = pd.DataFrame(...)
    pd.testing.assert_frame_equal(result.to_pandas(), expected)
```

### Можно ли использовать DataStore в Jupyter?

Да! DataStore работает в Jupyter Notebook:

```python theme={null}
from chdb import datastore as pd

ds = pd.read_csv("data.csv")
ds.head()  # Displays nicely in Jupyter
```

### Как сообщить о проблемах?

Если вы столкнулись с проблемами совместимости, сообщите о них здесь:
[https://github.com/chdb-io/chdb/issues](https://github.com/chdb-io/chdb/issues)