> ## 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 - auto أو chdb أو pandas

يمكن لـ DataStore تنفيذ العمليات باستخدام محركات خلفية مختلفة. يوضح هذا الدليل كيفية ضبط اختيار محرك التنفيذ وتحسينه.

<div id="engines">
  ## المحركات المتاحة
</div>

| المحرك   | الوصف                                       | الأنسب لـ                                |
| -------- | ------------------------------------------- | ---------------------------------------- |
| `auto`   | يختار تلقائيًا أفضل محرك لكل عملية          | الاستخدام العام (الافتراضي)              |
| `chdb`   | يفرض تنفيذ جميع العمليات عبر ClickHouse SQL | مجموعات البيانات الكبيرة وعمليات التجميع |
| `pandas` | يفرض تنفيذ جميع العمليات عبر pandas         | اختبار التوافق والميزات الخاصة بـ pandas |

<div id="setting">
  ## ضبط المحرك
</div>

<div id="global">
  ### التهيئة العامة
</div>

```python theme={null}
from chdb.datastore.config import config

# Option 1: Using set method
config.set_execution_engine('auto')    # Default
config.set_execution_engine('chdb')    # Force ClickHouse
config.set_execution_engine('pandas')  # Force pandas

# Option 2: Using shortcuts
config.use_auto()     # Auto-select
config.use_chdb()     # Force ClickHouse
config.use_pandas()   # Force pandas
```

<div id="checking">
  ### التحقق من المحرّك الحالي
</div>

```python theme={null}
print(config.execution_engine)  # 'auto', 'chdb', or 'pandas'
```

***

<div id="auto-mode">
  ## الوضع التلقائي
</div>

في وضع `auto` (الافتراضي)، يختار DataStore المحرّك الأنسب لكل عملية:

<div id="auto-chdb">
  ### العمليات المنفذة في chDB
</div>

* التصفية المتوافقة مع SQL (`filter()`, `where()`)
* تحديد الأعمدة (`select()`)
* الفرز (`sort()`, `orderby()`)
* التجميع والعمليات التجميعية (`groupby().agg()`)
* عمليات الربط (`join()`, `merge()`)
* القيم المميزة (`distinct()`, `drop_duplicates()`)
* تحديد العدد (`limit()`, `head()`, `tail()`)

<div id="auto-pandas">
  ### العمليات المُنفَّذة في pandas
</div>

* دوال apply مخصّصة (`apply(custom_func)`)
* جداول محورية معقّدة مع تجميعات مخصّصة
* عمليات لا يمكن التعبير عنها باستخدام SQL
* عندما تكون المدخلات أصلًا `pandas DataFrame`

<div id="auto-example">
  ### مثال
</div>

```python theme={null}
from chdb import datastore as pd
from chdb.datastore.config import config

config.use_auto()  # Default

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

# This uses chDB (SQL)
result = (ds
    .filter(ds['amount'] > 100)   # SQL: WHERE
    .groupby('region')            # SQL: GROUP BY
    .agg({'amount': 'sum'})       # SQL: SUM()
)

# This uses pandas (custom function)
result = ds.apply(lambda row: complex_calculation(row), axis=1)
```

***

<div id="chdb-mode">
  ## وضع chDB
</div>

أجبِر جميع العمليات على المرور عبر ClickHouse SQL:

```python theme={null}
config.use_chdb()
```

<div id="chdb-when">
  ### متى يُستخدم
</div>

* معالجة مجموعات بيانات كبيرة (ملايين الصفوف)
* أعباء تجميع كثيفة
* عندما تريد أقصى استفادة من تحسينات SQL
* سلوك متسق في جميع العمليات

<div id="chdb-performance">
  ### خصائص الأداء
</div>

| نوع العملية                   | الأداء                          |
| ----------------------------- | ------------------------------- |
| GroupBy/التجميع               | ممتاز (أسرع بما يصل إلى 20 مرة) |
| التصفية المعقدة               | ممتاز                           |
| الفرز                         | جيد جدًا                        |
| عوامل التصفية الفردية البسيطة | جيد (مع تكلفة إضافية طفيفة)     |

<div id="chdb-limitations">
  ### القيود
</div>

* قد لا تكون دوال بايثون المخصّصة مدعومة
* تتطلب بعض الخصائص الخاصة بـ pandas إجراء تحويل

***

<div id="pandas-mode">
  ## وضع pandas
</div>

افرض تنفيذ جميع العمليات من خلال pandas:

```python theme={null}
config.use_pandas()
```

<div id="pandas-when">
  ### متى تستخدم pandas
</div>

* اختبار التوافق مع pandas
* استخدام الميزات الخاصة بـ pandas
* استكشاف المشكلات المرتبطة بـ pandas وإصلاحها
* عندما تكون البيانات موجودة بالفعل بصيغة pandas

<div id="chdb-performance">
  ### خصائص الأداء
</div>

| نوع العملية          | الأداء                |
| -------------------- | --------------------- |
| عمليات بسيطة منفردة  | جيد                   |
| دوال مخصصة           | ممتاز                 |
| عمليات تجميع معقدة   | أبطأ من chDB          |
| مجموعات بيانات كبيرة | استهلاك مرتفع للذاكرة |

***

<div id="cross-datastore">
  ## محرك Cross-DataStore
