> ## 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

يوفّر DataStore تحسينات ملحوظة في الأداء مقارنةً بـ pandas في كثير من العمليات. يوضّح هذا الدليل سبب ذلك وكيفية تحسين أحمال العمل لديك.

<div id="why-faster">
  ## لماذا DataStore أسرع
</div>

<div id="sql-pushdown">
  ### 1. SQL Pushdown
</div>

تُنفَّذ العمليات مباشرةً في مصدر البيانات:

```python theme={null}
# pandas: Loads ALL data, then filters in memory
df = pd.read_csv("huge.csv")       # Load 10GB
df = df[df['year'] == 2024]        # Filter in Python

# DataStore: Filter at source
ds = pd.read_csv("huge.csv")       # Just metadata
ds = ds[ds['year'] == 2024]        # Filter in SQL
df = ds.to_df()                    # Only load filtered data
```

<div id="column-pruning">
  ### 2. استبعاد الأعمدة
</div>

لا تُقرأ إلا الأعمدة المطلوبة:

```python theme={null}
# DataStore: Only reads name, age columns
ds = pd.read_parquet("wide_table.parquet")
result = ds.select('name', 'age').to_df()

# vs pandas: Reads all 100 columns, then selects
```

<div id="lazy-evaluation">
  ### 3. التنفيذ الكسول
</div>

تُحوَّل عمليات متعددة إلى استعلام واحد:

```python theme={null}
# DataStore: One optimized SQL query
result = (ds
    .filter(ds['amount'] > 100)
    .groupby('region')
    .agg({'amount': 'sum'})
    .sort('sum', ascending=False)
    .head(10)
    .to_df()
)

# Becomes:
# SELECT region, SUM(amount) FROM data
# WHERE amount > 100
# GROUP BY region ORDER BY sum DESC LIMIT 10
```

***

<div id="benchmark">
  ## اختبار الأداء: DataStore مقابل pandas
</div>

<div id="test-environment">
  ### بيئة الاختبار
</div>

* البيانات: 10 ملايين صف
* العتاد: حاسوب محمول عادي
* صيغة الملف: CSV

<div id="results">
  ### النتائج
</div>

| العملية                          | pandas (مللي ثانية) | DataStore (مللي ثانية) | الفائز                 |
| -------------------------------- | ------------------- | ---------------------- | ---------------------- |
| عدد GroupBy                      | 347                 | 17                     | **DataStore (19.93x)** |
| عمليات مجمّعة                    | 1,535               | 234                    | **DataStore (6.56x)**  |
| pipeline معقّدة                  | 2,047               | 380                    | **DataStore (5.39x)**  |
| Filter متعدد+Sort+Head           | 1,963               | 366                    | **DataStore (5.36x)**  |
| Filter+Sort+Head                 | 1,537               | 350                    | **DataStore (4.40x)**  |
| Head/Limit                       | 166                 | 45                     | **DataStore (3.69x)**  |
| فائق التعقيد (أكثر من 10 عمليات) | 1,070               | 338                    | **DataStore (3.17x)**  |
| تجميع GroupBy                    | 406                 | 141                    | **DataStore (2.88x)**  |
| Select+Filter+Sort               | 1,217               | 443                    | **DataStore (2.75x)**  |
| Filter+GroupBy+Sort              | 466                 | 184                    | **DataStore (2.53x)**  |
| Filter+Select+Sort               | 1,285               | 533                    | **DataStore (2.41x)**  |
| Sort (مفرد)                      | 1,742               | 1,197                  | **DataStore (1.45x)**  |
| Filter (مفرد)                    | 276                 | 526                    | متقارب                 |
| Sort (متعدد)                     | 947                 | 1,477                  | متقارب                 |

<div id="insights">
  ### أبرز الاستنتاجات
</div>

1. **عمليات GroupBy**: DataStore أسرع بما يصل إلى **19.93x**
2. **مسارات المعالجة المعقدة**: DataStore أسرع بمقدار **5-6x** (ميزة SQL pushdown)
3. **عمليات التقطيع البسيطة**: الأداء متقارب - والفارق ضئيل
4. **أفضل حالة استخدام**: العمليات متعددة الخطوات مع GroupBy/التجميع
5. **Zero-copy**: لا يفرض `to_df()` أي عبء إضافي لتحويل البيانات

***

<div id="when-datastore-wins">
  ## متى يكون DataStore هو الخيار الأفضل
</div>

<div id="heavy-aggregations">
  ### التجميعات المكثفة
</div>

```python theme={null}
# DataStore excels: 19.93x faster
result = ds.groupby('category')['amount'].sum()
```

<div id="complex-pipelines">
  ### مسارات المعالجة المعقدة
</div>

```python theme={null}
# DataStore excels: 5-6x faster
result = (ds
    .filter(ds['date'] >= '2024-01-01')
    .filter(ds['amount'] > 100)
    .groupby('region')
    .agg({'amount': ['sum', 'mean', 'count']})
    .sort('sum', ascending=False)
    .head(20)
)
```

<div id="large-file-processing">
  ### معالجة الملفات الكبيرة
