واجهة Arrow Flight

توثيق لواجهة Apache Arrow Flight في ClickHouse، تتيح لعملاء Flight SQL الاتصال بـ ClickHouse

​

نظرة عامة

يدعم ClickHouse بروتوكول Apache Arrow Flight — وهو إطار RPC عالي الأداء لنقل البيانات العمودية بكفاءة باستخدام تنسيق Arrow IPC عبر gRPC.

يتضمن هذا التنفيذ دعم Arrow Flight SQL، مما يتيح لأدوات BI والتطبيقات التي تدعم بروتوكول Flight SQL الاستعلام من ClickHouse مباشرةً.

القدرات الأساسية:

• تنفيذ استعلامات SQL واسترجاع النتائج بتنسيق Apache Arrow.
• إدراج البيانات في الجداول باستخدام تنسيق Arrow.
• الاستعلام عن البيانات الوصفية (catalogs وschemas وtables وprimary keys) عبر أوامر Flight SQL.
• إنشاء العبارات المُحضّرة على جهة الخادم وربطها وتنفيذها وإغلاقها عبر Flight SQL.
• إدارة الجلسات والإعدادات عبر إجراءات Flight SQL.
• تشفير TLS والمصادقة باستخدام اسم المستخدم/كلمة المرور.
• الاسترجاع التدريجي للنتائج عبر PollFlightInfo.
• إلغاء الاستعلام عبر CancelFlightInfo.

​

تمكين خادم Arrow Flight

لتمكين خادم Arrow Flight، أضِف الإعداد arrowflight_port إلى إعدادات خادم ClickHouse:

<clickhouse>
    <arrowflight_port>9090</arrowflight_port>
</clickhouse>

عند بدء التشغيل، تؤكد رسالة في السجل أن الواجهة نشطة:

{} <Information> Application: Arrow Flight compatibility protocol: 0.0.0.0:9090

​

تهيئة TLS

لتمكين TLS لواجهة Arrow Flight، اضبط الإعدادات التالية:

<clickhouse>
    <arrowflight_port>9090</arrowflight_port>
    <arrowflight>
        <enable_ssl>true</enable_ssl>
        <ssl_cert_file>/path/to/server-cert.pem</ssl_cert_file>
        <ssl_key_file>/path/to/server-key.pem</ssl_key_file>
    </arrowflight>
</clickhouse>

عند تفعيل TLS، يجب على العملاء الاتصال باستخدام الصيغة grpc+tls:// بدلًا من grpc://.

​

المصادقة

تدعم واجهة Arrow Flight طريقتين للمصادقة:

​

المصادقة الأساسية

تُجري البرامج العميلة المصادقة باستخدام اسم مستخدم وكلمة مرور عبر ترويسة HTTP القياسية Authorization: Basic. وعند نجاح المصادقة، يُرجِع الخادم Bearer token في ترويسة الاستجابة.

​

مصادقة رمز Bearer

يمكن للطلبات اللاحقة استخدام رمز Bearer المُعاد من المصادقة الأساسية عبر ترويسة Authorization: Bearer <token>. ويُجدَّد الرمز تلقائيًا عند كل استخدام، وتنتهي صلاحيته وفقًا لإعداد الخادم default_session_timeout (الافتراضي: 60 ثانية).

​

مثال بلغة بايثون

import pyarrow.flight as flight

client = flight.FlightClient("grpc://localhost:9090")

# Basic auth returns a bearer token for subsequent calls
token_pair = client.authenticate_basic_token("default", "")
options = flight.FlightCallOptions(headers=[token_pair])

باستخدام TLS:

import pyarrow.flight as flight

with open("ca-cert.pem", "rb") as f:
    tls_root_certs = f.read()

client = flight.FlightClient(
    "grpc+tls://localhost:9090",
    tls_root_certs=tls_root_certs,
)

token_pair = client.authenticate_basic_token("default", "password")
options = flight.FlightCallOptions(headers=[token_pair])

​

إدارة الجلسات

