الاستعلامات المتقدمة

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

يمكن الحصول على QueryContext باستخدام طريقة العميل create_query_context. وتستقبل هذه الطريقة المعلمات نفسها التي تستقبلها طريقة الاستعلام الأساسية. ويمكن بعد ذلك تمرير سياق الاستعلام هذا إلى الطرق‏ query أو query_df أو query_np باعتباره وسيط الكلمة المفتاحية context بدلًا من أي من الوسائط الأخرى لهذه الطرق أو جميعها. لاحظ أن أي وسائط إضافية تُحدَّد عند استدعاء الطريقة ستتجاوز أي خصائص في QueryContext.

أوضح Use case لـ QueryContext هو إرسال الاستعلام نفسه مع قيم مختلفة لمَعلمات الربط. ويمكن تحديث جميع قيم المعلمات باستدعاء الطريقة ‏QueryContext.set_parameters باستخدام قاموس، كما يمكن تحديث أي قيمة مفردة باستدعاء QueryContext.set_parameter باستخدام زوج key وvalue المطلوب.

qc = client.create_query_context(
    query="SELECT {k:Int32}",
    parameters={"k": 13},
)
result = client.query(context=qc)
assert result.first_row == (13,)

qc.set_parameter("k", 79)
result = client.query(context=qc)
assert result.first_row == (79,)

لاحظ أن كائنات QueryContext ليست آمنة للاستخدام عبر الخيوط، ولكن يمكن الحصول على نسخة منها في بيئة متعددة الخيوط عبر استدعاء التابع QueryContext.updated_copy.

يوفّر ClickHouse Connect Client عدة طرق لاسترجاع البيانات كتدفق (وهو مُنفَّذ كمُولِّد في بايثون):

• query_column_block_stream – يعيد بيانات query في كتل على هيئة تسلسل من الأعمدة باستخدام كائنات بايثون الأصلية
• query_row_block_stream – يعيد بيانات query على هيئة كتلة من الصفوف باستخدام كائنات بايثون الأصلية
• query_rows_stream – يعيد بيانات query كتسلسل من الصفوف باستخدام كائنات بايثون الأصلية
• query_np_stream – يعيد كل كتلة من بيانات query في ClickHouse كمصفوفة NumPy
• query_df_stream – يعيد كل كتلة من بيانات query في ClickHouse على هيئة Pandas DataFrame
• query_arrow_stream – يعيد بيانات query على هيئة كائنات PyArrow RecordBatch
• query_df_arrow_stream – يعيد كل دفعة Arrow على هيئة Pandas DataFrame أو Polars DataFrame، ويُحدَّد ذلك بواسطة dataframe_library

تعيد كل طريقة كائن StreamContext، ويجب فتحه باستخدام عبارة with. وتُنتظر طرق التدفق في العميل غير المتزامن وتُفتح باستخدام async with.

يعالج ClickHouse Connect جميع البيانات القادمة من طريقة query الأساسية كتدفق من الكتل التي يتلقاها من خادم ClickHouse. وتُنقل هذه الكتل من ClickHouse وإليه باستخدام تنسيق "Native" المخصص. والـ"كتلة" هي ببساطة تسلسل من أعمدة البيانات الثنائية، حيث يحتوي كل عمود على عدد متساوٍ من قيم البيانات من نوع البيانات المحدد. (وبما أن ClickHouse قاعدة بيانات عمودية، فهو يخزّن هذه البيانات بصيغة مشابهة.) ويتحكم في حجم الكتلة المُعادة من الاستعلام إعدادان للمستخدم يمكن ضبطهما على عدة مستويات (ملف تعريف المستخدم، أو المستخدم، أو الجلسة، أو الاستعلام). وهما:

• max_block_size – الحد الأقصى لحجم الكتلة بالصفوف.
• preferred_block_size_bytes – حجم الكتلة المفضّل بالبايت.

بغض النظر عن preferred_block_size_bytes، لن تتجاوز أي كتلة أبدًا max_block_size صفًا. وقد يكون الحجم الفعلي أصغر، ويجب عدم اعتباره ثابتًا.