</div>

اضبط المحرك للعمليات التي تجمع أعمدة من وحدات DataStore مختلفة:

```python theme={null}
# Set cross-DataStore engine
config.set_cross_datastore_engine('auto')
config.set_cross_datastore_engine('chdb')
config.set_cross_datastore_engine('pandas')
```

<div id="auto-example">
  ### مثال
</div>

```python theme={null}
ds1 = pd.read_csv("sales.csv")
ds2 = pd.read_csv("inventory.csv")

# This operation involves two DataStores
result = ds1.join(ds2, on='product_id')
# Uses cross_datastore_engine setting
```

***

<div id="selection-logic">
  ## آلية اختيار المحرك
</div>

<div id="decision-tree">
  ### شجرة اتخاذ القرار في الوضع التلقائي
</div>

```text theme={null}
Operation requested
    │
    ├─ Can be expressed in SQL?
    │      │
    │      ├─ Yes → Use chDB
    │      │
    │      └─ No → Use pandas
    │
    └─ Cross-DataStore operation?
           │
           └─ Use cross_datastore_engine setting
```

<div id="function-override">
  ### تجاوز الإعدادات على مستوى الدالة
</div>

يمكن ضبط محرك لبعض الدوال بشكل صريح:

```python theme={null}
from chdb.datastore.config import function_config

# Force specific functions to use specific engine
function_config.use_chdb('length', 'substring')
function_config.use_pandas('upper', 'lower')
```

راجع [إعدادات الدالة](/docs/ar/chdb/configuration/function-config) لمزيد من التفاصيل.

***

<div id="performance-comparison">
  ## مقارنة الأداء
</div>

نتائج الاختبار المعياري على 10 ملايين صف:

| العملية        | pandas (ms) | chdb (ms) | عامل التسريع |
| -------------- | ----------- | --------- | ------------ |
| GroupBy count  | 347         | 17        | 19.93x       |
| عمليات مجمّعة  | 1,535       | 234       | 6.56x        |
| خط معالجة معقد | 2,047       | 380       | 5.39x        |
| تصفية+فرز+Head | 1,537       | 350       | 4.40x        |
| GroupBy agg    | 406         | 141       | 2.88x        |
| تصفية واحدة    | 276         | 526       | 0.52x        |

**أهم الملاحظات:**

* يتفوق chDB في عمليات التجميع وخطوط المعالجة المعقدة
* يكون pandas أسرع قليلًا عند تنفيذ العمليات البسيطة المنفردة
* استخدم وضع `auto` للحصول على أفضل ما في كليهما

***

<div id="best-practices">
  ## أفضل الممارسات
</div>

<div id="start-with-auto-mode">
  ### 1. ابدأ باستخدام الوضع التلقائي
</div>

```python theme={null}
config.use_auto()  # Let DataStore decide
```

<div id="profile-before-forcing">
  ### 2. قِس الأداء قبل الفرض
</div>

```python theme={null}
config.enable_profiling()
# Run your workload
# Check profiler report to see where time is spent
```

<div id="force-engine-for-specific-workloads">
  ### 3. فرض استخدام محرك معيّن لأعباء عمل محددة
</div>

```python theme={null}
# For heavy aggregation workloads
config.use_chdb()

# For pandas compatibility testing
config.use_pandas()
```

<div id="use-explain-to-understand-execution">
  ### 4. استخدم explain() لفهم آلية التنفيذ
</div>

```python theme={null}
ds = pd.read_csv("data.csv")
query = ds.filter(ds['age'] > 25).groupby('city').agg({'salary': 'sum'})

# See what SQL will be generated
query.explain()
```

***

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

<div id="issue-operation-slower">
  ### المشكلة: العملية أبطأ من المتوقع
</div>

```python theme={null}
# Check current engine
print(config.execution_engine)

# Enable debug to see what's happening
config.enable_debug()

# Try forcing specific engine
config.use_chdb()  # or config.use_pandas()
```

<div id="issue-unsupported-operation">
  ### المشكلة: عملية غير مدعومة في وضع chdb
</div>

```python theme={null}
# Some pandas operations aren't supported in SQL
# Solution: use auto mode
config.use_auto()

# Or explicitly convert to pandas first
df = ds.to_df()
result = df.some_pandas_specific_operation()
```

<div id="issue-memory-issues">
  ### المشكلة: مشكلات في الذاكرة عند التعامل مع كميات كبيرة من البيانات
</div>

```python theme={null}
# Use chdb engine to avoid loading all data into memory
config.use_chdb()

# Filter early to reduce data size
result = ds.filter(ds['date'] >= '2024-01-01').to_df()

# For maximum throughput on large datasets, use performance mode
# which enables parallel Parquet reading and single-SQL aggregation
config.use_performance_mode()
```

<Tip>
  **وضع الأداء**

  إذا كنت تشغّل أحمال تجميع كثيفة ولا تحتاج إلى توافق كامل ودقيق مع مخرجات pandas (ترتيب الصفوف، MultiIndex، تصحيحات نوع البيانات)، ففكّر في استخدام [وضع الأداء](/docs/ar/chdb/configuration/performance-mode). يضبط هذا تلقائيًا المحرك على `chdb` ويزيل كل العبء الإضافي المرتبط بتوافق pandas.
</Tip>