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

​
التثبيت

يُوزَّع المرمِّز المُصرَّف في حزمة wheel مستقلة باسم clickhouse-connect-core، توفّر وحدة الإضافة _ch_core. ثبّت المرمِّز مع التكاملات التي يستخدمها تطبيقك:
تُنشر حزم wheel الأساسية لإصدارات CPython من 3.10 حتى 3.14، وكذلك لإصدار CPython 3.14t الخالي من قفل GIL (free-threaded)، على أنظمة Linux وmacOS وWindows. وفي إصدارات بايثون الخالية من قفل GIL، لا يؤدي استيراد الامتداد الأساسي إلى إعادة تفعيل GIL. لا يتطلب الإخراج العادي بصيغتي NumPy وPandas المعتمد على Rust مكتبة PyArrow أو أي حزمة Arrow أخرى. ويشمل ذلك query_np وquery_df وبدائلهما المتدفقة، إضافةً إلى query(..., use_numpy=True). كما أن استعلامات NumPy لا تتطلب مكتبة Pandas. أضف مجموعة التبعيات الاختيارية async لاستخدام العميل غير المتزامن. أما طرق Arrow وتخزين Pandas المدعوم بـ Arrow، فلا تزال تتطلب PyArrow. ثبّت مجموعة التبعيات الاختيارية arrow لاستخدام هذه الميزات:
يتبع إخراج string الموسَّع في Pandas خيار mode.string_storage في Pandas. عند تثبيت PyArrow، تستخدم السلاسل النصية تحويل Arrow الحالي، مع تحقق كامل من صحة UTF-8، أيًّا كانت الواجهة الخلفية للتخزين. أما في غياب PyArrow، فيستخدم المشغّل تحويل الكائنات في Rust، ويستخدم التخزين الافتراضي في Pandas سلاسل بايثون النصية. ويؤدي طلب تخزين سلاسل Arrow صراحةً دون تثبيت PyArrow إلى إثارة error تبعية. ويظل UTF-8 غير الصالح يُعرض بالصيغة الست عشرية الحالية أيًّا كانت الواجهة الخلفية للتخزين. يُعدّ المرمِّز وطريقة تحزيمه ومجموعة تبعياته ميزات تجريبية. ويتعامل التحويل المباشر عبر المخازن المؤقتة الآن مع columns الأعداد الصحيحة غير القابلة لقيم NULL بأحجام من 8 إلى 64 بت، وcolumns Float32/64 وBoolean وBFloat16 وInterval وDate وDate32 وDateTime وDateTime64. كما تستخدم columns Time وTime64 المفردة، بما فيها القيم القابلة لـ NULL، المخازن المؤقتة المباشرة، وكذلك columns BFloat16 القابلة لـ NULL وإخراج Pandas الموسَّع للأعداد الصحيحة والعشرية وInterval القابلة لـ NULL. ويحتفظ BFloat16 بإخراج float32 وبسياسة القيم المفقودة الحالية لـ Float32 في Pandas. وتبقى قيم Interval أعدادًا ذات إشارة بالوحدة المُعلنة لها. ويحتفظ التحويل الزمني بالوحدات المُعلنة وبقواعد المنطقة الزمنية الحالية. وأصبحت الأسماء البديلة لـ Time64 من نوع SimpleAggregateFunction القابلة لـ NULL تُرجع الآن مُددًا صحيحة وNaT لقيم NULL. كما تستخدم columns DateTime64(9) المفردة القابلة لـ NULL المخازن المؤقتة للحفاظ على دقة النانوثانية في إخراج NumPy وPandas. أما التواريخ والطوابع الزمنية الأخرى القابلة لـ NULL فتحتفظ بمسارات تحويل الكائنات الخاصة بها. وتستخدم المخازن المؤقتة المباشرة أيضًا مصفوفاتُ Time/Time64، بما فيها المصفوفات المتداخلة والعناصر الطرفية القابلة لـ NULL، وكذلك LowCardinality(Time)، بما فيها القيم القابلة لـ NULL. ويبقى تداخلها ووحدات المدة وتمثيل القيم الفارغة دون تغيير. ولا يزال LowCardinality(Time64) غير مدعوم في نواة Rust. بالنسبة إلى columns DateTime64(9) المفردة القابلة لـ NULL، تحافظ query_df وquery_df_stream على الأرقام الكسرية التسعة كاملةً، بما في ذلك عبر الأسماء البديلة من نوع SimpleAggregateFunction. وفي Pandas 3، أصبحت columns التاريخ والوقت في الإخراج الافتراضي تستخدم وحدات النانوثانية بدلًا من الميكروثانية. ويبقى الاستنتاج الحالي لنوع object في الكتل المكوّنة بالكامل من قيم NULL دون تغيير. وإذا كانت منطقة زمنية مُسمّاة ستجعل قيمةً ما تقع خارج نطاق النانوثانية في Pandas، فإن ذلك الـ column يحتفظ بسلوكه السابق في تحويل الكائنات والتعامل مع النطاق. بالنسبة إلى هذه الـ columns، أصبحت حقول object في query_np وquery_np_stream تحتوي على خلايا numpy.datetime64 بدلًا من خلايا datetime في بايثون، مع None لقيم NULL في SQL. وتستخدم قيم المناطق المُسمّاة نبضات UTC دون بيانات وصفية للمنطقة الزمنية، بما يتوافق مع برنامج ترميز بايثون. ويتيح ذلك الحفاظ على دقة النانوثانية دون الحاجة إلى Pandas. استخدم query_df إذا كنت بحاجة إلى طوابع زمنية تتضمن المنطقة الزمنية. وتبقى أنواع خلايا NumPy الزمنية الأخرى القابلة لـ NULL دون تغيير. ترفض استعلامات NumPy وPandas لـ columns DateTime64 المفردة أي دقة غير 0 و3 و6 و9، وتُثير ProgrammingError، ويشمل ذلك الـ columns القابلة لـ NULL والأسماء البديلة من نوع SimpleAggregateFunction. إذا اختير برنامج ترميز Rust ولم تكن الوحدة المُصرَّفة مثبّتة، فإن إنشاء العميل يُثير NotSupportedError مع الإشارة إلى أمر التثبيت هذا.

