ArrowStream

وثائق تنسيق ArrowStream

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

​

الوصف

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

​

مثال للاستخدام

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

clickhouse-client --secure --host sql-clickhouse.clickhouse.com --user demo --database forex

يخزّن الجدول forex أسعار صرف العملات. ويمكننا فحص حجمه ومدى كفاءة ضغطه على القرص عبر الاستعلام عن system.columns:

Query

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

   ┌─table─┬─compressed_size─┬─uncompressed_size─┬───compression_ratio─┐
1. │ forex │ 63.69 GiB       │ 280.48 GiB        │ 0.22708227109363446 │
   └───────┴─────────────────┴───────────────────┴─────────────────────┘

على خلاف تنسيق Arrow في “وضع الملف”، الذي يتطلب اكتمال النتيجة بالكامل قبل أن يمكن قراءتها، يُرسَل ArrowStream على شكل تسلسل من دفعات السجلات يمكن للمستهلك قراءتها تدريجيًا فور وصولها. وهذا يجعله مناسبًا جدًا لبث نتيجة استعلام مباشرةً إلى أداة تصور أو تحليلات دون الحاجة أولًا إلى تخزين مجموعة البيانات بالكامل بعد احتسابها.

لبث النتيجة، أرسل الاستعلام عبر واجهة HTTP الخاصة بـ ClickHouse باستخدام طلب POST، واقرأ الاستجابة على أنها دفق Arrow. نعطّل ضغط خرج Arrow عبر الإعداد output_format_arrow_compression_method لكي تتمكن الجهات المستهلكة من فك ترميز الدفعات مباشرةً عند استلامها.

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

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

   ┌─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، فإن RecordBatchReader يُرجع كل دفعة من السجلات بمجرد بثّها من الخادم:

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، راجع مقالة المدونة بث تصورات آنية باستخدام ClickHouse وApache Arrow وPerspective.

​

إعدادات التنسيق

يستخدم ArrowStream إعدادات التنسيق نفسها المستخدمة في تنسيق 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