تدعم واجهة Arrow Flight جلسات ClickHouse من خلال رؤوس البيانات الوصفية المخصصة في gRPC:

الترويسة	الوصف
x-clickhouse-session-id	معرّف الجلسة. إذا تم تمريره، تشترك عدة طلبات في حالة الجلسة نفسها (الجداول المؤقتة، والإعدادات).
x-clickhouse-session-timeout	مهلة الجلسة بالثواني. يجب ألا تتجاوز max_session_timeout.
x-clickhouse-session-check	عيّن القيمة 1 للتحقق من وجود الجلسة من دون إنشائها.
x-clickhouse-session-close	عيّن القيمة 1 لإغلاق الجلسة بعد اكتمال الطلب. ويتطلب ذلك ضبط enable_arrow_close_session على true في تهيئة الخادم.

نظرًا إلى أن Arrow Flight يستخدم gRPC عبر HTTP/2، فإن أسماء رؤوس البيانات الوصفية حسّاسة لحالة الأحرف، ويجب كتابتها بأحرف صغيرة تمامًا كما هو موضح (على سبيل المثال، x-clickhouse-session-id وليس X-ClickHouse-Session-Id). وهذا مطلوب بموجب RFC 9113, Section 8.2، التي تنص على أن أسماء حقول HTTP/2 يجب أن تتكون من أحرف صغيرة فقط. ويختلف هذا عن HTTP/1.1، حيث تكون أسماء الرؤوس غير حسّاسة لحالة الأحرف.

تتيح الجلسات تعيين إعدادات ClickHouse دائمة عبر الإجراء SetSessionOptions (راجع DoAction).

​

مرجع تهيئة الخادم

الإعداد	الافتراضي	الوصف
arrowflight_port	—	المنفذ الخاص بخادم Arrow Flight. لا يبدأ الخادم إلا إذا جرى تحديد هذا الإعداد.
arrowflight.enable_ssl	false	تمكين تشفير TLS.
arrowflight.ssl_cert_file	—	المسار إلى ملف شهادة TLS. وهو مطلوب عند تمكين TLS.
arrowflight.ssl_key_file	—	المسار إلى ملف المفتاح الخاص لـ TLS. وهو مطلوب عند تمكين TLS.
arrowflight.tickets_lifetime_seconds	600	المدة بالثواني قبل انتهاء صلاحية تذاكر Flight وتنظيفها. اضبطها على 0 لتعطيل انتهاء صلاحية التذاكر تلقائيًا.
arrowflight.cancel_ticket_after_do_get	false	إذا كانت القيمة true، فستُلغى التذاكر مباشرةً بعد أن يستهلكها DoGet، مما يحرر الذاكرة.
arrowflight.poll_descriptors_lifetime_seconds	600	المدة بالثواني قبل انتهاء صلاحية واصفات الاستطلاع. اضبطها على 0 لتعطيل انتهاء الصلاحية التلقائي.
arrowflight.cancel_flight_descriptor_after_poll_flight_info	false	إذا كانت القيمة true، فستُلغى واصفات الاستطلاع بعد أن يستهلكها PollFlightInfo.
arrowflight.max_prepared_statements_per_user	100	الحد الأقصى لعدد العبارات المُحضّرة المفتوحة لكل مستخدم. اضبطه على 0 لتعطيل هذا الحد.
arrowflight.prepared_statements_lifetime_seconds	-1	وضع مدة بقاء العبارة المُحضّرة. > 0: استخدم هذه القيمة كمدة بقاء، وحدّث وقت انتهاء الصلاحية مع كل طلب لكلٍّ من العبارات المرتبطة بالجلسة وغير المرتبطة بها. 0: عطّل انتهاء الصلاحية التلقائي. -1: بالنسبة إلى العبارات المرتبطة بالجلسة، استخدم مهلة الجلسة كمدة بقاء وحدّثها مع كل طلب؛ أما العبارات غير المرتبطة بالجلسة فلا تنتهي صلاحيتها تلقائيًا.
enable_arrow_close_session	true	السماح للعملاء بإغلاق الجلسات عبر الترويسة x-clickhouse-session-close.
default_session_timeout	60	مهلة الجلسة الافتراضية بالثواني. وتتحكم أيضًا في انتهاء صلاحية رمز Bearer.
max_session_timeout	3600	الحد الأقصى المسموح به لمهلة الجلسة بالثواني.