عند استخدام إحدى طرائق Client query_*_stream، تُعاد النتائج كتلةً بكتلة. ولا يحمّل ClickHouse Connect سوى كتلة واحدة في كل مرة. ويتيح ذلك معالجة كميات كبيرة من البيانات دون الحاجة إلى تحميل مجموعة نتائج كبيرة كاملةً إلى الذاكرة. لاحظ أنه ينبغي أن يكون التطبيق مستعدًا لمعالجة أي عدد من الكتل، ولا يمكن التحكم في الحجم الدقيق لكل كتلة.

إذا كان أحد التطبيقات يستهلك الكتل بمعدل أبطأ بكثير من معدل إنتاجها من الخادم، فقد يُغلَق اتصال HTTP قبل اكتمال المعالجة. زِد الإعداد العام http_buffer_size عندما تتوفر للتطبيق ذاكرة كافية لتخزين المزيد من بيانات الاستجابة مؤقتًا. القيمة الافتراضية هي 10 MiB. تظل بايتات الاستجابة lz4 وzstd مضغوطة داخل هذا المخزن المؤقت، مما يزيد من سعته الفعلية.

تعيد كل واحدة من طرق query_*_stream (مثل query_row_block_stream) كائن StreamContext من ClickHouse، وهو كائن مدمج يجمع بين السياق والمولِّد في بايثون. وهذا هو الاستخدام الأساسي:

with client.query_row_block_stream(
    "SELECT pickup, dropoff, pickup_longitude, pickup_latitude FROM taxi_trips"
) as stream:
    for block in stream:
        for row in block:
            process_trip(row)

لاحظ أن محاولة استخدام StreamContext من دون تعليمة with ستؤدي إلى حدوث خطأ. ويضمن استخدام سياق بايثون إغلاق التدفق (في هذه الحالة، استجابة HTTP متدفقة) بشكل صحيح حتى إذا لم تُستهلك جميع البيانات و/أو حدث استثناء أثناء المعالجة. كذلك، لا يمكن استخدام StreamContext لاستهلاك التدفق إلا مرة واحدة. وستؤدي محاولة استخدام StreamContext بعد الخروج منه إلى ظهور StreamClosedError.

إذا فشل الاتصال أثناء قراءة نتيجة، فسيُطلق StreamFailureError بدلًا من إعادة نتيجة مقتطعة بصمت. وتتبع رسالته إعداد show_clickhouse_errors الخاص بالعميل.

يمكنك استخدام الخاصية source في StreamContext للوصول إلى الكائن الأب للنتيجة، الذي يتضمن أسماء الأعمدة وأنواعها. وبالنسبة إلى معظم التدفقات، يكون هذا الكائن QueryResult؛ أما الطريقتان query_np_stream وquery_df_stream فتُظهران بدلًا من ذلك NumpyResult.

تعيد الطريقة query_column_block_stream الكتلة كتسلسل من بيانات الأعمدة المخزَّنة على هيئة أنواع بيانات بايثون الأصلية. وباستخدام استعلامات taxi_trips أعلاه، ستكون البيانات المعادة قائمةً يكون كل عنصر فيها قائمةً أخرى (أو tuple) تضم كل البيانات الخاصة بالعمود المقابل. لذا فإن block[0] سيكون tuple لا يحتوي إلا على سلاسل نصية. وتُستخدم التنسيقات المعتمدة على الأعمدة غالبًا لإجراء عمليات تجميعية على جميع القيم في عمود معيّن، مثل جمع إجمالي الأجور.

تعيد الطريقة query_row_block_stream الكتلة كتسلسل من الصفوف، كما في قواعد البيانات العلائقية التقليدية. وبالنسبة إلى رحلات التاكسي، ستكون البيانات المعادة قائمةً يكون كل عنصر فيها قائمةً أخرى تمثل صفًا من البيانات. لذا فإن block[0] سيحتوي على جميع الحقول بالترتيب لأول رحلة تاكسي، وblock[1] سيحتوي على صف يضم جميع الحقول الخاصة برحلة التاكسي الثانية، وهكذا. وتُستخدم النتائج المعتمدة على الصفوف عادةً لأغراض العرض أو عمليات التحويل.

