واجهة برمجة تطبيقات برنامج تشغيل ClickHouse Connect

استخدم clickhouse_connect.get_client لإنشاء Client متزامن، أو ثبّت الإضافة async واستخدم await مع clickhouse_connect.get_async_client لإنشاء AsyncClient أصلي.

تقبل الدالة المُنشِئة غير المتزامنة أيضًا connector_limit=100 وconnector_limit_per_host=20 وkeepalive_timeout=30.0 لتهيئة مجمّع اتصالات aiohttp الخاص بها. ولا تقبل pool_mgr. تقبل الواجهة الخلفية المتزامنة لـ chDB أيضًا path وchdb_options؛ راجع الواجهة الخلفية المضمنة لـ chDB.

أخيرًا، تُستخدم وسيطة settings في get_client لتمرير إعدادات ClickHouse إضافية إلى الخادم مع كل طلب من العميل. لاحظ أنه في معظم الحالات، لا يمكن للمستخدمين الذين لديهم صلاحية وصول readonly=1 تعديل الإعدادات المرسلة مع الاستعلام، لذلك سيُسقط ClickHouse Connect هذه الإعدادات من الطلب النهائي ويسجل تحذيرًا. تنطبق الإعدادات التالية فقط على استعلامات/جلسات HTTP التي يستخدمها ClickHouse Connect، وليست موثقة باعتبارها إعدادات ClickHouse عامة.

للاطلاع على إعدادات ClickHouse الأخرى التي يمكن إرسالها مع كل استعلام، راجع وثائق ClickHouse.

• من دون أي معلمات، سيتصل عميل ClickHouse Connect بمنفذ HTTP الافتراضي على localhost باستخدام المستخدم default ومن دون كلمة مرور:

import clickhouse_connect

client = clickhouse_connect.get_client()
print(client.server_version)

• الاتصال بخادم ClickHouse خارجي آمن عبر HTTPS

import clickhouse_connect

client = clickhouse_connect.get_client(
    host="play.clickhouse.com",
    secure=True,
    port=443,
    username="play",
    password="clickhouse",
)
print(client.command("SELECT timezone()"))

• الاتصال باستخدام معرّف جلسة ومعلمات اتصال مخصّصة أخرى وإعدادات ClickHouse.

import clickhouse_connect

client = clickhouse_connect.get_client(
    host="play.clickhouse.com",
    username="play",
    password="clickhouse",
    port=443,
    secure=True,
    session_id="example_session_1",
    connect_timeout=15,
    database="github",
    settings={"distributed_ddl_task_timeout": 300},
)
print(client.database)
# Output: github

ثبّت clickhouse-connect[chdb] لاستخدام الواجهة الخلفية التجريبية لـ chDB التي تعمل داخل العملية. وهي توفّر طرق العميل المتزامنة للاستعلام والإدراج والتدفّق وArrow:

import clickhouse_connect

with clickhouse_connect.get_client(interface="chdb") as client:
    result = client.query("SELECT sum(number) FROM numbers(10)")
    print(result.first_row)
    # Output: (45,)

الإعداد الافتراضي هو قاعدة بيانات داخل الذاكرة. مرِّر path="/data/my_chdb" أو استخدم dsn="chdb:///data/my_chdb" للتخزين الدائم. تسمح الواجهة الخلفية بمسار محرك واحد لكل عملية، ولا تدعم get_async_client أو البيانات الخارجية.

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

• أعِد استخدام العملاء: أنشئ العملاء مرة واحدة عند بدء تشغيل التطبيق، وأعِد استخدامهم طوال دورة حياة التطبيق
• تجنّب الإنشاء المتكرر: لا تُنشئ عميلاً جديدًا لكل query أو طلب
• نظّف الموارد بشكل صحيح: احرص دائمًا على إغلاق العملاء عند إيقاف التشغيل لتحرير موارد مجمع الاتصالات
• استخدم عميلاً واحدًا عند الإمكان: يمكن لعميل واحد معالجة العديد من الاستعلامات المتزامنة عبر مجمع الاتصالات الخاص به (راجع ملاحظات مؤشرات الترابط أدناه)

