> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-postgresql-tls-support.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

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

<div id="summary">
  ## جدول موجز
</div>

| Aspect                  | pandas                   | DataStore                                                                                     |
| ----------------------- | ------------------------ | --------------------------------------------------------------------------------------------- |
| **التنفيذ**             | Eager (فوري)             | Lazy (كسول)                                                                                   |
| **أنواع القيم المعادة** | DataFrame/Series         | DataStore/ColumnExpr                                                                          |
| **ترتيب الصفوف**        | محفوظ                    | محفوظ (تلقائيًا)؛ غير مضمون في [وضع الأداء](/ar/products/chdb/configuration/performance-mode) |
| **inplace**             | مدعوم                    | غير مدعوم                                                                                     |
| **الفهرس**              | دعم كامل                 | مبسّط                                                                                         |
| **الذاكرة**             | جميع البيانات في الذاكرة | البيانات في المصدر                                                                            |

***

<div id="lazy-execution">
  ## 1. التنفيذ الكسول مقابل التنفيذ الفوري
</div>

<div id="pandas-eager">
  ### pandas (فوري)
</div>

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

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

<div id="datastore-lazy">
  ### DataStore (كسول)
</div>

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

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

<div id="why-lazy">
  ### لماذا يُعدّ هذا مهمًا
</div>

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

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

***

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

<div id="pandas-return-types">
  ### pandas
</div>

```python theme={null}
df['col']           # Returns pd.Series
df[['a', 'b']]      # Returns pd.DataFrame
df[df['x'] > 10]    # Returns pd.DataFrame
df.groupby('x')     # Returns DataFrameGroupBy
```

<div id="datastore-return-types">
  ### DataStore
</div>

```python theme={null}
ds['col']           # Returns ColumnExpr (lazy)
ds[['a', 'b']]      # Returns DataStore (lazy)
ds[ds['x'] > 10]    # Returns DataStore (lazy)
ds.groupby('x')     # Returns LazyGroupBy
```

<div id="converting-to-pandas-types">
  ### التحويل إلى أنواع بيانات pandas
</div>

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

***

<div id="triggers">
  ## 3. مشغّلات التنفيذ
</div>

يبدأ 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)` | تحتاج إلى المقارنة         |

<div id="stay-lazy">
  ### العمليات التي تبقى كسولة
</div>

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

***

<div id="row-order">
  ## 4. ترتيب الصفوف
</div>

<div id="pandas-return-types">
  ### pandas
</div>

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

```python theme={null}
df = pd.read_csv("data.csv")
print(df.head())  # Always same order as file
```

<div id="datastore-return-types">
  ### DataStore
</div>

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

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

<div id="order-preserved">
  ### عندما يُحفَظ الترتيب
</div>

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

<div id="order-may-differ">
  ### عندما قد يختلف الترتيب
</div>

* بعد عمليات التجميع باستخدام `groupby()` (استخدم `sort_values()` لضمان اتساق الترتيب)
* بعد `merge()` / `join()` مع بعض أنواع الربط
* في **وضع الأداء** (`config.use_performance_mode()`): لا يكون ترتيب الصفوف مضمونًا في أي عملية. راجع [وضع الأداء](/ar/products/chdb/configuration/performance-mode).

***

<div id="no-inplace">
  ## 5. عدم توفّر المعلمة inplace
</div>

<div id="pandas-return-types">
  ### pandas
</div>

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

<div id="datastore-return-types">
  ### DataStore
</div>

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

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

<div id="why-no-inplace">
  ### لماذا لا يوجد inplace؟
</div>

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

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

***

<div id="index">
  ## 6. دعم الفهارس
</div>

<div id="pandas-return-types">
  ### pandas
</div>

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

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

<div id="datastore-return-types">
  ### DataStore
</div>

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

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

<div id="datastore-source-matters">
  ### نوع مصدر DataStore مهم
</div>

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

***

<div id="comparison">
  ## 7. سلوك عمليات المقارنة
</div>

<div id="comparing-with-pandas">
  ### مقارنةً بـ pandas
</div>

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

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

<div id="using-equals">
  ### استخدام الدالة equals()
</div>

```python theme={null}
# DataStore.equals() also works
dsf.equals(pdf)  # Compares with pandas DataFrame
```

***

<div id="types">
  ## 8. استنتاج النوع
</div>

<div id="pandas-return-types">
  ### pandas
</div>

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

```python theme={null}
df['col'].dtype  # int64, float64, object, datetime64, etc.
```

<div id="datastore-return-types">
  ### DataStore
</div>

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

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

<div id="explicit-casting">
  ### التحويل الصريح للنوع
</div>

```python theme={null}
# Force specific type
ds['col'] = ds['col'].astype('int64')
```

***

<div id="memory">
  ## 9. نموذج الذاكرة
</div>

<div id="pandas-return-types">
  ### pandas
</div>

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

```python theme={null}
df = pd.read_csv("huge.csv")  # 10GB in memory!
```

<div id="datastore-return-types">
  ### DataStore
</div>

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

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

***

<div id="errors">
  ## 10. رسائل الخطأ
</div>

<div id="different-error-sources">
  ### مصادر الأخطاء المختلفة
</div>

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

```python theme={null}
# May see ClickHouse-style errors
# "Code: 62. DB::Exception: Syntax error..."
```

<div id="debugging-tips">
  ### نصائح لاستكشاف الأخطاء وإصلاحها
</div>

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

***

<div id="checklist">
  ## قائمة تحقق الترحيل
</div>

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

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

***

<div id="quick-ref">
  ## مرجع سريع
</div>

| 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)`               | كما هو (يؤدي إلى التنفيذ)      |