`.
* **واصف CMD**: إمّا سلسلة استعلام SQL خام، أو أمر Flight SQL protobuf مُسلسل (راجع [Flight SQL Commands](#flight-sql-commands)).
يُنفَّذ الاستعلام بالكامل، وتُخزَّن النتائج في تذاكر على جانب الخادم. وتنتج كل كتلة بيانات نقطة نهاية/تذكرة منفصلة، مما يتيح للعملاء استرجاع البيانات بالتوازي.
```python theme={null}
# 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`.
```python theme={null}
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 كقيمة للتذكرة.
```python theme={null}
# 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):
```python theme={null}
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):
```python theme={null}
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`. كما يُلغي أيضًا أي واصفات استطلاع مرتبطة بالاستعلام.
```python theme={null}
# 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`.
تكون العبارات المُحضَّرة مملوكة للمستخدم الذي جرت مصادقته، وليس لجلسة واحدة بعينها. وإذا فتحت عدة جلسات بالمستخدم نفسه، يمكنك تنفيذ معرّف التعليمة نفسه، وإعادة الربط به، وإغلاقه من أيٍّ من تلك الجلسات.
لا يمكن للمستخدمين الآخرين تنفيذ معرّف تعليمة لم ينشئوه، أو إجراء 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](https://arrow.apache.org/docs/format/FlightSql.html) مُسلسلة، يدعم 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. |
## مثال متكامل
```python title="Query" theme={null}
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())
```
```text title="Response" theme={null}
id value
0 1 a
1 2 b
2 3 c
```
## تنسيق البيانات
تُنقَل جميع البيانات بتنسيق Apache Arrow IPC. ولا يُدعَم سوى تنسيق `Arrow` — إذ إن تحديد تنسيقات ClickHouse أخرى (مثل `FORMAT JSON` و`FORMAT CSV`) يؤدي إلى ظهور خطأ.
تُطابَق أنواع بيانات ClickHouse مع أنواع Arrow أثناء التسلسل. ويحدّد الإعداد `output_format_arrow_unsupported_types_as_binary` ما إذا كانت أنواع ClickHouse غير المدعومة ستُسلسَل على شكل بيانات ثنائية.
## التوافق
واجهة 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](/ar/reference/engines/table-engines/integrations/arrowflight)
* [دالة جدول arrowFlight](/ar/reference/functions/table-functions/arrowflight)
## راجع أيضًا
* [مواصفة Apache Arrow Flight](https://arrow.apache.org/docs/format/Flight.html)
* [مواصفة Apache Arrow Flight SQL](https://arrow.apache.org/docs/format/FlightSql.html)
* [تنسيق Arrow في ClickHouse](/ar/reference/formats/Arrow/Arrow)