الاستخدام المتقدم

واجهة برمجة التطبيقات الخام

في حالات الاستخدام التي لا تتطلب إجراء تحويل بين بيانات ClickHouse وأنواع البيانات وبُناها الأصلية أو التابعة لجهات خارجية، يوفّر عميل ClickHouse Connect طرائق تتيح الاستخدام المباشر لاتصال ClickHouse.

طريقة `raw_query` الخاصة بـ `Client`

تتيح طريقة Client.raw_query استخدام واجهة الاستعلام عبر HTTP في ClickHouse مباشرةً من خلال اتصال العميل. وتكون القيمة المعادة كائن bytes غير معالَج. كما توفّر غلافًا عمليًا يتضمن ربط المعلمات، ومعالجة الأخطاء، وإعادة المحاولة، وإدارة الإعدادات عبر واجهة مبسطة:

Parameter	Type	Default	Description
query	str	Required	أي استعلام ClickHouse صالح
parameters	dict or iterable	None	راجع وصف parameters.
settings	dict	None	راجع وصف settings.
fmt	str	None	تنسيق الإخراج في ClickHouse للبايتات الناتجة. (يستخدم ClickHouse تنسيق TSV إذا لم يتم تحديده)
use_database	bool	True	استخدام قاعدة البيانات المعيّنة لعميل ClickHouse Connect ضمن سياق الاستعلام
external_data	ExternalData	None	كائن ExternalData يحتوي على بيانات ملف أو بيانات ثنائية لاستخدامها مع الاستعلام. راجع الاستعلامات المتقدمة (البيانات الخارجية)

تقع على عاتق المستدعي مسؤولية التعامل مع كائن 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 باستخدام اتصال العميل. ونظرًا إلى أنها لا تُجري أي معالجة لحمولة الإدراج، فهي تتمتع بأداء عالٍ جدًا. وتوفّر الطريقة خيارات لتحديد settings وتنسيق الإدراج:

Parameter	Type	Default	Description
table	str	Required	اسم الجدول البسيط أو اسم الجدول المؤهل باسم قاعدة البيانات
column_names	Sequence[str]	None	أسماء الأعمدة الخاصة بـ insert block. وهي مطلوبة إذا كانت المعلمة `fmt` لا تتضمن الأسماء
insert_block	str, bytes, Generator[bytes], BinaryIO	Required	البيانات المراد إدراجها. سيتم ترميز السلاسل النصية باستخدام ترميز العميل.
settings	dict	None	راجع وصف settings.
fmt	str	None	تنسيق الإدخال في ClickHouse لبايتات `insert_block`. (يستخدم ClickHouse تنسيق TSV إذا لم يتم تحديده)

تقع على عاتق المستدعي مسؤولية التأكد من أن insert_block بالتنسيق المحدد ويستخدم طريقة الضغط المحددة. ويستخدم ClickHouse Connect عمليات الإدراج الخام هذه لرفع الملفات وPyArrow Tables، مع تفويض عملية التحليل إلى خادم ClickHouse.

حفظ نتائج الاستعلامات كملفات

يمكنك تمرير الملفات مباشرةً من ClickHouse إلى نظام الملفات المحلي باستخدام الطريقة raw_stream. على سبيل المثال، إذا كنت ترغب في حفظ نتيجة استعلام في ملف CSV، فيمكنك استخدام مقتطف الشيفرة التالي:

import clickhouse_connect

if __name__ == '__main__':
    client = clickhouse_connect.get_client()
    query = 'SELECT number, toString(number) AS number_as_str FROM system.numbers LIMIT 5'
    fmt = 'CSVWithNames'  # or CSV, or CSVWithNamesAndTypes, or TabSeparated, etc.
    stream = client.raw_stream(query=query, fmt=fmt)
    with open("output.csv", "wb") as f:
        for chunk in stream:
            f.write(chunk)

تنتج الشيفرة أعلاه ملف output.csv بالمحتوى التالي:

"number","number_as_str"
0,"0"
1,"1"
2,"2"
3,"3"
4,"4"

وبالمثل، يمكنك حفظ البيانات بتنسيق TabSeparated أو بتنسيقات أخرى. راجع تنسيقات بيانات الإدخال والإخراج للحصول على نظرة عامة على جميع خيارات التنسيق المتاحة.

