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

> برنامج ترميز Rust مُصرَّف اختياري لـ ClickHouse Connect

# برنامج ترميز Rust الأصلي

يستطيع ClickHouse Connect فك ترميز نتائج الاستعلامات وترميز عمليات الإدراج باستخدام برنامج ترميز Rust مُصرَّف بدلاً من التنفيذ الافتراضي القائم على بايثون وCython. ولا ينطبق برنامج ترميز Rust إلا على حركة البيانات بصيغة `FORMAT Native` التي يديرها العميل، وهي تشمل `query` و`query_np` و`query_df` وبدائلها الخاصة ببث الكتل والصفوف، وعمليات الإدراج بما فيها `insert_df`. أما طرق Arrow فتستخدم `FORMAT Arrow` ولا تتأثر، وكذلك الاستعلامات الخام وعمليات الإدراج الخام والصيغ غير الأصلية.

برنامج الترميز هذا تجريبي ويُفعَّل اختيارياً، ويبقى برنامج ترميز بايثون هو الافتراضي.

<h2 id="installation">
  التثبيت
</h2>

يأتي الـ codec المُصرَّف في حزمة wheel منفصلة باسم `clickhouse-connect-core`، توفّر وحدة الـ extension‏ `_ch_core`. ولأغراض التقييم، ثبّت الـ codec وPyArrow معًا:

```bash theme={null}
pip install "clickhouse-connect[rust,arrow]"
```

في الإصدار 1.8، يتطلب كل مسار Rust يُنتج مخرجات NumPy أو Pandas وجود PyArrow. ويشمل ذلك `query_np` و`query_df` ونسختيهما التدفقيتين و`query(..., use_numpy=True)`. وبدون PyArrow، يسجّل `native_codec="rust"` تحذيراً ويُنفّذ تلك الاستعلامات باستخدام برنامج ترميز بايثون، بينما يُثير `native_codec="rust_strict"` الخطأ `NotSupportedError` بدلاً من ذلك.

تبقى الحزمة الإضافية `rust` وحدها خفيفة للتطبيقات التي تستخدم نتائج الصفوف القياسية في بايثون، أو تدفقات كتل الصفوف أو الأعمدة، وعمليات الإدراج دون طلب مخرجات NumPy أو Pandas. فهذه المسارات لا تتطلب PyArrow:

```bash theme={null}
pip install "clickhouse-connect[rust]"
```

يُعد الـ codec وطريقة تحزيمه ومجموعة اعتمادياته تجريبية جميعها. ويجري حالياً تقييم اعتمادية أصغر حجماً للتوافق مع Arrow لاعتمادها في إصدار مستقبلي.

في حال اختيار برنامج ترميز Rust دون تثبيت الوحدة المُصرَّفة، فإن إنشاء الـ client يثير الاستثناء `NotSupportedError` مع الإشارة إلى أمر التثبيت هذا.

<h2 id="enabling-the-codec">
  تمكين الـ codec
</h2>

حدّد الـ codec باستخدام خيار الـ client التالي `native_codec`:

```python theme={null}
import clickhouse_connect

client = clickhouse_connect.get_client(host="localhost", native_codec="rust")
```

القيم المقبولة:

| Value | السلوك |
| - | - |
| `python` | الافتراضي. برنامج ترميز بايثون وCython الحالي. |
| `rust` | تفضيل برنامج ترميز Rust. تُوجَّه الاستعلامات ذات الخيارات غير المدعومة وعمليات الإدراج ذات الأنواع غير المدعومة إلى برنامج ترميز بايثون. |
| `rust_strict` | إلزام استخدام برنامج ترميز Rust. تؤدي الخيارات والأنواع غير المدعومة إلى إطلاق خطأ بدلًا من إعادة التوجيه. |

يمكن أيضًا ضبط القيمة الافتراضية عبر الإعداد العام `native_codec` أو متغير البيئة `CLICKHOUSE_CONNECT_NATIVE_CODEC`. وترتيب الأسبقية هو: وسيطة الكلمة المفتاحية في العميل، ثم الإعداد العام، ثم متغير البيئة.

