> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> الاستخدام المتقدم مع ClickHouse Connect

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

<div id="raw-api">
  ## واجهة برمجة التطبيقات الخام
</div>

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

<div id="client-rawquery-method">
  ### طريقة `raw_query` الخاصة بـ `Client`
</div>

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

| Parameter      | Type             | Default    | Description                                                                                                                                                                                                |
| -------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| query          | str              | *Required* | أي استعلام ClickHouse صالح                                                                                                                                                                                 |
| parameters     | dict or iterable | *None*     | راجع [وصف parameters](/docs/ar/integrations/language-clients/python/driver-api#parameters-argument).                                                                                                            |
| settings       | dict             | *None*     | راجع [وصف settings](/docs/ar/integrations/language-clients/python/driver-api#settings-argument).                                                                                                                |
| fmt            | str              | *None*     | تنسيق الإخراج في ClickHouse للبايتات الناتجة. (يستخدم ClickHouse تنسيق TSV إذا لم يتم تحديده)                                                                                                              |
| use\_database  | bool             | True       | استخدام قاعدة البيانات المعيّنة لعميل ClickHouse Connect ضمن سياق الاستعلام                                                                                                                                |
| external\_data | ExternalData     | *None*     | كائن ExternalData يحتوي على بيانات ملف أو بيانات ثنائية لاستخدامها مع الاستعلام. راجع [الاستعلامات المتقدمة (البيانات الخارجية)](/docs/ar/integrations/language-clients/python/advanced-querying#external-data) |

تقع على عاتق المستدعي مسؤولية التعامل مع كائن `bytes` الناتج. لاحظ أن `Client.query_arrow` ليس سوى غلاف بسيط لهذه الطريقة يستخدم تنسيق الإخراج `Arrow` الخاص بـ ClickHouse.

<div id="client-rawstream-method">
  ### طريقة `raw_stream` في Client
</div>

توفّر الطريقة `Client.raw_stream` واجهة برمجة تطبيقات مماثلة للطريقة `raw_query`، لكنها تُرجع كائن `io.IOBase` يمكن استخدامه كمُولِّد/مصدر تدفق لكائنات `bytes`. ويجري استخدامها حاليًا في الطريقة `query_arrow_stream`.

<div id="client-rawinsert-method">
  ### الطريقة `raw_insert` في `Client`
</div>

تتيح الطريقة `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](/docs/ar/integrations/language-clients/python/driver-api#settings-argument).         |
| fmt           | str                                     | *None*     | تنسيق الإدخال في ClickHouse لبايتات `insert_block`. (يستخدم ClickHouse تنسيق TSV إذا لم يتم تحديده) |

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

<div id="saving-query-results-as-files">
  ## حفظ نتائج الاستعلامات كملفات
</div>

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

```python theme={null}
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` بالمحتوى التالي:

```csv theme={null}
"number","number_as_str"
0,"0"
1,"1"
2,"2"
3,"3"
4,"4"
```

وبالمثل، يمكنك حفظ البيانات بتنسيق [TabSeparated](/docs/ar/reference/formats/TabSeparated/TabSeparated) أو بتنسيقات أخرى. راجع [تنسيقات بيانات الإدخال والإخراج](/docs/ar/reference/formats) للحصول على نظرة عامة على جميع خيارات التنسيق المتاحة.

<div id="multithreaded-multiprocess-and-asyncevent-driven-use-cases">
  ## حالات الاستخدام متعددة الخيوط ومتعددة العمليات وغير المتزامنة/المعتمدة على الأحداث
</div>

يعمل ClickHouse Connect بكفاءة في التطبيقات متعددة الخيوط ومتعددة العمليات والتطبيقات غير المتزامنة/المعتمدة على حلقات الأحداث. تجري جميع عمليات معالجة الاستعلامات والإدراج داخل خيط واحد، لذا تكون العمليات عمومًا آمنة على مستوى الخيوط. (وقد تُضاف مستقبلًا إمكانية المعالجة المتوازية لبعض العمليات على مستوى منخفض لتجاوز تراجع الأداء الناتج عن الاعتماد على خيط واحد، ولكن حتى في هذه الحالة ستظل السلامة على مستوى الخيوط محفوظة.)

ولأن كل استعلام أو عملية إدراج تُنفَّذ تحتفظ بالحالة في كائن `QueryContext` أو `InsertContext` الخاص بها، على الترتيب، فإن هذه الكائنات المساعدة ليست آمنة على مستوى الخيوط، ولا ينبغي مشاركتها بين مسارات معالجة متعددة. راجع أيضًا المناقشة الإضافية حول كائنات السياق في قسمي [سياقات الاستعلام](/docs/ar/integrations/language-clients/python/advanced-querying#querycontexts) و[سياقات الإدراج](/docs/ar/integrations/language-clients/python/advanced-inserting#insertcontexts).

بالإضافة إلى ذلك، في التطبيقات التي يكون فيها استعلامان و/أو عمليتا إدراج أو أكثر "قيد التنفيذ" في الوقت نفسه، هناك اعتباران إضافيان ينبغي أخذهما في الحسبان. الأول هو "الجلسة" في ClickHouse المرتبطة بالاستعلام/الإدراج، والثاني هو مجمع اتصالات HTTP الذي تستخدمه نُسخ ClickHouse Connect Client.

<div id="asyncclient-wrapper">
  ## طبقة تغليف AsyncClient
</div>

يوفّر ClickHouse Connect طبقة تغليف غير متزامنة للعميل العادي `Client`، ما يتيح استخدام العميل في بيئة `asyncio`.

للحصول على مثيل من `AsyncClient`، يمكنك استخدام دالة الإنشاء `get_async_client`، التي تقبل المعلمات نفسها التي تقبلها الدالة القياسية `get_client`:

```python theme={null}
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](https://docs.python.org/3/library/asyncio-eventloop.html#asyncio.loop.run_in_executor).

سيتحسن الأداء متعدد الخيوط عند استخدام الغلاف `AsyncClient`، لأن خيوط التنفيذ وGIL يُحرَّران أثناء انتظار اكتمال عمليات I/O.

ملاحظة: بخلاف `Client` العادي، يفرض `AsyncClient` أن تكون القيمة الافتراضية لـ `autogenerate_session_id` هي `False`.

راجع أيضًا: [مثال run\_async](https://github.com/ClickHouse/clickhouse-connect/blob/main/examples/run_async.py).

<div id="managing-clickhouse-session-ids">
  ## إدارة معرّفات جلسات ClickHouse
</div>

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

* لربط إعدادات ClickHouse محددة بعدة استعلامات (راجع [إعدادات المستخدم](/docs/ar/reference/settings/session-settings)). ويُستخدم أمر ClickHouse `SET` لتغيير الإعدادات ضمن نطاق جلسة المستخدم.
* لتتبّع [الجداول المؤقتة.](/docs/ar/reference/statements/create/table#temporary-tables)

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

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

```python theme={null}
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`؛ ولا يتعامل الخادم مع الطلبات المنفصلة على أنها تنتمي إلى الجلسة نفسها. ولن تستمر الجداول المؤقتة وإعدادات مستوى الجلسة عبر الطلبات.

<div id="customizing-the-http-connection-pool">
  ## تخصيص مجمع اتصالات HTTP
</div>

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

بالنسبة إلى التطبيقات الكبيرة متعددة الخيوط، قد يكون من المناسب استخدام مجمعات اتصالات HTTP منفصلة. ويمكن توفير مجمعات اتصالات HTTP مخصّصة كوسيطة keyword ‏`pool_mgr` للدالة الرئيسية `clickhouse_connect.get_client`:

```python theme={null}
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`](https://urllib3.readthedocs.io/en/stable/advanced-usage.html#customizing-pool-behavior).