توافق DataStore مع Pandas

يدعم DataStore 209 من طرق pandas DataFrame لتوفير توافق كامل مع واجهة برمجة التطبيقات. تعمل شيفرة pandas الحالية لديك بأقل قدر من التغييرات.

نهج التوافق

# Typical migration - just change the import
- import pandas as pd
+ from chdb import datastore as pd

# Your code works unchanged
df = pd.read_csv("data.csv")
result = df[df['age'] > 25].groupby('city')['salary'].mean()

المبادئ الأساسية:

تم تنفيذ جميع طرائق pandas DataFrame البالغ عددها 209
التقييم الكسول لتحسين استعلامات SQL
تغليف تلقائي للأنواع (DataFrame → DataStore, Series → ColumnExpr)
عمليات غير قابلة للتعديل (من دون inplace=True)

السمات والخصائص

الخاصية	الوصف	يحفّز التنفيذ
`shape`	زوج (صفوف، أعمدة)	نعم
`columns`	أسماء الأعمدة (Index)	نعم
`dtypes`	أنواع بيانات الأعمدة	نعم
`values`	مصفوفة NumPy	نعم
`index`	فهرس الصفوف	نعم
`size`	عدد العناصر	نعم
`ndim`	عدد الأبعاد	لا
`empty`	ما إذا كان DataFrame فارغًا	نعم
`T`	منقول	نعم
`axes`	قائمة المحاور	نعم

أمثلة:

from chdb import datastore as pd

ds = pd.read_csv("data.csv")

print(ds.shape)      # (1000, 5)
print(ds.columns)    # Index(['name', 'age', 'city', 'salary', 'dept'])
print(ds.dtypes)     # name: object, age: int64, ...
print(ds.empty)      # False

الفهرسة والاختيار

الطريقة	الوصف	مثال
`df['col']`	اختيار عمود	`ds['age']`
`df[['col1', 'col2']]`	اختيار أعمدة	`ds[['name', 'age']]`
`df[condition]`	الفهرسة المنطقية	`ds[ds['age'] > 25]`
`df.loc[...]`	وصول يعتمد على التسميات	`ds.loc[0:10, 'name']`
`df.iloc[...]`	وصول يعتمد على الأعداد الصحيحة	`ds.iloc[0:10, 0:3]`
`df.at[...]`	قيمة واحدة حسب التسمية	`ds.at[0, 'name']`
`df.iat[...]`	قيمة واحدة حسب الموضع	`ds.iat[0, 0]`
`df.head(n)`	أول n صفوف	`ds.head(10)`
`df.tail(n)`	آخر n صفوف	`ds.tail(10)`
`df.sample(n)`	عينة عشوائية	`ds.sample(100)`
`df.select_dtypes()`	اختيار حسب نوع البيانات	`ds.select_dtypes(include='number')`
`df.query()`	تعبير استعلام	`ds.query('age > 25')`
`df.where()`	استبدال شرطي	`ds.where(ds['age'] > 0, 0)`
`df.mask()`	عكس where	`ds.mask(ds['age'] < 0, 0)`
`df.isin()`	احتواء القيمة	`ds['city'].isin(['NYC', 'LA'])`
`df.get()`	وصول آمن إلى عمود	`ds.get('col', default=None)`
`df.xs()`	مقطع عرضي	`ds.xs('key')`
`df.pop()`	إزالة عمود	`ds.pop('col')`

الطرق الإحصائية

الطريقة	الوصف	المكافئ في SQL
`mean()`	المتوسط	`AVG()`
`median()`	القيمة الوسيطة	`MEDIAN()`
`mode()`	المنوال	-
`std()`	الانحراف المعياري	`STDDEV()`
`var()`	التباين	`VAR()`
`min()`	الحد الأدنى	`MIN()`
`max()`	الحد الأقصى	`MAX()`
`sum()`	المجموع	`SUM()`
`prod()`	حاصل الضرب	-
`count()`	عدد القيم غير NULL	`COUNT()`
`nunique()`	عدد القيم الفريدة	`UNIQ()`
`value_counts()`	تكرارات القيم	`GROUP BY`
`quantile()`	الكَمّ	`QUANTILE()`
`describe()`	إحصاءات وصفية	-
`corr()`	مصفوفة الارتباط	`CORR()`
`cov()`	مصفوفة التغاير	`COV()`
`corrwith()`	الارتباط الزوجي	-
`rank()`	ترتيب القيم	`RANK()`
`abs()`	القيم المطلقة	`ABS()`
`round()`	تقريب القيم	`ROUND()`
`clip()`	قصّ القيم	-
`cumsum()`	المجموع التراكمي	دالة نافذة
`cumprod()`	حاصل الضرب التراكمي	دالة نافذة
`cummin()`	الحد الأدنى التراكمي	دالة نافذة
`cummax()`	الحد الأقصى التراكمي	دالة نافذة
`diff()`	الفرق	دالة نافذة
`pct_change()`	نسبة التغيّر	دالة نافذة
`skew()`	معامل الالتواء	`SKEW()`
`kurt()`	التفلطح	`KURT()`
`sem()`	الخطأ المعياري	-
`all()`	كلها صحيحة	-
`any()`	أيٌّ منها صحيح	-
`idxmin()`	فهرس القيمة الدنيا	-
`idxmax()`	فهرس القيمة العليا	-