​

طرق RPC المدعومة

​

GetFlightInfo

ينفّذ استعلامًا ويُرجع FlightInfo يتضمّن مخطط النتيجة، ونقاط النهاية مع التذاكر اللازمة لاسترجاع البيانات، وعدد الصفوف، وعدد البايتات.

يقبل FlightDescriptor، ويمكن أن يكون أحد ما يلي:

• واصف PATH: مسارًا أحادي المكوّن يُفسَّر على أنه اسم جدول. ويُنشئ SELECT * FROM <table>.
• واصف CMD: إمّا سلسلة استعلام SQL خام، أو أمر Flight SQL protobuf مُسلسل (راجع Flight SQL Commands).

يُنفَّذ الاستعلام بالكامل، وتُخزَّن النتائج في تذاكر على جانب الخادم. وتنتج كل كتلة بيانات نقطة نهاية/تذكرة منفصلة، مما يتيح للعملاء استرجاع البيانات بالتوازي.

# Query by table name
descriptor = flight.FlightDescriptor.for_path("my_table")
info = client.get_flight_info(descriptor, options)

# Query by SQL
descriptor = flight.FlightDescriptor.for_command(
    "SELECT * FROM my_table WHERE id > 100"
)
info = client.get_flight_info(descriptor, options)

# Retrieve results
for endpoint in info.endpoints:
    reader = client.do_get(endpoint.ticket, options)
    table = reader.read_all()
    print(table.to_pandas())

​

PollFlightInfo

يتيح استرداد النتائج بشكل تدريجي للاستعلامات طويلة التشغيل. فبدلًا من انتظار اكتمال الاستعلام بالكامل (كما يفعل GetFlightInfo)، يعيد PollFlightInfo النتائج على شكل كتل، كتلةً تلو الأخرى.

عند الاستدعاء الأول، يبدأ تنفيذ الاستعلام. وتتضمن الاستجابة ما يلي:

• كائن FlightInfo يحتوي على نقطة نهاية لأي كتل بيانات متاحة حتى تلك اللحظة.
• كائن FlightDescriptor لعملية الاستطلاع التالية (إذا كان من المتوقع توفر المزيد من النتائج).

تسترجع الاستدعاءات اللاحقة باستخدام الواصف المُعاد كتلًا إضافية. وعندما لا تعود هناك بيانات أخرى متاحة، لا تتضمن الاستجابة واصفًا تاليًا.

ينتظر التنفيذ الحالي حتى تتوفر كتلة بيانات، بدلًا من أن يعيد الاستجابة فورًا من دون بيانات.

​

GetSchema

يُرجع مخطط Arrow لنتيجة الاستعلام دون تنفيذ الاستعلام كاملًا. ويقبل أنواع الواصف نفسها كما في GetFlightInfo.

descriptor = flight.FlightDescriptor.for_command(
    "SELECT 1 AS x, 'hello' AS y"
)
schema_result = client.get_schema(descriptor, options)
schema = schema_result.schema
print(schema)  # x: int32, y: string

​

DoGet

يسترجع البيانات لتذكرة معيّنة. ويقبل أحد الخيارين التاليين:

• تذكرة مُعادة من GetFlightInfo أو PollFlightInfo.
• سلسلة استعلام Raw SQL كقيمة للتذكرة.

# Using a ticket from GetFlightInfo
reader = client.do_get(endpoint.ticket, options)
table = reader.read_all()

# Using a raw SQL query as ticket
ticket = flight.Ticket("SELECT number FROM system.numbers LIMIT 10")
reader = client.do_get(ticket, options)
table = reader.read_all()

​

DoPut