تنتقل الطريقة query_rows_stream تلقائيًا إلى الكتلة التالية وتُنتج صفًا واحدًا في كل مرة. وهي النظير صفًا بصفّ للطريقة query_row_block_stream.

تعيد الطريقة query_np_stream كل كتلة على شكل مصفوفة NumPy. وعندما تشترك جميع أعمدة النتائج في نوع بيانات NumPy نفسه (dtype)، تكون المصفوفة ثنائية الأبعاد بالشكل (rows, columns). أما النتائج المختلطة فتُعاد على هيئة مصفوفة مهيكلة أحادية البعد أو باستخدام نوع البيانات object.

تعيد الطريقة query_df_stream كل كتلة ClickHouse على شكل Pandas DataFrame ثنائية الأبعاد. إليك مثالًا يوضّح أنه يمكن استخدام الكائن StreamContext كسياق بصورة مؤجلة (ولكن مرة واحدة فقط).

df_stream = client.query_df_stream("SELECT * FROM hits")
column_names = df_stream.source.column_names
with df_stream:
    for df in df_stream:
        process_dataframe(df)

تحوّل الطريقة query_df_arrow_stream دفعات Arrow إلى DataFrame من Pandas أو Polars. حدِّد المكتبة باستخدام dataframe_library، وقيمتها الافتراضية "pandas".

أخيرًا، تُغلِّف query_arrow_stream استجابة ClickHouse ArrowStream داخل StreamContext. ويُرجِع كل تكرار RecordBatch من PyArrow.

import clickhouse_connect

client = clickhouse_connect.get_client()

# Stream large result sets row by row
with client.query_rows_stream("SELECT number, number * 2 as doubled FROM system.numbers LIMIT 100000") as stream:
    for row in stream:
        print(row)  # Process each row
        # Output:
        # (0, 0)
        # (1, 2)
        # (2, 4)
        # Additional rows follow

import clickhouse_connect

client = clickhouse_connect.get_client()

# Stream in blocks of rows (more efficient than row-by-row)
with client.query_row_block_stream("SELECT number, number * 2 FROM system.numbers LIMIT 100000") as stream:
    for block in stream:
        print(f"Received block with {len(block)} rows")

import clickhouse_connect

client = clickhouse_connect.get_client()

# Stream query results as Pandas DataFrames
with client.query_df_stream("SELECT number, toString(number) AS str FROM system.numbers LIMIT 100000") as stream:
    for df in stream:
        # Process each DataFrame block
        print(f"Received DataFrame with {len(df)} rows")
        print(df.head(3))

import clickhouse_connect

client = clickhouse_connect.get_client()

# Stream query results as Arrow record batches
with client.query_arrow_stream("SELECT * FROM large_table") as stream:
    for arrow_batch in stream:
        # Process each Arrow batch
        print(f"Received Arrow batch with {arrow_batch.num_rows} rows")

import asyncio

import clickhouse_connect


async def main():
    async_client = await clickhouse_connect.get_async_client()
    async with await async_client.query_rows_stream(
        "SELECT number FROM numbers(100000)"
    ) as stream:
        async for row in stream:
            print(row)


asyncio.run(main())

يوفّر ClickHouse Connect طرق استعلام متخصصة للعمل مع هياكل بيانات NumPy وPandas وArrow. وتتيح لك هذه الطرق استرجاع نتائج الاستعلام مباشرةً بهذه التنسيقات الشائعة للبيانات من دون تحويل يدوي.

تعيد الطريقة query_np نتائج الاستعلام على شكل مصفوفة NumPy بدلًا من كائن QueryResult في ClickHouse Connect.

import clickhouse_connect

client = clickhouse_connect.get_client()

# Query returns a NumPy array
np_array = client.query_np("SELECT number, number * 2 AS doubled FROM system.numbers LIMIT 5")