أمثلة:

ds = pd.read_csv("data.csv")

# Basic statistics
print(ds['salary'].mean())
print(ds['age'].std())
print(ds.describe())

# Group statistics
print(ds.groupby('department')['salary'].mean())
print(ds.groupby('city').agg({'salary': ['mean', 'std'], 'age': 'count'}))

معالجة البيانات

طريقة	Description
`drop()`	حذف الصفوف/الأعمدة
`drop_duplicates()`	إزالة القيم المكررة
`duplicated()`	تمييز القيم المكررة
`dropna()`	إزالة القيم المفقودة
`fillna()`	ملء القيم المفقودة
`ffill()`	الملء للأمام
`bfill()`	الملء للخلف
`interpolate()`	استيفاء القيم
`replace()`	استبدال القيم
`rename()`	إعادة تسمية الأعمدة/الفهرس
`rename_axis()`	إعادة تسمية المحور
`assign()`	إضافة أعمدة جديدة
`astype()`	تحويل الأنواع
`convert_dtypes()`	استنتاج الأنواع
`copy()`	نسخ DataFrame

أمثلة:

ds = pd.read_csv("data.csv")

# Drop operations
result = ds.drop(columns=['unused_col'])
result = ds.drop_duplicates(subset=['user_id'])
result = ds.dropna(subset=['email'])

# Fill operations
result = ds.fillna(0)
result = ds.fillna({'age': 0, 'name': 'Unknown'})

# Transform operations
result = ds.rename(columns={'old_name': 'new_name'})
result = ds.assign(
    full_name=lambda x: x['first_name'] + ' ' + x['last_name'],
    age_group=lambda x: pd.cut(x['age'], bins=[0, 25, 50, 100])
)

الفرز والترتيب

الطريقة	الوصف
`sort_values()`	فرز حسب القيم
`sort_index()`	فرز حسب الفهرس
`nlargest()`	أكبر N من القيم
`nsmallest()`	أصغر N من القيم

أمثلة:

# Sort by single column
result = ds.sort_values('salary', ascending=False)

# Sort by multiple columns
result = ds.sort_values(['department', 'salary'], ascending=[True, False])

# Get top/bottom N
result = ds.nlargest(10, 'salary')
result = ds.nsmallest(5, 'age')

إعادة التشكيل

الطريقة	الوصف
`pivot()`	جدول محوري
`pivot_table()`	جدول محوري مع التجميع
`melt()`	إلغاء التمحور
`stack()`	تكديس الأعمدة في الفهرس
`unstack()`	فك تكديس الفهرس إلى أعمدة
`transpose()` / `T`	منقول
`explode()`	تفكيك القوائم إلى صفوف
`squeeze()`	تقليل الأبعاد
`droplevel()`	حذف مستوى من الفهرس
`swaplevel()`	تبديل مستويات الفهرس
`reorder_levels()`	إعادة ترتيب المستويات

أمثلة:

# Pivot table
result = ds.pivot_table(
    values='amount',
    index='region',
    columns='product',
    aggfunc='sum'
)

# Melt (unpivot)
result = ds.melt(
    id_vars=['name'],
    value_vars=['score1', 'score2', 'score3'],
    var_name='test',
    value_name='score'
)

# Explode arrays
result = ds.explode('tags')

الدمج / الربط

الطريقة	الوصف
`merge()`	دمج بأسلوب SQL
`join()`	ربط باستخدام الفهرس
`concat()`	ربط متسلسل
`append()`	إلحاق صفوف
`combine()`	دمج باستخدام دالة
`combine_first()`	دمج حسب الأولوية
`update()`	تحديث القيم
`compare()`	إظهار الاختلافات

أمثلة:

# Merge (join)
result = pd.merge(df1, df2, on='id', how='left')
result = df1.join(df2, on='id')

# Concatenate
result = pd.concat([df1, df2, df3])
result = pd.concat([df1, df2], axis=1)

العمليات الثنائية

الطريقة	الوصف
`add()` / `radd()`	الجمع
`sub()` / `rsub()`	الطرح
`mul()` / `rmul()`	الضرب
`div()` / `rdiv()`	القسمة
`truediv()` / `rtruediv()`	القسمة الحقيقية
`floordiv()` / `rfloordiv()`	القسمة الصحيحة
`mod()` / `rmod()`	باقي القسمة
`pow()` / `rpow()`	الأس
`dot()`	ضرب المصفوفات

