> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# توافق DataStore مع Pandas

> القائمة الكاملة للطرق المتوافقة مع pandas في DataStore (209 من طرق DataFrame)

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

<div id="approach">
  ## نهج التوافق
</div>

```python theme={null}
# 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`)

***

<div id="attributes">
  ## السمات والخصائص
</div>

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

**أمثلة:**

```python theme={null}
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
```

***

<div id="indexing">
  ## الفهرسة والاختيار
</div>

| الطريقة                | الوصف                          | مثال                                 |
| ---------------------- | ------------------------------ | ------------------------------------ |
| `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')`                      |

***

<div id="statistical">
  ## الطرق الإحصائية
</div>

| الطريقة          | الوصف                | المكافئ في 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()`       | فهرس القيمة العليا   | -              |

**أمثلة:**

```python theme={null}
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'}))
```

***

<div id="manipulation">
  ## معالجة البيانات
</div>

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

**أمثلة:**

```python theme={null}
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])
)
```

***

<div id="sorting">
  ## الفرز والترتيب
</div>

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

**أمثلة:**

```python theme={null}
# 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')
```

***

<div id="reshaping">
  ## إعادة التشكيل
</div>

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

**أمثلة:**

```python theme={null}
# 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')
```

***

<div id="combining">
  ## الدمج / الربط
</div>

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

**أمثلة:**

```python theme={null}
# 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)
```

***

<div id="binary">
  ## العمليات الثنائية
</div>

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

**أمثلة:**

```python theme={null}
# 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)
```

***

<div id="comparison">
  ## عمليات المقارنة
</div>

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

***

<div id="application">
  ## تطبيق الدوال
</div>

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

**أمثلة:**

```python theme={null}
# 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)
)
```

***

<div id="timeseries">
  ## السلاسل الزمنية
</div>

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

**أمثلة:**

```python theme={null}
# 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
```

***

<div id="missing">
  ## البيانات المفقودة
</div>

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

***

<div id="io">
  ## طرق الإدخال/الإخراج
</div>

| الطريقة          | الوصف                      |
| ---------------- | -------------------------- |
| `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()` | الحافظة                    |

راجع [عمليات الإدخال/الإخراج](/docs/ar/chdb/datastore/io) للاطلاع على الوثائق التفصيلية.

***

<div id="iteration">
  ## التكرار
</div>

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

***

<div id="differences">
  ## أبرز الاختلافات عن Pandas
</div>

<div id="return-types">
  ### 1. أنواع القيم المُعادة
</div>

```python theme={null}
# Pandas returns Series
pdf['col']  # → pd.Series

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

<div id="lazy-execution">
  ### 2. التنفيذ المؤجل
</div>

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

<div id="no-inplace-parameter">
  ### 3. عدم وجود معامل inplace
</div>

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

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

<div id="comparing-results">
  ### 4. مقارنة النتائج
</div>

```python theme={null}
# Use to_pandas() for comparison
pd.testing.assert_frame_equal(
    ds.to_pandas(),
    expected_df
)
```

راجع [الاختلافات الرئيسية](/docs/ar/chdb/guides/pandas-differences) للاطلاع على التفاصيل الكاملة.