​
تمكين الـ codec

حدّد الـ codec باستخدام خيار الـ client التالي native_codec:
القيم المقبولة: يمكن أيضًا ضبط القيمة الافتراضية عبر الإعداد العام native_codec أو متغير البيئة CLICKHOUSE_CONNECT_NATIVE_CODEC. وترتيب الأسبقية هو: وسيطة الكلمة المفتاحية في العميل، ثم الإعداد العام، ثم متغير البيئة. يُتجاهل هذا الخيار مع عملاء interface="chdb"، إذ يستخدمون برنامج ترميز بايثون دائمًا.

​
متى تستخدم مرمِّز Rust

يكون مرمِّز Rust مفيدًا إلى أقصى حد مع نتائج DataFrame الكبيرة التي تتضمن أنواعًا نصية وحاوية وأنواعًا معقدة مثل String وLowCardinality وMap وArray وJSON وDecimal وUUID. كما يمكن أن يفيد تدفقات كتل الصفوف والـ columns الكبيرة، وأعباء عمل الاستعلامات المتزامنة، وعمليات الإدراج المجمّعة. أما النتائج الصغيرة والاستعلامات المقيّدة بالشبكة فقد لا تشهد تغيّرًا يُذكر. كذلك النتائج الرقمية المسطّحة، فهي تستخدم بالفعل مسارات مجمّعة فعّالة في مرمِّز بايثون، ولذلك قد تكون الفائدة منها أقل. تتجنّب المخازن المؤقتة المباشرة إنشاء مصفوفات Arrow وسيطة للأنواع المدعومة. غير أن التجميع النهائي لنتائج NumPy وPandas قد يظل يتطلب تخصيص الذاكرة والنسخ، ولذلك لا يعني هذا أن كل نتيجة استعلام ستصبح خالية من النسخ. في غياب PyArrow، يُنشئ تحويل السلاسل النصية في Rust كائنات نصية في بايثون من كل كتلة مفككة الترميز. ومع أحجام الكتل الافتراضية، تكون ذروة الذاكرة لنتائج String الكبيرة مقاربة لما هي عليه مع مرمِّز بايثون. أما الكتل الكبيرة جدًا، مثل كتلة واحدة تضم مليون صف، فتُبقي الكتلة المفككة الترميز بأكملها في الذاكرة أثناء إنشاء سلاسلها النصية، وقد تبلغ ذروة ذاكرة أعلى مما يبلغه مرمِّز بايثون. وبالنسبة إلى نتائج Pandas StringDtype الكبيرة، ثبّت الإضافة arrow واستخدم تخزين Arrow للسلاسل النصية. يختار Pandas 3 تخزين Arrow افتراضيًا عند تثبيت PyArrow، بينما يتطلب Pandas 2 ضبط pd.options.mode.string_storage = "pyarrow". قد تكون استدعاءات query() المخزَّنة مؤقتًا في الذاكرة أبطأ حاليًا وتستهلك ذروة ذاكرة أعلى مع مرمِّز Rust في حالة النتائج العريضة جدًا أو الرقمية بالكامل. ويُفضَّل استخدام query_df أو query_row_block_stream أو query_column_block_stream مع أعباء العمل هذه. وبالنسبة إلى NumPy وPandas، يمكن أيضًا أن تُسهم query_np_stream وquery_df_stream في خفض ذروة الذاكرة. عالِج كل كتلة ثم حرّرها بدلًا من تجميع الدفق كاملًا. ويظل استهلاك الذاكرة مرهونًا بحجم كل كتلة، لذا فإن بث كتلة واحدة كبيرة لا يحقق الفائدة نفسها. قِس أداء عبء العمل الخاص بك قبل اعتماد المرمِّز. واستخدم native_codec="rust_strict" أثناء القياس بحيث يُثار استثناء عند وجود خيار غير مدعوم أو اعتمادية مفقودة، بدلًا من توجيه الاستعلام إلى بايثون بصمت.

​
قواعد الاحتياط

تُتَّخذ قرارات الاحتياط (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.

​
Versioning

تصدر إصدارات clickhouse-connect-core بشكل مستقل عن clickhouse-connect. تتطلب الإضافة rust الإصدار clickhouse-connect-core>=0.2.1,<0.3. يتحقق المشغّل من كلٍّ من إصدار واجهة برمجة تطبيقات binding وقدرة column-buffer عند اختيار مرمِّز Rust. تفتقر حزمة wheel المنشورة للإصدار الأساسي 0.2.0 إلى قدرة column-buffer. وإذا كانت الحزمة (wheel) المثبّتة غير متوافقة، فإن إنشاء العميل يثير NotSupportedError لكلٍّ من rust وrust_strict، مع أمر الترقية التالي:
تُشحن الإصلاحات وتحسينات الأداء في المرمِّز المُصرَّف ضمن إصدارات (releases) clickhouse-connect-core، ويمكن الحصول عليها بترقية (upgrade) حزمة wheel الأساسية إلى إصدار متوافق. أما التغييرات على تكامل المشغّل مع Rust فتتطلب ترقية clickhouse-connect.

​
اختلافات سلوكية معروفة

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