يرسل البيانات إلى ClickHouse. يقبل FlightDescriptor وتدفّقًا من دفعات سجلات Arrow.

إدراج حسب اسم الجدول (واصف PATH):

schema = pa.schema([("id", pa.int64()), ("name", pa.string())])
batch = pa.record_batch(
    [pa.array([1, 2, 3]), pa.array(["Alice", "Bob", "Charlie"])],
    schema=schema,
)

descriptor = flight.FlightDescriptor.for_path("my_table")
writer, _ = client.do_put(descriptor, schema, options)
writer.write_batch(batch)
writer.close()

الإدراج باستخدام SQL (واصف CMD):

descriptor = flight.FlightDescriptor.for_command(
    "INSERT INTO my_table FORMAT Arrow"
)
writer, _ = client.do_put(descriptor, schema, options)
writer.write_batch(batch)
writer.close()

تنفيذ عبارات DDL/DML عبر Flight SQL CommandStatementUpdate:

يستخدم عملاء Flight SQL الأمر CommandStatementUpdate لتنفيذ عبارات DDL/DML ‏(CREATE، INSERT، ALTER، إلخ). وتتضمن الاستجابة عدد الصفوف المتأثرة.

الإدخال المجمّع عبر Flight SQL CommandStatementIngest:

لا يُدعَم إلا الإلحاق بالجداول الموجودة (TABLE_NOT_EXIST_OPTION_FAIL + TABLE_EXISTS_OPTION_APPEND). ولا تُدعَم الكتالوجات والجداول المؤقتة لهذا الأمر.

لا تتوفر إمكانية استخدام transaction_id مع CommandStatementUpdate أو CommandStatementIngest. وإذا تم توفيره، يعرض ClickHouse الخطأ NotImplemented.

لا يُقبل لنقل البيانات سوى التنسيق Arrow. ويؤدي تحديد تنسيقات أخرى في SQL (مثل FORMAT JSON) إلى حدوث خطأ.

​

DoAction

ينفّذ إجراءات مُسمّاة. الإجراءات التالية متاحة:

​

CancelFlightInfo

يلغي استعلامًا قيد التشغيل مرتبطًا بـ FlightInfo. ويُستخرَج معرّف الاستعلام من حقل app_metadata الخاص بـ FlightInfo. كما يُلغي أيضًا أي واصفات استطلاع مرتبطة بالاستعلام.

# Start a long-running query via PollFlightInfo, then cancel it
cancel_request = flight.CancelFlightInfoRequest(info)
result = client.cancel_flight_info(cancel_request, options)
# result.status is CancelStatus.CANCELLED if successful

​

SetSessionOptions

يضبط إعدادات خادم ClickHouse للجلسة الحالية. ويتطلب ذلك تعيين معرّف جلسة عبر الترويسة x-clickhouse-session-id.

أنواع القيم المدعومة: string وboolean وinteger وdouble وقوائم من string.

إذا كان اسم الإعداد غير معروف، فسيُعاد الخطأ INVALID_NAME. وإذا تعذّر تحليل القيمة، فسيُعاد الخطأ INVALID_VALUE.

​

GetSessionOptions

يعيد جميع إعدادات ClickHouse الحالية وقيمها الخاصة بالجلسة. ويعيد خريطة تربط أسماء الإعدادات بقيم نصية (ويستعلم داخليًا من system.settings).

​

CreatePreparedStatement

ينشئ عبارة مُحضَّرة على جانب الخادم ويُرجع معرّفًا لها. يحتوي الطلب على نص استعلام SQL مع عناصر نائبة ?.

transaction_id غير مدعوم لهذا الإجراء. وإذا تم توفيره، يعيد ClickHouse الخطأ NotImplemented.

بالنسبة إلى عبارات الاستعلام، قد تتضمن الاستجابة ما يلي:

• dataset_schema: مخطط مجموعة النتائج.
• parameter_schema: مخطط معلمات العبارة.