print(type(np_array))
# Output:
# <class 'numpy.ndarray'>

print(np_array)
# Output:
# [[0 0]
#  [1 2]
#  [2 4]
#  [3 6]
#  [4 8]]

تعيد الدالة query_df نتائج الاستعلام في صورة Pandas DataFrame بدلًا من QueryResult في ClickHouse Connect.

import clickhouse_connect

client = clickhouse_connect.get_client()

# Query returns a Pandas DataFrame
df = client.query_df("SELECT number, number * 2 AS doubled FROM system.numbers LIMIT 5")

print(type(df))
# Output: <class 'pandas.core.frame.DataFrame'>
print(df)
# Output:
#    number  doubled
# 0       0        0
# 1       1        2
# 2       2        4
# 3       3        6
# 4       4        8

تعيد الدالة query_arrow جدول PyArrow باستخدام تنسيق الإخراج Arrow في ClickHouse مباشرةً. وهي تقبل query وparameters وsettings وexternal_data وtransport_settings. ويتحكم الخيار use_strings في ما إذا كانت أعمدة ClickHouse من النوع String ستُخرَج كسلاسل نصية في Arrow أو كقيم ثنائية.

import clickhouse_connect

client = clickhouse_connect.get_client()

# Query returns a PyArrow Table
arrow_table = client.query_arrow("SELECT number, toString(number) AS str FROM system.numbers LIMIT 3")

print(type(arrow_table))
# Output:
# <class 'pyarrow.lib.Table'>

print(arrow_table)
# Output:
# pyarrow.Table
# number: uint64 not null
# str: string not null
# ----
# number: [[0,1,2]]
# str: [["0","1","2"]]

يدعم ClickHouse Connect إنشاء DataFrame بكفاءة من نتائج Arrow من خلال query_df_arrow وquery_df_arrow_stream. تتجنب هاتان الطريقتان التحويل عبر كائنات الصفوف في بايثون، وتعيدان استخدام مخازن Arrow المؤقتة عندما تسمح بذلك المكتبة المستهدفة:

• query_df_arrow: ينفّذ الاستعلام باستخدام تنسيق الإخراج Arrow في ClickHouse ويُرجع DataFrame.
  • dataframe_library="pandas" يُرجع DataFrame من Pandas 2.0 أو إصدار أحدث باستخدام pd.ArrowDtype.
  • dataframe_library="polars" يُرجع DataFrame من Polars مُنشأً عبر pl.from_arrow.
• query_df_arrow_stream: يبث دفعات Arrow على شكل DataFrames من Pandas أو Polars.

import clickhouse_connect

client = clickhouse_connect.get_client()

# Query returns a Pandas DataFrame with Arrow dtypes (requires pandas 2.x)
df = client.query_df_arrow(
    "SELECT number, toString(number) AS str FROM system.numbers LIMIT 3",
    dataframe_library="pandas"
)

print(df.dtypes)
# Output:
# number    uint64[pyarrow]
# str       string[pyarrow]
# dtype: object

# Or use Polars
polars_df = client.query_df_arrow(
    "SELECT number, toString(number) AS str FROM system.numbers LIMIT 3",
    dataframe_library="polars"
)
print(polars_df.dtypes)
# Output:
# [UInt64, String]

# Streaming into batches of DataFrames (polars shown)
with client.query_df_arrow_stream(
    "SELECT number, toString(number) AS str FROM system.numbers LIMIT 100000", dataframe_library="polars"
) as stream:
    for df_batch in stream:
        print(f"Received {type(df_batch)} batch with {len(df_batch)} rows and dtypes: {df_batch.dtypes}")

