> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8c05c8a2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Миграция с pandas

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

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

<div id="one-line">
  ## Миграция в одну строку
</div>

Самый простой вариант миграции — изменить строку импорта:

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

# После (DataStore)
from chdb import datastore as pd
```

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

<div id="step-by-step">
  ## Пошаговая миграция
</div>

<Steps>
  <Step>
    ### Установите chDB

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

  <Step>
    ### Измените импорт

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

    # На это:
    from chdb import datastore as pd
    ```
  </Step>

  <Step>
    ### Протестируйте код

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

    ```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")
    ```
  </Step>

  <Step>
    ### Учтите различия

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

***

<div id="works-unchanged">
  ## Что работает без изменений
</div>

<div id="loading-unchanged">
  ### Загрузка данных
</div>

```python theme={null}
# Все эти варианты работают одинаково
df = pd.read_csv("data.csv")
df = pd.read_parquet("data.parquet")
df = pd.read_json("data.json")
df = pd.read_excel("data.xlsx")
```

<div id="filtering-unchanged">
  ### Фильтрация
</div>

```python theme={null}
# Булева индексация
df[df['age'] > 25]
df[(df['age'] > 25) & (df['city'] == 'NYC')]

# метод query()
df.query('age > 25 and salary > 50000')
```

<div id="selection-unchanged">
  ### Выделение
</div>

```python theme={null}
# Выбор столбцов
df['name']
df[['name', 'age']]

# Выбор строк
df.head(10)
df.tail(10)
df.iloc[0:100]
```

<div id="groupby-unchanged">
  ### GroupBy и агрегация
</div>

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

<div id="sorting-unchanged">
  ### Сортировка
</div>

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

<div id="string-unchanged">
  ### Операции над строками
</div>

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

<div id="datetime-unchanged">
  ### Операции с DateTime
</div>

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

<div id="io-unchanged">
  ### Операции ввода-вывода
</div>

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

***

<div id="differences">
  ## Основные различия
</div>

<div id="lazy">
  ### 1. Отложенное вычисление
</div>

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

**pandas:**

```python theme={null}
# Выполняется немедленно
result = df[df['age'] > 25]
print(type(result))  # pandas.DataFrame
```

**DataStore:**

```python theme={null}
# Формирует запрос, но не выполняет его
result = ds[ds['age'] > 25]
print(type(result))  # DataStore (ленивый)

# Выполняется, когда нужны данные
print(result)        # Запускает выполнение
df = result.to_df()  # Запускает выполнение
```

<div id="return-types">
  ### 2. Возвращаемые типы
</div>

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

<div id="no-inplace">
  ### 3. Параметр inplace не поддерживается
</div>

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

**pandas:**

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

**DataStore:**

```python theme={null}
ds = ds.drop(columns=['col'])  # Присвоить результат
```

<div id="comparing">
  ### 4. Сравнение объектов DataStore
</div>

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

```python theme={null}
# Это может сработать не так, как ожидается
df == ds  # pandas doesn't know DataStore

# Вместо этого используйте такой вариант
df.equals(ds.to_pandas())
```

<div id="row-order">
  ### 5. Порядок строк
</div>

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

```python theme={null}
# pandas сохраняет порядок
df = pd.read_csv("data.csv")

# DataStore - используйте sort для гарантированного порядка
ds = pd.read_csv("data.csv")
ds = ds.sort('id')  # Явная сортировка
```

***

<div id="patterns">
  ## Схемы миграции
</div>

<div id="pattern-1">
  ### Сценарий 1: Чтение, анализ и запись
</div>

```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 — тот же код тоже работает!
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")
```

<div id="pattern-2">
  ### Сценарий 2: DataFrame с операциями pandas
</div>

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

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

# Быстрые операции DataStore
ds = pd.read_csv("large_data.csv")
ds = ds.filter(ds['date'] >= '2024-01-01')
ds = ds.filter(ds['amount'] > 100)

# Преобразование в pandas для использования специфических возможностей
df = ds.to_df()
df_pivoted = df.pivot_table(...)  # специфично для pandas
```

<div id="pattern-3">
  ### Сценарий 3: Смешанный рабочий процесс
</div>

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

# Начните с DataStore для быстрой фильтрации
ds = pd.read_csv("huge_file.csv")  # 10 млн строк
ds = ds.filter(ds['year'] == 2024)  # Быстрый SQL-фильтр
ds = ds.select('col1', 'col2', 'col3')  # Оптимизация по столбцам

# Преобразуйте для операций, характерных для pandas
df = ds.to_df()  # Теперь осталось только ~100 тыс. строк
result = df.apply(complex_custom_function)  # pandas
```

***

<div id="performance">
  ## Сравнение производительности
</div>

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

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

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

***

<div id="troubleshooting">
  ## Устранение неполадок при миграции
</div>

<div id="issue-op">
  ### Проблема: Операция не работает
</div>

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

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

<div id="issue-results">
  ### Проблема: Разные результаты
</div>

Включите отладочное логирование, чтобы понять, в чем дело:

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

# Просмотр генерируемого SQL
ds.filter(ds['x'] > 10).explain()
```

<div id="issue-slow">
  ### Проблема: Низкая производительность
</div>

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

```python theme={null}
# Плохо: множество мелких выполнений
for i in range(1000):
    result = ds.filter(ds['id'] == i).to_df()

# Хорошо: одно выполнение
result = ds.filter(ds['id'].isin(ids)).to_df()
```

<div id="issue-types">
  ### Проблема: Несоответствие типов
</div>

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

```python theme={null}
# Проверка типов
print(ds.dtypes)

# Принудительное преобразование
ds['col'] = ds['col'].astype('int64')
```

***

<div id="gradual">
  ## Поэтапная стратегия миграции
</div>

<div id="week-1">
  ### Неделя 1: Проверка совместимости
</div>

```python theme={null}
# Оставить оба импорта
import pandas as pd
from chdb import datastore as ds

# Сравнить результаты
pdf = pd.read_csv("data.csv")
dsf = ds.read_csv("data.csv")

# Убедиться, что они совпадают
assert pdf.equals(dsf.to_pandas())
```

<div id="week-2">
  ### Неделя 2: Переведите простые скрипты
</div>

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

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

<div id="week-3">
  ### Неделя 3: Обработка сложных случаев
</div>

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

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

# Позвольте DataStore взять на себя основную работу
ds = pd.read_csv("data.csv")
ds = ds.filter(ds['year'] == 2024)  # SQL

# Преобразование для пользовательской обработки
df = ds.to_df()
result = df.apply(my_custom_function)
```

<div id="week-4">
  ### Неделя 4: Полная миграция
</div>

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

***

<div id="faq">
  ## Часто задаваемые вопросы
</div>

<div id="faq-both">
  ### Можно ли использовать и pandas, и DataStore?
</div>

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

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

# DataStore в pandas
df = ds_result.to_pandas()

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

<div id="faq-tests">
  ### Мои тесты по-прежнему будут проходить?
</div>

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

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

<div id="faq-jupyter">
  ### Можно ли использовать DataStore в Jupyter?
</div>

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

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

ds = pd.read_csv("data.csv")
ds.head()  # Красиво отображается в Jupyter
```

<div id="faq-issues">
  ### Как сообщить о проблемах?
</div>

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