يُتجاهل هذا الخيار مع عملاء `interface="chdb"`، إذ يستخدمون برنامج ترميز بايثون دائمًا.

<h2 id="when-to-use-the-rust-codec">
  متى تستخدم برنامج ترميز Rust
</h2>

يكون برنامج ترميز Rust مفيدًا إلى أقصى حد مع نتائج DataFrame الكبيرة التي تتضمن أنواعًا نصية وحاوية وأنواعًا معقدة مثل `String` و`LowCardinality` و`Map` و`Array` و`JSON` و`Decimal` و`UUID`. كما يمكن أن يفيد تدفقات كتل الصفوف والأعمدة الكبيرة، وأحمال عمل الاستعلامات المتزامنة، وعمليات الإدراج المجمّعة.

أما النتائج الصغيرة والاستعلامات المقيّدة بالشبكة فقد لا تشهد تغيّرًا يُذكر. كذلك النتائج الرقمية المسطّحة، فهي تستخدم بالفعل مسارات مجمّعة فعّالة في برنامج ترميز بايثون، ولذلك قد تكون الفائدة منها أقل.

قد تكون استدعاءات `query()` المخزَّنة مؤقتًا في الذاكرة أبطأ حاليًا وتستهلك ذروة ذاكرة أعلى مع برنامج ترميز Rust في حالة النتائج العريضة جدًا أو الرقمية بالكامل. ويُفضَّل استخدام `query_df` أو `query_row_block_stream` أو `query_column_block_stream` مع أحمال العمل هذه، إذ يُبقي البث استهلاك الذاكرة ضمن حدود معلومة.

قِس أداء حمل العمل الخاص بك قبل اعتماد الـ codec. واستخدم `native_codec="rust_strict"` أثناء القياس بحيث يُثار استثناء عند وجود خيار غير مدعوم أو اعتمادية مفقودة، بدلًا من توجيه الاستعلام إلى بايثون بصمت.

<h2 id="fallback-rules">
  قواعد الاحتياط
</h2>

تُتَّخذ قرارات الاحتياط (fallback) قبل قراءة أي بايتات أو إرسالها، لذا لا يحدث تبديل للـ codec في منتصف الـ stream مطلقًا. ففي حالة الـ queries يجري الاختيار قبل استهلاك جسم الاستجابة، أما في حالة الـ inserts فلا يُختار مُرمِّز Rust إلا إذا كانت جميع أنواع الأعمدة مدعومة، وإلا نُفِّذت عملية الـ insert بأكملها باستخدام برنامج ترميز بايثون.

عند تفعيل `naive_datetime_insert="server"`، يوجّه `rust` أي عملية insert تحتوي على عمود من نوع `DateTime` أو `DateTime64` إلى برنامج ترميز بايثون، بحيث يُطبَّق الـ timezone المعلن للعمود أو server timezone. أما `rust_strict` فيرفض هذا المزيج، بينما يواصل الوضع الافتراضي `naive_datetime_insert="local"` استخدام مُرمِّز Rust.

أما استعلامات الـ metadata الداخلية للـ driver، بما في ذلك عبارات reflection الخاصة بـ dialect في SQLAlchemy، فتستخدم برنامج ترميز بايثون دائمًا وبصمت، في جميع الأوضاع.

وتؤدي payloads الـ Native المشوّهة التي يكتشفها برنامج ترميز Rust إلى إطلاق `DataError`.

<h2 id="versioning">
  Versioning
</h2>

تصدر إصدارات `clickhouse-connect-core` بشكل مستقل عن `clickhouse-connect`. يعلن driver عن نطاق التوافق عبر الإضافة `rust`، وتصدّر الوحدة إصدار واجهة برمجة تطبيقات binding الذي يتحقق منه driver عند اختيار برنامج ترميز Rust. وإذا كانت الحزمة (wheel) المثبّتة أقدم من أن يدعمها driver، فإن إنشاء العميل يثير `NotSupportedError` مع ذكر أمر الترقية:

```bash theme={null}
pip install --upgrade clickhouse-connect-core
```