• يتحكم ClickHouse في مخطط Arrow. ويمكن إرجاع الأنواع التي لا تملك تمثيلًا مباشرًا في Arrow باستخدام نوع فعلي متوافق، بما في ذلك الحقول الثنائية. افحص table.schema أو أنواع بيانات DataFrame قبل تطبيق التحويلات الخاصة بالتطبيق.
• تتطلب نتائج Pandas المستندة إلى Arrow الإصدار 2.0 من Pandas أو أحدث.
• يتحكم use_strings في ما إذا كانت أعمدة ClickHouse String تستخدم حقول Arrow النصية أم الثنائية عندما يدعم الخادم output_format_arrow_string_as_string.
• لا تزال tz_mode="schema" غير مدعومة في طرق الاستعلام المستندة إلى Arrow. وهي تصدر تحذيرًا وتحافظ على البيانات الوصفية للمنطقة الزمنية التي يوفّرها رد Arrow.

تتحكم تنسيقات القراءة في القيم المُعادة من query وquery_np وquery_df. ولا تنطبق على الأساليب الخام أو أساليب Arrow، لأن هذه الأساليب تستخدم تنسيق إخراج الخادم مباشرةً. على سبيل المثال، يؤدي تعيين تنسيق قراءة معرّف UUID إلى "string" إلى إرجاع سلاسل UUID بدلًا من كائنات uuid.UUID.

يمكن أن تتضمن وسيطة "نوع البيانات" لأي دالة تنسيق أحرف بدل. ويكون التنسيق سلسلة واحدة بأحرف صغيرة. وتحافظ المغلّفات الحاوية مثل Array وNullable وLowCardinality على التنسيق المحدد لنوع العنصر فيها.

يمكن تعيين تنسيقات القراءة على عدة مستويات:

• على المستوى العام، باستخدام الأساليب المعرّفة في الحزمة clickhouse_connect.datatypes.format. وسيتحكم ذلك في تنسيق نوع البيانات المُعَدّ لجميع الاستعلامات.

from clickhouse_connect.datatypes.format import set_read_format

# Return both IPv6 and IPv4 values as strings
set_read_format("IPv*", "string")

# Return all Date types as the underlying epoch second or epoch day
set_read_format("Date*", "int")

• على مستوى الاستعلام بأكمله، باستخدام وسيطة القاموس الاختيارية query_formats. في هذه الحالة، سيستخدم أي عمود (أو عمود فرعي) من أنواع البيانات المحددة التنسيق المُهيّأ.

# Return any UUID column as a string
client.query(
    "SELECT user_id, user_uuid, device_uuid FROM users",
    query_formats={"UUID": "string"},
)

• لعمود نتيجة معيّن، استخدم القاموس الاختياري column_formats. يمثّل كل مفتاح اسم عمود مُعاد، وتمثّل قيمته سلسلة تنسيق أو تعيينًا متداخلًا من أسماء أنواع ClickHouse إلى التنسيقات، وهذا مفيد مع Tuples وMaps وغيرها من أنواع الحاويات.

# Return IPv6 values in the `dev_address` column as strings
client.query(
    "SELECT device_id, dev_address, gw_address FROM devices",
    column_formats={"dev_address": "string"},
)

يمكن لاستعلامات ClickHouse قبول بيانات خارجية بأي تنسيق إدخال مدعوم. يرسل العميل البيانات كجزء من الطلب، ويمكن للاستعلام الرجوع إليها باعتبارها جدولًا خارجيًا مؤقتًا. راجع توثيق البيانات الخارجية في ClickHouse. تقبل طرائق استعلام العميل كائن clickhouse_connect.driver.external.ExternalData عبر المعلمة external_data.

يوضح هذا المثال ربط ملف CSV خارجي بجدول directors مخزَّن على الخادم:

import clickhouse_connect

from clickhouse_connect.driver.external import ExternalData

client = clickhouse_connect.get_client()
ext_data = ExternalData(
    file_path="/data/movies.csv",
    fmt="CSV",
    structure=[
        "movie String",
        "year UInt16",
        "rating Decimal32(3)",
        "director String",
    ],
)
result = client.query(
    "SELECT name, avg(rating) "
    "FROM directors INNER JOIN movies ON directors.name = movies.director "
    "GROUP BY directors.name",
    external_data=ext_data,
).result_rows

يمكن إضافة ملفات بيانات خارجية إضافية إلى الكائن ExternalData الأساسي باستخدام الطريقة add_file، التي تأخذ المعاملات نفسها التي يأخذها المُنشئ. بالنسبة إلى HTTP، تُرسَل جميع البيانات الخارجية كجزء من تحميل ملف multi-part/form-data.