أعِد استخدام عميل واحد:

import clickhouse_connect

# Create once at startup
client = clickhouse_connect.get_client(
    host="my-host",
    username="default",
    password="password",
)

# Reuse for all queries
for i in range(1000):
    result = client.query("SELECT count() FROM users")

# Close on shutdown
client.close()

تجنّب إنشاء clients بصورة متكررة:

# BAD: Creates 1000 clients with expensive initialization overhead
for i in range(1000):
    client = clickhouse_connect.get_client(
        host="my-host",
        username="default",
        password="password",
    )
    result = client.query("SELECT count() FROM users")
    client.close()

لمشاركة عميل بين خيوط متعددة بأمان:

import clickhouse_connect
import threading

# Option 1: Disable sessions (recommended for shared clients)
client = clickhouse_connect.get_client(
    host="my-host",
    username="default",
    password="password",
    autogenerate_session_id=False,
)

def worker(thread_id):
    # All threads can now safely use the same client
    result = client.query(f"SELECT {thread_id}")
    print(f"Thread {thread_id}: {result.result_rows[0][0]}")

threads = [threading.Thread(target=worker, args=(i,)) for i in range(10)]
for t in threads:
    t.start()
for t in threads:
    t.join()

client.close()

بديل عند الحاجة إلى الجلسات: إذا كنت بحاجة إلى جلسات (مثلًا، لاستخدام الجداول المؤقتة)، فأنشئ عميلًا منفصلًا لكل خيط تنفيذ:

def worker(thread_id):
    # Each thread gets its own client with isolated session
    client = clickhouse_connect.get_client(
        host="my-host",
        username="default",
        password="password",
    )
    client.command("CREATE TEMPORARY TABLE temp (id UInt32) ENGINE = Memory")
    # ... use temp table ...
    client.close()

أغلق كائنات العميل دائمًا عند إيقاف التشغيل. لاحظ أن client.close() يحرّر العميل ويغلق اتصالات HTTP المجمّعة فقط عندما يكون العميل هو مالك مدير الـ pool الخاص به (على سبيل المثال، عند إنشائه باستخدام خيارات TLS/proxy مخصّصة). أمّا بالنسبة إلى الـ pool المشتركة الافتراضية، فاستخدم client.close_connections() لإغلاق الـ sockets بشكل استباقي؛ وإلا فستُسترد الاتصالات تلقائيًا عند انتهاء مهلة الخمول وعند خروج العملية.

client = clickhouse_connect.get_client(
    host="my-host",
    username="default",
    password="password",
)
try:
    result = client.query("SELECT 1")
finally:
    client.close()

أو استخدم مدير السياق:

with clickhouse_connect.get_client(
    host="my-host",
    username="default",
    password="password",
) as client:
    result = client.query("SELECT 1")

يكون استخدام عدة عملاء مناسبًا في الحالات التالية:

• خوادم مختلفة: عميل واحد لكل ClickHouse server أو عنقود
• بيانات اعتماد مختلفة: عملاء منفصلون لمستخدمين مختلفين أو لمستويات وصول مختلفة
• قواعد بيانات مختلفة: عندما تحتاج إلى العمل مع عدة قواعد بيانات
• جلسات معزولة: عندما تحتاج إلى جلسات منفصلة للجداول المؤقتة أو للإعدادات الخاصة بالجلسة
• عزل لكل خيط تنفيذ: عندما تحتاج خيوط التنفيذ إلى جلسات مستقلة (كما هو موضح أعلاه)

تستخدم عدة طرق في العميل إحدى وسيطتي parameters وsettings الشائعتين أو كلتيهما. وتُشرح وسائط الكلمات المفتاحية هذه أدناه.

تقبل طرائق query* وcommand في ClickHouse Connect Client وسيطة keyword اختيارية باسم parameters، تُستخدم لربط تعبيرات بايثون بتعبير قيمة في ClickHouse. ويتوفر نوعان من هذا الربط.