أمثلة:

# Arithmetic operations
result = ds['col1'].add(ds['col2'])
result = ds['price'].mul(ds['quantity'])

# With fill_value for missing data
result = ds['col1'].add(ds['col2'], fill_value=0)

عمليات المقارنة

الطريقة	الوصف
`eq()`	يساوي
`ne()`	لا يساوي
`lt()`	أقل من
`le()`	أقل من أو يساوي
`gt()`	أكبر من
`ge()`	أكبر من أو يساوي
`equals()`	اختبار المساواة
`compare()`	إظهار الاختلافات

تطبيق الدوال

الطريقة	الوصف
`apply()`	تطبيق دالة
`applymap()`	تطبيق على مستوى كل عنصر
`map()`	تعيين القيم
`agg()` / `aggregate()`	التجميع
`transform()`	التحويل
`pipe()`	تمرير الدوال
`groupby()`	التجميع حسب

أمثلة:

# Apply function
result = ds['name'].apply(lambda x: x.upper())
result = ds.apply(lambda row: row['a'] + row['b'], axis=1)

# Aggregate
result = ds.agg({'col1': 'sum', 'col2': 'mean'})
result = ds.agg(['sum', 'mean', 'std'])

# Pipe
result = (ds
    .pipe(filter_active)
    .pipe(calculate_metrics)
    .pipe(format_output)
)

السلاسل الزمنية

الطريقة	الوصف
`rolling()`	نافذة متحركة
`expanding()`	نافذة متزايدة
`ewm()`	موزون أسيًا
`resample()`	إعادة أخذ عينات من السلاسل الزمنية
`shift()`	إزاحة القيم
`asfreq()`	تحويل التردد
`asof()`	أحدث قيمة حتى ذلك الوقت
`at_time()`	التحديد عند وقت
`between_time()`	تحديد النطاق الزمني
`first()` / `last()`	الفترات الأولى/الأخيرة
`to_period()`	تحويل إلى فترة
`to_timestamp()`	تحويل إلى طابع زمني
`tz_convert()`	تحويل المنطقة الزمنية
`tz_localize()`	تعيين المنطقة الزمنية

أمثلة:

# Rolling window
result = ds['value'].rolling(window=7).mean()

# Expanding window
result = ds['value'].expanding().sum()

# Shift
result = ds['value'].shift(1)  # Lag
result = ds['value'].shift(-1)  # Lead

البيانات المفقودة

الطريقة	الوصف
`isna()` / `isnull()`	اكتشاف القيم المفقودة
`notna()` / `notnull()`	اكتشاف القيم غير المفقودة
`dropna()`	حذف القيم المفقودة
`fillna()`	ملء القيم المفقودة
`ffill()`	الملء الأمامي
`bfill()`	الملء الخلفي
`interpolate()`	الاستيفاء
`replace()`	استبدال القيم

طرق الإدخال/الإخراج

الطريقة	الوصف
`to_csv()`	تصدير إلى CSV
`to_json()`	تصدير إلى JSON
`to_excel()`	تصدير إلى Excel
`to_parquet()`	تصدير إلى Parquet
`to_feather()`	تصدير إلى Feather
`to_sql()`	تصدير إلى قاعدة بيانات SQL
`to_pickle()`	Pickle
`to_html()`	جدول HTML
`to_latex()`	جدول LaTeX
`to_markdown()`	جدول Markdown
`to_string()`	تمثيل نصي
`to_dict()`	قاموس
`to_records()`	سجلات
`to_numpy()`	مصفوفة NumPy
`to_clipboard()`	الحافظة

راجع عمليات الإدخال/الإخراج للاطلاع على الوثائق التفصيلية.

التكرار

طريقة	الوصف
`items()`	التكرار عبر (عمود، Series)
`iterrows()`	التكرار عبر (فهرس، Series)
`itertuples()`	التكرار على شكل named tuples

أبرز الاختلافات عن Pandas

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

# Pandas returns Series
pdf['col']  # → pd.Series

# DataStore returns ColumnExpr (lazy)
ds['col']   # → ColumnExpr

2. التنفيذ المؤجل

# DataStore operations are lazy
result = ds.filter(ds['age'] > 25)  # Not executed yet
df = result.to_df()  # Executed here

3. عدم وجود معامل inplace

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

# DataStore (always returns new object)
ds = ds.drop(columns=['col'])

4. مقارنة النتائج

# Use to_pandas() for comparison
pd.testing.assert_frame_equal(
    ds.to_pandas(),
    expected_df
)

راجع الاختلافات الرئيسية للاطلاع على التفاصيل الكاملة.