Миграция с pandas

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

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

​

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

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

# До (pandas)
import pandas as pd

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

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

​

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

1. ​

   Установите chDB

   pip install "chdb>=4.0"
   
2. ​

   Измените импорт

   # Замените это:
   import pandas as pd
   
   # На это:
   from chdb import datastore as pd
   
3. ​

   Протестируйте код

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

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

   Учтите различия

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

---

​

Что работает без изменений

​

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

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

​

Фильтрация

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

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

​

Выделение

# Выбор столбцов
df['name']
df[['name', 'age']]

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

​

GroupBy и агрегация

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

​

Сортировка

df.sort_values('salary', ascending=False)
df.sort_values(['city', 'age'])

​

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

df['name'].str.upper()
df['name'].str.contains('John')
df['name'].str.len()

​

Операции с DateTime

df['date'].dt.year
df['date'].dt.month
df['date'].dt.dayofweek

​

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

df.to_csv("output.csv")
df.to_parquet("output.parquet")
df.to_json("output.json")

---

​

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

​

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

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

pandas:

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

DataStore:

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

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

​

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:

df.drop(columns=['col'], inplace=True)

DataStore:

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

​

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

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

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

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

​

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

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

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

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

---

​

Схемы миграции

​

Сценарий 1: Чтение, анализ и запись

# 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")

​

Сценарий 2: DataFrame с операциями pandas

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

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

​

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

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

---

​

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

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 строк

---

​

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

​

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

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

1. Есть ли эта операция в списке совместимости?
2. Попробуйте сначала преобразовать в pandas: ds.to_df().operation()

​

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

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

from chdb.datastore.config import config
config.enable_debug()

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

​

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

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

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

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

​

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

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

# Проверка типов
print(ds.dtypes)

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

---

​

Поэтапная стратегия миграции

​

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

# Оставить оба импорта
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())

​

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

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

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

​

Неделя 3: Обработка сложных случаев

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

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)

​

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

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

---

​

Часто задаваемые вопросы

​

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

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

from chdb import datastore as ds
import pandas as pd

# DataStore в pandas
df = ds_result.to_pandas()

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

​

Мои тесты по-прежнему будут проходить?

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

def test_my_function():
    result = my_function()
    expected = pd.DataFrame(...)
    pd.testing.assert_frame_equal(result.to_pandas(), expected)

​

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

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

from chdb import datastore as pd

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

​

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

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