> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8c05c8a2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> وثائق تنسيق ArrowStream

# ArrowStream

| الإدخال | الإخراج | اسم مستعار |
| ------- | ------- | ---------- |
| ✔       | ✔       |            |

<div id="description">
  ## الوصف
</div>

`ArrowStream` هو تنسيق Apache Arrow في "وضع البث". وقد صُمم لمعالجة البيانات المتدفقة داخل الذاكرة.

<div id="example-usage">
  ## مثال للاستخدام
</div>

في المثال أدناه، نستخدم مجموعة البيانات `forex` المتاحة في
[ClickHouse SQL playground](https://sql.clickhouse.com). يمكنك الاتصال بها
عن بُعد باستخدام `clickhouse-client` مع المضيف `sql-clickhouse.clickhouse.com`
والمستخدم `demo` (من دون كلمة مرور). يوجد الجدول `forex` في
قاعدة البيانات `forex`، لذا نحدده كقاعدة البيانات الافتراضية:

```bash theme={null}
clickhouse-client --secure --host sql-clickhouse.clickhouse.com --user demo --database forex
```

يخزّن الجدول `forex` أسعار صرف العملات. ويمكننا فحص حجمه
ومدى كفاءة ضغطه على القرص عبر الاستعلام عن [`system.columns`](/ar/reference/system-tables/columns):

```sql title="Query" theme={null}
SELECT
    table,
    formatReadableSize(sum(data_compressed_bytes)) AS compressed_size,
    formatReadableSize(sum(data_uncompressed_bytes)) AS uncompressed_size,
    sum(data_compressed_bytes) / sum(data_uncompressed_bytes) AS compression_ratio
FROM system.columns
WHERE (database = 'forex') AND (table = 'forex')
GROUP BY table
ORDER BY table ASC
```

```response title="Response" theme={null}
   ┌─table─┬─compressed_size─┬─uncompressed_size─┬───compression_ratio─┐
1. │ forex │ 63.69 GiB       │ 280.48 GiB        │ 0.22708227109363446 │
   └───────┴─────────────────┴───────────────────┴─────────────────────┘
```

على خلاف تنسيق [`Arrow`](/ar/reference/formats/Arrow/Arrow) في "وضع الملف"، الذي
يتطلب اكتمال النتيجة بالكامل قبل أن يمكن قراءتها، يُرسَل `ArrowStream` على
شكل تسلسل من دفعات السجلات يمكن للمستهلك قراءتها تدريجيًا فور
وصولها. وهذا يجعله مناسبًا جدًا لبث نتيجة استعلام مباشرةً إلى
أداة تصور أو تحليلات دون الحاجة أولًا إلى تخزين مجموعة البيانات بالكامل بعد احتسابها.

لبث النتيجة، أرسل الاستعلام عبر واجهة HTTP الخاصة بـ ClickHouse باستخدام
طلب `POST`، واقرأ الاستجابة على أنها دفق Arrow. نعطّل ضغط
خرج Arrow عبر الإعداد
[`output_format_arrow_compression_method`](/ar/reference/settings/formats#output_format_arrow_compression_method)
لكي تتمكن الجهات المستهلكة من فك ترميز الدفعات مباشرةً عند استلامها.

خرج `ArrowStream` هو بيانات ثنائية خام، لذا بدلًا من طباعته في
الطرفية نمرّره عبر pipe إلى مستهلك. وهذا الدفق ذاتي الوصف (يحمل
المخطط الخاص به)، لذلك نمرّره هنا مباشرةً إلى
[`clickhouse-local`](/ar/concepts/features/tools-and-utilities/clickhouse-local)، الذي يقرأ
الدفعات الواردة باستخدام `--input-format ArrowStream` ويستعلم عنها كأنها جدول.
جدول `forex` كبير، لذا قيّدنا الاستعلام البعيد باستخدام شرط `WHERE`
و`LIMIT` لإبقاء هذا المثال صغيرًا:

```bash theme={null}
curl "https://sql-clickhouse.clickhouse.com:8443/?user=demo&database=forex" \
    --data-binary "
        SELECT
            concat(base, '.', quote) AS base_quote,
            datetime AS last_update,
            CAST(bid, 'Float32') AS bid,
            CAST(ask, 'Float32') AS ask,
            ask - bid AS spread
        FROM forex
        WHERE base = 'USD' AND quote = 'CHF'
        ORDER BY datetime ASC
        LIMIT 5
        FORMAT ArrowStream
        SETTINGS output_format_arrow_compression_method='none'" \
  | clickhouse-local --input-format ArrowStream \
      --query "SELECT * FROM table ORDER BY last_update ASC FORMAT PrettyCompact"
```

```response title="Response" theme={null}
   ┌─base_quote─┬─────────────last_update─┬────bid─┬────ask─┬────────────────spread─┐
1. │ USD.CHF    │ 2000-05-30 17:23:44.000 │  1.688 │ 1.6885 │ 0.0005000829696655273 │
2. │ USD.CHF    │ 2000-05-30 17:23:46.000 │ 1.6885 │  1.689 │ 0.0004999637603759766 │
3. │ USD.CHF    │ 2000-05-30 17:23:48.000 │ 1.6886 │ 1.6891 │ 0.0005000829696655273 │
4. │ USD.CHF    │ 2000-05-30 17:23:49.000 │ 1.6888 │ 1.6893 │ 0.0004999637603759766 │
5. │ USD.CHF    │ 2000-05-30 17:24:45.000 │  1.689 │ 1.6895 │ 0.0004999637603759766 │
   └────────────┴─────────────────────────┴────────┴────────┴───────────────────────┘
```

يمكن لأي عميل يدعم Arrow استهلاك نفس الدفق تدريجيًا، إذ
يقرأه على دفعات بدلًا من تخزين النتيجة كاملةً مؤقتًا. على سبيل المثال،
باستخدام [مكتبة Apache Arrow لـ JavaScript](https://arrow.apache.org/docs/js/)، فإن
`RecordBatchReader` يُرجع كل دفعة من السجلات بمجرد بثّها من
الخادم:

```js theme={null}
const reader = await RecordBatchReader.from(response);
await reader.open();
for await (const recordBatch of reader) {
    const batchTable = new Table(recordBatch);
    const ipcStream = tableToIPC(batchTable, 'stream');
    const bytes = new Uint8Array(ipcStream);
    table.update(bytes);
}
```

للاطلاع على شرح كامل خطوة بخطوة لكيفية بث بيانات `ArrowStream` من ClickHouse إلى
تصور آني باستخدام [Perspective](https://perspective.finos.org/)، راجع
مقالة المدونة
[بث تصورات آنية باستخدام ClickHouse وApache Arrow وPerspective](https://clickhouse.com/blog/streaming-real-time-visualizations-clickhouse-apache-arrow-perpsective).

<div id="format-settings">
  ## إعدادات التنسيق
</div>

يستخدم `ArrowStream` إعدادات التنسيق نفسها المستخدمة في تنسيق [`Arrow`](/ar/reference/formats/Arrow/Arrow).

| الإعداد                                                                      | الوصف                                                                                                                                  | الافتراضي   |
| ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `input_format_arrow_allow_missing_columns`                                   | السماح بوجود أعمدة مفقودة عند قراءة تنسيقات إدخال Arrow                                                                                | `1`         |
| `input_format_arrow_case_insensitive_column_matching`                        | تجاهل حالة الأحرف عند مطابقة أعمدة Arrow مع أعمدة CH.                                                                                  | `0`         |
| `input_format_arrow_import_nested`                                           | إعداد مهمل، ولا تأثير له.                                                                                                              | `0`         |
| `input_format_arrow_skip_columns_with_unsupported_types_in_schema_inference` | تخطي الأعمدة ذات الأنواع غير المدعومة أثناء استدلال المخطط لتنسيق Arrow                                                                | `0`         |
| `output_format_arrow_compression_method`                                     | طريقة الضغط لتنسيق إخراج Arrow. خوارزميات الضغط المدعومة: lz4\_frame و zstd و none (غير مضغوط)                                         | `lz4_frame` |
| `output_format_arrow_date_as_uint16`                                         | كتابة قيم Date كأرقام 16-بت عادية (تُقرأ لاحقًا كـ UInt16)، بدلًا من تحويلها إلى نوع Arrow DATE32 بحجم 32 بت (تُقرأ لاحقًا كـ Date32). | `0`         |
| `output_format_arrow_fixed_string_as_fixed_byte_array`                       | استخدام نوع Arrow FIXED\_SIZE\_BINARY بدلًا من Binary لأعمدة FixedString.                                                              | `1`         |
| `output_format_arrow_low_cardinality_as_dictionary`                          | تمكين إخراج النوع LowCardinality كنوع Arrow Dictionary                                                                                 | `0`         |
| `output_format_arrow_string_as_string`                                       | استخدام نوع Arrow String بدلًا من Binary لأعمدة String                                                                                 | `1`         |
| `output_format_arrow_unsupported_types_as_binary`                            | إخراج الأنواع التي لا يتوفر لها تحويل كبيانات ثنائية خام. إذا كانت القيمة false، فستؤدي هذه الأنواع إلى ظهور الاستثناء UNKNOWN\_TYPE.  | `1`         |
| `output_format_arrow_use_64_bit_indexes_for_dictionary`                      | استخدام أعداد صحيحة 64-بت دائمًا لفهارس القاموس في تنسيق Arrow                                                                         | `0`         |
| `output_format_arrow_use_signed_indexes_for_dictionary`                      | استخدام أعداد صحيحة موقعة لفهارس القاموس في تنسيق Arrow                                                                                | `1`         |