</div>

```python theme={null}
# DataStore: Only loads what you need
ds = pd.read_parquet("huge_file.parquet")
result = ds.filter(ds['id'] == 12345).to_df()  # Fast!
```

<div id="multiple-column-operations">
  ### عمليات على عدة أعمدة
</div>

```python theme={null}
# DataStore: Combines into single SQL
ds['total'] = ds['price'] * ds['quantity']
ds['is_large'] = ds['total'] > 1000
ds = ds.filter(ds['is_large'])
```

***

<div id="when-pandas-wins">
  ## متى يكون pandas منافسًا
</div>

في معظم الحالات، يضاهي DataStore أداء pandas أو يتفوق عليه. ومع ذلك، قد يكون pandas أسرع قليلًا في الحالات التالية:

<div id="small-datasets">
  ### مجموعات بيانات صغيرة (\<1,000 صف)
</div>

```python theme={null}
# For very small datasets, overhead is minimal for both
# Performance difference is negligible
small_df = pd.DataFrame({'x': range(100)})
```

<div id="simple-slice-operations">
  ### عمليات التقطيع البسيطة
</div>

```python theme={null}
# Single slice operations without aggregation
df = df[df['x'] > 10]  # pandas slightly faster
ds = ds[ds['x'] > 10]  # DataStore comparable
```

<div id="custom-python-functions">
  ### دوال لامبدا مخصّصة بلغة بايثون
</div>

```python theme={null}
# pandas required for custom Python code
def complex_function(row):
    return custom_logic(row)

df['result'] = df.apply(complex_function, axis=1)
```

<Info>
  **مهم**

  حتى في الحالات التي يكون فيها DataStore "أبطأ"، يكون الأداء عادةً **مماثلًا لأداء pandas** - والفارق لا يكاد يُذكر عمليًا. كما أن مزايا DataStore في العمليات المعقدة تفوق هذه الحالات الطرفية بكثير.

  للتحكم الدقيق في التنفيذ، راجع [إعدادات محرك التنفيذ](/docs/ar/chdb/configuration/execution-engine).
</Info>

***

<div id="zero-copy">
  ## تكامل DataFrame بتقنية zero-copy
</div>

يستخدم DataStore تقنية **zero-copy** لقراءة pandas DataFrames وكتابتها. وهذا يعني:

```python theme={null}
# to_df() does NOT copy data - it's a zero-copy operation
result = ds.filter(ds['x'] > 10).to_df()  # No data conversion overhead

# Same for creating DataStore from DataFrame
ds = DataStore(existing_df)  # No data copy
```

**النتائج الرئيسية:**

* `to_df()` عمليًا بلا تكلفة - من دون تسلسل أو نسخ للذاكرة
* إنشاء DataStore من pandas DataFrame يتم فورًا
* الذاكرة مشتركة بين DataStore وpandas views

***

<div id="tips">
  ## نصائح لتحسين الأداء
</div>

<div id="use-performance-mode">
  ### 1. فعِّل وضع الأداء لأحمال العمل المكثفة
</div>

بالنسبة إلى أحمال العمل التي تكثر فيها عمليات التجميع ولا تحتاج فيها إلى تنسيق مخرجات pandas الدقيق (ترتيب الصفوف، أعمدة MultiIndex، وتصحيحات نوع البيانات)، فعِّل وضع الأداء لتحقيق أقصى إنتاجية:

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

config.use_performance_mode()

# Now all operations use SQL-first execution with no pandas overhead:
# - Parallel Parquet reading (no preserve_order)
# - Single-SQL aggregation (filter+groupby in one query)
# - No row-order preservation overhead
# - No MultiIndex, no dtype corrections
result = (ds
    .filter(ds['amount'] > 100)
    .groupby('region')
    .agg({'amount': ['sum', 'mean', 'count']})
)
```

**التحسّن المتوقع**: سرعة أعلى بما يصل إلى 2-8 مرات في أعباء عمل filter+groupby، مع تقليل استخدام الذاكرة عند التعامل مع ملفات Parquet الكبيرة.

راجع [وضع الأداء](/docs/ar/chdb/configuration/performance-mode) للاطلاع على التفاصيل الكاملة.

<div id="use-parquet">
  ### 2. استخدم Parquet بدلًا من CSV
</div>

```python theme={null}
# CSV: Slower, reads entire file
ds = pd.read_csv("data.csv")

# Parquet: Faster, columnar, compressed
ds = pd.read_parquet("data.parquet")

# Convert once, benefit forever
df = pd.read_csv("data.csv")
df.to_parquet("data.parquet")
```

**التحسّن المتوقع**: قراءة أسرع بمقدار 3-10x

<div id="filter-early">
  ### 3. نفّذ التصفية مبكرًا
</div>

```python theme={null}
# Good: Filter first, then aggregate
result = (ds
    .filter(ds['date'] >= '2024-01-01')  # Reduce data early
    .groupby('category')['amount'].sum()
)