تُشحن الإصلاحات وتحسينات الأداء في المرمِّز المُصرَّف ضمن إصدارات (releases) `clickhouse-connect-core`، ويمكن الحصول عليها بترقية (upgrade) حزمة wheel الأساسية إلى إصدار متوافق. أما التغييرات على تكامل driver مع Rust فتتطلب ترقية `clickhouse-connect`.

<h2 id="known-behavior-differences">
  اختلافات سلوكية معروفة
</h2>

يهدف برنامج ترميز Rust إلى تحقيق تطابق خلية بخلية مع برنامج ترميز بايثون. وفيما يلي الاختلافات المعروفة.

* تحتوي نتائج `query_np` و`query_df` لأعمدة `Variant` على كائنات بايثون عادية بدلاً من قيم scalar من numpy. القيم متساوية، لكن أنواع الخلايا تختلف.
* قيم `Dynamic` التي تحتوي على `Time64` تُجسَّد على هيئة `datetime.timedelta` في نتائج `query_np` و`query_df` عبر Rust. عند المقاييس 0 و3 و6 و9 تساوي القيمُ خلايا `numpy.timedelta64` الناتجة عن برنامج ترميز بايثون، لكن أنواع الخلايا تختلف. أما عند المقاييس الأخرى فيُرجع برنامج ترميز Rust قيمة `datetime.timedelta`، بينما يُثير برنامج ترميز بايثون `ProgrammingError` لعدم وجود وحدة مطابقة في NumPy. ولا تُتاح metadata أعضاء Dynamic لـ driver بعد فك الترميز في Rust، لذا استخدم `native_codec="python"` عند الحاجة إلى أنواع خلايا NumPy أو إلى validation للمقاييس غير المدعومة.
* في حالة `query_df`، قد يحوّل برنامج ترميز بايثون القيم Compound المخزَّنة في shared data داخل JSON إلى نصوص، في حين يُرجع برنامج ترميز Rust كائنات مفكوكة الترميز، بما يطابق نتائج `query_np` في كلا الـ codecs.
* ينتج عن البديل `LowCardinality` داخل حاوية تُجسَّد لكل خلية، مثل `Array(Variant(...))`، خلايا متساوية القيمة لا تتشارك هوية الكائن لكل slot في الـ dictionary كما يحدث مع برنامج ترميز بايثون.
* تُفكّ ترميز أعمدة `Nullable(Tuple(...))` التي تضم عنصراً واحداً أو أكثر بشكل صحيح على برنامج ترميز Rust، بينما يقرأ برنامج ترميز بايثون هذا الـ layout قراءةً خاطئة، وتُعد نتيجة Rust هي السلوك المرجعي. ويدعم كلا الـ codecs النوع `Nullable(Tuple())`.
* يرفض `rust_strict` خيارات الـ query التي لا يُنفّذها مسار Rust، مثل `query_formats` المخصصة لكل query، بدلاً من تغيير السلوك بصمت.
* قد تُثير أخطاء التحويل والـ validation عند الـ insert في Rust استثناء `DataError` حيث يُثير برنامج ترميز بايثون `ValueError`، وقد يختلف نص الرسالة. ومن الأمثلة على ذلك قيم `Time` و`Time64` غير الصالحة، وعناوين IPv6، وأبعاد QBit، وأطوال `FixedString`، ونصوص `Float64`، ومحاولات إدراج elements في عمود `Tuple()`.
* يرفض المُرمِّز في Rust القيمة `b""` لـ `FixedString(N)` والنصوص الرقمية مثل `"2"` لأعمدة الأعداد الصحيحة، في حين يملأ برنامج ترميز بايثون قيمة `FixedString` الفارغة بالأصفار ويُحوّل النصوص الرقمية قسراً.
* يفك برنامج ترميز Rust ترميز بعض قيم `Dynamic` من نوع shared-variant إلى أنواع بايثون المقابلة، حيث يُبقي برنامج ترميز بايثون القيمة على شكل raw bytes. فعلى سبيل المثال، قد تُرجَع قيمة `Date` مخزَّنة على هيئة `datetime.date` من Rust وكقيمة ثنائية من بايثون.