Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Миграция с pandas

View as MarkdownEdit this pageReport an issueSet up docs MCP

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

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

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

# Before (pandas)
import pandas as pd

# After (DataStore)
from chdb import datastore as pd

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

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

Установите chDB

pip install "chdb>=4.0"

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

# Измените это:
import pandas as pd

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

Проверьте свой код

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

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

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

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

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

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

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

Фильтрация

# Boolean indexing
df[df['age'] > 25]
df[(df['age'] > 25) & (df['city'] == 'NYC')]

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

Выборка

# Column selection
df['name']
df[['name', 'age']]

# Row selection
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()

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

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:

# Executes immediately
result = df[df['age'] > 25]
print(type(result))  # pandas.DataFrame

DataStore:

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

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

DataStore:

ds = ds.drop(columns=['col'])  # Assign the result

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

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

# This may not work as expected
df == ds  # pandas doesn't know DataStore

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

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

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

# 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: чтение, анализ, запись

# 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, выполните преобразование в конце:

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: Смешанный процесс работы

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. Есть ли эта операция в списке совместимости?
  2. Попробуйте сначала преобразовать данные в pandas: ds.to_df().operation()

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

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

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

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

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

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

# 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 может по-разному определять типы:

# Check types
print(ds.dtypes)

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

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

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

# 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: Разбор сложных случаев

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

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?

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

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:

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()  # Displays nicely in Jupyter

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

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

Navigation