يدعم ClickHouse الربط من جهة الخادم لقيم الاستعلام. تُرسَل القيمة المربوطة منفصلةً عن الاستعلام كمعلمة HTTP. يستخدم ClickHouse Connect هذا الوضع عندما يكتشف تعبيرًا بالصيغة {<name>:<datatype>}. مرِّر القيم في قاموس بايثون.

يجب أن تكون أسماء المعلمات أسماء BareWord ASCII في ClickHouse. يقبل برنامج التشغيل الرمز $ في بداية الاسم أو داخله أو نهايته عندما يقبله الخادم، مثل {$tenant_id:String}. يُحجز مفتاح قاموس يبدأ وينتهي بـ $ وتكون قيمته مخزنًا مؤقتًا مثل bytes أو bytearray أو memoryview لاتفاقية المعلمات الثنائية الخام في ClickHouse Connect. إذا استُخدم مثل هذا المفتاح لمعلمة غير ثنائية من جهة الخادم، فاحصره في عنصر نائب واحد {name:Type}. يمكن لـ ClickHouse تحليل أسماء $tag$ المتكررة كوسوم Heredoc.

استخدم None في بايثون للقيم القابلة لأن تكون NULL. القيم المتداخلة None مدعومة داخل معلمات Array وTuple، وداخل القيم الحرفية Map عندما يُضبط dict_parameter_format على "map".

• الربط من جهة الخادم باستخدام قاموس بايثون، وقيمة DateTime، وقيمة نصية

import datetime

my_date = datetime.datetime(2022, 10, 1, 15, 20, 5)

parameters = {
    "table": "my_table",
    "v1": my_date,
    "v2": "a string with a single quote'",
}
client.query(
    "SELECT * FROM {table:Identifier} "
    "WHERE date >= {v1:DateTime} AND string ILIKE {v2:String}",
    parameters=parameters,
)

وهذا يكافئ:

SELECT *
FROM my_table
WHERE date >= '2022-10-01 15:20:05'
  AND string ILIKE 'a string with a single quote\''

يدعم ClickHouse Connect أيضًا ربط المعلمات من جهة العميل، ما يتيح مرونة أكبر عند إنشاء استعلامات SQL المعتمدة على القوالب. بالنسبة إلى الربط من جهة العميل، يجب أن تكون وسيطة parameters قاموسًا أو تسلسلًا. ويستخدم الربط من جهة العميل تنسيق السلاسل بأسلوب "printf" في بايثون لإجراء استبدال المعلمات.

لاحظ أنه، بخلاف الربط من جهة الخادم، لا يعمل الربط من جهة العميل مع معرّفات قاعدة البيانات مثل أسماء قواعد البيانات أو الجداول أو الأعمدة، لأن التنسيق بأسلوب بايثون لا يستطيع التمييز بين الأنواع المختلفة من السلاسل، ولأنها تحتاج إلى تنسيق مختلف (backticks أو علامتا الاقتباس المزدوجتان لمعرّفات قاعدة البيانات، وعلامتا الاقتباس المفردتان لقيم البيانات).

• مثال باستخدام قاموس بايثون، وقيمة DateTime، وإفلات السلاسل

import datetime

my_date = datetime.datetime(2022, 10, 1, 15, 20, 5)

parameters = {"v1": my_date, "v2": "a string with a single quote'"}
client.query(
    "SELECT * FROM my_table "
    "WHERE date >= %(v1)s AND string ILIKE %(v2)s",
    parameters=parameters,
)

يؤدي ذلك إلى إنشاء الاستعلام التالي على الخادم:

SELECT *
FROM my_table
WHERE date >= '2022-10-01 15:20:05'
  AND string ILIKE 'a string with a single quote\''

• مثال على تسلسل في بايثون (Tuple) وFloat64 وIPv4Address

import ipaddress

parameters = (35200.44, ipaddress.IPv4Address(0x443d04fe))
client.query(
    "SELECT * FROM some_table WHERE metric >= %s AND ip_address = %s",
    parameters=parameters,
)

يؤدي ذلك إلى إنشاء الاستعلام التالي على الخادم:

SELECT *
FROM some_table
WHERE metric >= 35200.44
  AND ip_address = '68.61.4.254'