إذا فشل استنتاج المخطط لاستعلام صالح (على سبيل المثال، عندما لا يكون استبدال العناصر النائبة بـ NULL صالحًا لهذا الاستعلام)، فسيواصل ClickHouse إنشاء العبارة المُحضَّرة ويُرجع المعرّف من دون dataset_schema.

يمثّل dataset_schema أفضل تخمين ممكن، وهو ما تقصده مواصفة Flight SQL — إذ تنص على أن مخطط النتيجة قد يعتمد على المعلمات، وأن على الخادم تقديم أفضل تخمين لديه، وأنه يجب على العملاء عدم افتراض دقة المخطط. لا تعتمد عليه؛ نفّذ العبارة للحصول على المخطط الذي يصف البيانات. وفي ClickHouse قد يختلف عمّا يُقدَّم فعليًا لسببين:

• يستبدل الاستنتاج كل ? بـ NULL، لذا فإن العنصر النائب الذي يحدّد أحد أعمدة النتيجة يُشتق نوعه من ذلك NULL وليس من القيمة التي تربطها لاحقًا. فالاستعلام SELECT ? AS x يستنتج عمودًا من النوع Nothing، لكن ربط القيمة 5 يقدّم UInt8. أما العنصر النائب المستخدم داخل مسند فقط، كما في SELECT id, name FROM t WHERE id = ?، فلا تنطبق عليه هذه المشكلة، لأن أنواع النتيجة تأتي من الجدول.
• العمود الذي لا يوجد له مكافئ في Arrow يأخذ نوع Arrow الخاص به من output_format_arrow_unsupported_types، والذي يُحلّ في كل استدعاء انطلاقًا من الجلسة التي تجريه. وبما أن المعرّف يعود إلى المستخدم لا إلى جلسة واحدة، فقد يحلّه استدعاء لاحق بصورة مختلفة فيقدّم binary حيث أُعلن عن utf8، أو العكس. وضبط الوضع داخل الاستعلام المُحضَّر نفسه يثبّته في الحالتين.

تكون العبارات المُحضَّرة مملوكة للمستخدم الذي جرت مصادقته، وليس لجلسة واحدة بعينها. وإذا فتحت عدة جلسات بالمستخدم نفسه، يمكنك تنفيذ معرّف العبارة نفسه، وإعادة الربط به، وإغلاقه من أيٍّ من تلك الجلسات.

لا يمكن للمستخدمين الآخرين تنفيذ معرّف عبارة لم ينشئوه، أو إجراء bind له، أو إغلاقه.

يتحكم arrowflight.prepared_statements_lifetime_seconds في سلوك انتهاء الصلاحية:

• > 0: استخدم القيمة المُعدّة على أنها مدة بقاء العبارة. ويُجدَّد انتهاء الصلاحية مع كل طلب لكلٍّ من العبارات المرتبطة بجلسة وغير المرتبطة بجلسة.
• 0: لا تنتهي صلاحية العبارات المُحضَّرة تلقائيًا.
• -1 (default): إذا أُنشئت العبارة داخل جلسة، فإن مدة بقائها تتبع مهلة تلك الجلسة ويُجدَّد مع كل طلب داخلها. وإذا أُنشئت العبارة من دون جلسة، فلا تنتهي صلاحيتها تلقائيًا.

تُزال العبارات منتهية الصلاحية، ولا تعود تُحتسب ضمن arrowflight.max_prepared_statements_per_user.

​

ClosePreparedStatement

يغلق عبارة مُحضَّرة ويحرّر موارد جهة الخادم المرتبطة بها عندما يحتوي الطلب على معرّف عبارة غير فارغ.

يدعم ClickHouse أيضًا الإغلاق المجمّع باستخدام ClosePreparedStatement عندما يكون المعرّف فارغًا:

• إذا كان x-clickhouse-session-id موجودًا، فسيُغلق جميع العبارات المُحضَّرة للمستخدم المُصادَق عليه ضمن تلك الجلسة.
• إذا لم يكن هناك معرّف جلسة، فسيُغلق فقط العبارات المُحضَّرة غير المرتبطة بجلسة للمستخدم المُصادَق عليه.

