الاختلافات الرئيسية مقارنةً بـ pandas

اختلافات مهمة بين DataStore وpandas

على الرغم من أن DataStore متوافق إلى حدّ كبير مع pandas، فهناك اختلافات مهمة ينبغي فهمها.

​

جدول موجز

Aspect	pandas	DataStore
التنفيذ	Eager (فوري)	Lazy (كسول)
أنواع القيم المعادة	DataFrame/Series	DataStore/ColumnExpr
ترتيب الصفوف	محفوظ	محفوظ (تلقائيًا)؛ غير مضمون في وضع الأداء
inplace	مدعوم	غير مدعوم
الفهرس	دعم كامل	مبسّط
الذاكرة	جميع البيانات في الذاكرة	البيانات في المصدر

---

​

1. التنفيذ الكسول مقابل التنفيذ الفوري

​

pandas (فوري)

تُنفَّذ العمليات على الفور:

import pandas as pd

df = pd.read_csv("data.csv")  # Loads entire file NOW
result = df[df['age'] > 25]   # Filters NOW
grouped = result.groupby('city')['salary'].mean()  # Aggregates NOW

​

DataStore (كسول)

تُؤجَّل العمليات إلى حين الحاجة إلى النتائج:

from chdb import datastore as pd

ds = pd.read_csv("data.csv")  # Just records the source
result = ds[ds['age'] > 25]   # Just records the filter
grouped = result.groupby('city')['salary'].mean()  # Just records

# Execution happens here:
print(grouped)        # Executes when displaying
df = grouped.to_df()  # Or when converting to pandas

​

لماذا يُعدّ هذا مهمًا

يُمكّن التنفيذ الكسول مما يلي:

• تحسين الاستعلام: تُحوَّل عمليات متعددة إلى استعلام SQL واحد
• تشذيب الأعمدة: لا تُقرأ إلا الأعمدة المطلوبة
• تمرير عوامل التصفية إلى المصدر: تُطبَّق عوامل التصفية عند المصدر
• كفاءة الذاكرة: لا تُحمِّل بيانات لا تحتاج إليها

---

​

2. أنواع القيم المُعادة

​

pandas

df['col']           # Returns pd.Series
df[['a', 'b']]      # Returns pd.DataFrame
df[df['x'] > 10]    # Returns pd.DataFrame
df.groupby('x')     # Returns DataFrameGroupBy

​

DataStore

ds['col']           # Returns ColumnExpr (lazy)
ds[['a', 'b']]      # Returns DataStore (lazy)
ds[ds['x'] > 10]    # Returns DataStore (lazy)
ds.groupby('x')     # Returns LazyGroupBy

​

التحويل إلى أنواع بيانات pandas

# Get pandas DataFrame
df = ds.to_df()
df = ds.to_pandas()

# Get pandas Series from column
series = ds['col'].to_pandas()

# Or trigger execution
print(ds)  # Automatically converts for display

---

​

3. مشغّلات التنفيذ

يبدأ DataStore التنفيذ عندما تحتاج إلى القيم الفعلية:

المحفّز	مثال	ملاحظات
print() / repr()	print(ds)	يتطلب العرض بيانات
len()	len(ds)	تحتاج إلى عدد الصفوف
.columns	ds.columns	تحتاج إلى أسماء الأعمدة
.dtypes	ds.dtypes	تحتاج إلى معلومات الأنواع
.shape	ds.shape	تحتاج إلى الأبعاد
.values	ds.values	تحتاج إلى البيانات الفعلية
.index	ds.index	تحتاج إلى الفهرس
to_df()	ds.to_df()	تحويل صريح
التكرار	for row in ds	تحتاج إلى التكرار
equals()	ds.equals(other)	تحتاج إلى المقارنة

​

العمليات التي تبقى كسولة

العملية	تُرجع
filter()	DataStore
select()	DataStore
sort()	DataStore
groupby()	LazyGroupBy
join()	DataStore
ds['col']	ColumnExpr
ds[['a', 'b']]	DataStore
ds[condition]	DataStore

---

​

4. ترتيب الصفوف

​

pandas

يُحافَظ دائمًا على ترتيب الصفوف:

df = pd.read_csv("data.csv")
print(df.head())  # Always same order as file

​

DataStore

يُحفَظ ترتيب الصفوف تلقائيًا في معظم العمليات:

ds = pd.read_csv("data.csv")
print(ds.head())  # Matches file order

# Filter preserves order
ds_filtered = ds[ds['age'] > 25]  # Same order as pandas

يتتبّع DataStore تلقائيًا المواضع الأصلية للصفوف داخليًا (باستخدام rowNumberInAllBlocks()) لضمان الحفاظ على اتساق الترتيب مع pandas.

​

عندما يُحفَظ الترتيب

• المصادر المعتمدة على الملفات (CSV وParquet وJSON وما إلى ذلك)
• مصادر pandas DataFrame
• عمليات التصفية
• اختيار الأعمدة
• بعد استخدام sort() أو sort_values() صراحةً
• العمليات التي تحدد الترتيب (nlargest() وnsmallest() وhead() وtail())