# Less optimal: Process all data
result = (ds
    .groupby('category')['amount'].sum()
    .filter(ds['sum'] > 1000)  # Filter too late
)
```

<div id="select-only-needed-columns">
  ### 4. حدّد الأعمدة المطلوبة فقط
</div>

```python theme={null}
# Good: Column pruning
result = ds.select('name', 'amount').filter(ds['amount'] > 100)

# Less optimal: All columns loaded
result = ds.filter(ds['amount'] > 100)  # Loads all columns
```

<div id="leverage-sql-aggregations">
  ### 5. استفد من التجميعات في SQL
</div>

```python theme={null}
# GroupBy is where DataStore shines
# Up to 20x speedup!
result = ds.groupby('category').agg({
    'amount': ['sum', 'mean', 'count', 'max'],
    'quantity': 'sum'
})
```

<div id="use-head">
  ### 6. استخدم الدالة head() بدلًا من الاستعلامات الكاملة
</div>

```python theme={null}
# Don't load entire result if you only need a sample
result = ds.filter(ds['type'] == 'A').head(100)  # LIMIT 100

# Avoid this for large results
# result = ds.filter(ds['type'] == 'A').to_df()  # Loads everything
```

<div id="batch-operations">
  ### 7. العمليات المجمّعة
</div>

```python theme={null}
# Good: Single execution
result = ds.filter(ds['x'] > 10).filter(ds['y'] < 100).to_df()

# Bad: Multiple executions
result1 = ds.filter(ds['x'] > 10).to_df()  # Execute
result2 = result1[result1['y'] < 100]       # Execute again
```

<div id="use-explain">
  ### 8. استخدم explain() لتحسين الأداء
</div>

```python theme={null}
# View the query plan before executing
query = ds.filter(...).groupby(...).agg(...)
query.explain()  # Check if operations are pushed down

# Then execute
result = query.to_df()
```

***

<div id="profiling">
  ## تحليل أداء عبء العمل لديك
</div>

<div id="enable-profiling">
  ### فعّل تحليل الأداء
</div>

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

config.enable_profiling()

# Run your workload
result = your_pipeline()

# View report
profiler = get_profiler()
profiler.report()
```

<div id="identify-bottlenecks">
  ### تحديد نقاط الاختناق
</div>

```text theme={null}
Performance Report
==================
Step                    Duration    % Total
----                    --------    -------
SQL execution           2.5s        62.5%     <- Bottleneck!
read_csv                1.2s        30.0%
Other                   0.3s        7.5%
```

<div id="compare-approaches">
  ### مقارنة النُّهج
</div>

```python theme={null}
# Test approach 1
profiler.reset()
result1 = approach1()
time1 = profiler.get_steps()[-1]['duration_ms']

# Test approach 2
profiler.reset()
result2 = approach2()
time2 = profiler.get_steps()[-1]['duration_ms']

print(f"Approach 1: {time1:.0f}ms")
print(f"Approach 2: {time2:.0f}ms")
```

***

<div id="summary">
  ## ملخص أفضل الممارسات
</div>

| الممارسة                 | الأثر                                         |
| ------------------------ | --------------------------------------------- |
| فعّل وضع الأداء          | أسرع بمقدار 2-8 مرات لأعباء عمل التجميع       |
| استخدم ملفات Parquet     | أسرع بمقدار 3-10 مرات في القراءة              |
| صفِّ البيانات مبكرًا     | تقليل معالجة البيانات                         |
| حدّد الأعمدة المطلوبة    | تقليل عمليات الإدخال/الإخراج واستهلاك الذاكرة |
| استخدم GroupBy/التجميعات | أسرع بما يصل إلى 20 مرة                       |
| استخدم العمليات المجمّعة | تجنّب التنفيذ المتكرر                         |
| حلّل الأداء قبل التحسين  | اعثر على مواضع الاختناق الفعلية               |
| استخدم explain()         | تحقّق من تحسين الاستعلام                      |
| استخدم head() للعينات    | تجنّب المسح الكامل للجدول                     |

***

<div id="decision">
  ## دليل اتخاذ القرار السريع
</div>

| عبء العمل لديك                 | التوصية                        |
| ------------------------------ | ------------------------------ |
| GroupBy/التجميع                | استخدم DataStore               |
| مسار معالجة معقد متعدد الخطوات | استخدم DataStore               |
| ملفات كبيرة مع عوامل تصفية     | استخدم DataStore               |
| عمليات التقطيع البسيطة         | أيٌّ منهما (أداء متقارب)       |
| دوال لامبدا مخصّصة في بايثون   | استخدم pandas أو أجّل التحويل  |
| بيانات صغيرة جدًا (\<1,000 صف) | أيٌّ منهما (فرق يكاد لا يُذكر) |

<Tip>
  للاختيار التلقائي لأفضل محرك تنفيذ، استخدم `config.set_execution_engine('auto')` (الافتراضي).
  لتحقيق أقصى إنتاجية في أعباء عمل التجميع، استخدم `config.use_performance_mode()`.
  راجع [محرك التنفيذ](/docs/ar/chdb/configuration/execution-engine) و[وضع الأداء](/docs/ar/chdb/configuration/performance-mode) لمزيد من التفاصيل.
</Tip>