إذا أُنشئت عبارة مُحضَّرة داخل جلسة (عبر x-clickhouse-session-id)، فستُغلق أيضًا تلقائيًا عند إغلاق تلك الجلسة.

​

Flight SQL Commands

عندما يحتوي الواصف CMD على رسالة Protobuf لـ Flight SQL مُسلسلة، يدعم ClickHouse الأوامر التالية:

​

مدعوم من خلال GetFlightInfo / GetSchema

Command	Description
CommandStatementQuery	نفّذ أي استعلام SQL. transaction_id غير مدعوم.
CommandGetSqlInfo	استرجع البيانات الوصفية للخادم (الاسم، الإصدار، إصدار Arrow، والإمكانات).
CommandGetCatalogs	اعرض الكتالوجات. يُرجع نتيجة فارغة (لا يستخدم ClickHouse الكتالوجات).
CommandGetDbSchemas	اعرض قواعد البيانات. يدعم db_schema_filter_pattern اختياريًا (نمط SQL LIKE).
CommandGetTables	اعرض الجداول. يدعم عوامل تصفية للمخطط واسم الجدول وأنواع الجداول والتضمين الاختياري للمخطط.
CommandGetTableTypes	اعرض أنواع محركات الجداول (من system.table_engines).
CommandGetPrimaryKeys	استرجع أعمدة المفتاح الأساسي لجدول محدد.
CommandPreparedStatementQuery	نفّذ عبارة مُعدّة بنمط SELECT باستخدام المعرّف.

​

المدعوم عبر DoPut

الأمر	الوصف
CommandStatementUpdate	نفِّذ عبارة DDL/DML (CREATE، INSERT، ALTER، إلخ). يُرجع عدد الصفوف المتأثرة. transaction_id غير مدعوم.
CommandStatementIngest	إدراج بيانات Arrow بكميات كبيرة في جدول موجود. لا يُدعم سوى وضع الإلحاق. transaction_id غير مدعوم.
CommandPreparedStatementQuery	اربط قيم المعلمات لعبارة مُحضَّرة عند إرسالها عبر DoPut، ثم أعِد DoPutPreparedStatementResult مع معرّف العبارة. لا تُقبل سوى مجموعة معلمات واحدة (صف واحد)، ويجب أن يطابق عدد القيم المرتبطة تمامًا عدد العناصر النائبة ?.
CommandPreparedStatementUpdate	نفِّذ عبارة DDL/DML مُحضَّرة باستخدام معرّفها، ثم أعِد عدد الصفوف المتأثرة.

​

غير مدعوم في ClickHouse

تشير هذه الأوامر إلى ميزات لا يوفّرها ClickHouse، لذلك فهي غير مدعومة في واجهة Arrow Flight SQL.

الأمر	السبب
CommandGetCrossReference	لا يُعد ClickHouse قاعدة بيانات علائقية، ولا يطبّق قيود المفاتيح الخارجية، لذلك لا تتوفر بيانات تعريف المراجع المتبادلة.
CommandGetExportedKeys	لا يُعد ClickHouse قاعدة بيانات علائقية، ولا يطبّق قيود المفاتيح الخارجية، لذلك لا تتوفر بيانات تعريف المفاتيح المُصدَّرة.
CommandGetImportedKeys	لا يُعد ClickHouse قاعدة بيانات علائقية، ولا يطبّق قيود المفاتيح الخارجية، لذلك لا تتوفر بيانات تعريف المفاتيح المستوردة.
CommandStatementSubstraitPlan	لا يدعم ClickHouse خطط Substrait.

​

مثال متكامل

Query

import pyarrow as pa
import pyarrow.flight as flight

# Connect and authenticate
client = flight.FlightClient("grpc://localhost:9090")
token = client.authenticate_basic_token("default", "")
options = flight.FlightCallOptions(headers=[token])