​

عندما قد يختلف الترتيب

• بعد عمليات التجميع باستخدام groupby() (استخدم sort_values() لضمان اتساق الترتيب)
• بعد merge() / join() مع بعض أنواع الربط
• في وضع الأداء (config.use_performance_mode()): لا يكون ترتيب الصفوف مضمونًا في أي عملية. راجع وضع الأداء.

---

​

5. عدم توفّر المعلمة inplace

​

pandas

df.drop(columns=['col'], inplace=True)  # Modifies df
df.fillna(0, inplace=True)              # Modifies df
df.rename(columns={'old': 'new'}, inplace=True)

​

DataStore

inplace=True غير مدعوم. أَسنِد النتيجة دائمًا:

ds = ds.drop(columns=['col'])           # Returns new DataStore
ds = ds.fillna(0)                       # Returns new DataStore
ds = ds.rename(columns={'old': 'new'})  # Returns new DataStore

​

لماذا لا يوجد inplace؟

يستخدم DataStore عمليات غير قابلة للتعديل لإتاحة:

• بناء الاستعلامات (التنفيذ الكسول)
• أمان الخيوط
• تصحيح الأخطاء بسهولة أكبر
• شيفرة أوضح

---

​

6. دعم الفهارس

​

pandas

دعم كامل للفهارس:

df = df.set_index('id')
df.loc['user123']           # Label-based access
df.loc['a':'z']             # Label-based slicing
df.reset_index()
df.index.name = 'user_id'

​

DataStore

دعم مبسّط للفهارس:

# Basic operations work
ds.loc[0:10]               # Integer position
ds.iloc[0:10]              # Same as loc for DataStore

# For pandas-style index operations, convert first
df = ds.to_df()
df = df.set_index('id')
df.loc['user123']

​

نوع مصدر DataStore مهم

• مصدر DataFrame: يحتفظ بفهرس pandas
• مصدر File: يستخدم فهرسًا عدديًا بسيطًا

---

​

7. سلوك عمليات المقارنة

​

مقارنةً بـ pandas

لا يتعرّف pandas على كائنات DataStore:

import pandas as pd
from chdb import datastore as ds

pdf = pd.DataFrame({'a': [1, 2, 3]})
dsf = ds.DataFrame({'a': [1, 2, 3]})

# This doesn't work as expected
pdf == dsf  # pandas doesn't know DataStore

# Solution: convert DataStore to pandas
pdf.equals(dsf.to_pandas())  # True

​

استخدام الدالة equals()

# DataStore.equals() also works
dsf.equals(pdf)  # Compares with pandas DataFrame

---

​

8. استنتاج النوع

​

pandas

يستخدم أنواع بيانات numpy/pandas:

df['col'].dtype  # int64, float64, object, datetime64, etc.

​

DataStore

يمكنه استخدام أنواع ClickHouse:

ds['col'].dtype  # Int64, Float64, String, DateTime, etc.

# Types are converted when going to pandas
df = ds.to_df()
df['col'].dtype  # Now pandas type

​

التحويل الصريح للنوع

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

---

​

9. نموذج الذاكرة

​

pandas

تُخزَّن جميع البيانات في الذاكرة:

df = pd.read_csv("huge.csv")  # 10GB in memory!

​

DataStore

تبقى البيانات في المصدر حتى تدعو الحاجة إليها:

ds = pd.read_csv("huge.csv")  # Just metadata
ds = ds.filter(ds['year'] == 2024)  # Still just metadata

# Only filtered result is loaded
df = ds.to_df()  # Maybe only 1GB now

---

​

10. رسائل الخطأ

​

مصادر الأخطاء المختلفة

• أخطاء pandas: صادرة من مكتبة pandas
• أخطاء DataStore: صادرة من chDB أو ClickHouse

# May see ClickHouse-style errors
# "Code: 62. DB::Exception: Syntax error..."

​

نصائح لاستكشاف الأخطاء وإصلاحها

# View the SQL to debug
print(ds.to_sql())

# See execution plan
ds.explain()

# Enable debug logging
from chdb.datastore.config import config
config.enable_debug()

---

​

قائمة تحقق الترحيل

عند الترحيل من pandas:

• غيّر تعليمة الاستيراد
• أزل المَعلمات inplace=True
• أضف استدعاء to_df() بشكل صريح حيث تكون pandas DataFrame مطلوبة
• أضف الفرز إذا كان ترتيب الصفوف مهمًا
• استخدم to_pandas() في اختبارات المقارنة
• اختبر بأحجام بيانات ممثلة للواقع

---

​

مرجع سريع

pandas	DataStore
df[condition]	كما هو (يعيد DataStore)
df.groupby()	كما هو (يعيد LazyGroupBy)
df.drop(inplace=True)	ds = ds.drop()
df.equals(other)	ds.to_pandas().equals(other)
df.loc['label']	ds.to_df().loc['label']
print(df)	كما هو (يؤدي إلى التنفيذ)
len(df)	كما هو (يؤدي إلى التنفيذ)