واجهة برمجة التطبيقات الخام
الطريقة raw_query في Client
Client.raw_query استخدام واجهة استعلام HTTP الخاصة بـ ClickHouse مباشرةً عبر اتصال العميل. وتكون القيمة المُعادة كائن bytes غير مُعالَج. كما توفّر طبقة تغليف ملائمة مع ربط المعلمات، ومعالجة الأخطاء، وإعادات المحاولة، وإدارة الإعدادات من خلال واجهة مبسطة:
تقع على عاتق المستدعي مسؤولية التعامل مع كائن
bytes الناتج. لاحظ أن Client.query_arrow ليس سوى طبقة تغليف خفيفة حول هذه الطريقة باستخدام تنسيق الإخراج Arrow في ClickHouse.
طريقة raw_stream في Client
Client.raw_stream واجهة برمجة تطبيقات مماثلة للطريقة raw_query، لكنها تُرجع كائن io.IOBase يمكن استخدامه كمصدر تدفق/مولّد لكائنات bytes. وتُستخدم حاليًا في الطريقة query_arrow_stream.
طريقة raw_insert في Client
Client.raw_insert إجراء عمليات إدراج مباشرة لكائنات bytes أو مولدات كائنات bytes باستخدام اتصال العميل. ونظرًا لأنها لا تجري أي معالجة لحمولة الإدراج، فهي عالية الكفاءة جدًا. كما توفّر الطريقة خيارات لتحديد الإعدادات وتنسيق الإدراج:
تقع على عاتق المستدعي مسؤولية التأكد من أن
insert_block بالتنسيق المحدد ويستخدم طريقة الضغط المحددة. ويستخدم ClickHouse Connect عمليات الإدراج الخام هذه لرفع الملفات وجداول PyArrow، مع تفويض التحليل إلى خادم ClickHouse.
حفظ نتائج الاستعلامات كملفات
raw_stream. على سبيل المثال، إذا كنت ترغب في حفظ نتائج استعلام في ملف CSV، فيمكنك استخدام مقتطف الشيفرة التالي:
output.csv بالمحتوى التالي:
حالات الاستخدام متعددة الخيوط، ومتعددة العمليات، وغير المتزامنة/القائمة على حلقة الأحداث
QueryContext أو InsertContext الخاص به، على التوالي، فإن هذه الكائنات المساعدة ليست آمنة على مستوى الخيوط، ولا ينبغي مشاركتها بين عدة تدفقات معالجة. راجع أيضًا المناقشة الإضافية حول كائنات السياق في قسمي QueryContexts وInsertContexts.
إضافةً إلى ذلك، في التطبيق الذي توجد فيه استعلامات و/أو عمليات إدراج، اثنتان أو أكثر، “قيد التنفيذ” في الوقت نفسه، هناك اعتباران إضافيان ينبغي أخذهما في الحسبان. الأول هو “الجلسة” في ClickHouse المرتبطة بالاستعلام/الإدراج، والثاني هو تجمع اتصالات HTTP الذي تستخدمه مثيلات ClickHouse Connect Client.
طبقة تغليف AsyncClient
Client العادي، مما يتيح استخدام العميل في بيئة asyncio.
للحصول على مثيل من AsyncClient، يمكنك استخدام دالة المصنع get_async_client، التي تقبل المعلمات نفسها التي تقبلها get_client القياسية:
AsyncClient نفس الطرق وبنفس المعاملات مثل Client القياسي، لكنها تكون coroutines حيثما ينطبق ذلك. داخليًا، تُغلَّف الطرق في Client التي تُجري عمليات I/O داخل استدعاء run_in_executor.
سيتحسن الأداء متعدد الخيوط عند استخدام طبقة تغليف AsyncClient، إذ سيُحرَّر كلٌّ من خيوط التنفيذ وGIL أثناء انتظار اكتمال عمليات I/O.
ملاحظة: بخلاف Client العادي، يفرض AsyncClient تعيين autogenerate_session_id إلى False افتراضيًا.
راجع أيضًا: مثال run_async.
إدارة معرّفات الجلسات في ClickHouse
- ربط إعدادات ClickHouse محددة بعدة استعلامات (راجع إعدادات المستخدم). ويُستخدم الأمر
SETفي ClickHouse لتغيير الإعدادات ضمن نطاق جلسة المستخدم. - تتبّع الجداول المؤقتة.
Client من ClickHouse Connect معرّف الجلسة الخاص بذلك العميل. تعمل عبارات SET والجداول المؤقتة كما هو متوقع عند استخدام عميل واحد. ومع ذلك، لا يسمح خادم ClickHouse بتنفيذ استعلامات متزامنة ضمن الجلسة نفسها (وسيرفع العميل الخطأ ProgrammingError إذا جرت محاولة ذلك). بالنسبة إلى التطبيقات التي تنفّذ استعلامات متزامنة، استخدم أحد الأنماط التالية:
- أنشئ مثيل
Clientمنفصلًا لكل thread/process/event handler يحتاج إلى عزل للجلسة. يحافظ ذلك على حالة الجلسة الخاصة بكل عميل (الجداول المؤقتة وقيمSET). - استخدم
session_idفريدًا لكل استعلام عبر الوسيطsettingsعند استدعاءqueryأوcommandأوinsert، إذا لم تكن بحاجة إلى حالة جلسة مشتركة. - عطّل الجلسات على عميل مشترك عبر تعيين
autogenerate_session_id=Falseقبل إنشاء العميل (أو مرّره مباشرةً إلىget_client).
autogenerate_session_id=False مباشرةً إلى get_client(...).
في هذه الحالة، لا يرسل ClickHouse Connect قيمة session_id؛ ولا يعتبر الخادم الطلبات المنفصلة جزءًا من الجلسة نفسها. ولن تستمر الجداول المؤقتة وإعدادات مستوى الجلسة عبر الطلبات.
تخصيص مجمع اتصالات HTTP
urllib3 لإدارة اتصال HTTP الأساسي مع الخادم. افتراضيًا، تشترك جميع مثيلات العميل في مجمع الاتصالات نفسه، وهو كافٍ لمعظم حالات الاستخدام. ويحافظ هذا المجمع الافتراضي على ما يصل إلى 8 اتصالات HTTP Keep Alive مع كل خادم ClickHouse يستخدمه التطبيق.
بالنسبة إلى التطبيقات الكبيرة متعددة الخيوط، قد يكون من الأنسب استخدام مجمعات اتصالات منفصلة. ويمكن توفير مجمعات اتصالات مخصّصة عبر وسيط الكلمة المفتاحية pool_mgr للدالة الرئيسية clickhouse_connect.get_client:
PoolManager، راجع وثائق urllib3.