الإعدادات العامة
common ذات المستوى الأعلى:
يجب دائمًا تعديل هذه الإعدادات الشائعة
autogenerate_session_id وproduct_name وreadonly قبل إنشاء عميل باستخدام الدالة clickhouse_connect.get_client. إن تغيير هذه الإعدادات بعد إنشاء العميل لا يؤثر في سلوك العملاء الحاليين.| اسم الإعداد | الافتراضي | الخيارات | الوصف |
|---|---|---|---|
| autogenerate_session_id | True | True, False | يُنشئ تلقائيًا معرّف جلسة UUID(1) جديدًا (إذا لم يتم توفيره) لكل session للعميل. وإذا لم يتم توفير معرّف جلسة (إما على مستوى العميل أو query)، فسيُنشئ ClickHouse معرّفًا داخليًا عشوائيًا لكل query. |
| dict_parameter_format | ’json' | 'json’, ‘map’ | يحدد هذا ما إذا كانت queries المعلَّمة تحوّل قاموس بايثون إلى JSON أو إلى صياغة ClickHouse Map. يجب استخدام json لعمليات insert في JSON columns، وmap لأعمدة ClickHouse Map. |
| invalid_setting_action | ’error' | 'drop’, ‘send’, ‘error’ | الإجراء الذي يجب اتخاذه عند تقديم إعداد غير صالح أو readonly (سواء كان ذلك لجلسة العميل أو query). إذا كانت القيمة drop فسيتم تجاهل الإعداد، وإذا كانت send فسيُرسَل الإعداد إلى ClickHouse، وإذا كانت error فسيتم رفع ProgrammingError من جهة العميل. |
| max_connection_age | 600 | الحد الأقصى بالثواني الذي سيظل خلاله اتصال HTTP Keep Alive مفتوحًا أو قابلًا لإعادة الاستخدام. يمنع ذلك تكدس connections على عقدة ClickHouse واحدة خلف load balancer/وكيل. القيمة الافتراضية هي 10 دقائق. | |
| product_name | سلسلة نصية تُمرَّر مع query إلى ClickHouse لتتبّع التطبيق الذي يستخدم ClickHouse Connect. يجب أن تكون بالشكل <اسم المنتج;&gl/<إصدار المنتج>. | ||
| readonly | 0 | 0, 1 | إعدادات ClickHouse “read_only” الضمنية للإصدارات الأقدم من 19.17. يمكن ضبطها لتطابق قيمة ClickHouse “read_only” الخاصة بالإعدادات، بما يسمح بالتشغيل مع إصدارات ClickHouse القديمة جدًا. |
| send_os_user | True | True, False | تضمين مستخدم نظام التشغيل المكتشف ضمن معلومات العميل المُرسلة إلى ClickHouse (سلسلة HTTP User-Agent). |
| send_integration_tags | True | True, False | تضمين مكتبات التكامل المستخدمة وإصداراتها (مثل Pandas/SQLAlchemy/etc.) ضمن معلومات العميل المُرسلة إلى ClickHouse (سلسلة HTTP User-Agent). |
| use_protocol_version | True | True, False | استخدام protocol version الخاص بالعميل. هذا مطلوب لأعمدة المنطقة الزمنية DateTime، لكنه لا يعمل مع الإصدار الحالي من chproxy. |
| max_error_size | 1024 | الحد الأقصى لعدد الأحرف التي ستُعاد في رسائل error الخاصة بالعميل. استخدم القيمة 0 لهذا الإعداد للحصول على رسالة الخطأ الكاملة من ClickHouse. القيمة الافتراضية هي 1024 حرفًا. | |
| http_buffer_size | 10MB | الحجم (بالبايت) للـ buffer “داخل الذاكرة” المستخدم في Streaming Queries عبر HTTP. | |
| preserve_pandas_datetime_resolution | False | True, False | عند ضبطها على True ومع استخدام pandas 2.x، فإنها تحافظ على دقة نوع البيانات datetime64/timedelta64 (مثل ‘s’ و’ms’ و’us’ و’ns’). أما إذا كانت False (أو عند استخدام pandas <2.x)، فسيتم تحويلها إلى دقة النانوثانية (‘ns’) لأغراض التوافق. |
الضغط
enable_http_compression على خادم ClickHouse إلى 1، أو يجب أن يمتلك المستخدم إذنًا بتغيير هذا الإعداد على أساس “لكل استعلام”.
يُتحكَّم في الضغط عبر المَعلمة compress عند استدعاء دالة المصنع clickhouse_connect.get_client. افتراضيًا، تكون compress مضبوطة على True، مما يؤدي إلى تفعيل إعدادات الضغط الافتراضية. بالنسبة إلى الاستعلامات المنفَّذة باستخدام طرق العميل query وquery_np وquery_df، يضيف ClickHouse Connect ترويسة Accept-Encoding مع
ترميزات lz4 وzstd وbr (أي brotli، إذا كانت مكتبة brotli مثبّتة) وgzip وdeflate إلى الاستعلامات المنفَّذة باستخدام طريقة العميل query (وبشكل غير مباشر، query_np وquery_df). (في معظم الطلبات، سيُرجع خادم ClickHouse
حمولة مضغوطة باستخدام zstd.) أما بالنسبة إلى عمليات الإدراج، فيضغط ClickHouse Connect افتراضيًا كتل الإدراج باستخدام ضغط lz4، ويرسل ترويسة HTTP Content-Encoding: lz4.
يمكن أيضًا ضبط المَعلمة compress في get_client على طريقة ضغط محددة، وهي إحدى lz4 أو zstd أو br أو gzip. وعندئذٍ ستُستخدم هذه الطريقة لكلٍّ من عمليات الإدراج ونتائج الاستعلام (إذا كان خادم ClickHouse يدعمها). تُثبَّت الآن مكتبتا الضغط المطلوبتان zstd وlz4 افتراضيًا مع ClickHouse Connect. وإذا جرى تحديد br/brotli، فيجب تثبيت مكتبة brotli بشكل منفصل.
لاحظ أن طرق العميل raw* لا تستخدم الضغط المحدد في إعدادات العميل.
كما نوصي بعدم استخدام ضغط gzip، لأنه أبطأ بكثير من البدائل، سواء في ضغط البيانات أو فك ضغطها.
دعم وكيل HTTP
urllib3. وهي تتعرّف على متغيرَي البيئة القياسيين HTTP_PROXY وHTTPS_PROXY. لاحظ أن استخدام متغيرات البيئة هذه سيُطبَّق على أي عميل يتم إنشاؤه باستخدام الطريقة clickhouse_connect.get_client. وبدلًا من ذلك، لتهيئة كل عميل على حدة، يمكنك استخدام الوسيطتين http_proxy أو https_proxy في الطريقة get_client. وللاطلاع على تفاصيل تنفيذ دعم وكيل HTTP، راجع توثيق urllib3.
لاستخدام وكيل SOCKS، يمكنك تمرير urllib3 SOCKSProxyManager باعتباره الوسيطة pool_mgr إلى get_client. لاحظ أن هذا يتطلب تثبيت مكتبة PySocks، إما مباشرةً أو باستخدام الخيار [socks] لتبعية urllib3.
نوع بيانات JSON “القديم”
Object (أو Object('json')) مُهمَل ويجب تجنّب استخدامه في بيئة الإنتاج. يواصل ClickHouse Connect توفير دعم محدود لهذا النوع من البيانات حفاظًا على التوافق مع الإصدارات السابقة. لاحظ أن هذا الدعم لا يشمل الاستعلامات التي يُتوقع أن تُرجع قيم JSON على “المستوى الأعلى” أو على مستوى “العنصر الأب” على هيئة قواميس أو ما يعادلها، وستؤدي مثل هذه الاستعلامات إلى استثناء.
أنواع البيانات “الجديدة” Variant/Dynamic/JSON (ميزة تجريبية)
clickhouse-connect دعمًا تجريبيًا لأنواع ClickHouse الجديدة — وهي أيضًا تجريبية — وهي Variant وDynamic وJSON.
ملاحظات الاستخدام
- يمكن insert بيانات JSON إما على هيئة قاموس بايثون أو كسلسلة JSON تحتوي على JSON object
{}. ولا تُدعَم الأشكال الأخرى لبيانات JSON. - ستُرجع queries التي تستخدم subcolumns/paths لهذه الأنواع نوع العمود الفرعي.
- راجع الوثائق الرئيسية لـ ClickHouse للاطلاع على ملاحظات استخدام أخرى.
القيود المعروفة
- يجب تمكين كل نوع من هذه الأنواع في إعدادات ClickHouse قبل استخدامه.
- يتوفر نوع JSON “الجديد” بدءًا من إصدار ClickHouse 24.8
- بسبب تغييرات التنسيق الداخلية، لا يتوافق
clickhouse-connectإلا مع أنواع Variant بدءًا من إصدار ClickHouse 24.7 - لن تُرجِع كائنات JSON المُعادة سوى عدد العناصر المحدد في
max_dynamic_paths(والذي تكون قيمته الافتراضية 1024). سيُصلَح هذا في إصدار مستقبلي. - ستكون عمليات الإدراج في أعمدة
Dynamicدائمًا بالتمثيل النصي لقيمة بايثون. سيُصلَح هذا في إصدار مستقبلي، بمجرد إصلاح https://github.com/ClickHouse/ClickHouse/issues/70395. - لم يُحسَّن تنفيذ الأنواع الجديدة في شيفرة C، لذلك قد يكون الأداء أبطأ إلى حد ما مقارنةً بأنواع البيانات الأبسط والأكثر استقرارًا.