تقبل جميع طُرق insert وselect الأساسية في ClickHouse Connect Client وسيطةً اختيارية باسم settings لتمرير إعدادات المستخدم الخاصة بخادم ClickHouse لعبارة SQL المضمَّنة. يجب أن تكون وسيطة settings قاموسًا. ويجب أن يتكوّن كل عنصر من اسم إعداد في ClickHouse والقيمة المرتبطة به. لاحظ أن القيم ستُحوَّل إلى سلاسل نصية عند إرسالها إلى الخادم كمعلمات استعلام.

وكما هو الحال مع الإعدادات على مستوى العميل، سيتجاهل ClickHouse Connect أي إعدادات يضع الخادم عليها العلامة readonly=1، مع تسجيل رسالة في السجل بذلك. أما الإعدادات التي تنطبق فقط على الاستعلامات عبر ClickHouse HTTP interface فتكون صالحة دائمًا. وتجد وصف هذه الإعدادات ضمن واجهة برمجة تطبيقات get_client واجهة برمجة تطبيقات.

مثال على استخدام إعدادات ClickHouse:

settings = {
    "merge_tree_min_rows_for_concurrent_read": 65535,
    "session_id": "session_1234",
    "use_skip_indexes": False,
}
client.query(
    "SELECT event_type, sum(timeout) "
    "FROM event_errors WHERE event_time > '2022-08-01'",
    settings=settings,
)

استخدم Client.command مع التعليمات التي لا تُرجِع مجموعة بيانات جدولية، أو مع الاستعلامات التي تُرجِع قيمة بدائية واحدة أو صفًا واحدًا. وبحسب الاستجابة، فإنها تُرجِع سلسلة نصية، أو عددًا صحيحًا، أو تسلسلًا من السلاسل النصية، أو QuerySummary. وتُرجِع عملية القراءة التي تنتج مجموعة نتائج فارغة سلسلةً نصية فارغة.

import clickhouse_connect

client = clickhouse_connect.get_client()

# Create a table. A successful DDL returns QuerySummary.
summary = client.command(
    "CREATE TABLE test_command "
    "(col_1 String, col_2 DateTime) "
    "ENGINE MergeTree ORDER BY tuple()"
)
print(summary.query_id())

# Show table definition
result = client.command("SHOW CREATE TABLE test_command")
print(result)
# Output:
# CREATE TABLE default.test_command
# (
#     `col_1` String,
#     `col_2` DateTime
# )
# ENGINE = MergeTree
# ORDER BY tuple()

# Drop table
client.command("DROP TABLE test_command")

import clickhouse_connect

client = clickhouse_connect.get_client()

# Single value result
count = client.command("SELECT count() FROM system.tables")
print(count)

# Server version
version = client.command("SELECT version()")
print(version)

import clickhouse_connect

client = clickhouse_connect.get_client()

# Using client-side parameters
table_name = "system"
result = client.command(
    "SELECT count() FROM system.tables WHERE database = %(db)s",
    parameters={"db": table_name}
)

# Using server-side parameters
result = client.command(
    "SELECT count() FROM system.tables WHERE database = {db:String}",
    parameters={"db": "system"}
)

import clickhouse_connect

client = clickhouse_connect.get_client()

# Execute command with specific settings
result = client.command(
    "OPTIMIZE TABLE large_table FINAL",
    settings={"optimize_throw_if_noop": 1}
)

تسترجع Client.query مجموعة بيانات جدولية بتنسيق ClickHouse Native وتُرجع QueryResult. تُحمَّل النتيجة الكاملة في الذاكرة عند الوصول إلى إحدى خصائص النتيجة. استخدم طريقة بث للنتائج التي لا ينبغي الاحتفاظ بها في الذاكرة.

import clickhouse_connect

client = clickhouse_connect.get_client()

# Simple SELECT query
result = client.query(
    "SELECT number, toString(number) AS label FROM numbers(3)"
)

# Access results as rows
for row in result.result_rows:
    print(row)
# Output:
# (0, '0')
# (1, '1')
# (2, '2')

# Access column names and types
print(result.column_names)
# Output: ('number', 'label')
print([col_type.name for col_type in result.column_types])
# Output: ['UInt64', 'String']