# Insert data using DoPut with a PATH descriptor
schema = pa.schema([("id", pa.uint32()), ("value", pa.string())])
batch = pa.record_batch(
    [pa.array([1, 2, 3], type=pa.uint32()), pa.array(["a", "b", "c"])],
    schema=schema,
)
descriptor = flight.FlightDescriptor.for_path("test")
writer, _ = client.do_put(descriptor, schema, options)
writer.write_batch(batch)
writer.close()

# Query data using GetFlightInfo + DoGet
descriptor = flight.FlightDescriptor.for_command(
    "SELECT * FROM test ORDER BY id"
)
info = client.get_flight_info(descriptor, options)
for endpoint in info.endpoints:
    reader = client.do_get(endpoint.ticket, options)
    table = reader.read_all()
    print(table.to_pandas())

Response

   id value
0   1     a
1   2     b
2   3     c

​

تنسيق البيانات

تُنقل جميع البيانات بتنسيق Apache Arrow IPC. والتنسيق Arrow هو الوحيد المدعوم — أما تحديد تنسيقات ClickHouse الأخرى (مثل FORMAT JSON أو FORMAT CSV) فيؤدي إلى خطأ.

تُربط أنواع بيانات ClickHouse بأنواع Arrow أثناء التسلسل. ويستخدم Arrow Flight دائمًا الربط القياسي (canonical) الخاص بـ Arrow، وخلافًا لتنسيقي الإخراج Arrow وArrowStream، فإنه لا يتبع إعدادات output_format_arrow_* التي تغيّر طريقة تمثيل النوع — فإعدادات output_format_arrow_string_as_string وoutput_format_arrow_low_cardinality_as_dictionary وoutput_format_arrow_date_as_uint16 وoutput_format_arrow_fixed_string_as_fixed_byte_array وإعدادات فهرس الـ dictionary لا أثر لها هنا. لذلك قد يُنتج الاستعلام نفسه مخططًا عبر Arrow Flight يختلف عمّا يُنتجه عبر FORMAT Arrow، وهذا مقصود بالتصميم، لسببين:

• يُثبّت Flight SQL مخطط استجابات البيانات الوصفية الخاصة به. فعلى سبيل المثال، يجب أن يُرجع CommandGetTables القيم catalog_name: utf8, db_schema_name: utf8, table_name: utf8 not null, table_type: utf8 not null, table_schema: bytes not null. والسماح لأحد إعدادات الـ session بتحويل تلك الأعمدة من utf8 إلى binary سيجعل ClickHouse غير متوافق مع كل مشغّل (driver) لـ Flight SQL، كما سيغيّر المخطط الخاص بكل جدول والذي يُعلن عنه ClickHouse داخل table_schema.
• يجلب عميل Flight المخطط والبيانات في نداءات منفصلة (GetFlightInfo أو GetSchema، ثم DoGet). وأي إعداد قادر على تغيير المخطط يفتح الباب لعدم تطابق المخطط المُعلن مع الدفق المُسلّم إذا تغيّرت الـ session في الأثناء.

والاستثناء الوحيد هو نوع لا مقابل له في Arrow على الإطلاق، مثل JSON أو Dynamic أو QBit أو AggregateFunction. فلا يوجد ربط قياسي يمكن الالتزام به، ومن ثمّ يجب على ClickHouse اختيار تمثيل ما، ويتيح لك output_format_arrow_unsupported_types تحديد أيّها:

Value	السلوك
throw	يُرفض الاستعلام.
text	قيمة واحدة لكل row في شكلها النصي، كعمود Utf8 في Arrow — وهو ما يُرجعه CAST(col AS String).
binary (الافتراضي)	قيمة واحدة لكل row في شكلها الثنائي، كعمود Binary في Arrow — وهو الترميز الذي يستخدمه RowBinary.

وعمود AggregateFunction هو النوع الوحيد الذي يبقى عمود Binary في Arrow حتى في وضع text: إذ إن شكله النصي هو aggregate state الخام، وهو ليس UTF-8 صالحًا، بينما يجب أن يحتوي عمود Utf8 في Arrow على UTF-8 صالح. استخدم finalizeAggregation إذا أردت قيمة قابلة للقراءة.

