FORMAT Native التي يديرها العميل، وهي تشمل query وquery_np وquery_df وبدائلها الخاصة ببث الكتل والصفوف، وعمليات الإدراج بما فيها insert_df. أما طرق Arrow فتستخدم FORMAT Arrow ولا تتأثر، وكذلك الاستعلامات الخام وعمليات الإدراج الخام والصيغ غير الأصلية.
برنامج الترميز هذا تجريبي ويُفعَّل اختيارياً، ويبقى برنامج ترميز بايثون هو الافتراضي.
التثبيت
يأتي الـ codec المُصرَّف في حزمة wheel منفصلة باسمclickhouse-connect-core، توفّر وحدة الـ extension _ch_core. ولأغراض التقييم، ثبّت الـ codec وPyArrow معًا:
query_np وquery_df ونسختيهما التدفقيتين وquery(..., use_numpy=True). وبدون PyArrow، يسجّل native_codec="rust" تحذيراً ويُنفّذ تلك الاستعلامات باستخدام برنامج ترميز بايثون، بينما يُثير native_codec="rust_strict" الخطأ NotSupportedError بدلاً من ذلك.
تبقى الحزمة الإضافية rust وحدها خفيفة للتطبيقات التي تستخدم نتائج الصفوف القياسية في بايثون، أو تدفقات كتل الصفوف أو الأعمدة، وعمليات الإدراج دون طلب مخرجات NumPy أو Pandas. فهذه المسارات لا تتطلب PyArrow:
NotSupportedError مع الإشارة إلى أمر التثبيت هذا.
تمكين الـ codec
حدّد الـ codec باستخدام خيار الـ client التاليnative_codec:
يمكن أيضًا ضبط القيمة الافتراضية عبر الإعداد العام
native_codec أو متغير البيئة CLICKHOUSE_CONNECT_NATIVE_CODEC. وترتيب الأسبقية هو: وسيطة الكلمة المفتاحية في العميل، ثم الإعداد العام، ثم متغير البيئة.
يُتجاهل هذا الخيار مع عملاء interface="chdb"، إذ يستخدمون برنامج ترميز بايثون دائمًا.
متى تستخدم برنامج ترميز Rust
يكون برنامج ترميز 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" أثناء القياس بحيث يُثار استثناء عند وجود خيار غير مدعوم أو اعتمادية مفقودة، بدلًا من توجيه الاستعلام إلى بايثون بصمت.
قواعد الاحتياط
تُتَّخذ قرارات الاحتياط (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. يعلن driver عن نطاق التوافق عبر الإضافة rust، وتصدّر الوحدة إصدار واجهة برمجة تطبيقات binding الذي يتحقق منه driver عند اختيار برنامج ترميز Rust. وإذا كانت الحزمة (wheel) المثبّتة أقدم من أن يدعمها driver، فإن إنشاء العميل يثير NotSupportedError مع ذكر أمر الترقية:
clickhouse-connect-core، ويمكن الحصول عليها بترقية (upgrade) حزمة wheel الأساسية إلى إصدار متوافق. أما التغييرات على تكامل driver مع Rust فتتطلب ترقية clickhouse-connect.
اختلافات سلوكية معروفة
يهدف برنامج ترميز 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 وكقيمة ثنائية من بايثون.