لا تدعم الواجهة الخلفية لـ chDB البيانات الخارجية.

تُنقل قيم DateTime وDateTime64 في ClickHouse على هيئة قيم رقمية مستندة إلى epoch. ويحوّلها ClickHouse Connect إلى كائنات datetime في بايثون باستخدام البيانات الوصفية للأعمدة، وتجاوزات الاستعلام، وسياسة المنطقة الزمنية الخاصة بالعميل.

لدى العميل خياران مستقلان للمنطقة الزمنية:

• يحدّد tz_source المنطقة الزمنية الاحتياطية للأعمدة التي لا تحتوي على بيانات وصفية صريحة للمنطقة الزمنية:
  • "auto" هو الخيار الافتراضي. ويستخدم المنطقة الزمنية للخادم عندما يتمكن العميل من تحديدها بأمان عبر انتقالات التوقيت الصيفي، وإلا يستخدم المنطقة الزمنية المحلية.
  • تستخدم "server" دائماً المنطقة الزمنية للخادم.
  • تستخدم "local" دائماً المنطقة الزمنية المحلية للعملية.
• يحدّد tz_mode كيفية التعامل مع معلومات المنطقة الزمنية:
  • "naive_utc" هو الخيار الافتراضي. وتُعاد النتائج ذات التوقيت UTC أو المكافئ له على هيئة كائنات datetime غير مرتبطة بمنطقة زمنية، حفاظاً على التوافق مع الإصدارات السابقة.
  • تحافظ "aware" على tzinfo الخاصة بـ UTC وتعيد قيماً مرتبطة بمنطقة زمنية بتوقيت UTC.
  • تعيد "schema" قيماً مرتبطة بمنطقة زمنية فقط عندما يصرّح نوع العمود بمنطقة زمنية، وتعيد قيماً غير مرتبطة بمنطقة زمنية لأعمدة DateTime/DateTime64 المجرّدة.

في الاستعلامات العادية "naive_utc" و"aware"، تُحدَّد المنطقة الزمنية النشطة بهذا الترتيب:

1. تجاوز column_tzs لكل عمود.
2. البيانات الوصفية للمنطقة الزمنية في نوع عمود ClickHouse.
3. تجاوز query_tz على مستوى الاستعلام.
4. معلومات المنطقة الزمنية المُعادة مع استجابة HTTP.
5. المنطقة الزمنية الاحتياطية التي يحددها tz_source.

يتجاهل tz_mode="schema" المناطق الزمنية الخاصة بالاستعلام والمناطق الزمنية الاحتياطية، لكن تجاوز column_tzs الصريح يظل ذا أولوية.

result = client.query(
    "SELECT "
    "toDateTime('2026-01-15 12:00:00', 'UTC') AS utc_time, "
    "toDateTime('2026-01-15 12:00:00', 'America/Denver') AS denver_time",
    tz_mode="aware",
)

assert result.first_row[0].tzinfo is not None
assert result.first_row[1].tzinfo is not None

تُحدَّد أسماء المناطق الزمنية باستخدام وحدة zoneinfo من المكتبة القياسية. تتلقى عمليات تثبيت Windows حزمة tzdata تلقائيًا. في صور Linux المصغّرة التي لا تتضمن قاعدة بيانات IANA للمناطق الزمنية، ثبّت clickhouse-connect[tzdata].

تحافظ نتائج Pandas على الدقة الطبيعية لكل نوع في ClickHouse، مثل datetime64[s] لـ DateTime وdatetime64[ms] لـ DateTime64(3). لا تدعم طريقتا DataFrame المعتمدتان على Arrow، query_df_arrow وquery_df_arrow_stream، الخيار tz_mode="schema" بعد، وستصدران تحذيرًا عند طلبه. وتُرجع query_arrow وquery_arrow_stream البيانات الوصفية للمنطقة الزمنية من استجابة Arrow كما هي.