وللسبب نفسه، يستبدل ClickHouse كل تسلسل UTF-8 غير صالح في قيمة text بالمحرف U+FFFD (�) قبل كتابته في عمود Utf8. فالنوع Dynamic الذي يحمل String يُسلسل تلك البايتات حرفيًا، وقد تكون عشوائية، ولولا هذه المعالجة لخالف العمود مواصفة Arrow ولأمكن أن يرفضه عميل صارم. ولا تتغيّر سوى القيم التي هي أصلًا ليست نصًا صالحًا. استخدم وضع binary حين يتعيّن الحفاظ على البايتات كما هي تمامًا.

ولا ينطبق الإعداد output_format_arrow_string_as_string على هذه الأعمدة إطلاقًا، ولا حتى في FORMAT Arrow — فهو يحكم أعمدة String وFixedString الحقيقية فقط. لذا فإن نوع Arrow لعمود clickhouse.opaque يبيّن دائمًا الترميز الذي يحمله: Utf8 للشكل النصي، وBinary للشكل الثنائي.

ولهذا السبب يفقد aggregate state المحفوظ داخل Dynamic جزءًا من البيانات في وضع text، بخلاف عمود AggregateFunction. فنوع العمود مُشتق من Dynamic، وهو لا يقول شيئًا عمّا تحتويه صفوفه، ويُثبَّت المخطط قبل الاطلاع على أي قيمة، ولذلك لا يمكن منح الـ state عمود Binary خاصًا به. استخدم وضع binary للحفاظ عليه. أما Variant فيسرد بدائله، ومن ثمّ يحصل AggregateFunction الموجود بينها على عمود فرعي Binary خاص به ولا يتأثر.

وفيما عدا ذلك، لا يمكن تمييز مثل هذا العمود عن عمود Utf8/Binary حقيقي، ولذلك يُعلَن كنوع extension في Arrow: تحمل بيانات الحقل الوصفية ARROW:extension:name = clickhouse.opaque واسم نوع ClickHouse الأصلي في ARROW:extension:metadata. والعميل الذي لا يتعرّف على اسم الـ extension يرى نوع التخزين البسيط، كما تنص مواصفة Arrow. وتُوسم nested columns على حقلها الخاص، فيحمل العنصر الفرعي لـ Array(JSON) الوسم، وكذلك مفتاح Map(JSON, ...)، لا الحاوية نفسها.

لا يزال الإعداد المنطقي الأقدم output_format_arrow_unsupported_types_as_binary يعمل، وهو مكافئ لـ throw عند القيمة 0 ولـ binary عند القيمة 1. ولا يُؤخَذ به إلا ما دام output_format_arrow_unsupported_types على قيمته الافتراضية.

​

التوافق

واجهة Arrow Flight متوافقة مع أي عميل أو أداة تدعم بروتوكول Arrow Flight أو Arrow Flight SQL، بما في ذلك:

• بايثون (pyarrow)
• Java (org.apache.arrow.flight)
• C++ (arrow::flight)
• Go (apache/arrow/go)
• برامج تشغيل ADBC ‏(Arrow Database Connectivity)
• DBeaver، وأدوات أخرى تدعم Flight SQL

إذا كان هناك موصل ClickHouse أصلي متاح لأداتك (مثل JDBC أو ODBC أو البروتوكول الأصلي)، ففضّل استخدامه ما لم تكن هناك حاجة محددة إلى Arrow Flight لأسباب تتعلق بالأداء أو بتوافق التنسيقات.

​

ميزات ArrowFlight على جهة العميل

يمكن لـ ClickHouse أيضًا العمل كعميل لـ Flight لقراءة البيانات من خوادم Arrow Flight الخارجية. راجع:

• محرك جدول ArrowFlight
• دالة جدول arrowFlight

​

راجع أيضًا

• مواصفة Apache Arrow Flight
• مواصفة Apache Arrow Flight SQL
• تنسيق Arrow في ClickHouse