> ## 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 لربط بايثون بـ ClickHouse

# مقدمة

يوفّر ClickHouse Connect برنامج تشغيل أساسيًا لقاعدة البيانات يتيح التوافق مع مجموعة واسعة من تطبيقات بايثون.

* الواجهة الرئيسية هي الكائن `Client` في الحزمة `clickhouse_connect.driver`. وتتضمن هذه الحزمة الأساسية أيضًا أصنافًا مساعدة متنوعة ودوالًا خدمية تُستخدم للتواصل مع خادم ClickHouse، بالإضافة إلى تنفيذات "السياق" للإدارة المتقدمة لاستعلامات insert وselect.
* توفّر الحزمة `clickhouse_connect.datatypes` تنفيذًا أساسيًا وأصنافًا فرعية لجميع أنواع بيانات ClickHouse غير التجريبية. وتتمثل وظيفتها الأساسية في تسلسل بيانات ClickHouse وإلغاء تسلسلها إلى التنسيق الثنائي العمودي "Native" الخاص بـ ClickHouse، والمستخدم لتحقيق أعلى كفاءة ممكنة في النقل بين ClickHouse وتطبيقات العميل.
* تعمل أصناف Cython/C في الحزمة `clickhouse_connect.cdriver` على تحسين بعض عمليات التسلسل وإلغاء التسلسل الأكثر شيوعًا، ما يوفّر أداءً أفضل بكثير مقارنةً بـ pure Python.
* توجد لهجة [SQLAlchemy](https://www.sqlalchemy.org/) في الحزمة `clickhouse_connect.cc_sqlalchemy`، وهي مبنية على الحزمتين `datatypes` و`dbi`. ويدعم هذا التنفيذ وظائف SQLAlchemy Core، بما في ذلك استعلامات `SELECT` مع `JOIN`s (`INNER`, `LEFT OUTER`, `FULL OUTER`, `CROSS`)، وعبارات `WHERE`، و`ORDER BY`، و`LIMIT`/`OFFSET`، وعمليات `DISTINCT`، وعبارة `DELETE` خفيفة الوزن مع شروط `WHERE`، وانعكاس الجداول، وعمليات DDL الأساسية (`CREATE TABLE`, `CREATE`/`DROP DATABASE`). وعلى الرغم من أنه لا يدعم ميزات ORM المتقدمة أو ميزات DDL المتقدمة، فإنه يوفّر إمكانات استعلام قوية مناسبة لمعظم أعباء العمل التحليلية على قاعدة بيانات ClickHouse الموجّهة لـ OLAP.
* يُعد برنامج التشغيل الأساسي وتنفيذ [ClickHouse Connect SQLAlchemy](/docs/ar/integrations/language-clients/python/sqlalchemy) الطريقة المفضلة لربط ClickHouse بـ Apache Superset. استخدم اتصال قاعدة البيانات `ClickHouse Connect`، أو سلسلة اتصال لهجة SQLAlchemy ‏`clickhousedb`.

هذه الوثائق محدّثة حتى إصدار clickhouse-connect ‏0.9.2.

<Note>
  يستخدم برنامج تشغيل ClickHouse Connect الرسمي لبايثون بروتوكول HTTP للتواصل مع خادم ClickHouse. يتيح ذلك دعم موازن التحميل HTTP، ويعمل بكفاءة في بيئات المؤسسات التي تستخدم جدران الحماية والوكلاء، لكنه يوفّر ضغطًا وأداءً أقل قليلًا مقارنةً بالبروتوكول الأصلي المعتمد على TCP، كما يفتقر إلى دعم بعض الميزات المتقدمة مثل إلغاء الاستعلامات. في بعض حالات الاستخدام، قد يكون من المناسب استخدام أحد [برامج تشغيل بايثون المجتمعية](/docs/ar/integrations/language-clients/third-party/client-libraries) التي تستخدم البروتوكول الأصلي المعتمد على TCP.
</Note>

<div id="requirements-and-compatibility">
  ## المتطلبات والتوافق
</div>

|     بايثون |    |         المنصة¹ |    |      ClickHouse |    | SQLAlchemy² |    | Apache Superset |    | Pandas |    | Polars |    |
| ---------: | :- | --------------: | :- | --------------: | :- | ----------: | :- | --------------: | :- | -----: | :- | -----: | :- |
| 2.x, \<3.9 | ❌  |     Linux (x86) | ✅  |         \<25.x³ | 🟡 |    \<1.4.40 | ❌  |           \<1.4 | ❌  |   ≥1.5 | ✅  |    1.x | ✅  |
|      3.9.x | ✅  | Linux (Aarch64) | ✅  |           25.x³ | 🟡 |     ≥1.4.40 | ✅  |           1.4.x | ✅  |    2.x | ✅  |        |    |
|     3.10.x | ✅  |     macOS (x86) | ✅  |    25.3.x (LTS) | ✅  |        ≥2.x | ✅  |           1.5.x | ✅  |        |    |        |    |
|     3.11.x | ✅  |     macOS (ARM) | ✅  | 25.6.x (مستقرة) | ✅  |             |    |           2.0.x | ✅  |        |    |        |    |
|     3.12.x | ✅  |         Windows | ✅  | 25.7.x (مستقرة) | ✅  |             |    |           2.1.x | ✅  |        |    |        |    |
|     3.13.x | ✅  |                 |    |    25.8.x (LTS) | ✅  |             |    |           3.0.x | ✅  |        |    |        |    |
|            |    |                 |    | 25.9.x (مستقرة) | ✅  |             |    |                 |    |        |    |        |    |

¹خضع ClickHouse Connect لاختبارات مباشرة على المنصات المدرجة. بالإضافة إلى ذلك، تُبنى `binary wheels` غير المختبرة (مع تحسينات C) لجميع المعماريات التي يدعمها مشروع [`cibuildwheel`](https://cibuildwheel.readthedocs.io/en/stable/) الممتاز. وأخيرًا، بما أن ClickHouse Connect يمكنه أيضًا العمل كـ pure Python، فمن المفترض أن يعمل التثبيت من المصدر على أي تثبيت حديث لبايثون.

²يقتصر دعم SQLAlchemy على وظائف Core (الاستعلامات وDDL الأساسي). ميزات ORM غير مدعومة. راجع وثائق [دعم تكامل SQLAlchemy](/docs/ar/integrations/language-clients/python/sqlalchemy) لمزيد من التفاصيل.

³يعمل ClickHouse Connect عمومًا بشكل جيد مع الإصدارات الواقعة خارج النطاق المدعوم رسميًا.

<div id="installation">
  ## التثبيت
</div>

ثبّت ClickHouse Connect من [PyPI](https://pypi.org/project/clickhouse-connect/) باستخدام pip:

`pip install clickhouse-connect`

يمكن أيضًا تثبيت ClickHouse Connect من المصدر:

* نفّذ `git clone` لـ [مستودع GitHub](https://github.com/ClickHouse/clickhouse-connect).
* (اختياري) شغّل `pip install cython` لبناء تحسينات C/Cython وتفعيلها
* انتقل باستخدام `cd` إلى الدليل الجذر للمشروع، ثم شغّل `pip install .`

<div id="support-policy">
  ## سياسة الدعم
</div>

يُرجى التحديث إلى أحدث إصدار من ClickHouse Connect قبل الإبلاغ عن أي مشكلات. يجب تقديم المشكلات في [مشروع GitHub](https://github.com/ClickHouse/clickhouse-connect/issues). من المفترض أن تكون الإصدارات المستقبلية من ClickHouse Connect متوافقة مع إصدارات ClickHouse المدعومة رسميًا وقت الإصدار. يمكن العثور على الإصدارات المدعومة رسميًا من خادم ClickHouse [هنا](https://github.com/ClickHouse/ClickHouse/blob/master/SECURITY.md). إذا لم تكن متأكدًا من إصدار خادم ClickHouse الذي ينبغي استخدامه، فاقرأ هذا النقاش [هنا](/docs/ar/resources/support-center/knowledge-base/setup-installation/production#how-to-choose-between-clickhouse-releases). تختبر مصفوفة اختبارات CI لدينا أحدث إصدارين من LTS وأحدث ثلاثة إصدارات مستقرة. ومع ذلك، وبفضل بروتوكول HTTP والحد الأدنى من التغييرات غير المتوافقة بين إصدارات ClickHouse، فإن ClickHouse Connect يعمل عمومًا بشكل جيد مع إصدارات الخادم الواقعة خارج النطاق المدعوم رسميًا، رغم أن التوافق مع بعض أنواع البيانات المتقدمة قد يختلف.

<div id="basic-usage">
  ## الاستخدام الأساسي
</div>

<div id="gather-your-connection-details">
  ### جهّز بيانات الاتصال الخاصة بك
</div>

للاتصال بـ ClickHouse باستخدام HTTP(S)، تحتاج إلى المعلومات التالية:

| المعلمات                  | الوصف                                                                                         |
| ------------------------- | --------------------------------------------------------------------------------------------- |
| `HOST` and `PORT`         | عادةً ما يكون المنفذ 8443 عند استخدام TLS، أو 8123 عند عدم استخدام TLS.                       |
| `DATABASE NAME`           | افتراضيًا، توجد قاعدة بيانات باسم `default`. استخدم اسم قاعدة البيانات التي تريد الاتصال بها. |
| `USERNAME` and `PASSWORD` | افتراضيًا، يكون اسم المستخدم `default`. استخدم اسم المستخدم المناسب لحالة الاستخدام لديك.     |

تتوفر تفاصيل خدمة ClickHouse Cloud الخاصة بك في ClickHouse Cloud console.
حدِّد خدمة ثم انقر على **Connect**:

<div className="ch-image-md">
  <Frame>
    <img src="https://mintcdn.com/private-7c7dfe99/CFFsa2agBPbviR4r/images/_snippets/cloud-connect-button.webp?fit=max&auto=format&n=CFFsa2agBPbviR4r&q=85&s=ec0a298a33ca841e947fa5e8bae47362" alt="زر Connect لخدمة ClickHouse Cloud" width="998" height="932" data-path="images/_snippets/cloud-connect-button.webp" />
  </Frame>
</div>

اختر **HTTPS**. ستظهر تفاصيل الاتصال في مثال لأمر `curl`.

<div className="ch-image-md">
  <Frame>
    <img src="https://mintcdn.com/private-7c7dfe99/CFFsa2agBPbviR4r/images/_snippets/connection-details-https.webp?fit=max&auto=format&n=CFFsa2agBPbviR4r&q=85&s=cb0fbd98aa2b5b7ca484c9f53395ee07" alt="تفاصيل اتصال HTTPS لخدمة ClickHouse Cloud" width="1320" height="1184" data-path="images/_snippets/connection-details-https.webp" />
  </Frame>
</div>

إذا كنت تستخدم ClickHouse مُدارًا ذاتيًا، فسيُحدِّد مسؤول ClickHouse لديك تفاصيل الاتصال.

<div id="establish-a-connection">
  ### إنشاء اتصال
</div>

فيما يلي مثالان للاتصال بـ ClickHouse:

* الاتصال بخادم ClickHouse على localhost.
* الاتصال بخدمة ClickHouse Cloud.

<div id="use-a-clickhouse-connect-client-instance-to-connect-to-a-clickhouse-server-on-localhost">
  #### استخدم مثيل عميل ClickHouse Connect للاتصال بخادم ClickHouse على localhost:
</div>

```python theme={null}
import clickhouse_connect

client = clickhouse_connect.get_client(host='localhost', username='default', password='password')
```

<div id="use-a-clickhouse-connect-client-instance-to-connect-to-a-clickhouse-cloud-service">
  #### استخدم مثيل عميل ClickHouse Connect للاتصال بخدمة ClickHouse Cloud:
</div>

<Tip>
  استخدم تفاصيل الاتصال التي جمعتها سابقًا. تتطلب خدمات ClickHouse Cloud استخدام TLS، لذا استخدم المنفذ 8443.
</Tip>

```python theme={null}
import clickhouse_connect

client = clickhouse_connect.get_client(host='HOSTNAME.clickhouse.cloud', port=8443, username='default', password='your password')
```

<div id="interact-with-your-database">
  ### التفاعل مع قاعدة بياناتك
</div>

لتنفيذ أمر ClickHouse SQL، استخدم الطريقة `command` الخاصة بالعميل:

```python theme={null}
client.command('CREATE TABLE new_table (key UInt32, value String, metric Float64) ENGINE MergeTree ORDER BY key')
```

لإدراج البيانات على دفعات، استخدم الأسلوب `insert` الخاص بالعميل مع مصفوفة ثنائية الأبعاد من الصفوف والقيم:

```python theme={null}
row1 = [1000, 'String Value 1000', 5.233]
row2 = [2000, 'String Value 2000', -107.04]
data = [row1, row2]
client.insert('new_table', data, column_names=['key', 'value', 'metric'])
```

لاسترداد البيانات باستخدام ClickHouse SQL، استخدم الطريقة `query` الخاصة بالعميل:

```python theme={null}
result = client.query('SELECT max(key), avg(metric) FROM new_table')
print(result.result_rows)
# Output: [(2000, -50.9035)]
```