حالات الاستخدام متعددة الخيوط ومتعددة العمليات وغير المتزامنة/المعتمدة على الأحداث

يعمل ClickHouse Connect بكفاءة في التطبيقات متعددة الخيوط ومتعددة العمليات والتطبيقات غير المتزامنة/المعتمدة على حلقات الأحداث. تجري جميع عمليات معالجة الاستعلامات والإدراج داخل خيط واحد، لذا تكون العمليات عمومًا آمنة على مستوى الخيوط. (وقد تُضاف مستقبلًا إمكانية المعالجة المتوازية لبعض العمليات على مستوى منخفض لتجاوز تراجع الأداء الناتج عن الاعتماد على خيط واحد، ولكن حتى في هذه الحالة ستظل السلامة على مستوى الخيوط محفوظة.) ولأن كل استعلام أو عملية إدراج تُنفَّذ تحتفظ بالحالة في كائن QueryContext أو InsertContext الخاص بها، على الترتيب، فإن هذه الكائنات المساعدة ليست آمنة على مستوى الخيوط، ولا ينبغي مشاركتها بين مسارات معالجة متعددة. راجع أيضًا المناقشة الإضافية حول كائنات السياق في قسمي سياقات الاستعلام وسياقات الإدراج. بالإضافة إلى ذلك، في التطبيقات التي يكون فيها استعلامان و/أو عمليتا إدراج أو أكثر “قيد التنفيذ” في الوقت نفسه، هناك اعتباران إضافيان ينبغي أخذهما في الحسبان. الأول هو “الجلسة” في ClickHouse المرتبطة بالاستعلام/الإدراج، والثاني هو مجمع اتصالات HTTP الذي تستخدمه نُسخ ClickHouse Connect Client.

طبقة تغليف AsyncClient

يوفّر ClickHouse Connect طبقة تغليف غير متزامنة للعميل العادي Client، ما يتيح استخدام العميل في بيئة asyncio. للحصول على مثيل من AsyncClient، يمكنك استخدام دالة الإنشاء get_async_client، التي تقبل المعلمات نفسها التي تقبلها الدالة القياسية get_client:

import asyncio

import clickhouse_connect

async def main():
    client = await clickhouse_connect.get_async_client()
    result = await client.query("SELECT name FROM system.databases LIMIT 1")
    print(result.result_rows)
    # Output:
    # [('INFORMATION_SCHEMA',)]

asyncio.run(main())

يحتوي AsyncClient على نفس الطرائق وبنفس المَعلمات الموجودة في Client القياسي، لكنها تكون coroutines عند الاقتضاء. داخليًا، تُغلَّف طرائق Client التي تُجري عمليات I/O داخل استدعاء run_in_executor. سيتحسن الأداء متعدد الخيوط عند استخدام الغلاف AsyncClient، لأن خيوط التنفيذ وGIL يُحرَّران أثناء انتظار اكتمال عمليات I/O. ملاحظة: بخلاف Client العادي، يفرض AsyncClient أن تكون القيمة الافتراضية لـ autogenerate_session_id هي False. راجع أيضًا: مثال run_async.

إدارة معرّفات جلسات ClickHouse

يُنفَّذ كل استعلام في ClickHouse ضمن سياق “جلسة” في ClickHouse. وتُستخدم الجلسات حاليًا لغرضين:

لربط إعدادات ClickHouse محددة بعدة استعلامات (راجع إعدادات المستخدم). ويُستخدم أمر ClickHouse SET لتغيير الإعدادات ضمن نطاق جلسة المستخدم.
لتتبّع الجداول المؤقتة.

بشكل افتراضي، يستخدم كل استعلام يُنفَّذ عبر مثيل ClickHouse Connect Client معرّف الجلسة الخاص بذلك العميل. وتعمل عبارات SET والجداول المؤقتة كما هو متوقع عند استخدام عميل واحد. ومع ذلك، لا يسمح خادم ClickHouse بتنفيذ استعلامات متزامنة داخل الجلسة نفسها (وسيرفع العميل ProgrammingError إذا تمت محاولة ذلك). بالنسبة إلى التطبيقات التي تنفّذ استعلامات متزامنة، استخدم أحد الأنماط التالية:

أنشئ مثيل Client منفصلًا لكل thread/process/event handler يحتاج إلى عزل الجلسة. يحافظ ذلك على حالة الجلسة لكل عميل (الجداول المؤقتة وقيم SET).
استخدم session_id فريدًا لكل استعلام عبر الوسيطة settings عند استدعاء query أو command أو insert، إذا لم تكن بحاجة إلى حالة جلسة مشتركة.
عطّل الجلسات على عميل مشترك من خلال تعيين autogenerate_session_id=False قبل إنشاء العميل (أو مرّره مباشرةً إلى get_client).

from clickhouse_connect import common
import clickhouse_connect

common.set_setting('autogenerate_session_id', False)  # This should always be set before creating a client
client = clickhouse_connect.get_client(host='somehost.com', user='dbuser', password=1234)

بدلاً من ذلك، مرّر autogenerate_session_id=False مباشرةً إلى get_client(...). في هذه الحالة، لا يرسل ClickHouse Connect قيمة session_id؛ ولا يتعامل الخادم مع الطلبات المنفصلة على أنها تنتمي إلى الجلسة نفسها. ولن تستمر الجداول المؤقتة وإعدادات مستوى الجلسة عبر الطلبات.

تخصيص مجمع اتصالات HTTP

يستخدم ClickHouse Connect مجمعات اتصالات urllib3 لإدارة اتصال HTTP الأساسي بالخادم. وبشكل افتراضي، تشترك جميع مثيلات العميل في مجمع اتصالات HTTP نفسه، وهو ما يكفي لمعظم حالات الاستخدام. ويحافظ هذا المجمع الافتراضي على ما يصل إلى 8 اتصالات HTTP Keep Alive مع كل ClickHouse server يستخدمه التطبيق. بالنسبة إلى التطبيقات الكبيرة متعددة الخيوط، قد يكون من المناسب استخدام مجمعات اتصالات HTTP منفصلة. ويمكن توفير مجمعات اتصالات HTTP مخصّصة كوسيطة keyword ‏pool_mgr للدالة الرئيسية clickhouse_connect.get_client:

import clickhouse_connect
from clickhouse_connect.driver import httputil

big_pool_mgr = httputil.get_pool_manager(maxsize=16, num_pools=12)

client1 = clickhouse_connect.get_client(pool_mgr=big_pool_mgr)
client2 = clickhouse_connect.get_client(pool_mgr=big_pool_mgr)

كما يوضّح المثال أعلاه، يمكن للبرامج العميلة مشاركة مدير مجمّع واحد، أو يمكن إنشاء مدير مجمّع منفصل لكل برنامج عميل. لمزيد من التفاصيل حول الخيارات المتاحة عند إنشاء PoolManager، راجع وثائق urllib3.

بايثون

برامج عميلة تابعة لجهات خارجية

واجهة برمجة التطبيقات الخام

طريقة `raw_query` الخاصة بـ `Client`

طريقة `raw_stream` في Client

الطريقة `raw_insert` في `Client`

حفظ نتائج الاستعلامات كملفات

حالات الاستخدام متعددة الخيوط ومتعددة العمليات وغير المتزامنة/المعتمدة على الأحداث

طبقة تغليف AsyncClient

إدارة معرّفات جلسات ClickHouse

تخصيص مجمع اتصالات HTTP

​واجهة برمجة التطبيقات الخام

​طريقة raw_query الخاصة بـ Client

​طريقة raw_stream في Client

​الطريقة raw_insert في Client

​حفظ نتائج الاستعلامات كملفات

​حالات الاستخدام متعددة الخيوط ومتعددة العمليات وغير المتزامنة/المعتمدة على الأحداث

​طبقة تغليف AsyncClient

​إدارة معرّفات جلسات ClickHouse

​تخصيص مجمع اتصالات HTTP

واجهة برمجة التطبيقات الخام

طريقة `raw_query` الخاصة بـ `Client`

طريقة `raw_stream` في Client

الطريقة `raw_insert` في `Client`

حفظ نتائج الاستعلامات كملفات

حالات الاستخدام متعددة الخيوط ومتعددة العمليات وغير المتزامنة/المعتمدة على الأحداث

طبقة تغليف AsyncClient

إدارة معرّفات جلسات ClickHouse

تخصيص مجمع اتصالات HTTP