import clickhouse_connect

client = clickhouse_connect.get_client()

result = client.query("SELECT number, toString(number) AS str FROM system.numbers LIMIT 3")

# Row-oriented access (default)
print(result.result_rows)
# Output: [(0, '0'), (1, '1'), (2, '2')]

# Column-oriented access
print(result.result_columns)
# Output: [[0, 1, 2], ['0', '1', '2']]

# Named results (list of dictionaries)
for row_dict in result.named_results():
    print(row_dict)
# Output:
# {'number': 0, 'str': '0'}
# {'number': 1, 'str': '1'}
# {'number': 2, 'str': '2'}

# First row as dictionary
print(result.first_item)
# Output: {'number': 0, 'str': '0'}

# First row as tuple
print(result.first_row)
# Output: (0, '0')

import clickhouse_connect

client = clickhouse_connect.get_client()

# Using dictionary parameters (printf-style)
query = "SELECT * FROM system.tables WHERE database = %(db)s AND name LIKE %(pattern)s"
parameters = {"db": "system", "pattern": "%query%"}
result = client.query(query, parameters=parameters)

# Using tuple parameters
query = "SELECT * FROM system.tables WHERE database = %s LIMIT %s"
parameters = ("system", 5)
result = client.query(query, parameters=parameters)

import clickhouse_connect

client = clickhouse_connect.get_client()

# Server-side binding (more secure, better performance for SELECT queries)
query = "SELECT * FROM system.tables WHERE database = {db:String} AND name = {tbl:String}"
parameters = {"db": "system", "tbl": "query_log"}

result = client.query(query, parameters=parameters)

import clickhouse_connect

client = clickhouse_connect.get_client()

# Pass ClickHouse settings with the query
result = client.query(
    "SELECT sum(number) FROM numbers(1000000)",
    settings={
        "max_block_size": 100000,
        "max_execution_time": 30
    }
)

تُرجِع طريقة query الأساسية كائن QueryResult بالخصائص العامة التالية:

• result_rows – مصفوفة النتائج منظَّمة على شكل صفوف.
• result_columns – مصفوفة النتائج منظَّمة على شكل أعمدة.
• result_set – result_rows أو result_columns، بحسب اتجاه الاستعلام.
• column_names – Tuple يضم أسماء أعمدة النتائج.
• column_types – Tuple من كائنات ClickHouseType.
• row_count – عدد صفوف النتائج المُخزَّنة فعليًا.
• query_id – معرّف الاستعلام الذي تم الإبلاغ عنه أو إنشاؤه للطلب. وتعني السلسلة الفارغة عدم توفر أي معرّف.
• summary – قاموس مفكوك الترميز من ترويسة الاستجابة X-ClickHouse-Summary.
• first_item – الصف الأول على هيئة قاموس، أو None إذا كانت النتيجة فارغة.
• first_row – الصف الأول على هيئة تسلسل، أو None إذا كانت النتيجة فارغة.
• column_block_stream وrow_block_stream وrows_stream – سياقات تدفق داخلية. استخدم بدلًا من ذلك طرق البث المقابلة في العميل.

راجع الاستعلامات المتدفقة للتعرّف على واجهات برمجة التطبيقات StreamContext المدعومة.

يوفّر ClickHouse Connect طرق استعلام متخصصة لتنسيقات بيانات NumPy وPandas وArrow. للحصول على معلومات مفصلة حول استخدام هذه الطرق، بما في ذلك الأمثلة وإمكانات البث والتعامل المتقدم مع الأنواع، راجع الاستعلام المتقدم (استعلامات NumPy وPandas وArrow).

لبث مجموعات نتائج كبيرة، يوفّر ClickHouse Connect عدة أساليب للبث المتدفق. راجع الاستعلامات المتقدمة (الاستعلامات المتدفقة) للاطلاع على التفاصيل والأمثلة.

في حالة الاستخدام الشائعة المتمثلة في إدراج عدة سجلات في ClickHouse، تتوفر الطريقة Client.insert. وتقبل المعلمات التالية:

