مقدمة - ClickHouse Documentation

يوفّر 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 في الحزمة clickhouse_connect.cc_sqlalchemy، وهي مبنية على الحزمتين datatypes وdbi. ويدعم هذا التنفيذ وظائف SQLAlchemy Core، بما في ذلك استعلامات SELECT مع JOINs (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 الطريقة المفضلة لربط ClickHouse بـ Apache Superset. استخدم اتصال قاعدة البيانات ClickHouse Connect، أو سلسلة اتصال لهجة SQLAlchemy ‏clickhousedb.

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

يستخدم برنامج تشغيل ClickHouse Connect الرسمي لبايثون بروتوكول HTTP للتواصل مع خادم ClickHouse. يتيح ذلك دعم موازن التحميل HTTP، ويعمل بكفاءة في بيئات المؤسسات التي تستخدم جدران الحماية والوكلاء، لكنه يوفّر ضغطًا وأداءً أقل قليلًا مقارنةً بالبروتوكول الأصلي المعتمد على TCP، كما يفتقر إلى دعم بعض الميزات المتقدمة مثل إلغاء الاستعلامات. في بعض حالات الاستخدام، قد يكون من المناسب استخدام أحد برامج تشغيل بايثون المجتمعية التي تستخدم البروتوكول الأصلي المعتمد على TCP.

المتطلبات والتوافق

بايثون		المنصة¹		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 الممتاز. وأخيرًا، بما أن ClickHouse Connect يمكنه أيضًا العمل كـ pure Python، فمن المفترض أن يعمل التثبيت من المصدر على أي تثبيت حديث لبايثون. ²يقتصر دعم SQLAlchemy على وظائف Core (الاستعلامات وDDL الأساسي). ميزات ORM غير مدعومة. راجع وثائق دعم تكامل SQLAlchemy لمزيد من التفاصيل. ³يعمل ClickHouse Connect عمومًا بشكل جيد مع الإصدارات الواقعة خارج النطاق المدعوم رسميًا.

التثبيت

ثبّت ClickHouse Connect من PyPI باستخدام pip: pip install clickhouse-connect يمكن أيضًا تثبيت ClickHouse Connect من المصدر:

نفّذ git clone لـ مستودع GitHub.
(اختياري) شغّل pip install cython لبناء تحسينات C/Cython وتفعيلها
انتقل باستخدام cd إلى الدليل الجذر للمشروع، ثم شغّل pip install .

سياسة الدعم

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

الاستخدام الأساسي

جهّز بيانات الاتصال الخاصة بك

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

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

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

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

تفاصيل اتصال HTTPS لخدمة ClickHouse Cloud

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

إنشاء اتصال

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

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

استخدم مثيل عميل ClickHouse Connect للاتصال بخادم ClickHouse على localhost:

import clickhouse_connect

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

استخدم مثيل عميل ClickHouse Connect للاتصال بخدمة ClickHouse Cloud:

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

import clickhouse_connect

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

التفاعل مع قاعدة بياناتك

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

client.command('CREATE TABLE new_table (key UInt32, value String, metric Float64) ENGINE MergeTree ORDER BY key')

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

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 الخاصة بالعميل:

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

​المتطلبات والتوافق

​التثبيت

​سياسة الدعم

​الاستخدام الأساسي

​جهّز بيانات الاتصال الخاصة بك

​إنشاء اتصال

​استخدم مثيل عميل ClickHouse Connect للاتصال بخادم ClickHouse على localhost:

​استخدم مثيل عميل ClickHouse Connect للاتصال بخدمة ClickHouse Cloud:

​التفاعل مع قاعدة بياناتك

المتطلبات والتوافق

التثبيت

سياسة الدعم

الاستخدام الأساسي

جهّز بيانات الاتصال الخاصة بك

إنشاء اتصال

استخدم مثيل عميل ClickHouse Connect للاتصال بخادم ClickHouse على localhost:

استخدم مثيل عميل ClickHouse Connect للاتصال بخدمة ClickHouse Cloud:

التفاعل مع قاعدة بياناتك