تعيد هذه الطريقة QuerySummary. ويحتوي قاموس summary الخاص بها على القيم التي يبلّغ عنها الخادم. وتمثل written_rows خاصيةً تيسيرية، بينما تعيد written_bytes() وquery_id() القيم المناظرة. ويؤدي فشل الإدراج إلى رفع استثناء.

للاطلاع على طرق الإدراج المتخصصة التي تعمل مع Pandas DataFrames وPyArrow Tables وDataFrames المعتمدة على Arrow، راجع الإدراج المتقدم (طرق الإدراج المتخصصة).

تفترض الأمثلة الواردة أدناه وجود جدول users مسبقًا، بمخطط (id UInt32, name String, age UInt8).

import clickhouse_connect

client = clickhouse_connect.get_client()

# Row-oriented data: each inner list is a row
data = [
    [13, "user_1", 25],
    [79, "user_2", 30],
]

client.insert("users", data, column_names=["id", "name", "age"])

import clickhouse_connect

client = clickhouse_connect.get_client()

# Column-oriented data: each inner list is a column
data = [
    [13, 79],  # id column
    ["user_1", "user_2"],  # name column
    [25, 30],  # age column
]

client.insert("users", data, column_names=["id", "name", "age"], column_oriented=True)

import clickhouse_connect

client = clickhouse_connect.get_client()

# Useful when you want to avoid a DESCRIBE query to the server
data = [
    [13, "user_1", 25],
    [79, "user_2", 30],
]

client.insert(
    "users",
    data,
    column_names=["id", "name", "age"],
    column_type_names=["UInt32", "String", "UInt8"],
)

import clickhouse_connect

client = clickhouse_connect.get_client()

data = [
    [13, "user_1", 25],
    [79, "user_2", 30],
]

# Insert into a table in a specific database
client.insert(
    "users",
    data,
    column_names=["id", "name", "age"],
    database="production",
)

لإدراج البيانات مباشرةً من الملفات إلى جداول ClickHouse، راجع الإدراج المتقدم (الإدراج من الملفات).

للاطلاع على حالات الاستخدام المتقدمة التي تتطلب وصولًا مباشرًا إلى واجهات HTTP الخاصة بـ ClickHouse من دون تحويلات للأنواع، راجع الاستخدام المتقدم (واجهة برمجة التطبيقات الخام).

تُنفِّذ وحدة clickhouse_connect.dbapi واجهة الاتصال والمُؤشِّر وفقًا للمعيار PEP 249. وهي تُعرِّف مستوى واجهة برمجة التطبيقات بأنه 2.0، وthreadsafety=2، وparamstyle="pyformat". وتوفّر الوحدة أيضًا مُنشئات الأنواع وفقًا للمعيار PEP 249، وهي Date وTime وTimestamp وBinary، والدوال DateFromTicks وTimeFromTicks وTimestampFromTicks.

from clickhouse_connect import dbapi

connection = dbapi.connect(
    host="localhost",
    username="default",
    password="password",
    database="default",
)
cursor = connection.cursor()

try:
    cursor.execute(
        "SELECT name FROM system.tables "
        "WHERE database = %(database)s ORDER BY name LIMIT 5",
        {"database": "system"},
    )
    print(cursor.description)
    print(cursor.fetchall())
finally:
    cursor.close()
    connection.close()

يقبل كلٌّ من Cursor.execute وCursor.executemany وسيطتَي الكلمات المفتاحية الإضافيتين settings وquery_formats. تمرّر settings إعدادات ClickHouse. وتطبّق query_formats تنسيقات القراءة حسب نوع ClickHouse عندما تُرجع العبارة صفوفًا، باستخدام التعيين نفسه المستخدم في Client.query. ويقبل Cursor.execute أيضًا الوسيطة pyformat_encoded التي تُمرَّر بالكلمات المفتاحية فقط. وتتبع قيمتها الافتراضية True عقد DB-API الخاص بـ pyformat. ويضبطها نمط SQLAlchemy على False عندما يُصدر مصرّف العبارة علامات نسبة مئوية خامًا، لذا ينبغي للتطبيقات عادةً عدم ضبطها. ويستخدم executemany مسار الإدراج المجمّع Native الخاص ببرنامج التشغيل لعبارات INSERT ... VALUES المتوافقة مع تسلسل صفوف مُخزَّن فعليًا. وتستهلك fetchone وfetchmany وfetchall النتيجة المُخزَّنة فعليًا الحالية.

يستمدّ Cursor.description القيمة null_ok من نوع كل عمود في النتيجة. وتُرجع الأنواع غير القابلة للقيم الفارغة False، بينما تُرجع الأنواع القابلة للقيم الفارغة True، بما في ذلك أغلفة Nullable وVariant وDynamic. وتعني None أن قابلية القيم الفارغة غير معروفة. عندما لا يُرجع استعلام يبدأ بـ SELECT أو WITH، مع تجاهل التعليقات البادئة، أي صفوف أو بيانات وصفية للأعمدة، يشغّل المؤشّر استعلام بيانات وصفية بـ LIMIT 0 لملء description. وإذا فشل استعلام البيانات الوصفية هذا، يُترك description فارغًا.

لا يوفّر ClickHouse معاملات تقليدية عبر واجهة HTTP هذه. وتُعدّ Connection.commit() وConnection.rollback() عمليتَي no-op. ولا تزال قواعد تزامن معرّف الجلسة تنطبق عند مشاركة الاتصال.

توفر الوحدات التالية أدوات مساعدة عامة إضافية تستخدمها التطبيقات العميلة.

يُعرض إصدار الحزمة المثبتة في السلسلة clickhouse_connect.__version__.

تُعرَّف الاستثناءات المخصّصة، بما في ذلك التسلسل الهرمي للاستثناءات في DB-API 2.0، في clickhouse_connect.driver.exceptions. ويوفّر كلٌّ من DatabaseError وOperationalError السمة الرقمية code التي تحمل رمز الخطأ في ClickHouse، والسمة name التي تحمل الاسم الرمزي مثل UNKNOWN_TABLE، بحيث يمكن للتطبيقات التفريع بناءً على exc.code بدلًا من تحليل الرسالة. تُضبط code حتى عند تعطيل show_clickhouse_errors، بينما تتطلب name تفاصيل الخطأ (True أو "scrub"). وتكون كلتاهما None عند عدم توفرهما، كما في أخطاء النقل. استخدم show_clickhouse_errors="scrub" عندما ينبغي للمستخدمين النهائيين رؤية أخطاء SQL دون معلومات عن المضيف أو إصدار الخادم. يتحكم الإعداد أيضًا في رسائل StreamFailureError أثناء التدفق ورسائل النقل العامة. وهو يتحكم في str(exc) فقط. تظل أخطاء النقل مرفقة باعتبارها __cause__، ويمكن أن تحتوي آثار التتبع على نص الخطأ الأصلي للمضيف أو URL أو المكتبة.

يمكن استخدام الدوال والفئة DT64Param في الوحدة clickhouse_connect.driver.binding لبناء استعلامات ClickHouse SQL وإفلاتها بشكل صحيح. وبالمثل، يمكن استخدام الدوال في الوحدة clickhouse_connect.driver.parser لتحليل أسماء أنواع بيانات ClickHouse.

للحصول على معلومات حول استخدام ClickHouse Connect في التطبيقات متعددة الخيوط، ومتعددة العمليات، وغير المتزامنة أو القائمة على الأحداث، راجع الاستخدام المتقدم (حالات الاستخدام متعددة الخيوط، ومتعددة العمليات، وغير المتزامنة أو القائمة على الأحداث).

للاطلاع على الاستخدام الأصلي لـ asyncio، راجع الاستخدام المتقدم (AsyncClient).

للاطلاع على معلومات حول إدارة معرّفات جلسات ClickHouse في التطبيقات متعددة الخيوط أو المتزامنة، راجع الاستخدام المتقدم (إدارة معرّفات الجلسات في ClickHouse).

لمزيد من المعلومات حول تخصيص مجمّع اتصالات HTTP للتطبيقات الكبيرة متعددة الخيوط، راجع الاستخدام المتقدم (تخصيص مجمّع اتصالات HTTP).