صيغة Native - ClickHouse Documentation

صيغة Native هي تنسيق wire العمودي الذي يعتمده ClickHouse لنقل البيانات الجدولية، وتُستخدم في عدة مواضع:

متن حزم Data وTotals وExtremes وLog وProfileEvents في بروتوكول TCP الأصلي (علمًا بأن حزمة TableColumns ليست كتلة Native، إذ تحمل سلسلتين ثنائيتين، ولذلك يُشرح تخطيطها في مواصفة البروتوكول الأصلي)؛
إخراج SELECT ... FORMAT Native عبر HTTP؛
الملفات المُصدَّرة باستخدام INTO OUTFILE ... FORMAT Native؛
حمولات النسخ المتماثل بين الخوادم.

تصف هذه الصفحة البايتات داخل كتلة — أي الحمولة العمودية — وترميزات الأنواع الخاصة بكل عمود التي تتكوّن منها. أما تأطير الحزم وحالة الاتصال والتفاوض على الإصدار فتتناولها مواصفة البروتوكول الأصلي. تُرمَّز جميع حقول الأعداد الصحيحة متعددة البايتات بترتيب little-endian، وتُمثَّل الأعداد الصحيحة ذات الإشارة بنظام المتمم الثنائي (two’s complement).

للاطلاع على مقدمة موجّهة للمستخدمين حول صيغة Native (مع أمثلة باستخدام curl)، راجع صفحة صيغة Native. أما هذه المواصفة فهي مرجع منخفض المستوى لتنسيق wire.

نظرة عامة

كل ما ينقل الصفوف في تنسيق النقل هو كتلة: مقطع ذاتي الوصف من الصفوف مُخزَّن عمودًا تلو الآخر، إذ تأتي جميع قيم العمود 1 أولًا، ثم جميع قيم العمود 2، وهكذا. ولا تحمل الكتلة إلا الأعمدة التي يشير إليها الاستعلام، ولا تحمل الجدول كاملًا أبدًا. تُرتَّب بيانات data الخاصة بالعمود وفقًا لـالعائلة التي ينتمي إليها نوعه. وفيما يلي هذه العائلات مرتبةً تصاعديًا بحسب تعقيد أداة فك الترميز:

بنية كتلة wire عمودية وعائلات تخطيط بياناتها

الأنواع ثابتة العرض ترتّب data على هيئة بايتات خام بحجم bytes_per_value × num_rows، دون أي تأطير على مستوى الصف.
الأنواع المركّبة (Nullable وArray وTuple وMap وNested) لها بنية تعاودية يمكن اشتقاقها بالكامل من سلسلة النوع، فلا بادئة إصدار لها ولا حالة تمتد عبر الكتل.
الأنواع ذات الإصدارات / ذات الحالة (LowCardinality وJSON وVariant وDynamic) تبدأ كل كتلة غير فارغة ببادئة إصدار التسلسل/بادئة الحالة. وفي تنسيق النقل Native، تكون هذه البادئة وأي قاموس مرتبطَين بكل كتلة على حدة — فالصيغة لا تحمل أي حالة عبر الكتل (إذ يُنشئ الكاتب حالة تسلسل جديدة لكل كتلة ويضبط low_cardinality_max_dictionary_size = 0). أما الحالة الممتدة عبر الكتل فتخص تخزين MergeTree على القرص، ولا علاقة لها بتخطيط wire الخاص بصيغة Native.

العناصر الأولية للتمثيل الثنائي

تعتمد صيغة Native على أربعة ترميزات أولية.

العنصر الأولي	الحجم	الوصف
VarUInt	1–10 B	عدد صحيح بلا إشارة ومتغير الطول بترميز LEB-128
عدد صحيح ثابت العرض	1, 2, 4, 8, 16, 32 B	ترتيب بايتات little-endian، مع تمثيل المتمم الثنائي (two’s complement) للأعداد ذات الإشارة
String	متغير	بادئة طول من نوع VarUInt تليها البايتات الخام لكل قيمة؛ ويُستخدم دفق إزاحات منفصل بدءًا من revision `54492`+
Bool	1 B	`0x00` = false، وأي قيمة غير صفرية = true

VarUInt

عدد صحيح بدون إشارة متغير الطول يستخدم ترميز LEB-128. يحمل كل بايت 7 بتات بيانات في المواضع 0–6، وبت استمرار واحدًا في الموضع 7. تكون قيمة بت الاستمرار 1 عندما تليه بايتات أخرى، و0 في البايت الأخير.

نطاق القيمة	عدد البايتات
0 – 127	1
128 – 16383	2
16384 – 2097151	3
حتى النطاق الكامل لـ UInt64	حتى 10

ترميز القيمة 300:

300 = 0b100101100

Byte 0: 0xAC = 0b10101100   (data: 0101100, continuation: 1)
Byte 1: 0x02 = 0b00000010   (data: 0000010, continuation: 0)

فك ترميز البايتين 0xAC 0x02:

Byte 0: data = 0x2C, continuation = 1 → accumulator = 0x2C, shift = 7
Byte 1: data = 0x02, continuation = 0 → accumulator = (0x02 << 7) | 0x2C = 300

الأعداد الصحيحة ذات العرض الثابت

النوع	البايتات	الترميز
UInt8	1	بايت خام
UInt16	2	Little-endian
UInt32	4	Little-endian
UInt64	8	Little-endian
UInt128	16	Little-endian
UInt256	32	Little-endian
Int8	1	بايت خام، بتمثيل المتمم الثنائي
Int16	2	Little-endian، بتمثيل المتمم الثنائي
Int32	4	Little-endian، بتمثيل المتمم الثنائي
Int64	8	Little-endian، بتمثيل المتمم الثنائي
Int128	16	Little-endian، بتمثيل المتمم الثنائي
Int256	32	Little-endian، بتمثيل المتمم الثنائي
Float32	4	IEEE 754 أحادي الدقة، little-endian
Float64	8	IEEE 754 مزدوج الدقة، little-endian

على سبيل المثال، تُرمَّز القيمة 1 من النوع UInt32 بالشكل 01 00 00 00، والقيمة -1 من النوع Int32 بالشكل FF FF FF FF.

String

سلسلة من البايتات مسبوقة بطولها:

[VarUInt: byte_length] [byte_length bytes: raw value]

لا يُشترط أن يكون تسلسل البايتات بترميز UTF-8 صالحًا. تُرمَّز السلسلة الفارغة في صورة بايت واحد هو 0x00، ويمكن أن تحتوي السلاسل النصية على أي قيم للبايتات، بما في ذلك محارف NUL المُضمَّنة. فعلى سبيل المثال، تُرمَّز السلسلة "ab" في صورة 02 61 62؛ ولفك ترميزها، اقرأ الطول المُرمَّز بصيغة VarUInt (2)، ثم اقرأ العدد نفسه من البايتات.

Bool

بايت واحد. تمثّل القيمة 0x00 القيمة false، بينما تمثّل أي قيمة غير صفرية القيمة true (والصيغة القياسية لها هي 0x01).

بنية الكتلة والأعمدة

تخطيط wire للكتلة

[BlockInfo]               metadata (only on the TCP Data-packet path; see below)
[VarUInt: num_columns]    number of columns in this block
[VarUInt: num_rows]       number of rows in this block
[Column × num_columns]    column entries, omitted when num_columns = 0

يعتمد وجود البادئة BlockInfo على القناة المستخدمة، لأن الكاتب يُضبط وفق revision (راجع مراجعة البروتوكول وصيغة Native للاطلاع على الشرح الكامل، بما في ذلك كون client_protocol_version خاصًا بالإخراج فقط):

في بروتوكول TCP الأصلي، يكتب الخادم الكتل وفق الـ revision المتفاوض عليها للاتصال (وهي قيمة كبيرة — DBMS_TCP_PROTOCOL_VERSION، راجع src/Core/ProtocolDefines.h). وتُكتب BlockInfo متى كانت قيمة الـ revision أكبر من الصفر، وهو ما يتحقق دائمًا في أي اتصال فعلي. أما البايت has_custom_serialization في كل عمود (راجع تخطيط wire للأعمدة) فيُكتب ابتداءً من الـ revision 54454.
أما تنسيق الإخراج Native — أي SELECT ... FORMAT Native عبر HTTP، وINTO OUTFILE ... FORMAT Native، وصيغة Native التي يُنتجها clickhouse-client — فيُجري التسلسل عند الـ revision 0 افتراضيًا. وعند الـ revision 0 تُحذف البادئة BlockInfo والبايت has_custom_serialization معًا، فلا تتكوّن الكتلة إلا من num_columns وnum_rows والأعمدة. غير أن هذه الـ revision ليست ثابتة عبر HTTP، إذ يمكن للعميل رفعها باستخدام معامل الاستعلام ?client_protocol_version=<n>، فيعتمد الخادم تلك القيمة revision للتسلسل في الاستجابة. وعند استخدام قيمة مرتفعة بما يكفي، يتضمن إخراج HTTP البادئة BlockInfo (التي تُكتب متى كانت الـ revision أكبر من 0) والبايت has_custom_serialization (الذي يُكتب ابتداءً من الـ revision 54454)، تمامًا كما في مسار TCP. لذا لا ينبغي للعملاء أن يفترضوا أن كل حمولة FORMAT Native عبر HTTP تكون بالـ revision 0.

بعبارة أخرى، تصف أمثلة البايتات الواردة في هذا القسم والتي تبدأ ببادئة BlockInfo حمولةَ حزمة Data في TCP، في حين يُنتج الاستعلام نفسه عند تنفيذه عبر FORMAT Native الشكلَ الأقصر المعروض بجانبها.

BlockInfo

‏BlockInfo هو تسلسل من الحقول، يسبق كلًّا منها معرّف حقل من النوع VarUInt، وينتهي بمعرّف حقل قيمته 0. وتنسيق wire هنا ليس ذاتي الوصف: فمعرّف الحقل لا يُرمِّز طول قيمته ولا نوعها، ولذا يجب أن يعرف القارئ مسبقًا نوع كل معرّف حقل قد يصادفه. ويعامل القارئ الخاص بـ ClickHouse أي معرّف حقل غير معروف على أنه تلف في البيانات، فيُطلق استثناءً (UNKNOWN_BLOCK_INFO_FIELD). أما التوافق المستقبلي فتتكفّل به revision البروتوكول بدلًا من ذلك: إذ لا يكتب المُرسِل حقلًا إلا إذا كانت revision المتفاوض عليها لا تقل عن الحد الأدنى لـ revision الخاص بذلك الحقل، وبذلك لا يصادف المستقبِل الأقدم أبدًا حقلًا لا يعرفه.

معرّف الحقل	الحقل	النوع	الحد الأدنى لـ revision	الوصف
1	is_overflows	UInt8	0	كتلة الفائض الناتجة عن GROUP BY. القيمة `0` للكتل غير الفائضة.
2	bucket_number	Int32	0	حاوية التجميع. القيمة `-1` للكتل غير المقسّمة إلى حاويات.
3	out_of_order_buckets	قائمة من Int32	54480	الحاويات المؤجَّلة أثناء التجميع الموزّع. تُرمَّز على هيئة عدد من النوع VarUInt تليه قيم `Int32` بالعدد نفسه.
0	(علامة الإنهاء)	—	—	نهاية BlockInfo. مطلوبة دائمًا.

الحد الأدنى لـ revision للحقلين 1 و2 هو 0، ولذا يكونان موجودين كلما كُتب BlockInfo. أما الحقل 3 فلا يُكتب إلا عند revision 54480 فما فوق. فيما يلي تخطيط wire للحالة الشائعة (revision أقل من 54480):

[VarUInt: 1] [UInt8: is_overflows]
[VarUInt: 2] [Int32: bucket_number]
[VarUInt: 0]

تخطيط wire للعمود

يظهر العمود num_columns مرة داخل الكتلة (كتلة).

#	الحقل	النوع	الشرط	الوصف
1	name	String	دائمًا	اسم العمود
2	type	String أو ترميز ثنائي للنوع	دائمًا	سلسلة نوع ClickHouse (مثل `"UInt64"` و`"Array(String)"`) افتراضيًا؛ أو ترميز ثنائي للنوع عند ضبط `output_format_native_encode_types_in_binary_format = 1`، باستثناء الاستعلام الثانوي (راجع الملاحظة أدناه)
3	has_custom_serialization	UInt8	الميزة `CUSTOM_SERIALIZATION` (v54454)	`0` = افتراضي، `1` = مخصص (يليه kind_stack)
4	kind_stack	bytes	عندما يكون الحقل 3 = `1`	بايت تعداد واحد من نوع UInt8 (راجع أدناه) يصف التسلسل غير الافتراضي (متناثر وغيره). في حالة القيمة `COMBINATION`، يليه عدد من نوع VarUInt ثم بايتات نوع إضافية بقدر ذلك العدد. أما في حالة `Tuple` (والأنواع المركبة الأخرى التي تحمل معلومات تسلسل على مستوى العناصر)، فتكون الحمولة تعاودية — راجع أدناه.
5	data	bytes	دائمًا	قيم العمود لجميع الصفوف البالغ عددها `num_rows`. يختلف التخطيط بحسب النوع — راجع أنواع البيانات. أما الأعمدة المتناثرة، فراجع ما يلي.

تحدد أداة فك الترميز طريقة المعالجة بناءً على سلسلة type. وكثيرًا ما تتضمن سلاسل الأنواع معلمات بين قوسين؛ فتُزيل أداة فك الترميز اللاحقة (...) لاستخراج النوع الأساسي، ثم تحلل المعلمات لتحديد الحجم أو المقياس أو النوع الداخلي. ويتطلب تحليل قائمة معلمات تتضمن أنواعًا متداخلة (مثل Tuple داخل Array) أداة تقسيم بالفواصل تراعي العمق وتتتبع تداخل الأقواس، بدلًا من التقسيم البسيط على ,.

الترميز الثنائي للنوعلا يكون الحقل type من النوع النصي String إلا في الوضع الافتراضي. أما عند ضبط إعداد الاستعلام output_format_native_encode_types_in_binary_format = 1، فيصبح هذا الحقل ترميزًا ثنائيًا للنوع — وهو الترميز نفسه القائم على الوسوم والموثّق في الترميز الثنائي لأنواع البيانات — كما تستخدم قوائم النوع Dynamic المسطّحة الترميز الثنائي نفسه لأسماء أنواعها. وأي أداة فك ترميز تقرأ الحقل 2 دائمًا على أنه سلسلة مسبوقة بطولها ستفسّر أول وسم ثنائي للنوع على أنه طول سلسلة فتفقد التزامن، لذا يجب أن تعرف الوضع الذي يستخدمه التدفق.بالنسبة إلى الاستعلام الذي يكون فيه query_kind = SECONDARY_QUERY (المُرسَل من خادم آخر عبر remote أو Distributed أو النسخ المتماثلة المتوازية، أو عبر clickhouse-client --query_kind secondary_query)، يتجاهل كلا الطرفين output_format_native_encode_types_in_binary_format وinput_format_native_decode_types_in_binary_format في كتل ذلك الاستعلام، إذ تحمل هذه الكتل أسماء الأنواع بصيغتها النصية في كلا الاتجاهين. أما الخوادم الأقدم من هذه القاعدة فتطبّق هذه الإعدادات على الاستعلام الثانوي كما تطبّقها على أي استعلام آخر.

توجيه أداة فك الترميز من وصف النوع إلى عائلة الترميز الخاصة به

kind_stack والترميز المتناثر

يُعدِّد البايت kind_stack تسلسلًا غير افتراضي خاصًا بكل عمود:

البايت	الاسم	المعنى	الأثر على `data` في تنسيق wire
`0x00`	DEFAULT	التسلسل الافتراضي	مطابق لـ `has_custom = 0`
`0x01`	SPARSE	التسلسل المتناثر (v54465+)	دفق الإزاحات + القيم غير الافتراضية؛ انظر أدناه
`0x02`	DETACHED	عمود مُغلَّف داخل `ColumnBLOB` بواسطة التجهيز المتوازي للكتل (v54478+)	كائن blob مُنظَّم مسبقًا: `VarUInt size` يليه ذلك العدد من البايتات؛ انظر أدناه
`0x03`	DETACHED_OVER_SPARSE	عمود متناثر مُغلَّف داخل `ColumnBLOB`	حمولة blob نفسها كما في `DETACHED`؛ انظر أدناه
`0x04`	REPLICATED	صيغة قاموس للقيم المتكررة (v54482+)	دفق الفهارس + قيم العناصر الكثيفة؛ انظر أدناه
`0x05`	COMBINATION	مكدس متعدد الأنواع	يليه `count` من نوع VarUInt ثم `count` من بايتات الأنواع الإضافية — انظر الملاحظة أدناه

تستخدم حمولة COMBINATION تعدادًا مختلفًا. الصفوف الخمسة أعلاه رموز مضغوطة بطول بايت واحد. أما COMBINATION (0x05) فهو المخرج العام لأي مكدس لا تغطيه تلك الرموز: إذ يليه count من نوع VarUInt ثم count من الإدخالات بطول بايت واحد. وهذه الإدخالات ليست الرموز المضغوطة الواردة في الجدول، بل هي قيم ISerialization::Kind الخام:

البايت	`Kind` المتداخل
`0x00`	DEFAULT
`0x01`	SPARSE
`0x02`	DETACHED
`0x03`	REPLICATED

تختلف قيم البايتات هنا عن الرموز المضغوطة: فقيمة REPLICATED هي 0x03 في هذا التعداد المتداخل، بينما هي 0x04 كرمز مضغوط، ولا يوجد إدخال DETACHED_OVER_SPARSE، إذ يظهر هذا التركيب على هيئة إدخالين متتاليين هما SPARSE ثم DETACHED. وأي أداة فك ترميز تستمر في استخدام الجدول المضغوط للبايتات المتداخلة ستخطئ في تعيين 0x03/0x04 وتفقد التزامن. يمثل count الطول الكامل للمكدس بما في ذلك إدخال DEFAULT الأول الذي يبدأ به كل مكدس. ولأن الرموز المضغوطة تغطي أصلًا كل مكدس مكوّن من إدخال واحد أو إدخالين، فإن قيمة count في COMBINATION لا تقل أبدًا عن ثلاثة. صلاحية مكدس الأنواع. ترفض أداة فك الترميز المكدس غير السليم بالخطأ INCORRECT_DATA بدلًا من بناء التسلسل الذي يصفه، إذ يجب أن:

يبدأ المكدس بـ DEFAULT؛
يكون المكدس تسلسلًا فرعيًا من DEFAULT وSPARSE وREPLICATED وDETACHED، وهو الترتيب الذي تُغلِّف به الأنواع بعضها بعضًا. فيمكن أن يقع SPARSE داخل REPLICATED لا العكس، ويأتي DETACHED دائمًا في النهاية لأن ColumnBLOB يحتوي على الصيغة المُسلسَلة لكل ما تحته. ويعني هذا أيضًا أن أي نوع لا يتكرر، مما يجعل count محدودًا بعدد الأنواع.

لاحظ أن هذا الترتيب ليس ترتيب قيم بايتات الأنواع المذكورة أعلاه. فأي مكدس آخر يصف تخطيطًا للعمود لا يبنيه أي كاتب، ولا تفكّ أي خطوة تجسيد تغليفه ليعود عمودًا كاملًا من النوع المُعلَن؛ فمثلًا يبقى ColumnSparse مُغلَّفًا إذا كان عمود قيمه نفسه متناثرًا أو متماثلًا. kind_stack التعاودي لأعمدة Tuple. حمولة kind_stack المذكورة أعلاه هي البايت (أو تسلسل COMBINATION) الخاص بمعلومات التسلسل لعمود واحد. أما Tuple فيحمل SerializationInfoTuple، الذي يكتب أولًا حمولة مكدس الأنواع الخاصة بالـ Tuple، ثم يكتب حمولة كاملة لمكدس الأنواع لـكل عنصر بالترتيب؛ وتقرأ أداة فك الترميز البنية التعاودية نفسها. وبذلك تكون بايتات الحقل 4 لـ Tuple(A, B, C) هي [tuple_kind][A_kind][B_kind][C_kind]، وتكون حمولة كل عنصر بدورها تعاودية إذا كان ذلك العنصر مركّبًا أيضًا. يُضبط البايت has_custom_serialization (الحقل 3) كلما كانت معلومات الـ Tuple نفسه أو معلومات أي من عناصره غير افتراضية، لذا فإن Tuple الذي لا يتميز من عناصره إلا عنصر واحد متناثر أو متماثل يستدعي هو الآخر حمولة مكدس الأنواع. وأي أداة فك ترميز تكتفي بقراءة بايت التعداد الأول لـ Tuple ستتوقف قبل الأوان، وتقرأ خطأً بايتات أنواع العناصر المتبقية على أنها بيانات أعمدة. تنسيق wire المتناثر. عندما تكون kind_stack = 0x01، تتكوّن data الخاصة بالعمود من دفقين مكتوبين على التوالي ضمن دفق TCP المشترك الوحيد:

دفق الإزاحات — تسلسل من قيم VarUInt. وكل قيمة v تكون على إحدى حالتين:
- v يكون فيها البت ذو الموضع 62 غير مضبوط: (v & 0x3FFFFFFFFFFFFFFF) = عدد المواضع الافتراضية التي تسبق القيمة الصريحة غير الافتراضية التالية. ويكون ذلك الموضع غير الافتراضي هو cursor + group_size، حيث cursor هو الموضع الحالي؛ ثم يتقدّم cursor بمقدار group_size + 1.
- v يكون فيها البت 62 مضبوطًا (END_OF_GRANULE_FLAG): القيمة بعد مسح العلامة = عدد المواضع الافتراضية اللاحقة لآخر قيمة غير افتراضية. ويدل ذلك على نهاية دفق الإزاحات الخاص بالكتلة.
دفق القيم — عدد count من القيم غير الافتراضية المُرمَّزة بشكل متراص وفق النوع الداخلي، حيث count هو عدد قيم VarUInt المقروءة أعلاه التي لا تدل على نهاية الحبيبة (EOG).

تعيد أداة فك الترميز بناء عمود متراص يضم num_rows عنصرًا، وذلك بملء كل موضع غير صريح بالقيمة الافتراضية للنوع الداخلي (0 للأعداد الصحيحة والأعداد ذات الفاصلة العائمة، و"" لـ String، و0 يوم لـ Date، وهكذا). يُعدّ العمود المتناثر من النوع Nullable(T) حالة خاصة، لأن القيمة الافتراضية لـ Nullable(T) هي NULL. إذ يستغني الترميز المتناثر كليًّا عن دفق null-map المعتاد في Nullable: فدفق الإزاحات يحدّد المواضع غير الافتراضية — أي المواضع غير NULL — ودفق القيم يضم تلك القيم غير NULL وحدها بشكل متراص وفق T، ويُعاد بناء كل موضع غير صريح على أنه NULL. لذا يجب على أداة فك الترميز ألّا تبحث عن null map في دفق القيم، وألّا تملأ الفجوات بقيمة 0 فعلية، بل تملؤها بـ NULL. تنسيق wire للنوع Replicated. عندما تكون kind_stack = 0x04، تكون بيانات العمود data قاموسًا، أي قائمة بقيم العناصر المميزة مع فهرس لكل صف يشير إلى موضعه في تلك القائمة (وهي بنية البحث نفسها المستخدمة في LowCardinality). وإذا كان النوع الداخلي نفسه ذا إصدار — مثل LowCardinality(T) — فإن بادئة الحالة الخاصة به تُكتب أولًا، قبل دفق الفهرس: إذ يفوّض التسلسل المتماثل مرحلة البادئة إلى النوع الداخلي قبل كتابة num_rows. أما الأنواع الداخلية ذات البادئة الفارغة (الأنواع الطرفية والأنواع المركّبة البسيطة) فلا تضيف أي بايتات هنا.

[inner type's state prefix]              empty for leaf inners; e.g. LowCardinality version (Int64 = 1)
[VarUInt num_rows]
[UInt8  size_of_indexes_type]            width of each index: 1, 2, 4, or 8 bytes
[indexes: num_rows × size_of_indexes_type bytes]
[VarUInt num_elements]
[elements: num_elements dense inner-type values]

تعيد أداة فك الترميز بناء column كثيف عبر اختيار elements[indexes[i]] لكل صف إخراج i. أما الأنواع الداخلية المركّبة فتُعالَج تعاوديًا: إذ تُجسَّد قائمة العناصر بالنوع الداخلي أولًا، ثم تُفهرَس. وتشمل الأنواع الداخلية المدعومة الأنواع الطرفية، وNullable(T)، وArray(T)، وTuple(...)، وMap(K, V)، وNested(...) (حيث يُوسَّع كل حقل كما في Array)، وLowCardinality(T) (حيث يُحتفَظ بالقاموس المشترك، ولا تُفهرَس إلا المفاتيح الخاصة بكل عنصر). تنسيق wire المنفصل. يظهر DETACHED (0x02) وDETACHED_OVER_SPARSE (0x03) فعلًا أثناء النقل عبر الشبكة، فهما ليسا داخليين بحتين. ففي مسار TCP، عند تفعيل الضغط وكون قيمة revision المتفاوض عليها لا تقل عن DBMS_MIN_REVISON_WITH_PARALLEL_BLOCK_MARSHALLING (v54478)، يمر الـ column بثلاث خطوات:

يُغلَّف كل column مؤهَّل (أي غير const، وغير Tuple، وموجود في كتلة تضم أكثر من صف واحد) داخل ColumnBLOB يحتفظ بالـ column بعد ترتيبه وضغطه مسبقًا خارج خيط التنفيذ الرئيسي.
يُضاف DETACHED إلى مكدس الأنواع الخاص بالـ column المُغلَّف.
تُكتب data الخاصة بالـ column على هيئة حجم blob بصيغة VarUInt، يليه عدد مطابق له تمامًا من بايتات الـ blob.

إذا كان الـ column المُغلَّف متناثرًا، يكون مكدسه {DEFAULT, SPARSE, DETACHED}، ويُسلسَل على هيئة DETACHED_OVER_SPARSE. وعند فك ترميز column كهذا، يقرأ العميل طول الـ blob وبايتاته، ثم يفك ضغط الـ blob لاستعادة حمولة الـ column الداخلي (راجع ملاحظة ColumnBLOB في قسم الضغط). DETACHED أحادي الاتجاه: فلا يمكن أن يظهر إلا في كتل النتائج التي يرسلها الخادم، ولا يُطبَّق إلا على عمود كامل من المستوى الأعلى، ولا يظهر أبدًا كأحد أنواع العناصر داخل Tuple. وخلافًا للأنواع الأخرى، فإنه يجعل العمود في وقت التشغيل من النوع ColumnBLOB بدلًا من عمود من النوع المُعلَن، ولذلك لا يقبله المستقبِل إلا إذا كان مسار المعالجة لديه يعيد تحويل الـ blob إلى صيغته الأصلية. ولهذا يرفض الخادم DETACHED في أي كتلة يرسلها العميل، سواء أكانت بيانات جدول خارجي أم قيمًا مفردة أم بيانات إدراج، ويُرجع الخطأ INCORRECT_DATA.

بدائل الكتلة

تشترك جميع حزم عائلة Data في تنسيق wire نفسه الخاص بالكتلة، ولا تختلف البدائل فيما بينها إلا في عدد الأعمدة والصفوف:

البديل	num_columns	num_rows	الغرض
كتلة الترويسة (كتلة الترويسة)	N > 0	0	تُعلن عن مخطط النتيجة (أسماء الأعمدة وأنواعها).
كتلة النتيجة (كتلة النتيجة)	N > 0	M > 0	صفوف النتيجة الفعلية.
الكتلة الفارغة (كتلة فارغة)	0	0	قيمة حارسة؛ تدل على نهاية الإدخال من جهة العميل، وتُستخدم وسمًا للحدود من جهة الخادم.

أمثلة على مستوى البايت

جميع الأمثلة في هذا القسم مأخوذة من مسار حزمة Data عبر TCP، ولذلك تتضمن البادئة BlockInfo والبايت has_custom_serialization. أما عبر FORMAT Native فتكون الكتل نفسها أقصر، وسنورد الصيغة المختصرة المكافئة حيثما كان ذلك مفيدًا. كتلة فارغة (مع BlockInfo)، حجمها الإجمالي 8 بايتات:

00                   BlockInfo: field_id=1, is_overflows=0
FF FF FF FF          BlockInfo: field_id=2, bucket_number=-1
                    BlockInfo terminator
                    num_columns = 0
                    num_rows = 0

تُعلن كتلة الترويسة الخاصة بالاستعلام SELECT 1 عن column واحد باسم "1" من النوع UInt8، دون أي صفوف. وعندما يكون إصدار البروتوكول ≥ 54454، يُضاف البايت has_custom_serialization:

00                   BlockInfo: is_overflows = 0
FF FF FF FF          BlockInfo: bucket_number = -1
                    BlockInfo terminator
                    num_columns = 1
                    num_rows = 0
"1"                  Column[0].name = "1"
"UInt8"              Column[0].type = "UInt8"
                    Column[0].has_custom_serialization = 0
                        Column[0].data: no bytes (num_rows = 0)

كتلة النتائج للاستعلام نفسه، وتحتوي على صف واحد:

00                   BlockInfo: is_overflows = 0
FF FF FF FF          BlockInfo: bucket_number = -1
                    BlockInfo terminator
                    num_columns = 1
                    num_rows = 1
"1"                  Column[0].name = "1"
"UInt8"              Column[0].type = "UInt8"
                    Column[0].has_custom_serialization = 0
                    Column[0].data: one UInt8 byte = 1

عند استخدام FORMAT Native (الـ revision 0)، لا تتضمّن كتلة النتيجة نفسها BlockInfo ولا البايت has_custom_serialization، إذ يبلغ حجم SELECT 1 FORMAT Native ‏11 بايت:

                    num_columns = 1
                    num_rows = 1
"1"                  Column[0].name = "1"
"UInt8"              Column[0].type = "UInt8"
                    Column[0].data: one UInt8 byte = 1

(لا تُنتج النتيجة الخالية من الصفوف، كالكتلة التي تقتصر على الترويسة، أي بايتات على الإطلاق عبر FORMAT Native: إذ لا يُصدر تنسيق الإخراج هذا كتلًا فارغة.)

revision البروتوكول وصيغة Native

يتحدد شكل دفق البايتات بصيغة Native قبل كل شيء بحسب revision البروتوكول التي يعمل بها كلٌّ من الكاتب والقارئ. ولا تَرِد revision في أي موضع من البايتات نفسها — إذ لا يوجد حقل لـ revision في تنسيق النقل — ومع ذلك فهي التي تحدد ما إذا كانت عدة ميزات ستظهر من الأساس. ولذلك يتعين على أداة فك الترميز أن تعرف revision التي كُتبت بها الحمولة قبل أن تتمكن من تحليلها. وبما أن revision غير موجودة في الدفق، فلا بد أن يتفق القارئ والكاتب عليها بوسيلة أخرى. وrevision قيمة واحدة من النوع UInt64، يستقبلها كلٌّ من NativeWriter وNativeReader وسيطًا في المُنشئ. ويسميها الكاتب client_revision بينما يسميها القارئ server_revision، لكنها الرقم نفسه في الحالتين. وأحدث revision يعرفها هذا الإصدار هي DBMS_TCP_PROTOCOL_VERSION (راجع src/Core/ProtocolDefines.h).

ما الذي تتحكم فيه المراجعة (revision)

تخضع كل ميزة لعتبة من نوع DBMS_MIN_REVISION_WITH_*. لا يُصدر الكاتب الميزة إلا عندما تبلغ مراجعته (revision) تلك العتبة، ويبحث عنها القارئ وفق القاعدة ذاتها تمامًا، فيبقى الطرفان متزامنين؛ أما إذا أخطأت في تحديد المراجعة (revision) على أي من الجانبين فسيفقدان التزامن. البوابات المهمة لصيغة Native هي:

الميزة	ثابت العتبة	المراجعة (revision)	الأثر عند الوقوع دون العتبة
بادئة `BlockInfo`	(أي قيمة `> 0`)	`1`	تُحذف بادئة `BlockInfo` كليًا؛ وتتكون الكتلة من `num_columns` و`num_rows` والأعمدة (columns) فقط.
بايت `has_custom_serialization`	`DBMS_MIN_REVISION_WITH_CUSTOM_SERIALIZATION`	`54454`	يُحذف بايت `has_custom_serialization` الخاص بكل عمود (column)؛ ويستخدم كل عمود (column) التسلسل الافتراضي (دون الأشكال المتناثرة أو المتماثلة أو المنفصلة).
`LowCardinality` في تنسيق النقل	`DBMS_MIN_REVISION_WITH_LOW_CARDINALITY_TYPE`	`54405`	حالة خاصة — لا تخضع للقاعدة البسيطة لما دون العتبة. يُجرَّد `LowCardinality(T)` إلى النوع الأساسي `T` فقط عندما تكون المراجعة (revision) غير صفرية وأقل من `54405`، أو عند فرض التجريد بشكل منفصل. أما المراجعة (revision) `0` فتُبقي عليه. راجع الملاحظة أدناه.
تسلسل `Dynamic` / `JSON` بالإصدار V2	`DBMS_MIN_REVISION_WITH_V2_DYNAMIC_AND_JSON_SERIALIZATION`	`54473`	يستخدم `Dynamic` و`JSON`/`Object` تسلسل V1 (مع المعلمة `max_dynamic_*`) بدلًا من V2.
تسلسل `String` بالإزاحات	`DBMS_MIN_REVISION_WITH_STRING_WITH_SIZE_STREAM_SERIALIZATION`	`54492`	دون العتبة، تستخدم بيانات أعمدة (columns) `String` تخطيط القيمة المفردة (بادئة طول `VarUInt` + بايتات خام لكل صف) بدلًا من تخطيط الإزاحات (إزاحات بايتات تراكمية بنوع `UInt64`، تليها جميع البيانات متسلسلة). يعتمد ذلك على المراجعة (revision) وحدها، دون أي علامة لكل عمود (column) في تنسيق النقل. عند العتبة أو فوقها، ينطبق تخطيط الإزاحات أيضًا على `String` المتداخل داخل الأنواع المركبة (`Array` و`Nullable` و`Map` و`Tuple` و`Variant` و`Dynamic` و`JSON`)، لكنه لا ينطبق على قاموس عمود (column) `LowCardinality`: إذ يُكتب قاموس `LowCardinality` دائمًا بالتسلسل المتداخل الافتراضي، فتحتفظ قيم `String` فيه بتخطيط القيمة المفردة (ويشمل ذلك `LowCardinality(String)` و`LowCardinality(Nullable(String))`). أما صيغة `Buffers` فليست جزءًا من البروتوكول، وتستخدم دائمًا تخطيط القيمة المفردة.
إدارة إصدارات دوال التجميع	`DBMS_MIN_REVISION_WITH_AGGREGATE_FUNCTIONS_VERSIONING`	`54452`	تُكتب حالة `AggregateFunction` دون إصدار مضمَّن.
`skip_degree` في حالة `quantileDeterministic`	`DBMS_MIN_REVISION_WITH_QUANTILE_DETERMINISTIC_SKIP_DEGREE`	`54491`	تُكتب حالات `AggregateFunction(quantileDeterministic, ...)` (وكذلك صيغتا `quantiles`/`median` للدالة نفسها) بإصدار الحالة `0`، دون الحقل اللاحق `UInt8 skip_degree`. راجع الملاحظة ضمن الأسماء البديلة للأنواع.
عينة تجزئات 64 بت في حالة `uniq`	`DBMS_MIN_REVISION_WITH_UNIQ_STATE_VERSION_1`	`54493`	تُكتب حالات `AggregateFunction(uniq, ...)` بإصدار الحالة `0`: دون بايت الأعلام البادئ ودون العينة اللاحقة من تجزئات 64 بت. راجع الملاحظة ضمن الأسماء البديلة للأنواع.
`out_of_order_buckets` في `BlockInfo`	`DBMS_MIN_REVISION_WITH_OUT_OF_ORDER_BUCKETS_IN_AGGREGATION`	`54480`	لا يُكتب الحقل ذو المعرّف `3` في `BlockInfo` (راجع BlockInfo).
التجهيز المتوازي للكتل (`DETACHED`)	`DBMS_MIN_REVISON_WITH_PARALLEL_BLOCK_MARSHALLING`	`54478`	لا تُغلَّف الأعمدة (columns) أبدًا في `ColumnBLOB`؛ ولا تظهر الأنواع `DETACHED` / `DETACHED_OVER_SPARSE` (راجع kind_stack).
معلمة النوع `DateTime(tz)`	`DBMS_MIN_REVISION_WITH_TIME_ZONE_PARAMETER_IN_DATETIME_DATA_TYPE`	`54337`	تُحذف معلمة المنطقة الزمنية من سلسلة `type` — فيُعلَن عن `DateTime('UTC')` على أنه `DateTime` مجردًا.

وهذا يجعل الـ revision 0 الترميز الأكثر تحفّظًا في كل شيء تقريبًا: إذ لا يحمل الدفق أي BlockInfo، ولا بايت has_custom_serialization، ويستخدم الإصدار V1 من Dynamic/JSON، ولا يتضمن إصدارًا لدوال التجميع، ويحتوي على DateTime مجرّد مع حذف معلمة المنطقة الزمنية. وتُستثنى من ذلك إصدارات حالة دوال التجميع عند الـ revision 0: فلا يوجد طرف مقابل يُشتقّ منه الإصدار، إذ تكتب الدفقَ الجهةُ نفسها التي أنتجته وتعيد قراءته (ملف بيانات StripeLog، أو نسخة احتياطية لـ Set/Join، أو ملف بصيغة Native). لذا يحتفظ الكاتب بالإصدار المثبّت على النوع (مع التصريح به في سلسلة النوع كالمعتاد) بدلًا من خفض الحالة إلى الإصدار 0، ولا يُكتب بالإصدار 0 إلا النوع الذي لا يثبّت أي إصدار. أما LowCardinality فهو الاستثناء الوحيد، وهو استثناء مهم. فشرط الكاتب هو remove_low_cardinality || (client_revision && client_revision < DBMS_MIN_REVISION_WITH_LOW_CARDINALITY_TYPE). ويكمن السرّ في الجزء الأول client_revision &&: فعندما تساوي قيمة الـ revision 0 تمامًا، يُقيَّم الشرط بأكمله فورًا إلى false وفق مبدأ التقييم المختصر (short-circuit). لذلك عند الـ revision 0، وهي القيمة الافتراضية لـ FORMAT Native، لا يُزال LowCardinality(T)، بل تبقى سلسلة نوعه وبادئة الحالة الخاصة بكل كتلة في الدفق، ويعيد القارئ ذو الـ revision 0 قراءتهما مباشرةً. ولا تُطبَّق الإزالة إلا عند revision غير صفرية أقل من 54405، أو عند فرضها بصرف النظر عن الـ revision. ويتم هذا الفرض عبر الخيار remove_low_cardinality. ولا يضبطه إخراج FORMAT Native أبدًا، في حين يضبطه مسار البروتوكول الأصلي عندما تكون low_cardinality_allow_in_native_format = 0 (القيمة الافتراضية 1). بعبارة أخرى، يغيّر هذا الإعداد إخراج البروتوكول الأصلي، لكنه لا يؤثر إطلاقًا في FORMAT Native. الخلاصة العملية: قد يحتوي دفق FORMAT Native الافتراضي على LowCardinality بشكل مشروع، فلا تفترض أنه ميزة غائبة عند الـ revision 0.

مصدر الـ revision بحسب طريقة انتقال البيانات

يمكن أن تنتقل بايتات Native ذاتها عبر مسارات مختلفة: بروتوكول TCP الأصلي، أو طلب HTTP، أو ملف على القرص. ولكل مسار طريقته الخاصة في تحديد الـ revision. وثمة أمر ينبغي الانتباه إليه: يُهيَّأ جانبا القراءة والكتابة كلٌّ على حدة، ولذلك قد ينتهي بهما الأمر إلى قيمتَي revision مختلفتين.

بروتوكول TCP الأصلي — قيمة متفاوض عليها، في كلا الاتجاهين

في بروتوكول TCP الأصلي، تُستمد قيمة revision من مصافحة Hello. يرسل العميل DBMS_TCP_PROTOCOL_VERSION، ويردّ الخادم بقيمته الخاصة، ومن ثمّ يُجري كل طرف التسلسل وفق قيمة revision التي أعلنها الطرف الآخر: إذ يبني الخادم NativeReader/NativeWriter الخاصين به استنادًا إلى client_tcp_protocol_version، في حين يستخدم العميل قيمة server_revision التي تلقّاها. لا توجد عملية min صريحة، غير أن أيًّا من الطرفين لا يستطيع إرسال ميزة لم يُنفّذها، ولذلك يتحدد سقف كل اتجاه فعليًا بالطرف الأقدم من الطرفين. عندما يعمل الطرفان على الإصدار الحديث نفسه، يستقر الاتجاهان على قيمة revision نفسها (DBMS_TCP_PROTOCOL_VERSION، راجع src/Core/ProtocolDefines.h) وتكون جميع البوابات مفعّلة. هذه هي الحالة الشائعة، لكنها ليست مضمونة. فإذا اختلفت إصدارات الطرفين أو كان أحدهما من جهة خارجية، فقد يعمل الاتجاهان بقيمتَي revision مختلفتين، ولذا يجب تقييم البوابات لكل اتجاه على حدة: يكون BlockInfo حاضرًا عند أي قيمة revision غير صفرية، أما البقية — بما فيها has_custom_serialization — فلا تظهر إلا حين تبلغ قيمة revision الفعلية لذلك الاتجاه الحدود الخاصة بها. فعلى سبيل المثال، الطرف الذي يعلن قيمة revision أقل من 54454 لا يرسل البايت has_custom_serialization ولا يستقبله.

إخراج `FORMAT Native` — revision 0 افتراضيًا، مع إمكانية رفعها عبر HTTP

تستخدم صيغة الإخراج Native revision 0 افتراضيًا. ويشمل ذلك SELECT ... FORMAT Native عبر HTTP، وINTO OUTFILE ... FORMAT Native، وإخراج Native الذي يكتبه clickhouse-client؛ ففي كل حالة من هذه الحالات، يمرّر مصنع الإخراج FormatSettings::client_protocol_version مباشرةً إلى NativeWriter، الذي يتحكم في بنية التأطير الخاصة بـ BlockInfo / has_custom_serialization وكذلك في تخطيط String القائم على الإزاحات. وعليه، فإن استعلام SELECT ... FORMAT Native عبر HTTP مع قيمة مرفوعة لـ client_protocol_version (≥ 54492) يكتب التخطيط القائم على الإزاحات، بينما تُبقي revision الافتراضية 0 على التخطيط المحمول الذي تُرمَّز فيه كل قيمة على حدة. غير أن هذه القيمة الافتراضية ليست نهاية المطاف عند استخدام HTTP، إذ يمكن للعميل رفعها عبر معلمة الاستعلام ?client_protocol_version=<n>، التي يعاملها معالج HTTP على أنها معلمة محجوزة لا إعداد SQL: فهي تُخزَّن في سياق الاستعلام، ثم تنسخها طبقة الصيغة إلى FormatSettings. وعند ضبطها بقيمة مرتفعة بما يكفي، يبدأ إخراج FORMAT Native عبر HTTP بتضمين البادئة BlockInfo والبايت has_custom_serialization، تمامًا كما في مسار TCP — لذا لا تفترض أن حمولة FORMAT Native عبر HTTP تكون دائمًا بـ revision 0. ولأن المعلمة تُخزَّن في سياق الاستعلام بأكمله، فإنها تصل إلى كل NativeWriter يُنشأ لذلك الطلب، لا إلى دفق النتائج وحده. فعلى سبيل المثال، تؤدي عملية كتابة من جهة الخادم مثل INSERT INTO FUNCTION file('x.native', 'Native', ...) SELECT ... عبر HTTP مع قيمة مرفوعة لـ ?client_protocol_version= إلى كتابة الملف بتلك revision. وهذا سلوك قائم منذ زمن طويل (إذ يسبق ظهور تسلسل String القائم على الإزاحات، وينطبق كذلك على BlockInfo وhas_custom_serialization)، وهو غير متناظر: فجهة القراءة (الموضحة أدناه) لا تُرفع revision الخاصة بها بالطريقة نفسها، ولذلك تتعذّر إعادة قراءة مثل هذا الملف عبر file(...). لا تُضمِّن client_protocol_version في أي طلب يكتب بيانات يُراد قراءتها لاحقًا. أما INTO OUTFILE وإخراج clickhouse-client المحلي فلا يتوفر لهما مثل هذا الخيار، ويبقيان عند revision 0.

إدخال `FORMAT Native` — دائمًا بـ revision 0

تُنشئ صيغة الإدخال Native قارئها NativeReader دائمًا عند revision 0. فهي لا تتوقع أبدًا بادئة BlockInfo، ولا تقرأ البايت has_custom_serialization إطلاقًا، وتفترض دائمًا التسلسل الافتراضي، سواء أكانت تحلّل متن استعلام INSERT ... FORMAT Native، أم تقرأ ملف Native، أم تستنتج المخطط. ولا يرفع ?client_protocol_version=<n> قيمة revision الإدخال، إذ لا يقرأ هذه المعلمة سوى جانب الإخراج. ولأن revision الإدخال يساوي 0 دائمًا، فإن صيغة الإدخال تقرأ دائمًا تخطيط String الذي تُرمَّز فيه كل قيمة على حدة؛ أما الدفق المكتوب بتخطيط الإزاحات (عبر بروتوكول TCP الأصلي، أو عبر SELECT ... FORMAT Native مع رفع قيمة client_protocol_version) فلا يمكن قراءته مجددًا عبر إدخال FORMAT Native، وهو عدم التماثل نفسه الذي نجده في تأطير BlockInfo.

تداعيات الكتابة ثم القراءة

بالنسبة إلى FORMAT Native، تكون revision الافتراضية 0 في كلا الطرفين. فالبيانات المكتوبة بواسطة SELECT ... FORMAT Native عند revision 0 يمكن قراءتها مباشرةً في INSERT ... FORMAT Native دون أي مفاجآت. أما الدفق المُنتَج بـ revision إخراج مرفوعة (?client_protocol_version=<n> في SELECT) فيحمل بنية التأطير BlockInfo وhas_custom_serialization وتخطيط String القائم على الإزاحات، ولا تستطيع صيغة الإدخال قراءة أيٍّ منها لأنها تعمل دائمًا عند revision 0. لذا لا يكون رفع client_protocol_version منطقيًا إلا لمستهلك يتعامل ببروتوكول TCP الأصلي، لا لعملية كتابة ثم قراءة باستخدام FORMAT Native عبر HTTP. أما الملفات فهي الحالة غير المتناظرة. إذ إن رفع ?client_protocol_version= في عملية INSERT INTO FUNCTION file(...) من جهة الخادم (أو s3، أو url) يكتب الملف بتلك revision، في حين أن قراءة file(...) تحلّل دائمًا عند revision 0، ولذلك يتعذّر قراءة مثل هذا الملف بعد كتابته. والحل إما أن تحذف client_protocol_version من طلب الكتابة ليُكتب الملف بـ revision 0 العادية، وإما أن تنقل البيانات عبر بروتوكول TCP الأصلي، حيث يستخدم كل اتجاه revision المتفاوض عليها أثناء المصافحة.

القناة	revision الكتابة	revision القراءة	`BlockInfo` / التسلسل المخصّص
حزمة Data في بروتوكول TCP الأصلي	revision التي يُعلنها الطرف الآخر (لكل اتجاه)	revision التي يُعلنها الطرف الآخر (لكل اتجاه)	`BlockInfo` كلما كانت revision `> 0`؛ و`has_custom_serialization` عند `≥ 54454`
`SELECT ... FORMAT Native` عبر HTTP	`client_protocol_version` (الافتراضي `0`)	لا ينطبق	فقط إذا رُفع `client_protocol_version`
`INSERT ... FORMAT Native` عبر HTTP (في متن الطلب)	لا ينطبق	`0` (دائمًا)	لا يوجد تأطير؛ و`String` دائمًا لكل قيمة على حدة
`INSERT INTO FUNCTION file`/`s3`/`url(..., 'Native')` عبر HTTP	`client_protocol_version` (الافتراضي `0`)	`0` (القراءة دائمًا)	عند الكتابة فقط إذا رُفع `client_protocol_version`، ويتعذّر حينها قراءة الملف
`INTO OUTFILE` / `clickhouse-client` المحلي مع `FORMAT Native`	`0`	`0`	غير موجود (لكن يُحتفَظ بـ `LowCardinality`، راجع الملاحظة أعلاه)

revision البروتوكول مقابل إصدار التسلسللا تخلط بين revision البروتوكول وإصدار التسلسل. فـ revision هنا تسري على مستوى الاتصال أو الطلب بأكمله، ولا تظهر أبدًا في البايتات. أما إصدار التسلسل فهو خاص بكل عمود، وتحمله الأنواع ذات الإصدارات، ويُكتب في كل كتلة غير فارغة. فـ revision تحدّد ما إذا كانت ميزة ما موجودة أصلًا، بينما يحدّد إصدار التسلسل، داخل العمود ذي الإصدار، أيّ متغيّر من ترميز ذلك النوع بعينه يأتي بعده.

أنواع البيانات

يوثّق هذا القسم ترميز wire للأنواع التي يمكن لصيغة Native حملها ضمن data الخاصة بالعمود، مقسّمةً إلى أربع عائلات يتزايد فيها تعقيد أداة فك الترميز تدريجيًا. يُعدّ النوعان AggregateFunction(func, ...) وQBit(T, N[, stride]) من أنواع الأعمدة الصالحة في Native، إلا أن لكلٍّ منهما حمولة خاصة بالدالة أو بالنوع تقع خارج نطاق هذا القسم؛ وسننبّه إليهما أدناه في المواضع التي قد يُظنّ فيها خطأً أنهما أسماء بديلة.

العائلة	القسم	عدد التدفقات لكل عمود	الحالة عبر الكتل
ذات عرض ثابت	الأنواع ذات العرض الثابت	واحد	لا توجد
ذات طول متغير	الأنواع ذات الطول المتغير	واحد	لا توجد
مركّبة (بنية ثابتة)	الأنواع المركّبة	متعددة	لا توجد
ذات إصدارات / ذات حالة	الأنواع ذات الإصدارات	متعددة	لا توجد في Native wire — بادئة حالة لكل كتلة، تُعاد تهيئتها مع كل كتلة جديدة

الأنواع ذات العرض الثابت

تشغل كل قيمة عددًا ثابتًا من البايتات. ويشغل عمود مكوَّن من M صفًا bytes_per_row × M بايتًا بالضبط في تنسيق النقل، متلاصقةً دون أي فواصل أو حشو.

سلسلة النوع	البايتات لكل قيمة	القيمة المنطقية	ترميز wire
`UInt8`	1	عدد صحيح بلا إشارة بطول 8 بت	بايت خام
`UInt16`	2	عدد صحيح بلا إشارة بطول 16 بت	Little-endian
`UInt32`	4	عدد صحيح بلا إشارة بطول 32 بت	Little-endian
`UInt64`	8	عدد صحيح بلا إشارة بطول 64 بت	Little-endian
`UInt128`	16	عدد صحيح بلا إشارة بطول 128 بت	Little-endian
`UInt256`	32	عدد صحيح بلا إشارة بطول 256 بت	Little-endian
`Int8`	1	عدد بإشارة بطول 8 بت، بتمثيل المتمم الثنائي	بايت خام
`Int16`	2	عدد بإشارة بطول 16 بت، بتمثيل المتمم الثنائي	Little-endian
`Int32`	4	عدد بإشارة بطول 32 بت، بتمثيل المتمم الثنائي	Little-endian
`Int64`	8	عدد بإشارة بطول 64 بت، بتمثيل المتمم الثنائي	Little-endian
`Int128`	16	عدد بإشارة بطول 128 بت، بتمثيل المتمم الثنائي	Little-endian
`Int256`	32	عدد بإشارة بطول 256 بت، بتمثيل المتمم الثنائي	Little-endian
`Float32`	4	IEEE 754 أحادي الدقة	Little-endian
`Float64`	8	IEEE 754 مزدوج الدقة	Little-endian
`BFloat16`	2	البتات الـ 16 العليا من `Float32` وفق IEEE 754	Little-endian
`Bool`	1	`0x00` = false، `0x01` = true	بايت خام
`Date`	2	عدد الأيام منذ `1970-01-01`	Little-endian UInt16
`Date32`	4	عدد الأيام منذ `1970-01-01` (بإشارة؛ يدعم ما قبل 1970)	Little-endian Int32
`DateTime`	4	طابع زمني لـ Unix بالثواني	Little-endian UInt32
`DateTime(tz)`	4	مماثل لـ `DateTime`؛ المنطقة الزمنية بيانات وصفية	Little-endian UInt32
`DateTime64(s)`	8	عدد tick بمقياس `s` (10^-s ثانية منذ epoch)	Little-endian Int64
`DateTime64(s, tz)`	8	مماثل لـ `DateTime64(s)`؛ المنطقة الزمنية بيانات وصفية	Little-endian Int64
`Time`	4	مدة زمنية بإشارة بالثواني	Little-endian Int32
`Time64(s)`	8	مدة زمنية بإشارة بعدد tick بمقياس `s`	Little-endian Int64
`Interval<Unit>`	8	عدد بإشارة؛ والوحدة محددة في سلسلة النوع	Little-endian Int64
`UUID`	16	معرّف بطول 128 بت	نصفان من نوع UInt64 بترتيب LE، مع تبديل بايتات كلٍّ منهما (راجع UUID)
`IPv4`	4	عنوان IPv4	Little-endian UInt32
`IPv6`	16	عنوان IPv6	ترتيب بايتات الشبكة، دون تبديل
`Enum8`	1	عدد بإشارة بطول 8 بت (فهرس قيمة التعداد)	بايت خام
`Enum16`	2	عدد بإشارة بطول 16 بت (فهرس قيمة التعداد)	Little-endian
`Decimal(P, S)`	4 / 8 / 16 / 32	`value × 10^S` كعدد صحيح بإشارة؛ يعتمد العرض على P (‏≤9 → 4 B، ≤18 → 8 B، ≤38 → 16 B، ≤76 → 32 B)	عدد صحيح بإشارة بترتيب Little-endian

أنواع الأعداد الصحيحة

تمثّل الأنواع UInt8–UInt256 وInt8–Int256 ترميزات ثنائية مباشرة لقيم الأعداد الصحيحة، إذ تقرأ أداة فك الترميز bytes_per_row × num_rows بايت وتفسّرها وفقًا للنوع. مثال على عمود من النوع UInt32 يحتوي على القيم [1, 256, 65536]:

00 00 00              row 0: 1
01 00 00              row 1: 256
00 01 00              row 2: 65536

عمود من النوع Int32 يحتوي على القيم [-1, 42]:

FF FF FF FF              row 0: -1
2A 00 00 00              row 1: 42

Float32 و Float64

أعداد ذات فاصلة عائمة ثنائية قياسية وفق معيار IEEE 754: بطول 4 بايتات أحادية الدقة (binary32) و8 بايتات بدقة مزدوجة (binary64)، وكلاهما بترتيب little-endian. وتُحفَظ قيم NaN و±Infinity و±0.0 والقيم دون الطبيعية (subnormals) كما هي عند كتابتها ثم قراءتها (round-trip)، دون أي تطبيع. القيمة 1.5 من النوع Float32 (0x3FC00000):

00 00 C0 3F              little-endian IEEE 754

القيمة 1.5 من النوع Float64 (0x3FF8000000000000):

00 00 00 00 00 00 F8 3F  little-endian IEEE 754

BFloat16

صيغة الفاصلة العائمة الدماغية (brain-floating-point): وهي البتات الـ 16 العليا من Float32 وفق معيار IEEE 754 — بت واحد للإشارة، و8 بتات للأس، و7 بتات للجزء العشري. تشغل كل قيمة بايتين بترتيب little-endian، وتحمل النمط الخام المؤلف من 16 بت. لاستعادة القيمة العددية، وسّعها مجددًا إلى Float32 بوضع النمط في النصف الأعلى وتصفير النصف الأدنى (أي تفسير bits << 16 على أنه Float32)؛ وعندئذٍ تُنسَّق القيمة الموسّعة نصيًا بالطريقة نفسها التي يُنسَّق بها Float32. قيمة BFloat16 ‏1.5 (النمط 0x3FC0، وهو النصف الأعلى من Float32 ‏0x3FC00000):

C0 3F                    little-endian, widens to Float32 1.5

Bool

متوافق في تنسيق النقل مع UInt8: بايت واحد لكل صف، حيث 0x00 = false و0x01 = true. غير أن سلسلة النوع في تنسيق النقل هي Bool حرفيًا (وليست UInt8)، لذا يجب على أداة فك الترميز التي توجّه المعالجة وفقًا لسلسلة النوع أن تتعرّف عليها بشكل مستقل. عمود من النوع Bool يحتوي على القيم [true, false, true]:

01 00 01

Date و Date32

يُرمِّز كلاهما التواريخ في صورة عدد صحيح يمثّل عدد الأيام منذ حقبة Unix 1970-01-01، ولا يتضمن أيٌّ منهما مكوّنًا زمنيًا.

النوع	البايتات	الترميز	النطاق
`Date`	2	UInt16 بترتيب little-endian	من `1970-01-01` إلى `2149-06-06`
`Date32`	4	Int32 بترتيب little-endian	نطاق واسع بإشارة، ويدعم التواريخ السابقة لعام 1970

القيمة 1970-01-02 من النوع Date (يوم واحد):

01 00                    UInt16 LE = 1

قيمة Date32 ‏1900-01-01 (‎-25567 يومًا):

21 9C FF FF              Int32 LE = -25567

DateTime

متوافق على مستوى التمثيل الثنائي (wire) مع UInt32: طابع زمني لـ Unix بالثواني، يُخزَّن في 4 بايتات بترتيب little-endian. قد يظهر النوع بالصيغة DateTime أو DateTime('Timezone')؛ ولا تؤثر المنطقة الزمنية إلا في طريقة العرض، فهي ليست جزءًا من القيمة المُرسَلة. وبذلك يُنتج عمودان من النوع DateTime بمعلمات منطقة زمنية مختلفة البايتات نفسها للّحظة الزمنية ذاتها. تُزيل أداة فك الترميز لاحقة المعلمة (...) وتعالج العمود على أنه UInt32. القيمة 2024-03-15 14:30:00 UTC من النوع DateTime('UTC') (الطابع الزمني 1710513000):

68 5B F4 65              UInt32 LE = 1710513000

DateTime64(scale[, timezone])

8 بايت: قيمة Int64 بترتيب little-endian تمثّل عدد وحدات tick بمقياس 10^-scale ثانية منذ حقبة Unix. تُحدَّد المعلمة scale (من 0 إلى 9) ضمن سلسلة النوع، وهي التي تحدد وحدة الوقت:

المقياس	حجم الـ tick	الاسم الشائع
0	ثانية واحدة	ثوانٍ
3	ملّي ثانية واحدة	ms
6	ميكروثانية واحدة	µs
9	نانوثانية واحدة	ns

يظهر النوع بالصيغة DateTime64(s) (ضمنيًا بالمنطقة الزمنية الافتراضية للخادم) أو DateTime64(s, 'TimezoneName') (بمنطقة زمنية صريحة تُستخدم للعرض فقط). تمثّل القيم السالبة وحدات tick سابقة للحقبة. القيمة 2024-01-15 12:30:45.123 UTC من النوع DateTime64(3, 'UTC') (1705321845123 ms):

83 51 1A 0D 8D 01 00 00  Int64 LE = 1705321845123

قيمة DateTime64(0) ‏2024-01-15 12:30:45 UTC (1705321845 ثانية):

75 25 A5 65 00 00 00 00  Int64 LE = 1705321845

Time و Time64(scale)

مدة زمنية بحساب الساعة، لا لحظة زمنية محددة. النوع Time عدد ثوانٍ بإشارة، يُخزَّن في 4 بايتات بصيغة Int32 بترتيب little-endian؛ أما Time64(scale) فعدد tick بإشارة وفق المقياس العشري المحدد (0–9)، يُخزَّن في 8 بايتات بصيغة Int64 بترتيب little-endian، أي بالبنية الثنائية نفسها المستخدمة في DateTime64. الصيغة النصية هي [-]HH:MM:SS[.fraction]، لكن حقل الساعات، على خلاف DateTime، لا يعود إلى الصفر بعد 24 ساعة، بل يمثّل العدد الإجمالي للساعات وقد يتجاوز 23. الحد الأقصى للمقدار المعروض هو 999:59:59 (أي 3599999 ثانية)؛ وأي مقدار أكبر من ذلك تُعرض ثوانيه عند هذا الحد مع الإبقاء على الكسر المخزَّن كما هو، فعدد tick قدره 3700000.25 مثلًا يُعرض بالشكل 999:59:59.250000. أما عملية CAST فتُقيّد القيمة المخزَّنة بأكبر tick يمكن تمثيله في المقياس الهدف (999:59:59.999999 في حالة Time64(6))، لا بأكبر ثانية كاملة، في حين قد تُخلّف العمليات الحسابية في العمود عدد tick خارج النطاق لا يُطبَّق عليه الحد إلا عند العرض. ولا يؤثر شيء من ذلك في البايتات المنقولة، فهي مجرد العدد الصحيح بإشارة. القيمة 45296 من النوع Time (12:34:56):

F0 B0 00 00              Int32 LE = 45296

قيمة Time64(3) هي 45296789 tick (12:34:56.789):

95 2C B3 02 00 00 00 00  Int64 LE = 45296789

النوعان Time وTime64 تجريبيان، ويتطلّب استخدامهما ضبط allow_experimental_time_time64_type = 1 على الخادم.

Interval

Interval<Unit> — IntervalSecond وIntervalMinute وIntervalHour وIntervalDay وIntervalWeek وIntervalMonth وIntervalQuarter وIntervalYear وIntervalNanosecond وغيرها. تشترك جميع الوحدات في ترميز wire واحد: يُخزَّن العدد بوصفه Int64 بإشارة (signed) بطول 8 بايت وبترتيب little-endian. ولا تظهر الوحدة إلا في سلسلة النوع، فهي لا تغيّر بايتات wire ولا الشكل النصي، الذي يقتصر على العدد الصحيح وحده. ويكفي مسار واحد في أداة فك الترميز للتعامل مع جميع الوحدات. القيمة 5 من النوع IntervalDay:

05 00 00 00 00 00 00 00  Int64 LE = 5

UUID

16 بايت لكل قيمة. ترميز wire ليس البايتات القياسية الستة عشر بترتيب big-endian، بل تُعكس بايتات كلٍّ من النصفين (8 بايت لكل منهما) على حدة. النموذج المنطقي هو معرّف بطول 128 بت بصيغته النصية القياسية xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx، حيث تُكتب البايتات عادةً بترتيب big-endian. أما نموذج النقل فيأخذ هذه البايتات القياسية الستة عشر، ويقسمها إلى نصفين طول كلٍّ منهما 8 بايت، ثم يكتب كل نصف بترتيب little-endian:

البايتات المنقولة من 0 إلى 7 = البايتات القياسية من 0 إلى 7 بترتيب معكوس.
البايتات المنقولة من 8 إلى 15 = البايتات القياسية من 8 إلى 15 بترتيب معكوس.

معرّف UUID ‏550e8400-e29b-41d4-a716-446655440000:

Canonical bytes (16):    55 0E 84 00 E2 9B 41 D4  A7 16 44 66 55 44 00 00

Wire bytes:
D4 41 9B E2 00 84 0E 55  high half byte-reversed
00 00 44 55 66 44 16 A7  low half byte-reversed

يظهر معرّف UUID الصفري (المكوّن بالكامل من أصفار) بالشكل نفسه في كلا التمثيلين.

IPv4 وIPv6

نوعان من العناوين مترابطان، لكن لكلٍّ منهما طريقة ترميز مختلفة. يشغل IPv4 أربعة بايتات، ويُرمَّز على هيئة UInt32 بترتيب little-endian يحمل العنوان المعياري ذا 32 بت (أي القيمة (a << 24) | (b << 16) | (c << 8) | d المستخرجة من a.b.c.d). وبذلك تكون البايتات المنقولة (wire bytes) هي بايتات ترتيب الشبكة بترتيب معكوس. 192.168.1.10 (القيمة المعيارية ذات 32 بت هي 0xC0A8010A):

0A 01 A8 C0              Little-endian UInt32

يشغل IPv6 مساحة 16 بايت، ويُكتب كما هو بترتيب بايتات الشبكة دون أي تبديل، أي بترتيب البايتات نفسه الذي تُنتجه inet_pton(AF_INET6, ...). 2001:db8::1:

20 01 0D B8 00 00 00 00  network bytes 0..7
00 00 00 00 00 00 00 01  network bytes 8..15

هذا التباين مقصود: إذ يُخزَّن IPv4 على هيئة u32 لتيسير العمليات الحسابية وإجراء استعلامات نطاق موجزة، في حين يحتفظ IPv6 بتخطيط ترتيب بايتات الشبكة (network order) المعتمد في معظم واجهات برمجة التطبيقات الخاصة بالشبكات.

Enum8 و Enum16

متوافقان على مستوى التمثيل الثنائي (wire) مع Int8 وInt16 على الترتيب: بايت واحد أو بايتان لكل صف، مع تمثيل المتمم الثنائي (two’s complement) بترتيب little-endian في النوع ذي 16 بت. ويرد التعيين الكامل للقيم ضمن سلسلة النوع:

Enum8('active' = 1, 'inactive' = 2, 'banned' = -1)
Enum16('a' = 1, 'b' = 30000)

قد تُزيل أداة فك الترميز لاحقة المعلمات (...) وتتعامل مع القيمة على أنها Int8 / Int16، إذ إن البايتات المنقولة ليست سوى الفهرس العددي الصحيح. أما العميل الذي يعرض الوسم، فيستخرج خريطة 'name' = value من سلسلة النوع ويحتفظ بها إلى جانب العمود، لأن العدد الصحيح وحده لا يكفي لاستعادة الوسم. ويعرض الإخراج النصي الوسم (active) بدلًا من الفهرس، محاطًا بعلامتي اقتباس مفردتين ('active') عندما يكون الـ enum متداخلًا ضمن نوع مركّب. ولمّا كانت الخريطة لا تُستعاد من عمود الأعداد الصحيحة، فلا بد من الاحتفاظ بها في حالة أنواع enum المتداخلة، مثل Array(Enum8(...)) أو Map(Enum16(...), V). عمود من النوع Enum8('active' = 1, 'inactive' = 2) يحتوي على [active, inactive, active]:

01 02 01

قيمة من النوع Enum16(...) تساوي 30000:

30 75                    Int16 LE = 30000

Decimal(P, S)

عدد صحيح ذو إشارة مضروب في قوة للعدد 10. تُحدِّد الدقة P عرض العدد الصحيح بالبايت ضمنيًا، أما المقياس S فهو الأس السالب (أي عدد الأرقام بعد الفاصلة العشرية). وكلاهما مُضمَّن في سلسلة النوع.

الدقة (P)	العدد الصحيح الأساسي	البايتات
1 ≤ P ≤ 9	Int32	4
10 ≤ P ≤ 18	Int64	8
19 ≤ P ≤ 38	Int128	16
39 ≤ P ≤ 76	Int256	32

ترميز wire هو العدد الصحيح الأساسي ممثَّلًا بالمتمم الثنائي بترتيب little-endian، أما القيمة العشرية المنطقية فهي wire_integer × 10^(-S). يُصدر ClickHouse دائمًا Decimal(P, S) أيًّا كانت طريقة التصريح عن النوع؛ إذ تُوحَّد Decimal32(S) وDecimal64(S) وغيرها جميعًا إلى Decimal(P, S) في تنسيق النقل (مع ضبط P على الحد الأقصى الطبيعي للعرض: 9، 18، 38، 76). وبالتالي فإن أداة فك الترميز التي لا تتعرّف إلا على Decimal(P, S) تغطي جميع الصيغ التي يُصدرها الخادم. القيمة 123.4567 من النوع Decimal(9, 4) ← العدد الصحيح الأساسي 1234567:

87 D6 12 00              Int32 LE = 1234567

القيمة -1.5 من النوع Decimal(18, 1) ← العدد الصحيح الأساسي -15:

F1 FF FF FF FF FF FF FF  Int64 LE = -15

القيمة 123.4567 من النوع Decimal(38, 4) (16 بايت إجمالًا):

87 D6 12 00 00 00 00 00 00 00 00 00 00 00 00 00

Nothing

لا يحمل النوع Nothing أي قيم. ولا يظهر عمليًا إلا بوصفه النوع الداخلي لـ Nullable(Nothing)، وهو ما يُرجعه الخادم لتعبير مثل SELECT NULL لا قيمة صالحة له سوى غياب القيمة. ومن الناحية المفاهيمية، فهو نوع وحدة (unit type). في تنسيق النقل، يشغل هذا النوع بايتًا نائبًا واحدًا لكل صف بالضبط. يُصدر الخادم حرف ASCII '0' (0x30)، لكن أداة إلغاء التسلسل تتجاهل هذه البايتات؛ فمحتواها غير محدد، ويجب ألا تعتمد أدوات فك الترميز على أي قيمة بعينها. ولأن عدد البايتات المكتوبة يساوي num_rows × 1، فإن قيمة num_rows في ترويسة العمود تحدد وحدها مقدار البيانات الواجب قراءتها. يحافظ تخصيص بايت لكل صف على ثبات خاصية الكتلة: إذ يمتد كل عمود على طول يمكن اشتقاقه من num_rows، فتواصل أدوات فك الترميز الفحص قُدُمًا دون الحاجة إلى بادئات طول لكل خلية. ولأن النوع المحيط Nullable يُبلغ دائمًا عن كل موضع بأنه NULL، فلا تُفحص العناصر النائبة أبدًا. عمود من النوع Nullable(Nothing) يحتوي على 3 صفوف (جميعها NULL):

01 01 01                 null map: 1, 1, 1 (three NULLs)
30 30 30                 Nothing placeholder bytes (one per row)

بادئة null-map هي بنية التأطير القياسية لـ Nullable (راجع Nullable)؛ أما البايتات الثلاثة الداخلية فتمثّل حمولة Nothing التي تتخطاها أداة فك الترميز.

الأنواع ذات الطول المتغير

تحمل كل قيمة طولها الخاص بها في تنسيق النقل.

String

سلسلة النوع: String. لعمود String تخطيطا wire، ويُختار أحدهما وفقًا لـ revision البروتوكول (راجع ما الذي تتحكم فيه الـ revision). والـ revision هي القيمة المتفاوض عليها في بروتوكول TCP الأصلي، أو قيمة client_protocol_version في حالة إخراج FORMAT Native (القيمة الافتراضية 0)؛ أما الإدخال بصيغة FORMAT Native فيكون دائمًا بالـ revision 0، في حين تستخدم صيغة Buffers دائمًا التخطيط القائم على كل قيمة على حدة. التخطيط القائم على كل قيمة على حدة — يُستخدم عندما تكون الـ revision أقل من DBMS_MIN_REVISION_WITH_STRING_WITH_SIZE_STREAM_SERIALIZATION (54492)، ويشمل ذلك الـ revision الافتراضية 0 لـ FORMAT Native: ويتألف من سلسلة تضم num_rows من تسلسلات البايتات، كلٌّ منها مسبوق بطوله:

[VarUInt: byte_length] [byte_length bytes: raw value]
[VarUInt: byte_length] [byte_length bytes: raw value]
...

لا توجد فواصل بين الصفوف باستثناء بادئات الطول، ولا توجد حالة على مستوى الصف. وتُمثَّل السلسلة الفارغة ببايت واحد هو 0x00. ويبلغ إجمالي عدد البايتات التي يشغلها العمود Σ (varuint_size(len_i) + len_i) محسوبًا على جميع الصفوف. مثال لعمود يضم 3 سلاسل نصية ["ab", "", "c"] (بإجمالي 6 بايتات):

61 62                 row 0: length 2, "ab"
                     row 1: length 0, empty
63                    row 2: length 1, "c"

تخطيط الإزاحات — في الـ revision 54492 وما بعده: دفقان متتاليان، أولهما إزاحات البايتات التراكمية، ثم تليها جميع البيانات:

[UInt64 × num_rows: cumulative byte offset (end of each value), little-endian]
[last offset bytes: all values concatenated, no separators]

تُرسَل قيم الإزاحة كما هي، تمامًا كما يُرسل Array قيم الإزاحة الخاصة به عبر البروتوكول الأصلي. تمثّل الإزاحة i موضع نهاية القيمة i في كتلة البيانات (blob)، ومن ثَمّ يكون حجم القيمة i هو offset[i] - offset[i-1] (حيث offset[-1] = 0)، وتساوي الإزاحة الأخيرة الحجم الكلي لكتلة البيانات. تقرأ أداة فك الترميز 8 × num_rows بايت من قيم الإزاحة، ثم تقرأ كتلة البيانات كاملةً دفعةً واحدة، مستخدمةً الإزاحة الأخيرة طولًا دقيقًا لها، وهذا يتيح حجز المخزن المؤقت مسبقًا بدقة والنسخ المجمّع بدلًا من التحليل صفًّا صفًّا، دون الحاجة إلى أي تحويل من الأحجام إلى قيم الإزاحة. أما العمود الذي يكون فيه num_rows = 0 فلا يُضيف أي بايتات إلى أيٍّ من الدفقين. السلاسل النصية الثلاث نفسها ["ab", "", "c"] (‏27 بايت إجمالًا):

00 00 00 00 00 00 00  row 0 offset: 2  (end of "ab")
00 00 00 00 00 00 00  row 1 offset: 2  (end of "", so unchanged)
00 00 00 00 00 00 00  row 2 offset: 3  (end of "c")
62 63                 "ab" + "" + "c"

عندما يكون تخطيط الإزاحات (offsets layout) مفعّلًا، فإنه ينطبق على كل String في الكتلة، بما في ذلك String المتداخل داخل الأنواع المركّبة (Array(String)، وNullable(String)، وMap، وTuple، وVariant، وDynamic، وJSON)، باستثناء حالة واحدة: يُكتب قاموس عمود LowCardinality دائمًا بالتسلسل المتداخل الافتراضي، ولذلك تظل قيم String فيه محتفظة بالتخطيط لكل قيمة (per-value layout) في جميع قيم revision. ويشمل ذلك LowCardinality(String)، وLowCardinality(Nullable(String))، وأي قاموس LowCardinality آخر يحتوي على قيم String. في كلا التخطيطين، يتعامل String في ClickHouse مع البيانات بوصفها بايتات لا نصوصًا: فلا يُشترط أن تكون بترميز UTF-8 صالح، ويمكن أن تحتوي القيمة على أي بايتات، بما فيها محرف NUL المضمّن. لذا، فإن أداة فك الترميز التي تحوّل القيم إلى نوع سلسلة UTF-8 يجب عليها إما أن تتحقق من صلاحيتها عند القراءة، أو أن تمرّر البايتات الخام كما هي إلى الشيفرة المستدعية.

FixedString(N)

سلسلة النوع: FixedString(N)، حيث N عدد صحيح موجب (مثل FixedString(16)). يتكوّن العمود من N × num_rows بايت خام بالضبط، دون بادئات طول ودون فواصل. تستخرج أداة فك الترميز قيمة N من سلسلة النوع، ثم تقرأ هذا العدد من البايتات لكل صف. عندما يُدرج استعلام SQL قيمة أقصر من N بايت (مثل CAST('abc' AS FixedString(5)))، يُكمل الخادم القيمة من اليمين ببايتات NUL (0x00) حتى تبلغ الطول المُعلَن. وتُعدّ بايتات الحشو هذه جزءًا من القيمة المخزَّنة، وتُرسَل في تنسيق النقل كما هي؛ أما إزالتها فمسؤولية جهة العميل. وكما هو الحال مع String، فإن FixedString(N) أقرب إلى مصفوفة بايتات منه إلى نص، ويُستخدم عادةً للمعرّفات ثابتة العرض، أو بايتات العناوين، أو ملخصات التجزئة. قيمتان من النوع FixedString(3) هما ["abc", "de\0"] (بإجمالي 6 بايتات):

61 62 63                 row 0: 3 bytes, "abc"
64 65 00                 row 1: 3 bytes, "de" + NUL padding

مقارنة بين نوعَي string:

الخاصية	`String`	`FixedString(N)`
بادئة طول لكل صف	نعم (VarUInt)، أو دفق إزاحات منفصل بدءًا من revision `54492`+	لا
حجم الصف	متغير	`N` بايت بالضبط
إجمالي بايتات العمود	متغير	`N × num_rows`
الحشو ببايتات NUL	لا ينطبق	يحشوه الخادم من اليمين
يُتوقَّع ترميز UTF-8	عادةً (دون إلزام)	لا (يُعامَل كبايتات خام)
معلمة النوع	لا يوجد	عدد صحيح `N` إلزامي

الأنواع المركبة

تغلّف الأنواع المركبة نوعًا داخليًا واحدًا أو أكثر، وتشترك في نموذج نقل موحّد: عدة دفقات لكل عمود. فالعمود المنطقي الواحد يُرمَّز في صورة تسلسلين أو أكثر من البايتات، يُقرأ كلٌّ منها على حدة، ثم تُوصَل ببعضها على التوالي. وتشترك هذه الأنواع في ثلاث خصائص بنيوية:

شكل ثابت لكل مخطط. تتحدد البنية بالكامل من سلسلة النوع وقت فك الترميز. فالنوع Array(UInt32) له دائمًا تخطيط الدفقات نفسه في كل كتلة.
لا بادئة إصدار خاصة بها. لا يضيف الغلاف المركب بحد ذاته أي بايت إصدار؛ إذ يظل تأطيره (الإزاحات، وnull-map، ودفقات العناصر) مستقرًا عبر إصدارات ClickHouse. ينطبق هذا على الغلاف فقط — راجع الملاحظة الخاصة بمرحلة البادئة أدناه بشأن الأنواع الداخلية ذات الإصدارات.
لا حالة خاصة بها عبر الكتل. تأطير الغلاف ذاتي الوصف بالكامل في كل كتلة؛ وأي مسألة تتعلق بالحالة عبر الكتل مصدرها نوع داخلي ذو إصدار، لا الغلاف.

الأنواع المركبة تعاودية، أي أن النوع الداخلي قد يكون هو نفسه نوعًا مركبًا. مرحلة البادئة قبل دفقات البيانات. تجري قراءة العمود على مرحلتين بهذا الترتيب: مرحلة بادئة الحالة ثم مرحلة دفقات البيانات. لا يملك الغلاف المركب بايتات بادئة خاصة به، لكنه يفوّض مرحلة البادئة إلى التسلسل الداخلي قبل كتابة أيٍّ من دفقات بياناته: فالمكوّن SerializationArray ينفّذ مرحلة البادئة لنوعه الداخلي قبل كتابة إزاحات المصفوفة، وكذلك تفعل الأنواع Tuple وMap وNested وNullable عبر تسلسلات عناصرها (إذ ينفّذ Nullable البادئة الداخلية قبل null map الخاصة به). ولذلك، عندما يغلّف نوع مركب نوعًا ذا إصدار/حالة (LowCardinality أو Variant أو Dynamic أو JSON)، تُصدَر بادئة الإصدار/الحالة الخاصة بذلك النوع الداخلي أولًا، قبل إزاحات الغلاف وحمولة عناصره. فعلى سبيل المثال، يُرتَّب Array(LowCardinality(String)) على النحو التالي: [LowCardinality state prefix] ← [array offsets] ← [flattened LowCardinality element payload]، لا بالإزاحات أولًا. وأداة فك الترميز التي تقرأ الإزاحات قبل تنفيذ مرحلة البادئة الداخلية ستفقد التزامن مع أي نوع مركب يحتوي على LowCardinality أو Variant أو Dynamic أو JSON. أما إذا كان كل نوع داخلي نوعًا طرفيًا بسيطًا أو نوعًا مركبًا آخر بلا إصدار، فلا تُصدر مرحلة البادئة أي بايتات، وينطبق الوصف الوارد أدناه، القائم على البدء بالإزاحات، كما هو تمامًا.

Nullable(T)

سلسلة النوع: Nullable(InnerType). أمثلة: Nullable(UInt32)، Nullable(String)، Nullable(FixedString(16))، Nullable(DateTime('UTC')). على غرار الأنواع المركّبة الأخرى، يُحيل Nullable مرحلة البادئة إلى التسلسل الداخلي للنوع المضمَّن قبل كتابة خريطة القيم الفارغة (null map): فإذا كان النوع الداخلي ذا إصدار، تُرسَل بادئة الحالة الخاصة به أولًا. ولذلك يبدأ Nullable(Tuple(LowCardinality(String))) ببادئة الحالة الخاصة بـ LowCardinality، لا بخريطة القيم الفارغة. أما إذا كان النوع الداخلي نوعًا طرفيًا (leaf) أو نوعًا آخر غير ذي إصدار، فلا تُرسِل مرحلة البادئة أي بايتات. يتألف تخطيط wire من مرحلة البادئة الداخلية (وتكون فارغة ما لم يكن النوع الداخلي ذا إصدار)، يليها دفقان متتاليان تتقدّمهما خريطة القيم الفارغة (null-map):

[inner type's state prefix]   empty for leaf/non-versioned inners; emitted first when the inner is versioned
[null-map stream]             num_rows × UInt8
[values stream]               inner type's encoding for num_rows values

يبلغ حجم null-map ‏num_rows بايت بالضبط، أي بايت واحد لكل صف:

قيمة البايت	المعنى
`0x00`	توجد قيمة في هذا الصف.
غير صفرية (الشكل القياسي `0x01`)	القيمة NULL، والبايتات المقابلة لها في دفق القيم مجرد عنصر نائب.

يحتوي دفق القيم على الترميز القياسي للنوع الداخلي لـجميع الصفوف البالغ عددها num_rows، بما فيها مواضع القيم الفارغة. وعلى أداة فك الترميز أن تقرأ بايتات العنصر النائب في مواضع القيم الفارغة كي تتقدّم في الدفق، لكن عليها الرجوع إلى null-map قبل تفسير أي قيمة بعينها. ونظرًا لأن المُرسِلين قد يكتبون أي بايتات في مواضع القيم الفارغة، فلا يجوز لأدوات فك الترميز الاعتماد على قيمة محددة للعنصر النائب. قيم العنصر النائب بحسب عائلة النوع الداخلي:

عائلة النوع الداخلي	العنصر النائب في موضع القيمة الفارغة
ثابتة العرض (UInt/Int/Float/DateTime/UUID/إلخ)	بايتات مُهيّأة بالأصفار بعرض النوع
`String`	سلسلة فارغة — بايت واحد `0x00`
`FixedString(N)`	`N` بايت صفري
`Array(T)`	مصفوفة فارغة — تتقدّم الإزاحات بمقدار صفر
`Tuple(T1, T2, ...)`	يستخدم كل عنصر العنصر النائب الخاص بنوعه

يمكن أن يرد Nullable(T) داخل Array وTuple وMap وNested، ومن الشائع استخدام Array(Nullable(T)) وTuple(Nullable(T1), T2). غير أنه لا يمكن تداخل قابلية القيم الفارغة مع نفسها، إذ يرفض الخادم Nullable(Nullable(T)). مثال على Nullable(UInt8) يضم ثلاثة صفوف [5, NULL, 9] (بإجمالي 6 بايتات):

00 01 00                 null-map: present, null, present
05 00 09                 values:   5, placeholder, 9

عمود من النوع Nullable(String) يحتوي على ثلاثة صفوف ["hello", NULL, "world"] (بإجمالي 15 بايت):

01 00                 null-map
'h' 'e' 'l' 'l' 'o'   row 0: "hello"
                     row 1: placeholder (empty string)
'w' 'o' 'r' 'l' 'd'   row 2: "world"

Array(T)

سلسلة النوع: Array(InnerType). أمثلة: Array(UInt32) وArray(String) وArray(Nullable(UInt32)) وArray(Array(UInt8)). يتكوّن تخطيط wire من مرحلة البادئة الخاصة بالنوع الداخلي (وتكون فارغة ما لم يكن النوع الداخلي ذا إصدار)، يليها دفقان متتاليان، أولهما دفق الإزاحات:

[inner type's state prefix]   empty for leaf/non-versioned inners; emitted first when the inner is versioned
[offsets stream]              num_rows × UInt64 LE
[values stream]               inner type's encoding for offsets[num_rows - 1] values

يتكوّن دفق الإزاحات من num_rows قيمة UInt64 بالضبط بترتيب little-endian، وتمثّل كل قيمة منها موضع النهاية التراكمي في دفق القيم بعد عناصر ذلك الصف:

فهرس بداية العناصر للصف N = offsets[N - 1] (أو 0 عندما يكون N == 0).
فهرس نهاية العناصر (غير شامل) للصف N = offsets[N].
عدد عناصر الصف N = offsets[N] - offsets[N - 1].

وبناءً على ذلك، تمثّل offsets[num_rows - 1] إجمالي عدد العناصر في جميع الصفوف، ويضمّ دفق القيم هذا العدد من القيم الداخلية متتاليةً دون فواصل. الإزاحات رتيبة غير متناقصة؛ فتساوي إزاحتين متتاليتين يدل على صف فارغ، وينبغي لأداة فك الترميز أن ترفض الإزاحات غير الرتيبة وتعدّها تلفًا في البيانات. أما العمود الفارغ (num_rows == 0) فلا يُكتب له أي بايت، فلا يوجد دفق إزاحات ولا دفق قيم. ويجوز أن تكون الأنواع الداخلية من أي نوع، بما في ذلك الأنواع المركّبة الأخرى؛ فالأنواع Array(Array(T)) وArray(Tuple(...)) وArray(Nullable(T)) كلها صالحة. Array(UInt32) بالصفوف [[10, 20, 30], [], [40, 50]] (44 بايت إجمالًا):

Offsets (3 × UInt64 LE = 24 bytes):
03 00 00 00 00 00 00 00      offsets[0] = 3
03 00 00 00 00 00 00 00      offsets[1] = 3 (empty row)
05 00 00 00 00 00 00 00      offsets[2] = 5

Values (5 × UInt32 LE = 20 bytes):
0A 00 00 00                  10
14 00 00 00                  20
1E 00 00 00                  30
28 00 00 00                  40
32 00 00 00                  50

تمثّل كل إزاحة نهايةً تراكمية لجزء الصف من دفق القيم المشترك، أما بدايته فهي الإزاحة السابقة (أو 0 للصف 0). وتدل الإزاحتان المتتاليتان المتساويتان على صف فارغ:

النوع Array(String) بالصفوف [["a", "bb"], []] (20 بايت إجمالًا):

Offsets (2 × UInt64 LE = 16 bytes):
02 00 00 00 00 00 00 00      offsets[0] = 2
02 00 00 00 00 00 00 00      offsets[1] = 2 (empty row)

Values (2 strings, 4 bytes total):
01 'a'                       row's first string: "a"
02 'b' 'b'                   row's second string: "bb"

يتّبع Array(Array(UInt32)) ذو الصفوف [[[1,2]], [], [[3], [4,5]]] البنيةَ نفسها على نحوٍ متداخل:

الإزاحات الخارجية: [1, 1, 3]؛ إذ يحتوي الصف 0 على مصفوفة داخلية واحدة، والصف 1 على 0، والصف 2 على 2.
يفكّ Array(UInt32) الأوسط ترميز 3 صفوف بالإزاحات [2, 3, 5].
يفكّ UInt32 الأعمق ترميز 5 قيم: [1, 2, 3, 4, 5].

وبذلك يبلغ المجموع 24 (الإزاحات الخارجية) + 24 (الإزاحات الوسطى) + 20 (القيم) = 68 بايت.

Tuple(T1, T2, …)

سلسلة النوع: Tuple(T1, T2, ..., Tn). أمثلة: Tuple(UInt32, String)، Tuple(Int32)، Tuple(Array(UInt32), String)، Tuple(UInt8, Tuple(Int32, String)). يدعم ClickHouse أيضًا Tuple المسمّاة باستخدام Tuple(a UInt32, b String)؛ والأسماء مجرد بيانات وصفية لا تؤثر في تنسيق wire. يتكوّن تخطيط wire من مرحلة البادئة الخاصة بالعناصر (إذ يضيف كل عنصر ذي إصدار بادئة الحالة الخاصة به وفق ترتيب التصريح، وتكون هذه المرحلة فارغة للعناصر التي لا إصدار لها)، تليها N من التدفقات المتتالية، بواقع تدفق واحد لكل نوع عنصر، وفق ترتيب التصريح:

[element state prefixes]   in declaration order; empty unless an element type is versioned
[stream for T1]    inner T1's encoding for num_rows values
[stream for T2]    inner T2's encoding for num_rows values
 ...
[stream for Tn]    inner Tn's encoding for num_rows values

يُشفِّر كل دفق num_rows قيمةً بالضبط. لا توجد بادئة طول، ولا دفق إزاحات، ولا فواصل بين الدفقات. ولا يُكتب للعمود الفارغ (num_rows == 0) أي بايت في أي دفق. ويمكن أن تكون أنواع العناصر من أي نوع، بما في ذلك الأنواع المركّبة الأخرى؛ إذ إن Tuple(Tuple(...), ...) وTuple(Array(...), ...) وTuple(Nullable(T1), T2) كلها صالحة. والـ Tuple الخالي من العناصر Tuple() صالح أيضًا، وهو ينشأ من تعبيرات مثل SELECT tuple() أو CAST(x AS Tuple()). ولأنه لا يملك دفقات عناصر، فإنه يُسلسَل بطريقة Nothing نفسها: بايت عنصر نائب واحد (0x30، أي '0' في ASCII) لكل صف، تتجاهله أداة إلغاء التسلسل. ويُستمد عدد الصفوف من ترويسة الكتلة، تمامًا كما في Nothing. Tuple(UInt8, UInt8) مع 3 صفوف (1,4), (2,5), (3,6):

Element 0 stream (3 × UInt8 = 3 bytes):
01 02 03

Element 1 stream (3 × UInt8 = 3 bytes):
04 05 06

التخطيط ليس بترتيب الصفوف أولًا (row-major)، إذ تُعيد قراءة البايتات الخام القيمة [1, 2, 3] للعنصر 0 والقيمة [4, 5, 6] للعنصر 1. Tuple(UInt32, String) بصفّين (10, "a") و(20, "bb") (بإجمالي 13 بايت):

Element 0 stream (2 × UInt32 LE = 8 bytes):
0A 00 00 00                  10
14 00 00 00                  20

Element 1 stream (2 strings, 5 bytes total):
01 'a'                       "a"
02 'b' 'b'                   "bb"

Map(K, V)

سلسلة النوع: Map(KeyType, ValueType). أمثلة: Map(String, UInt32)، Map(String, Array(UInt32))، Map(UInt8, Tuple(Int32, String))، Map(Array(String), Int8). لا يفرض تنسيق wire أي قيد على أيٍّ من النوعين، إذ يمكن أن يكون كلٌّ من K وV أيَّ نوع مدعوم، بما في ذلك الأنواع المركّبة. (اختلفت قواعد ClickHouse على مستوى SQL بشأن أنواع المفاتيح المقبولة من إصدار إلى آخر؛ لذا راجع توثيق SQL الخاص بإصدار الخادم المستهدف.) يتطابق تخطيط wire بايتًا ببايت مع Array(Tuple(K, V))، ولذلك يبدأ بـمرحلة البادئة الداخلية (وتكون فارغة ما لم يكن K أو V ذا إصدار تسلسل):

[K/V state prefixes]   from the inner Tuple's prefix phase; empty unless K or V is versioned
[offsets stream]    num_rows × UInt64 LE                   ← from Array
[keys stream]       K's encoding for total_pairs values    ┐ from Tuple's
[values stream]     V's encoding for total_pairs values    ┘ per-element streams

حيث total_pairs = offsets[num_rows - 1] (أو 0 عندما يكون num_rows == 0). ولدفق الإزاحات الدلالات نفسها المتبعة في Array. والمفاتيح محاذاة موضعيًا مع القيم: فالزوج i هو (keys[i], values[i]). يُمثِّل ClickHouse عمود Map في الذاكرة على هيئة مصفوفة من صفوف مرتبة، غير أن نظام الأنواع يعرضه نوعًا مستقلًا لتيسير الاستخدام في SQL (m['key']، mapKeys، mapValues). وتنسيق wire ما هو إلا تسلسل مباشر لهذا التخزين، ولذلك فإن Map وArray(Tuple(K, V)) قابلان للتبادل بايتًا ببايت. الإزاحات رتيبة غير متناقصة، ويحتوي كلٌّ من دفق المفاتيح ودفق القيم على total_pairs قيمة بالضبط. ولا يُكتب أي بايت للعمود الفارغ. وعادةً ما تكون المفاتيح مميزة ضمن الصف الواحد، لكن هذه قاعدة دلالية لا يفرضها تنسيق wire: إذ يسمح تنسيق wire بكتابة المفاتيح المكررة وقراءتها مجددًا دون تغيير، ولا تُحسم التكرارات وفق الدلالات على جانب الخادم إلا عندما تستهلك الصفَّ دالةٌ تتعامل مع Map. Map(UInt8, UInt8) مع صفين {1:10, 2:20}، {3:30} (22 بايت إجمالًا):

Offsets (2 × UInt64 LE = 16 bytes):
02 00 00 00 00 00 00 00      offsets[0] = 2
03 00 00 00 00 00 00 00      offsets[1] = 3

Keys (3 × UInt8 = 3 bytes):
01 02 03                     keys: 1, 2, 3

Values (3 × UInt8 = 3 bytes):
0A 14 1E                     values: 10, 20, 30

تُخزَّن المفاتيح والقيم في تدفقات منفصلة لا متداخلة، إذ يُعاد بناء الزوج i بقراءة keys[i] وvalues[i] معًا. النوع Map(String, UInt32) مع صف واحد {'a':1, 'b':2} (بإجمالي 20 بايت):

Offsets (1 × UInt64 LE = 8 bytes):
02 00 00 00 00 00 00 00      offsets[0] = 2

Keys (2 strings, 4 bytes total):
01 'a'                       "a"
01 'b'                       "b"

Values (2 × UInt32 LE = 8 bytes):
01 00 00 00                  1
02 00 00 00                  2

Nested(name1 T1, name2 T2, …)

يتوقف تمثيل Nested أثناء النقل على قيمة الإعداد flatten_nested من جهة الخادم، ما يُفضي إلى حالتين مختلفتين.

الحالة أ: flatten_nested = 1 (القيمة الافتراضية للخادم). إذا أُنشئ الجدول بالإعدادات الافتراضية، فإن Nested ليس نوعًا من أنواع النقل (wire type)، إذ يخزّن الخادم العمود ويعرضه على هيئة N من أعمدة Array(T_i) المتوازية ذات أسماء منقّطة (outer.field1 وouter.field2 وهكذا). وبالنسبة لطبقة الصيغة لا جديد في ذلك، فكل عمود منقّط ما هو إلا Array عادية:

DESCRIBE TABLE t   -- t has column n Nested(a UInt8, b String)
id     UInt8
n.a    Array(UInt8)
n.b    Array(String)

الحالة B: flatten_nested = 0. عند إنشاء الجدول باستخدام flatten_nested = 0، يظهر العمود في تنسيق النقل عمودًا واحدًا سلسلةُ نوعه Nested(name1 T1, name2 T2, ...)، ويكون تخطيطه بعد سلسلة النوع مطابقًا بايتًا ببايت لـ Array(Tuple(T1, T2, ..., Tn))، بما في ذلك مرحلة البادئة الداخلية، ومن ثَمّ فإن أي حقل ذي إصدار T_i يُصدِر بادئة الحالة الخاصة به أولًا، قبل الإزاحات. يستخدم المثال أدناه حقولًا بلا إصدار، ولذلك تكون مرحلة البادئة فارغة:

Nested(a UInt8, b String) bytes (after type string):
  02 00 00 00 00 00 00 00       offsets[0] = 2
  03 00 00 00 00 00 00 00       offsets[1] = 3
  0A 14 1E                       UInt8 stream
  01 'x' 01 'y' 01 'z'           String stream

Array(Tuple(a UInt8, b String)) bytes (after type string):
  02 00 00 00 00 00 00 00       offsets[0] = 2
  03 00 00 00 00 00 00 00       offsets[1] = 3
  0A 14 1E                       UInt8 stream
  01 'x' 01 'y' 01 'z'           String stream

الفرق الوحيد هو نص سلسلة النوع: يحتفظ Nested بأسماء الحقول (a، b)، بينما لا يحمل Array(Tuple) هذه الأسماء كخانات مسمّاة. سلسلة النوع في الحالة B هي قائمة من أزواج (الاسم، النوع) مفصولة بفواصل. تفصل أول مسافة بيضاء بين الاسم ونوعه؛ وقد يحتوي النوع نفسه على مزيد من المسافات البيضاء والفواصل والأقواس، لذا يتطلب التحليل أداة التقسيم نفسها المستخدمة مع Tuple، والتي تراعي مستوى التداخل. تخطيط wire:

[offsets stream]    num_rows × UInt64 LE                       ← from Array
[field1 stream]     T1's encoding for total_elements values    ┐ from Tuple's
[field2 stream]     T2's encoding for total_elements values    │ per-element
 ...                                                            │ streams
[fieldn stream]     Tn's encoding for total_elements values    ┘

حيث total_elements = offsets[num_rows - 1] (أو 0 عندما تكون num_rows == 0). قيم الإزاحة رتيبة غير متناقصة، ويحتوي كل دفق حقل على total_elements قيمة بالضبط. ويشترط الخادم عند الإدراج (INSERT) أن تحمل جميع الحقول داخل الصف الواحد العدد نفسه من العناصر. أما العمود الفارغ فلا يُكتب له أي بايت. Nested(a UInt8, b String) بصفين هما [(10,'x'),(20,'y')] و[(30,'z')] (‏25 بايت بعد سلسلة النوع):

Offsets (2 × UInt64 LE = 16 bytes):
02 00 00 00 00 00 00 00      offsets[0] = 2
03 00 00 00 00 00 00 00      offsets[1] = 3

Field 'a' stream (3 × UInt8 = 3 bytes):
0A 14 1E                     10, 20, 30

Field 'b' stream (3 strings, 6 bytes):
01 'x' 01 'y' 01 'z'         "x", "y", "z"

الأسماء البديلة للأنواع

بعض الأنواع ليست سوى أسماء بديلة بحتة: إذ يرسل الخادم الاسم البديل في ترويسة العمود، غير أن البايتات التي تليه تعود إلى نوع أساسي. تربط أداة فك الترميز الاسم البديل بذلك النوع وتعيد استخدام المرمِّز الخاص به، دون الحاجة إلى أي تنسيق wire جديد. الأنواع الجغرافية أسماء بديلة لمصفوفات وصفوف مرتبة متداخلة:

سلسلة النوع	نوع wire الأساسي
`Point`	`Tuple(Float64, Float64)`
`Ring`, `LineString`, `MultiPoint`	`Array(Point)`
`Polygon`, `MultiLineString`	`Array(Ring)`
`MultiPolygon`	`Array(Polygon)`

وبذلك يُفك ترميز عمود Point تمامًا كما يُفك ترميز Tuple(Float64, Float64) (ويُعرض بالشكل (1,2))، ويُفك ترميز Ring كما يُفك ترميز Array(Tuple(Float64, Float64)) ([(0,0),(1,1)])، وهكذا صعودًا في التسلسل الهرمي. Geometry هو أيضًا اسم بديل، لكنه بديل لـ Variant لا لمصفوفة متداخلة: فحمولته هي الـ variant المكوّن من الأنواع الجغرافية السبعة المذكورة أعلاه. لا تحمل ترويسة العمود سوى سلسلة النوع Geometry، ولا تفصّل مكونات الـ variant، لذا يتعيّن على أداة فك الترميز توسيعه بنفسها. وخلافًا لـ Variant الذي يكتبه المستخدم صراحةً، فإن مميّزات Geometry لا تتبع الترتيب الأبجدي للأسماء: فهي ثابتة لضمان التوافق، ولا تُضاف الأنواع الجغرافية الجديدة إلا في النهاية. والتعيين كالتالي: 0 = LineString، 1 = MultiLineString، 2 = MultiPolygon، 3 = Point، 4 = Polygon، 5 = Ring، 6 = MultiPoint (أُضيف في الإصدار 26.7، ولذا لن تحتوي التدفقات الواردة من الخوادم الأقدم على المميّز 6 أصلًا). ثم يُفك ترميز كل قيمة مختارة عبر اسمها الجغرافي البديل المذكور أعلاه (وتستخدم NULL مميّز NULL الخاص بـ Variant، وهو 255). SimpleAggregateFunction(func, T) اسم بديل لنوع قيمته T. فهو يخزّن قيمة تجميعية مكتملة مسبقًا، ولذلك فإن صيغته على wire وطريقة عرضه مطابقتان تمامًا لـ T (إذ يُفك ترميز SimpleAggregateFunction(sum, UInt64) على أنه UInt64). ولا يُعدّ اسمًا بديلًا بهذه الطريقة إلا الشكل ذو نوع القيمة الواحد؛ وقد يكون النوع الأساسي نفسه نوعًا مركّبًا.

ثمة نوعان مرتبطان ليسا اسمين بديلين، رغم أنهما نوعا أعمدة Native صالحان، إذ يمكن للعميل مثلاً أن يستقبل عمود AggregateFunction ناتجاً عن مُركِّب -State أو عن تجميع موزّع. غير أن لكل منهما حمولته المتخصصة التي تقع خارج نطاق هذه الصفحة:

يحتفظ AggregateFunction(func, ...) بحالة تجميع وسيطة (لا بقيمة نهائية)، ويختلف تخطيطها الثنائي باختلاف الدالة التجميعية وإصدارها. وقد يتضمن اسم الدالة معلمات، تُطبع كل منها في صورة قيمة حرفية SQL، كما في AggregateFunction(topK(3), UInt64). وتطبع بعض الدوال التجميعية لاحقة ::Type صريحة على المعلمة، كما في AggregateFunction(topK('3'::Decimal32(0)), UInt64)، لأن قيم Decimal والأعداد الصحيحة الواسعة لا صيغة حرفية مجردة لها تصلح للطباعة؛ وقيام الدالة بذلك من عدمه سمةٌ للدالة نفسها لا للتنسيق، لذا يجب على أداة فك الترميز التي تفحص المعلمات أن تقبل الصيغتين كلتيهما. أما أداة فك الترميز التي لا تحتاج إلا إلى أنواع الوسيطات فلا تتأثر بذلك. وتكتب الدالة التجميعية ذات الإصدارات إصدار الحالة غير الصفري صراحةً بوصفه الوسيطة الأولى في سلسلة النوع — AggregateFunction(1, quantileDeterministic, UInt64, UInt64) — في حين لا يُطبع الإصدار 0، فتبقى سلسلة النوع AggregateFunction(quantileDeterministic, UInt64, UInt64). وفي الاتصال المتفاوض عليه (أي حين تكون revision أعلى من 0)، يحدد الكاتب الإصدار استناداً إلى مراجعة البروتوكول وحدها، ولا يعتمد مطلقاً على إصدار قد يكون مثبّتاً على نوعه المحلي، لأن الإصدار 0 لا يمكن تمييزه أثناء النقل عن “عدم الإعلان عن أي إصدار”. ولهذا قد تعلن الدالة نفسها عن إصدارات مختلفة باختلاف الاتصالات، ويجب على القارئ أن يستمد الإصدار من سلسلة النوع لا أن يفترض أنه الأحدث. أما عند revision 0 فلا يوجد نظير يُشتق له إصدار، إذ يصف الدفق نفسه بنفسه ويقرؤه من كتبه؛ لذا يبقى الإصدار المثبّت على النوع محفوظاً في الدفق (وفي سلسلة النوع المُعلنة) ولا يُخفَض إلى 0. وتصبح quantileDeterministic (ومعها الصيغتان quantilesDeterministic وmedianDeterministic) ذات إصدارات بدءاً من revision 54491: إذ يضيف الإصدار 1 حقلاً UInt8 skip_degree في نهاية الحالة، بينما تبقى بادئتها مطابقة بايتاً ببايت للإصدار 0. وفيما دون هذه المراجعة يُصدر الكاتب حالات بالإصدار 0، فلا يتأثر النظير الأقدم. وتصبح uniq ذات إصدارات بدءاً من revision 54493: إذ يضيف الإصدار 1 بايت أعلام في بداية تخطيط الإصدار 0، وعندما يكون البت 0 من الأعلام مضبوطاً، يُلحق في النهاية عيّنة إضافية صغيرة من قيم التجزئة الكاملة بطول 64 بت، تُطبَّق على كل منها عملية XOR مع الثابت 0x9E3779B97F4A0000 (UInt8 skip_degree، ثم VarUInt count، ثم القيم ذات الثمانية بايتات)، مما يحافظ على دقة التقدير عند الأعداد الأصلية التي تتجاوز ملياري قيمة؛ أما حالة الإصدار 0 فلا تحمل سوى العيّنة الرئيسية بطول 32 بت. ويشير البت 1 من الأعلام إلى أن عيّنة 64 بت غير مكتملة، أي أن الحالة قد استوعبت حالة بالإصدار 0 لم تُعرض عناصرها قط على عيّنة 64 بت؛ وعندئذٍ لا تُكتب أي عيّنة 64 بت، ويجب على القارئ أن يُجري التقدير استناداً إلى العيّنة الرئيسية بطول 32 بت وحدها (وأن يواصل الإشارة إلى ذلك في الحالات التي يكتبها لاحقاً)؛ ولذا فالبتان متنافيان، ويجب على القارئ رفض أي حالة تضبط كليهما. ولا يوجد أي بت آخر معرَّف، ويجب على القارئ رفض أي حالة تضبط بتاً غيرهما. وينطبق ذلك كله أيضاً على الحالة المتداخلة داخل نوع حاوٍ، مثل Array أو Tuple أو Map أو Nullable أو Variant (حيث يغيّر الإصدار المكتوب صراحةً للبديل سلسلة النوع دون أن يغيّر ترتيب المميّز)، أو داخل غلاف Nested / SimpleAggregateFunction. كما ينطبق على مُركِّبات الدوال التجميعية: فالمُركِّب التمريري المطبَّق على دالة ذات إصدارات — مثل uniqIf وuniqArray وuniqForEach وuniqMap وuniqArgMin / uniqArgMax وuniqOrNull / uniqOrDefault وuniqResample، والمُكيِّف الضمني لوسيطات Nullable — يمرّر الإصدار إلى الحالات المتداخلة التي تتضمنها حمولته، ويكتب الإصدار الحالي للدالة المتداخلة صراحةً في سلسلة نوع الحالة الجديدة تماماً كما تفعل الدالة المجردة (AggregateFunction(1, uniqIf, UInt64, UInt8))، ويشتق الإصدار من مراجعة البروتوكول في الاتصال المتفاوض عليه بالطريقة نفسها. ولأن الاسم المخصص للغلاف يتضمن نسخة ثانية من نوع وسيطته، يجب على الكاتب إعادة بناء تلك النسخة بإصدار حالة التجميع المتفاوض عليه نفسه، وإلا فقد تعلن ترويسته عن الإصدار 1 لحمولة مكتوبة بالإصدار 0. وثمة حالة حدّية واحدة في Variant لا يمكن تمثيلها أثناء النقل إطلاقاً: فعندما يختلف بديلان في إصدار الحالة المكتوب صراحةً فقط (وهو أمر جائز في نوع العمود، لأن سلسلتي النوع مختلفتان)، فإن إعادة تعيين إصدار كليهما وفق المراجعة المتفاوض عليها ستدمجهما في بديل واحد، لذا يجب على المُرسل أن يُفشل عملية النقل بدلاً من الإعلان عن إصدارات لم تُكتب بها الحمولة. ويُعد Dynamic استثناءً مقصوداً من قاعدة اشتقاق الإصدار من المراجعة: إذ يعلن عمود Dynamic عن أنواعه المتداخلة بنفسه، عبر قوائم أنواعه الخاصة وعبر الترميز الثنائي للأنواع، الذي يتضمن حقل إصدار صريحاً يحمل إصدار الحالة المكتوب صراحةً (وبهذه الطريقة تُضمِّن قيم المتغير المشترك نوعها حتى أثناء التخزين). وهذه الإعلانات جزء من بيانات العمود ذاتها، وهي متطابقة لكل نظير ولكل وسيط، لذا لا يُعاد كتابتها أبداً وفق مراجعة متفاوض عليها. وعليه، تُكتب الحالة المتداخلة داخل قيمة Dynamic بالإصدار المحدد في نوعها (وهو ما تحمله الحالة الجديدة، لأن نتيجة استعلام -State تكتب إصدارها صراحةً)، وبالإصدار 0 إذا لم يحدد النوع أي إصدار، وذلك على جميع الاتصالات والوسائط دون استثناء.
يخزّن QBit(T, N[, stride]) متجهاً بعد تبديل مستويات البتات فيه، لخدمة أحمال عمل البحث المتجهي. ويرد توثيق تخطيط دفقه أثناء النقل (دفقات مستويات بتات FixedString مرتبة حسب المجموعة أولاً، وعددها element_size * (N / stride) عند تحديد stride صراحةً) وترميزه الثنائي للنوع (الوسم 0x36، أو 0x37 QBitWithStride عندما يكون stride != N) في صفحة نوع البيانات QBit وفي المرجع الخاص بـالترميز الثنائي للأنواع، فلا يضطر قارئ Native إلى استخلاصها من شيفرة C++ المصدرية.

الأنواع ذات الإصدارات

تحمل الأنواع ذات الإصدارات، ضمن التمثيل المُرسَل عبر الاتصال، بادئةً تُحدِّد إصدار التسلسل وتُبيّن أيّ صيغة من صيغ الترميز تليها. وقد تستخدم أيضًا عدة تدفقات (كما هو الحال في الأنواع المركّبة). وفي تمثيل Native المُرسَل عبر الاتصال، تكون البادئة وأي قاموس مرتبطَين بكل كتلة على حدة، إذ لا تحتفظ هذه الأنواع بأي حالة تمتد عبر الكتل (راجع ملاحظة البادئة الخاصة بكل كتلة أدناه)؛ أما حالة التسلسل الممتدة عبر الكتل فلا توجد إلا في الدفق المخزَّن على القرص الخاص بـ MergeTree. هذه الأنواع أكثر تعقيدًا بكثير من الأنواع المركّبة ذات البنية الثابتة، ولذا يمكن للعميل الذي يستهدف استعلامات تحليلية بسيطة أن يؤجّل دعمها.

إصدار التسلسل: المفهوم

إصدار التسلسل هو رقم إصدار يُنقل ضمن البيانات المُرسَلة، ويكون خاصًا بكل نوع وبكل عمود، ويحدد أيّ صيغة من صيغ ترميز النوع يستخدمها المُرسِل. وهو أول ما يرد في بادئة الحالة الخاصة بالعمود، فتقرؤه أداة فك الترميز أولًا ثم توجّه بقية العمود إلى المحلّل المناسب. وهو يختلف عن إصدار البروتوكول:

البُعد	إصدار البروتوكول	إصدار التسلسل (هذا القسم)
النطاق	على مستوى الاتصال بأكمله	لكل نوع ولكل عمود
يُتفاوض عليه	نعم، أثناء المصافحة	لا — يكتبه المُرسِل ويقرؤه المُستقبِل
يتحكم في	الميزات المفعّلة على مستوى الحزمة	صيغة النقل المستخدمة لنوع واحد
إلزامي القراءة	نعم	نعم، لكل عمود ذي إصدار

تكتب معظم الأنواع ذات الإصدارات رقمَ الإصدار بصيغة UInt64 بترتيب little-endian مباشرةً قبل أي بيانات أخرى في بادئة الحالة، بينما يستخدم عدد قليل منها VarUInt أو UInt8. تقرأ أداة فك الترميز الإصدار أولًا وترفض القيم غير المعروفة؛ إذ يدل الإصدار الأعلى على صيغة أحدث لدى المُرسِل لا تفهمها أداة فك الترميز، وأي خطأ في تحليلها يُفسد كل البايتات التالية. تُرسَل بادئة الحالة في بداية كل كتلة يزيد عدد صفوفها على صفر، مباشرةً قبل حمولة تلك الكتلة. لا يحتفظ كاتب Native وقارئه بحالة التسلسل بين الكتل: إذ ينشئ NativeWriter حالة تسلسل جديدة ويكتب بادئة حالة لكل كتلة عمود غير فارغة يكتبها، وينشئ NativeReader حالة إلغاء تسلسل جديدة ويقرؤها لكل كتلة غير فارغة يقرؤها (ويتخطى كلاهما البادئة كليًا عندما يكون rows == 0). ولذلك لا تُرسِل كتل الترويسة (rows = 0) والكتل الفارغة أي شيء، ويجب على أداة فك الترميز أن تقرأ بادئة الحالة من جديد في بداية كل كتلة غير فارغة. أما أداة فك الترميز التي تقرأ البادئة مرة واحدة فقط وتعدّ الكتل اللاحقة حمولةً بلا بادئة، فستقرأ بادئة الكتلة التالية على أنها بيانات وتفقد التزامن:

مرجع إصدارات التسلسل

النوع	عرض الحقل	القيمة	الاسم	المعنى
Object (الأساس لـ JSON)	UInt64 LE	`0`	`V1`	الترميز الأصلي. يتضمن المعلمة `max_dynamic_paths` وقائمة بالمسارات الديناميكية.
		`1`	`STRING`	وضع التوافق مع صيغة Native — يُنقل Object على هيئة column `String` واحد يحتوي على نص JSON.
		`2`	`V2`	تخطيط V1 من دون المعلمة `max_dynamic_paths`.
		`3`	`FLATTENED`	وضع التوافق مع صيغة Native — تمثيل مسطّح للمسارات.
		`4`	`V3`	يُكتب في أجزاء بيانات MergeTree فقط، ولا يُرسل عبر الشبكة أبدًا؛ وتخطيطه غير محدَّد هنا.
Dynamic	UInt64 LE	`1`	`V1`	الترميز الأصلي. يتضمن `max_dynamic_types` وقائمة بالأنواع البديلة المحددة وقت التشغيل.
		`2`	`V2`	V1 من دون المعلمة `max_dynamic_types`.
		`3`	`FLATTENED`	وضع التوافق مع صيغة Native.
		`4`	`V3`	يُكتب في أجزاء بيانات MergeTree فقط، ولا يُرسل عبر الشبكة أبدًا؛ وتخطيطه غير محدَّد هنا.
وضع المميّزات في Variant	UInt64 LE	`0`	`BASIC`	يُكتب مميّز كل صف كما هو.
		`1`	`COMPACT`	إذا اشتركت جميع صفوف الحبيبة في مميّز واحد، فلا تُكتب سوى قيمة واحدة مع وسم الحبيبة.
صيغة الحبيبة في Variant (عندما يكون الوضع `COMPACT`)	UInt8	`0`	`PLAIN`	تحتوي الحبيبة على مميّزات غير متجانسة.
		`1`	`COMPACT`	تحتوي الحبيبة على مميّز واحد لجميع الصفوف.
تسلسل المفاتيح في LowCardinality	Int64	`1`	`sharedDictionariesWithAdditionalKeys`	الإصدار الوحيد المعرَّف حاليًا.
البديل الاحتياطي JSON-as-String (عند تفعيل `output_format_native_write_json_as_string`)	UInt64 LE	`1`	`JSONStringSerializationVersion`	يصل column JSON على هيئة column `String` تسبقه هذه البادئة.

ملاحظات جديرة بالانتباه حول هذا الجدول:

القيم ليست متتالية. يستخدم Dynamic القيم 1 و2 و3 و4، إذ تقابل V3 القيمة 4 وتقابل FLATTENED القيمة 3. فالرقم الأعلى لا يعني بالضرورة إصدارًا أحدث.
بعض القيم خاصة بصيغة Native فقط. توجد Object::STRING وObject::FLATTENED وDynamic::FLATTENED لضمان التوافق عبر البروتوكول الأصلي مع العملاء الذين لا يدعمون Object/Dynamic دعمًا كاملًا. ولا تظهر هذه القيم في التخزين على القرص في MergeTree.
V3 خاص بالتخزين على القرص فقط. أُدرج Object::V3 وDynamic::V3 لأن قيمتيهما مخصّصتان ولا يجوز إعادة استخدامهما، لا لأن أداة فك الترميز قد تصادفهما: فـClickHouse لا يرسلهما أبدًا عبر Native، بل يرفضهما فيه مع الخطأ INCORRECT_DATA. وكل ما يحملانه — الإصدار الفرعي لمنطقة shared-data في Object::V3 وتخطيطات الحاويات والحبيبات الخاصة به — يصف جزء بيانات لا كتلة، ولذلك يقع خارج نطاق هذه الصفحة. أما العملاء الذين يستهلكون بروتوكول TCP الأصلي فلا يرون سوى V1 أو V2 أو STRING أو FLATTENED.

LowCardinality(T)

أبسط الأنواع ذات الإصدارات، إذ يستبدل column مكوّنًا من N من القيم الداخلية بقاموس صغير من القيم المميزة، إضافةً إلى N من الفهارس التي تشير إلى هذا القاموس. سلسلة النوع: LowCardinality(InnerType). أمثلة: LowCardinality(String)، LowCardinality(FixedString(4))، LowCardinality(Nullable(String)).

[per block with rows > 0]:
  [8 bytes:  Int64 LE state prefix = 1]             ← repeated at the start of every non-empty block
  [8 bytes:  UInt64 LE metadata]                    ← key type code (low byte) + flag bits
  [8 bytes:  UInt64 LE dict_size]                   ← number of dict entries (incl. placeholder slot)
  [N bytes:  dict values]                           ← inner type's encoding for dict_size values
  [8 bytes:  UInt64 LE keys_count]                  ← number of values at this recursive level (see below)
  [K bytes:  keys]                                  ← (1 << key_type_code) bytes per key

بادئة الحالة (Int64 LE = 1) هي الإصدار الوحيد المعرَّف، sharedDictionariesWithAdditionalKeys؛ أما القيم الأخرى فمحجوزة. البيانات الوصفية لكل كتلة من نوع UInt64، وهي حقل بتات:

نطاق البتات	المعنى
0..7	رمز نوع المفتاح: `0` = UInt8، `1` = UInt16، `2` = UInt32، `3` = UInt64. ويُختار أصغر نوع يكفي لفهرسة `dict_size` من الإدخالات.
8 (`0x100`)	`NeedGlobalDictionaryBit` — قاموس واحد مشترك بين الكتل. لا يُضبط أبدًا في صيغة `Native`: إذ يستخدم Native writer الإعداد `low_cardinality_max_dictionary_size = 0`، ويرفض Native reader هذا البت (يُطلق `native_format` الخطأ `INCORRECT_DATA` — “cannot use global dictionary”). فهذا البت خاص بدفق MergeTree على القرص، لا بتنسيق النقل.
9 (`0x200`)	`HasAdditionalKeysBit` — يُضبط عندما تحمل الكتلة مفاتيح قاموس إضافية (تُكتب قبل الفهارس). ويكون مضبوطًا دائمًا في أي كتلة `Native` غير فارغة.
10 (`0x400`)	`NeedUpdateDictionary` — يُضبط عندما تحمل الكتلة تحديثًا للقاموس. ويكون مضبوطًا دائمًا في أي كتلة `Native` غير فارغة، لأن كل كتلة تحمل قاموسها المستقل الخاص بها.

في الاستجابة المعتادة لاستعلام يتضمن كتلة بيانات واحدة لكل column، تكون قيمة البيانات الوصفية 0x600 (HasAdditionalKeys + NeedUpdateDictionary). قيم القاموس هي dict_size قيمةً مُرمَّزة باستخدام النوع الداخلي T. ويحجز القاموس الخانات الأولى للقيم الخاصة: فالـ column غير القابل للقيم الفارغة يحجز خانة واحدة (تحتوي dict[0] على القيمة الافتراضية للنوع الداخلي، مثل "" في حالة String)، وتبدأ القيم المميزة الفعلية من dict[1]. أما في حالة LowCardinality(Nullable(T)) فيظل القاموس مُرمَّزًا بالنوع T العادي (دون دفق null-map)، لكن تُحجز خانتان اثنتان: dict[0] هي وسم NULL وdict[1] هي القيمة الافتراضية للنوع الداخلي (مثل "" في حالة String)؛ وتبدأ القيم المميزة الفعلية من dict[2]. ويشير مفتاح الصف ذي القيمة NULL إلى dict[0]، وتُكتب تلك الخانة في تنسيق النقل بالبايتات الافتراضية للنوع الداخلي. المفاتيح فهارس تشير إلى مواضع في القاموس؛ وحجم كل فهرس 1 << key_type_code بايت (1 أو 2 أو 4 أو 8)، وتُعاد بناء القيمة N بوصفها dict[keys[N]]. يمثل keys_count عدد قيم LowCardinality في المستوى التعاودي الحالي، وليس بالضرورة عدد صفوف الكتلة. ففي column LowCardinality على المستوى الأعلى يتساوى العددان. أما عندما يكون LowCardinality متداخلًا ضمن نوع مركّب، فإن العدد هو عدد القيم المسطّحة الذي يمرّره النوع المركّب إلى المستوى الأدنى: ففي Array(LowCardinality(String)) بثلاثة صفوف تضم خمسة عناصر إجمالًا، تكون قيمة keys_count هي 5 لا 3؛ وفي Map(K, LowCardinality(V)) تساوي إجمالي عدد الأزواج، وهكذا. ويجب على أداة فك الترميز أن تأخذ keys_count من هذا الحقل بدلًا من افتراض أنه يساوي عدد صفوف الكتلة. وعندما يكون هذا العدد المسطّح صفرًا — كما في كتلة جميع مصفوفاتها فارغة — فإن مرحلة بيانات LowCardinality لا تكتب شيئًا على الإطلاق: إذ لا توجد سوى بادئة الحالة (المُصدَرة في مرحلة البادئة للأنواع المركّبة)، دون أن تليها بيانات وصفية أو قاموس أو keys_count. تُقرأ بادئة الحالة في بداية كل كتلة يزيد عدد صفوفها على صفر، أما كتل الترويسة (rows = 0) والكتل الفارغة فلا يُكتب لها شيء. وداخل الكتلة، تساوي قيمة keys_count عدد الصفوف، وتساوي قيمة dict_size عدد القيم في دفق القاموس، ويشغل كل مفتاح 1 << key_type_code بايت.

في صيغة Native، تحمل كل كتلة قاموسًا مستقلًا خاصًا بها — إذ لا توجد حالة قاموس مشتركة بين الكتل. يضبط Native writer القيمة low_cardinality_max_dictionary_size = 0، ولذلك لا ينشئ SerializationLowCardinality قاموسًا مشتركًا أبدًا: فكل كتلة غير فارغة تكتب مفاتيحها بوصفها مفاتيح إضافية خاصة بالكتلة دون ضبط NeedGlobalDictionaryBit (البيانات الوصفية 0x600)، ويرفض Native reader البت NeedGlobalDictionaryBit عندما تكون قيمة native_format هي true. لذا يجب على أداة فك الترميز إعادة تعيين القاموس عند كل كتلة وقراءة عناصر dict_size الموجودة في تلك الكتلة؛ إذ إن الإبقاء على قاموس من كتلة سابقة سيؤدي إلى قراءة مفاتيح الكتلة التالية قراءةً خاطئة. (الاحتفاظ بقاموس LC عبر الكتل مسألة تخص تخزين MergeTree على القرص، ولا علاقة لها بتخطيط wire لصيغة Native.)

LowCardinality(String) مع القيم ['a', 'b', 'a', 'c', 'b']:

00 00 00 00 00 00 00      state prefix Int64 = 1
06 00 00 00 00 00 00      metadata UInt64 = 0x600
00 00 00 00 00 00 00      dict_size = 4
                         dict[0] = "" (placeholder)
'a'                       dict[1] = "a"
'b'                       dict[2] = "b"
'c'                       dict[3] = "c"
00 00 00 00 00 00 00      keys_count = 5
02 01 03 02               keys (UInt8): 1, 2, 1, 3, 2

إعادة البناء: dict[1], dict[2], dict[1], dict[3], dict[2] = ["a", "b", "a", "c", "b"]. يُظهر النوع LowCardinality(Nullable(String)) مع القيم ['a', NULL, '', 'b'] الخانتين المحجوزتين كلتيهما — dict[0] لقيمة NULL، وdict[1] للقيمة الافتراضية المتمثلة في الـ string الفارغ:

00 00 00 00 00 00 00      state prefix Int64 = 1
06 00 00 00 00 00 00      metadata UInt64 = 0x600
00 00 00 00 00 00 00      dict_size = 4
                         dict[0] = "" → NULL marker
                         dict[1] = "" → inner default value
'a'                       dict[2] = "a"
'b'                       dict[3] = "b"
00 00 00 00 00 00 00      keys_count = 4
00 01 03                  keys (UInt8): 2, 0, 1, 3

بعد إعادة البناء: dict[2] = "a"، وdict[0] = NULL، وdict[1] = ""، وdict[3] = "b"، أي ["a", NULL, "", "b"]. وكلٌّ من dict[0] وdict[1] بايتاتٌ فارغة في تنسيق النقل؛ فكون القيمة NULL ناتجٌ عن إشارة المفتاح إلى الخانة 0، لا عن البايتات نفسها.

JSON (Tier 1: String fallback)

يدعم النوع JSON في ClickHouse عدة أشكال من ترميز wire (راجع مرجع إصدارات التسلسل). ويُعد Tier 1 أبسطها: فعند ضبط إعداد الاستعلام output_format_native_write_json_as_string = 1، يحوّل الخادم كل قيمة JSON إلى تمثيلها النصي المُسلسَل، ويُخرج الـ column من النوع String مسبوقًا بوسم الحالة. سلسلة النوع: JSON.

[8 bytes:  Int64 LE state prefix = 1]        ← JSONStringSerializationVersion
[per block with rows > 0]:
  [N bytes: String column encoding for num_rows JSON text values]

قيمة بادئة الحالة في وضع String fallback هذا هي 1. أما القيم الأخرى فتشير إلى ترميزات مختلفة لـ JSON/Object: 0 = V1، و2 = V2 (الترميز الافتراضي عبر بروتوكول TCP الأصلي)، و3 = FLATTENED، و4 = V3 (راجع مرجع إصدارات التسلسل). فإذا صادفت أداة فك الترميز هنا قيمة غير 1، فهذا يعني أن البيانات التي تعالجها ليست بصيغة String fallback. تُقرأ البادئة في بداية كل كتلة يزيد عدد صفوفها على 0، أما دفق القيم فهو column قياسي من نوع String يضم num_rows صفًا. قيمة JSON هي '{"a":1}' (صف واحد):

01 00 00 00 00 00 00 00      state prefix Int64 = 1
07 7B 22 61 22 3A 31 7D      String: 7 bytes {"a":1}

تُرسَل القيمة في صورة نص JSON مضغوط — {"a":1}، مع إبقاء العدد الصحيح عددًا صحيحًا. ولأن هذا النص مجرد قيمة من النوع String، يتلقى العميل JSON لتمريره كما هو دون تفسير محتواه، لكنه لا يستعيد المسارات الفردية وأنواع ClickHouse الخاصة بها؛ فالحفاظ الدقيق على نوع كل مسار يتطلب استخدام ترميز Tier 2 الموضح أدناه.

Variant(T1, T2, …)

اتحاد مُميَّز: يحمل كل صف قيمةً من نوع واحد فقط من الأنواع البديلة، أو NULL. ويحمل كل صف مميّزًا عامًا بحجم بايت واحد يحدد نوعه، ثم تُخزَّن القيم الخاصة بكل نوع بشكل متراص، بحيث يُخصَّص لكل نوع بديل تتابع واحد متصل. سلسلة النوع: Variant(T1, T2, ...). يُوحِّد الخادم الترتيب إلى صيغته القياسية (إذ تُرتَّب الأنواع البديلة حسب الاسم)، ولذلك تأتي سلسلة النوع المستقبَلة وقد سُردت فيها الأنواع وفق ترتيب المميّز العام: فالمميّز 0 يختار النوع الأول في القائمة، و1 يختار النوع الثاني، وهكذا. أما 255 (NULL_DISCRIMINATOR) فيعني أن قيمة الصف NULL. لا تكون عناصر Variant من النوع Nullable أبدًا، لأن تمثيل NULL من مهام المميّز. أمثلة: Variant(String, UInt64)، Variant(Array(UInt8), String). تحمل بادئة الحالة وضع المميّزات بصيغة UInt64 LE: القيمة 0 = BASIC (يُكتب مميّز كل صف كما هو)، والقيمة 1 = COMPACT (ترميز الحبيبات بطول التتابع). يستخدم الخادم افتراضيًا الوضع BASIC عبر البروتوكول الأصلي (use_compact_variant_discriminators_serialization = false)، ولا يتناول هذا المستند سوى الوضع BASIC.

[per block with rows > 0]:
  [8 bytes:  UInt64 LE discriminators mode = 0]    ← state prefix, repeated at the start of every non-empty block;
                                                     followed by each variant element's own state prefix
                                                     (empty for leaf types)
  [num_rows bytes: UInt8 discriminators]           ← one global discriminator per row; 255 = NULL
  [for each variant type i, in declared order]:
    [values for the rows whose discriminator == i] ← dense encoding in type i; count = #rows selecting i

لإعادة البناء، اجتز المميّزات من اليسار إلى اليمين مع الاحتفاظ بعدّاد تراكمي لكل نوع. يأخذ الصف r ذو المميّز d (≠ 255) القيمة الموجودة عند الفهرس counter[d] من سلسلة قيم النوع البديل d، ثم يُزاد counter[d] بمقدار واحد. أما الصفوف ذات المميّز 255 فهي NULL ولا تستهلك أي قيمة من أي سلسلة، ولذلك يساوي مجموع العدّادات الخاصة بالأنواع عددَ الصفوف غير NULL. تُقرأ بادئة الحالة (وهي قيمة UInt64 الخاصة بالوضع) في بداية كل كتلة يزيد عدد صفوفها على 0؛ أما كتل الترويسة والكتل الفارغة فلا تُصدر شيئًا. ويكون كل مميّز غير NULL أصغر من عدد الأنواع البديلة، ويُفكّ ترميز النوع البديل i لعدد count[i] من الصفوف بالضبط.

عناصر Variant التي تكون هي نفسها ذات حالة (LowCardinality وVariant وDynamic وJSON) تُصدر بادئة الحالة الخاصة بها في مرحلة بادئة الحالة الخاصة بكل عنصر، بعد قيمة UInt64 الخاصة بالوضع. أما الأنواع الطرفية والأنواع المركّبة البسيطة (Array وTuple وMap المكوّنة من أنواع طرفية) فبادئات حالتها فارغة، ويمكن تركيبها بحرية.

Variant(String, UInt64) بالقيم [42, 'hi', NULL] (يضع الترتيب القياسي String قبل UInt64، ولذلك فإن المميّز 0 = String، و1 = UInt64):

00 00 00 00 00 00 00      state prefix: UInt64 discriminators mode = 0 (BASIC)
00 FF                     discriminators (3 rows): 1 (UInt64), 0 (String), 255 (NULL)
68 69                     String run (1 value): len=2 "hi"
2A 00 00 00 00 00 00 00      UInt64 run (1 value): 42

إعادة البناء: الصف 0 = UInt64 run[0] = 42؛ الصف 1 = String run[0] = "hi"؛ الصف 2 = NULL. يؤدي دفق المميّزات دور الفهرس؛ إذ يسحب كل مميّز غير NULL القيمة التالية من التسلسل الكثيف الخاص بنوعه، في حين لا يستهلك 255 (NULL) أي قيمة. وبالطريقة نفسها يُعاد بناء Dynamic، الذي لا يختلف إلا في كيفية ترميز NULL:

مميّزات تختار القيم من تسلسلات كثيفة خاصة بكل نوع

Dynamic

column يُكتشف نوع قيمته في وقت التشغيل: يحتوي كل صف على قيمة من أحد أنواع مجموعةٍ تُحدَّد في وقت التشغيل، أو على NULL. وعلى خلاف Variant، فإن مجموعة الأنواع ليست جزءًا من سلسلة النوع الخاصة بالـ column — بل تُحمَل في بادئة الحالة. سلسلة النوع: Dynamic أو Dynamic(max_types=N). تحدّد المعلمة max_types الحد الأقصى لعدد الأنواع المميزة التي يتتبعها الـ column، لكنها لا تؤثر في تنسيق wire الموضّح أدناه. لـ Dynamic أربعة أشكال ترميز: V1 = 1، وV2 = 2، وFLATTENED = 3، وV3 = 4. ويتوقف الشكل الذي يُصدره الخادم على القناة وعلى إعدادات الاستعلام:

عبر clickhouse-client وFORMAT Native في HTTP، تكون قيمة revision لدى الكاتب 0 (ما لم تُرفع باستخدام client_protocol_version)، ولذلك يكون الشكل الافتراضي V1.
عبر بروتوكول TCP الأصلي عند قيمة revision المتفاوض عليها، يكون الشكل الافتراضي V2. يُبقي كاتب Native الإحصاءات معطّلة، لذا لا تحمل حمولة V2 الافتراضية أي إحصاءات لكل نوع، إذ تلي قائمةَ الأنواع مباشرةً بادئةُ Variant المتداخلة ثم البيانات. (الإحصاءات لكل نوع شأن يخص تخزين MergeTree على القرص، وليست جزءًا من تنسيق wire الخاص بـ Native.)
يتجاوز إعداد الاستعلام output_format_native_use_flattened_dynamic_and_json_serialization = 1 كلتا الحالتين، ويُصدر FLATTENED (الإصدار 3) بصرف النظر عن قيمة revision.

النطاقتقتصر هذه الصفحة على توصيف التخطيط FLATTENED. أما التخطيطات الثنائية غير المسطّحة V1/V2/V3 فهي التمثيل الداخلي/المخزّن على القرص (قوائم أنواع مُرمَّزة ثنائيًا، وإحصاءات لكل نوع)، ولا تُوصَف هنا. ويجب على العميل الذي يريد فك ترميز Dynamic استنادًا إلى هذه الصفحة أن يطلب FLATTENED عبر ضبط output_format_native_use_flattened_dynamic_and_json_serialization = 1؛ إذ يفترض التخطيط أدناه تفعيل هذا الإعداد. ولأن بايت الإصدار يتصدّر البادئة، تستطيع أداة فك الترميز اكتشاف الترميز الفعلي الذي تلقّته، ورفض V1/V2/V3 إن كانت لا تدعم سوى FLATTENED.

تخطيط FLATTENED (الإصدار 3) الذي يُفعّله ذلك الإعداد:

[per block with rows > 0]:
  [8 bytes:  UInt64 LE version = 3]                ← state prefix, repeated at the start of every non-empty block
  [VarUInt num_types]                              ← number of runtime types
  [num_types × type]                               ← type names, in wire order; each a String, or a binary
                                                     type encoding when output_format_native_encode_types_in_binary_format = 1,
                                                     except for a secondary query (see the type field note)
  [per type: its own state prefix]                 ← empty for leaf types; + indexes-type prefix (empty, integer)
  [num_rows × discriminator]                       ← width by num_types (UInt8 if ≤ 255, else UInt16/32/64);
                                                     NULL discriminator = num_types (one past the last type)
  [for each type i, in wire order]:
    [values for the rows whose discriminator == i] ← dense encoding in type i

عرض المميّز هو أصغر عدد صحيح بلا إشارة يتّسع لفهرسة num_types من الأنواع إضافةً إلى خانة NULL — أي UInt8 عندما يكون num_types ≤ 255، ثم UInt16، ثم UInt32، ثم UInt64. وتُمثَّل NULL بقيمة المميّز num_types نفسها، بخلاف Variant حيث تُمثَّل NULL بالقيمة الثابتة 255. أما إعادة البناء فتتم بالمرور الكثيف نفسه المتّبع في Variant: احتفظ بعدّاد لكل نوع، فيأخذ الصف r ذو المميّز d (≠ num_types) القيمة counter[d] من تتابع قيم النوع d. تُقرأ بادئة الحالة (الإصدار + قائمة الأنواع) في بداية كل كتلة يكون عدد صفوفها > 0؛ أما كتل الترويسة والكتل الفارغة فلا تُصدر شيئًا.

عدد مشوّهتُقرأ قيمة num_types من الدفق قبل أي أسماء أنواع. ويجب على أداة فك الترميز أن تعاملها على أنها غير موثوقة، وألّا تستخدمها مباشرةً لتحديد حجم تخصيص الذاكرة — سواء كان العدد قريبًا من SIZE_MAX (مما قد يسبب تجاوزًا في العمليات الحسابية الوسيطة أو يُطلق استثناءً من غير نوع DB::Exception)، أو كان عددًا كبيرًا لكنه قابل للتمثيل مثل 100000000 (وهو أقل بكثير من max_size() الخاص بالمتجه، لكنه سيخصّص جيجابايتات من الذاكرة قبل قراءة اسم نوع واحد). يقرأ ClickHouse قائمة الأنواع عنصرًا تلو الآخر، ولا يستخدم سوى تلميح تخصيص مسبق محدود السقف، لذا تُرفض قيمة num_types التالفة إما بالخطأ INCORRECT_DATA (“Dynamic column has too many types”، عندما يتجاوز العدد ما تستطيع الحاوية استيعابه)، أو كخطأ قراءة عادي حين تنفد عناصر الأنواع من الدفق — ولا تُرفض أبدًا بسبب نفاد الذاكرة.لكن لا تقيّد قيمة num_types المسطّحة بالحد ColumnDynamic::MAX_DYNAMIC_TYPES_LIMIT (وقيمته 254 في ClickHouse): إذ تضم قائمة الأنواع المسطّحة كل نوع وقت تشغيل مميّز، بما في ذلك الأنواع التي فاضت إلى المتغيّر المشترك، لذا قد تسرد كتلة مسطّحة صالحة عددًا يفوق ذلك بكثير دون أن يكون ذلك خطأً. ولا ينطبق الحد MAX_DYNAMIC_TYPES_LIMIT إلا على العدد num_dynamic_types في البادئات غير المسطّحة V1/V2/V3، وهو عدد خانات المتغيّرات العادية المقيّد بهذا الحد (يتحقق منه ClickHouse هناك قبل إضافة + 1 الخاصة بالمتغيّر المشترك).

الدفقات المقتطعةتحتوي سلسلة المميّزات على num_rows عنصرًا بالضبط، ويجب على أداة فك الترميز التحقق من أنها قرأت هذا العدد كاملًا بدلًا من قبول ما يتضمنه الدفق أيًّا كان. فالسلسلة الأقصر لا تتعارض مع أي شيء يليها: إذ تُشتق عدّادات القيم لكل نوع من المميّزات المقروءة فعليًا، فتبقى متّسقة مع سلاسل القيم، كما أن السلسلة المكوّنة بالكامل من وسوم NULL لا تتطلب أي بايتات قيم على الإطلاق. ولهذا يرفض ClickHouse سلسلة المميّزات القصيرة بالخطأ INCORRECT_DATA (“Mismatch in flattened Dynamic column: N rows are expected, but the indexes stream contains only M rows”) قبل أي فحص خاص بكل نوع، لأن الـ column المُعاد بناؤه سيُستخدم حينها على أنه يضم num_rows من الصفوف بغض النظر عن حجمه الفعلي.

تحمل أنواع وقت التشغيل ذات التسلسل الحافظ للحالة (LowCardinality وVariant وDynamic وJSON) بادئات حالة متداخلة بعد قائمة أسماء الأنواع.

تتبع قائمة أنواع وقت التشغيل عادةً التوحيد القياسي الخاص بـ Variant — إذ تُكتب خانات المتغيّرات العادية بترتيب DataTypeVariant (حسب اسم النوع)، فلا يطابق ترتيب الإرسال ترتيب الإدراج. غير أنها ليست دائمًا مرتّبة ترتيبًا شاملًا: فالأنواع التي فاضت إلى المتغيّر المشترك (كما في حالة Dynamic(max_types=N) مثلًا) تُضاف بعد الخانات العادية بحسب ترتيب ظهورها الأول، مما قد يُخلّ بترتيب أسماء الأنواع في ذيل القائمة. لذلك يجب على أداة فك الترميز أن تعتمد قائمة الأنواع المُرسلة مرجعًا لتعيين المميّزات، وألّا تعيد ترتيبها بنفسها. أما ما لا يجوز أن تحتويه القائمة فهو نوع مكرّر أو Nothing: فالعنصران المتساويان يُعيَّنان إلى مميّز واحد، وNothing ليس متغيّرًا أصلًا، وفي كلتا الحالتين لا يبقى لجزء من القائمة موضع يُعاد بناؤه فيه. ويرفض ClickHouse كلتا الحالتين بالخطأ INCORRECT_DATA. فمثلًا، في الصفوف [42::UInt64, "hi", NULL] يكون النوعان هما String وUInt64، ويسبق "String" القيمة "UInt64" في الترتيب، لذا تكون المميّزات 0 = String و1 = UInt64 و2 = NULL:

00 00 00 00 00 00 00      state prefix: UInt64 version = 3 (FLATTENED)
                         VarUInt num_types = 2
53 74 72 69 6E 67         type[0] = "String"
55 49 6E 74 36 34         type[1] = "UInt64"
00 02                     discriminators (3 rows): 1 (UInt64), 0 (String), 2 (NULL)
68 69                     String run (type[0], 1 value): len=2 "hi"
2A 00 00 00 00 00 00 00      UInt64 run (type[1], 1 value): 42

بعد إعادة البناء: الصف 0 = UInt64 run[0] = 42؛ الصف 1 = String run[0] = "hi"؛ الصف 2 = NULL. تتبع السلاسل الخاصة بكل نوع ترتيبَ التسلسل الثنائي نفسه المتبع في قائمة الأنواع (String قبل UInt64).

JSON (Tier 2: FLATTENED Object)

هذا هو الترميز الأغنى لـ JSON: فبدلًا من تسطيح كل قيمة وتحويلها إلى نص (Tier 1)، يُقسَّم الـ column إلى columns فرعية، column فرعي لكل مسار JSON. ويُختار هذا الترميز عبر عدم طلب الحل البديل الخاص بـ Tier 1 (output_format_native_write_json_as_string = 0) مع تفعيل علامة التسلسل المسطّح (output_format_native_use_flattened_dynamic_and_json_serialization = 1)؛ وعندها يُصدر الخادم التسلسل بالإصدار 3. هناك نوعان من المسارات:

المسارات محددة النوع: تُعرَّف في سلسلة النوع، مثل JSON(a UInt32, b String)، ويُفك ترميزها وفق النوع المُعرَّف لها. ويُحاط اسم المسار الذي يحتوي على نقاط بعلامات backtick في سلسلة النوع.
المسارات الديناميكية: تُكتشف أثناء وقت التشغيل، ويُفك ترميز كل منها بوصفه column من نوع Dynamic.

في وضع FLATTENED لا يوجد column shared-data (إذ يخص مخزن الفائض هذا ترميزات Object غير المسطّحة V2/V3). وكل مسار هو column كامل يضم num_rows من القيم.

[per block with rows > 0]:
  -- prefix phase (repeated at the start of every non-empty block):
  [8 bytes:  UInt64 LE version = 3]                ← state prefix
  [VarUInt num_dynamic_paths]
  [num_dynamic_paths × String]                     ← dynamic path names, in wire order
  [per typed path: its column's state prefix]      ← empty for leaf types
  [per dynamic path: a Dynamic state prefix]       ← version + type list (see Dynamic)
  -- data phase:
  [for each typed path:   its column's data]       ← num_rows values in the declared type
  [for each dynamic path: its Dynamic data]        ← num_rows values (discriminators + runs)

لاحظ البنية ثنائية المراحل: تأتي جميع بادئات الحالة للمسارات أولاً، ثم جميع بيانات المسارات. ومن ثَمّ تكون بادئة Dynamic الخاصة بالمسار الديناميكي (في مرحلة البادئة) منفصلةً عن بياناته (في مرحلة البيانات). تُقرأ بادئة الحالة في بداية كل كتلة يزيد عدد صفوفها على 0، ويحتوي كل column مسار (مُحدَّد النوع أو ديناميكي) على num_rows قيمة بالضبط. يُجمَّع كائن الصف r بقراءة قيمة كل مسار عند الفهرس r؛ أما المسار الديناميكي الذي يكون مميّز Dynamic الخاص به NULL في ذلك الصف فلا يُضيف أي مفتاح. يجب أن تكون أسماء المسارات الديناميكية فريدة، ولا يجوز أن يكرر أيٌّ منها مسارًا صرّحت به سلسلة النوع مسبقًا على أنه مُحدَّد النوع — إذ يؤدي كلا الأمرين إلى وجود قيمتين تحت مفتاح واحد في الكائن المُجمَّع، ولذلك يرفض ClickHouse الحالتين كلتيهما بالخطأ INCORRECT_DATA. وينطبق الأمر نفسه على قائمة المسارات الديناميكية في الترميزات غير المسطّحة.

أعداد مشوّهةيُقرأ num_dynamic_paths في تخطيط FLATTENED الموثَّق هنا — وكذلك عدد المسارات الديناميكية في الترميزين غير المسطّحين V1/V2 — من الدفق قبل أسماء المسارات. (لا يوجد حقل مستقل للمسارات المسطّحة في بادئات الترميزات غير المسطّحة: فهي لا تحمل سوى عدد المسارات الديناميكية، إضافةً إلى قيمة max_dynamic_paths في V1 تُقرأ ثم تُهمَل.) وكما هو الحال مع Dynamic، يجب على أداة فك الترميز أن تعدّ هذه الأعداد غير موثوقة، وألا تعتمد عليها مباشرةً في تحديد حجم أي تخصيص للذاكرة — سواء كان العدد من فئة SIZE_MAX أو عددًا كبيرًا لكنه قابل للتمثيل. يقرأ ClickHouse أسماء المسارات إدخالًا تلو الآخر، مكتفيًا بتلميح تخصيص مسبق ذي حد أقصى، لذا يُرفض العدد التالف إما بالخطأ INCORRECT_DATA (“JSON/Object column has too many paths”، عندما يتجاوز ما تستطيع الحاوية استيعابه) أو بخطأ قراءة عادي عند نفاد أسماء المسارات من الدفق.

دفقات مقتطعةتُعدّ قيم num_rows لكل column مسار شرطًا إلزاميًا لا حدًا أعلى: يجب على أداة فك الترميز أن تتحقق من مطابقة كل column مسار، مُحدَّد النوع كان أو ديناميكيًا، لعدد صفوف الكتلة، بدلًا من الوثوق بأن الدفق سينتهي في موضعه الصحيح. فليس للكائن المُجمَّع حجم مستقل يمكن المقارنة به — إذ إن عدد صفوفه هو ببساطة ما تنتجه عملية إلغاء التسطيح — لذا يتعذّر لاحقًا اكتشاف column المسار الناقص، وتتجاوز قراءةُ الصف r منه نهايتَه. يرفضه ClickHouse بالخطأ INCORRECT_DATA (“Unexpected size of typed path / flattened path p in flattened Object column”). وفي حالة المسار الديناميكي، يأتي هذا التحقق إضافةً إلى التحقق المكافئ داخل column Dynamic الخاص به.

قيمة JSON هي {"a": 42, "b": "hi"} (صف واحد، وكلا المسارين ديناميكيان). يُستنتج نوع العدد الصحيح في JSON على أنه Int64:

00 00 00 00 00 00 00      version = 3 (Object)
                         num_dynamic_paths = 2
61                        path "a"
62                        path "b"
00 00 00 00 00 00 00 01 05 49 6E 74 36 34      "a" Dynamic prefix: version 3, 1 type, "Int64"
00 00 00 00 00 00 00 01 06 53 74 72 69 6E 67   "b" Dynamic prefix: version 3, 1 type, "String"
2A 00 00 00 00 00 00 00   "a" data: discriminator 0, Int64 42
02 68 69                  "b" data: discriminator 0, String "hi"

JSON غير المسطّح (V1/V2)

ترميزات Object غير المسطّحة هي ما يُرسله الخادم عبر الشبكة عندما تكون علامة التسطيح معطّلة: إذ يُستخدم V1 عبر clickhouse-client / HTTP FORMAT Native (revision 0)، ويُستخدم V2 عبر بروتوكول TCP الأصلي. (أما V3، وهو الترميز الثالث غير المسطّح، فلا يُكتب إلا في أجزاء بيانات MergeTree، ويُرفض عند نقله عبر الشبكة.) تتضمن هذه الترميزات عمود بيانات مشتركة (shared-data)، ولا تتناولها هذه الصفحة. لاحظ أنها لا تتضمن إحصاءات لكل مسار عند النقل بصيغة Native: إذ يُبقي NativeWriter الإحصاءات معطّلة، فلا تحتوي بادئة البنية الخاصة بـ Object على قسم للإحصاءات، وتليها مباشرةً بايتات البادئات والبيانات الخاصة بالمسارات محددة النوع (typed) والديناميكية (dynamic) والبيانات المشتركة (shared-data). ولا تظهر الإحصاءات إلا في مسارات MergeTree على القرص التي تُفعّلها. ولفك ترميز عمود JSON اعتمادًا على هذه الصفحة، يجب على العميل اختيار أحد المستويات الموثّقة: عيّن output_format_native_write_json_as_string = 1 لاستخدام الرجوع إلى String، أو output_format_native_use_flattened_dynamic_and_json_serialization = 1 (مع output_format_native_write_json_as_string = 0) لاستخدام تخطيط FLATTENED Object.

إطار الضغط

يستطيع ClickHouse ضغط بيانات الأعمدة في دفق Native باستخدام صيغة إطار داخلية. وتخطيط الإطار الموضح أدناه مستقل عن وسيلة النقل، إذ تظهر الإطارات نفسها في بروتوكول TCP الأصلي وعبر HTTP على حد سواء، غير أن طريقة طلب الضغط وما يحيط بالإطارات يختلفان باختلاف وسيلة النقل.

بروتوكول TCP الأصلي. الضغط اختياري ويُفعَّل لكل استعلام على حدة عبر العلامة compression في حزمة الاستعلام. وعند تفعيله، يُغلَّف متن كل حزمة من الحزم Data وTotals وExtremes وLog وProfileEvents، أي البايتات التي تلي سلسلة table_name، بصيغة الإطار. أما غلاف الحزمة نفسه، المؤلف من رمز نوع الحزمة وسلسلة table_name، فهو غير مضغوط، إذ يكتبهما الخادم في الدفق الخام. وكل ما يُصدره NativeWriter يدخل في الدفق المضغوط، ولذا تكون البادئة BlockInfo أول ما يرد داخل الإطار، إلى جانب الأبعاد والأعمدة. ومن ثَمّ يجب على العميل فك ضغط الإطار قبل أن يتمكن من قراءة BlockInfo.
HTTP. يُغلِّف SELECT ... FORMAT Native&compress=1 دفق بايتات FORMAT Native بأكمله بالإطارات نفسها (إذ يستخدم الخادم CompressedWriteBuffer الداخلي ذاته)، ويتوقع ?decompress=1 الإطارات نفسها في متن إدخال بصيغة Native، فيفك ترميزها عبر CompressedReadBuffer المقابل. ولا وجود في هذا المسار لنوع حزمة TCP ولا لـ table_name ولا لغلاف الحزمة، فالحمولة المضغوطة بأكملها ليست سوى كتل Native مؤطَّرة (ولا تظهر البادئة BlockInfo إلا إذا كانت قيمة revision المتفاوض عليها أكبر من 0، تمامًا كما في التخطيط غير المضغوط أعلاه). ويختلف هذا التأطير الداخلي compress/decompress عن ضغط النقل في HTTP (Content-Encoding: gzip/zstd، المُفعَّل عبر enable_http_compression)، الذي يُغلِّف الاستجابة على مستوى طبقة HTTP ولا علاقة له بصيغة الإطار الموضحة أدناه.

وعليه، فإن العميل الذي لم ينفّذ سوى تخطيط FORMAT Native غير المضغوط لا بد له من إضافة طبقة الإطار هذه كي يتمكن من قراءة استجابة Native مضغوطة عبر HTTP، أو من إرسال متن طلب مع decompress=1.

صيغة الإطار

[16 bytes: CityHash128 checksum over the 9-byte header + compressed body]
[1 byte:   method]                 ← 0x82 = LZ4, 0x90 = ZSTD, 0x02 = NONE
[4 bytes:  compressed_size LE u32] ← INCLUDES the 9-byte header, EXCLUDES the 16-byte checksum
[4 bytes:  uncompressed_size LE u32]
[N bytes:  compressed body]        ← N = compressed_size - 9

يبلغ الحجم الإجمالي للإطار 16 + compressed_size = 16 + 9 + body_size = 25 + body_size. لاحظ وجود نطاقين مختلفين: تغطي قيمة التحقق الترويسة البالغة 9 بايتات إضافةً إلى المتن، بينما يشمل compressed_size الترويسة والمتن دون قيمة التحقق نفسها:

قيم بايت الطريقة

هذه المرمِّزات الثلاثة هي التي يُنتجها الخادم عند تأطير Native للدفق بأكمله: يستخدم إخراج HTTP مع compress=1 المرمِّز الافتراضي للخادم (ZSTD(3))، بينما يستخدم بروتوكول TCP الأصلي أحد المرمِّزات LZ4 أو ZSTD أو NONE بحسب قيمة network_compression_method. ولا يحتاج أي عميل Native عام إلا إلى إنتاج هذه المرمِّزات واستهلاكها.

البايت	الطريقة	ترميز المتن
`0x02`	NONE	المتن هو البايتات الخام (دون ضغط). ومع ذلك يُصدَر الإطار، ويتحقق المُستقبِل من قيمة التحقق.
`0x82`	LZ4	المتن بـصيغة كتلة LZ4 — وليس بصيغة إطار LZ4. ولا يتضمن رقمًا سحريًا.
`0x90`	ZSTD	المتن دفق zstd خام بإطار واحد (الرقم السحري القياسي لـ zstd جزء من المتن).

يُرمِّز بايت الطريقة أيضًا المرمِّزات على مستوى العمود. تُطبَّق هذه المرمِّزات على كل عمود على حدة في مسارات MergeTree على القرص، لا على تأطير الدفق بأكمله، غير أن مسار إدخال HTTP مع decompress=1 يأخذ المرمِّز من بايت الطريقة في كل إطار، ولذا قد يظهر أيٌّ من هذه البايتات في الإدخال بصورة مشروعة. لذلك يجب على أي أداة فك الترميز متوافقة أن تتعرّف على النطاق المُخصَّص بأكمله، وأن ترفض أي بايت لا تدعمه بدلًا من أن تُسيء قراءة المتن. أما متون هذه المرمِّزات فخاصة بكل مرمِّز وتقع خارج نطاق عقد الإطار العام هذا:

البايت	الطريقة
`0x91`	`Multiple` (مرمِّز مُركَّب يغلّف سلسلة من المرمِّزات المتداخلة)
`0x92`	`Delta`
`0x93`	`T64`
`0x94`	`DoubleDelta`
`0x95`	`Gorilla`
`0x96`	`AES_128_GCM_SIV` (تشفير)
`0x97`	`AES_256_GCM_SIV` (تشفير)
`0x98`	`FPC`
`0x9a`	`GCD`
`0x9c`	`ALP`
`0x9d`	`SZ3`
`0x9e`	`Quantized`
`0x9f`	`ZXC`

يخزّن DoubleDelta (0x94) الفروق من الدرجة الثانية على هيئة بتات بادئة/إشارة/مقدار بترتيب البت الأعلى أولًا (MSB-first). ويحافظ فك الترميز القائم على الكلمات على هذا الترميز وعلى عدد العناصر والحشو في البايت الأخير. 0x9c (ALP) مرمِّز تجريبي (beta) بلا فقدان لـ Float32 وFloat64 (ضغط تكيّفي بلا فقدان للأعداد ذات الفاصلة العائمة). لا يمكن إنشاء جدول باستخدام CODEC(ALP) إلا عند تفعيل الإعداد enable_alp_codec، لكن بايت الطريقة يُقبَل دائمًا عند فك الضغط لتظل البيانات المكتوبة سابقًا قابلة للقراءة. أما 0x9d (SZ3) فهو مرمِّز تجريبي مع فقدان ومحدود الخطأ لـ Float32 وFloat64 وArray من هذين النوعين. لا يمكن إنشاء جدول باستخدام CODEC(SZ3) إلا عند تفعيل الإعداد enable_sz3_codec، لكن بايت الطريقة يُقبَل دائمًا عند فك الضغط لتظل البيانات المكتوبة سابقًا قابلة للقراءة. أما 0x9f (ZXC) فهو مرمِّز LZ تجريبي غير متناظر: بطيء في الضغط لكنه سريع جدًا في فك الضغط، بنسبة ضغط تقع بين LZ4 وZSTD. لا يمكن إنشاء جدول باستخدام CODEC(ZXC) إلا عند تفعيل الإعداد enable_zxc_codec، لكن بايت الطريقة يُقبَل دائمًا عند فك الضغط لتظل البيانات المكتوبة سابقًا قابلة للقراءة. وقد خُصِّص البايتان 0x99 (DeflateQpl) و0x9b (ZSTD_QPL) لمرمِّزات أُزيلت لاحقًا؛ وهما محجوزان ولا يُعاد استخدامهما. 0x9e (Quantized) مرمِّز أعمدة تجريبي لأعمدة المتجهات الكثيفة (Array(Float32) وما شابهها). وهو، مثل NONE، مرمِّز تمريري — إذ يُخزَّن المتن بدقته الكاملة كما هو — لكن وجوده يُلحق تسلسلًا يكتب دفقًا مرافقًا مُكمَّمًا ومدمجًا يُستخدم لتسريع البحث المتجهي. لا يمكن إنشاء جدول باستخدام CODEC(Quantized(...)) إلا عند تفعيل الإعداد enable_quantized_codec، ويُقبَل بايت الطريقة دائمًا عند فك الضغط.

قيمة التحقق

يستخدم ClickHouse الإصدار CityHash v1.0.2 (الإصدار التاريخي)، وليس إصدار Google CityHash الحديث؛ إذ يُنتج كلٌّ منهما مخرجات مختلفة عن الآخر. تُحسب قيمة التحقق على بايتات الترويسة التسعة (method + compressed_size + uncompressed_size) إضافةً إلى بايتات المتن البالغ عددها N، أي كل ما يقع بين قيمة التحقق ونهاية الإطار. تمثّل البايتات الثمانية الأولى من ناتج CityHash128 البالغ طوله 16 بايتًا النصفَ المنخفض (LE)، بينما تمثّل البايتات الثمانية التالية النصفَ المرتفع (LE). تعيد أداة فك الترميز حساب CityHash128 على الترويسة والمتن المستلمَين، ثم تقارن النتيجة بالبايتات الستة عشر الأولى؛ وأي عدم تطابق يُعدّ تلفًا في البيانات، فيفشل فك الترميز.

حدود كل كتلة

الحمولة المضغوطة لكتلة هي دفق من إطار واحد أو أكثر، وليست بالضرورة إطارًا واحدًا. يكتب المُرسِل الكتلة المُسلسَلة عبر CompressedWriteBuffer الذي يُصدر إطارًا كلما امتلأ مخزنه المؤقت الداخلي (≈1 MB، DBMS_DEFAULT_BUFFER_SIZE)، ثم إطارًا أخيرًا عند تفريغ الكتلة. وعليه، تشغل الكتلة الصغيرة إطارًا واحدًا، بينما تشغل الكتلة الكبيرة عدة إطارات متتالية. يسري هذا الثابت في اتجاه واحد فقط: فبما أن المُرسِل يُفرّغ المخزن المؤقت المضغوط في نهاية كل كتلة، فإن نهاية كل كتلة تتطابق مع حدّ إطار — غير أن العكس لا يصح. فحدّ الإطار الوسيط، الذي يُصدَر عند امتلاء المخزن المؤقت أثناء الكتلة، يقع في منتصف الكتلة ولا يُعدّ حدًّا لها. لذا يجب على أداة فك الترميز أن تعتمد على أبعاد الكتلة نفسها (num_columns/num_rows) لتحديد موضع انتهائها، ولا يجوز لها أن تفترض أن كل إطار يمثّل كتلة كاملة. يستقبل المُستقبِل الإطارات على هيئة دفق: يقرأ 16 + 9 بايت، ثم يقرأ compressed_size - 9 بايت بالضبط من المتن، ويفك ضغطها إلى uncompressed_size بايت بالضبط، ثم يمرّر هذه البايتات إلى أداة فك ترميز الكتل؛ وعندما تحتاج أداة فك الترميز إلى بيانات تتجاوز ما يحويه الإطار الحالي، يسحب الإطار التالي. ولأن المُرسِل يُفرّغ البيانات عند نهاية كل كتلة، يصبح المخزن المؤقت للإطار فارغًا بعد اكتمال فك ترميز الكتلة، وتبدأ الكتلة التالية في إطار جديد. في بروتوكول TCP الأصلي، يُكتب غلاف الحزمة — أي قيمة VarUInt التي تحدد نوع الحزمة وسلسلة table_name من النوع string — في الدفق الخام، خارج الحمولة المضغوطة؛ ولا يُؤطَّر سوى متن الكتلة (BlockInfo + الأعمدة). أما مسار compress/decompress عبر HTTP فلا يتضمن مثل هذا الغلاف، إذ يتكوّن الدفق بأكمله من كتل مؤطَّرة.

التفاوض

في بروتوكول TCP الأصلي، يُحدَّد الضغط لكل استعلام على حدة لا لكل اتصال. إذ يطلب الحقل compression: bool في حزمة الاستعلام الضغطَ لذلك الاستعلام وحده. فيلبّي الخادم الطلب ويُرسل متون Data/Totals/Extremes/Log/ProfileEvents مضغوطةً طوال مدة الاستعلام (أما Log/ProfileEvents فبدءًا من الإصدار v54481 فقط). كما يتوقع أن تكون كتل Data الصادرة من العميل — الجداول الخارجية، ووسم نهاية البيانات الفارغ، وصفوف INSERT — مؤطَّرةً بالطريقة نفسها. وقد تختلف الاستعلامات اللاحقة على الاتصال نفسه في ذلك. أما عبر HTTP فلا توجد حزمة الاستعلام: إذ تختار معلمة الاستعلام compress=1 إخراجًا مؤطَّرًا لذلك الطلب، بينما تُشير decompress=1 إلى أن متن الطلب مؤطَّر. ويُكتب إخراج compress=1 باستخدام المرمِّز الافتراضي للخادم (ZSTD(3)) لا باستخدام network_compression_method؛ في حين يستخلص قارئ decompress=1 المرمِّزَ من بايت الطريقة في كل إطار، ولذا يُقبل أي مرمِّز في الإدخال.

عند تفعيل الضغط، قد يمرّر الخادم الأعمدة أيضًا عبر مسار التنظيم المتوازي للكتل / ColumnBLOB (PARALLEL_BLOCK_MARSHALLING، الإصدار v54478) في الكتل التي تحتوي على أكثر من صف واحد. لذا يجب على أي تنفيذ يضغط بيانات INSERT أن يكون مستعدًا للتعامل مع هذا المسار (أو أن يعطّله صراحةً) تجنبًا لاختلال تزامن الدفق.

مسرد المصطلحات

كتلة — وحدة تبادل البيانات في صيغة Native، وهي كتلة ذاتية الوصف من الصفوف المخزّنة بشكل عمودي. راجع بنية الكتلة والعمود. BlockInfo — ترويسة البيانات الوصفية التي تسبق الكتلة في مسار حزم Data عبر TCP (وتُكتب متى كانت revision الاتصال أكبر من صفر). وهي سلسلة من الحقول الموسومة بمعرّفات حقول، ويتوقف وجود كلٍّ منها على الـ revision. لا يتضمنها تنسيق الإخراج Native، إذ يُجري التسلسل عند revision 0. راجع BlockInfo. متن العمود — بايتات العمود التي تحمل القيم الفعلية، وتأتي بعد ترويسة العمود (الاسم، والنوع، وبايت has_custom_serialization). ويختلف تخطيطه باختلاف النوع. راجع تخطيط العمود على الشبكة. النوع المركّب — نوع مبني من نوع داخلي واحد أو أكثر، ويُرمَّز على هيئة عدة تدفقات لكل عمود. صيغة النقل الخاصة به مستقرة ولا تخضع لإصدارات. راجع الأنواع المركّبة. القاموس (LowCardinality) — مصفوفة القيم الفريدة التي يشير إليها عمود LowCardinality(T) عبر فهارس عددية صحيحة. راجع LowCardinality. الكتلة الفارغة — كتلة تكون فيها num_columns = 0 وnum_rows = 0. تُستخدم قيمةً حارسة: فهي وسم لنهاية الإدخال من جهة العميل، ووسم لحدود الدفق من جهة الخادم. راجع بدائل الكتلة. كتلة الترويسة — كتلة تكون فيها num_columns > 0 وnum_rows = 0، يرسلها الخادم أولَ حزمة Data في استجابة الاستعلام، وتُعلن عن مخطط النتيجة. راجع بدائل الكتلة. النوع الداخلي — النوع الذي يغلّفه النوع المركّب. فالنوع الداخلي لـ Array(UInt32) هو UInt32، والنوع الداخلي لـ Nullable(T) هو T. دفق الإزاحات — مصفوفة UInt64 من مواضع النهاية التراكمية، تستخدمها Array وMap وNested لتحديد حدود العناصر في كل صف. راجع Array. القيمة البديلة المؤقتة — البايتات المكتوبة في مواضع القيم الفارغة ضمن دفق القيم لعمود Nullable(T). تقرؤها أداة فك الترميز لتتقدّم في الدفق، لكنها تتجاهل محتواها. راجع Nullable. كتلة النتيجة — كتلة تكون فيها num_rows > 0، وتحمل صفوفاً فعلية من نتيجة الاستعلام. راجع بدائل الكتلة. كتلة المخطط — مرادف لكتلة الترويسة، يُستخدم عند وصف مرحلة INSERT، حيث تُبلغ كتلة المخطط العميلَ بأشكال الأعمدة المتوقعة. إصدار التسلسل — رقم إصدار خاص بكل نوع يُنقل عبر الشبكة، تستخدمه الأنواع ذات الإصدارات للإعلان عن بديل الترميز الذي يليه. ويختلف عن إصدار البروتوكول. راجع إصدار التسلسل: المفهوم. بادئة الحالة — البايتات التي تسبق حمولة الكتلة في الأنواع ذات الإصدارات. تحمل إصدار التسلسل و(في حالة LowCardinality) البيانات الوصفية للقاموس الخاصة بكل كتلة. تُرسَل في بداية كل كتلة يزيد عدد صفوفها على 0، ولا يُحتفظ بها من كتلة إلى أخرى. الدفق — سلسلة متصلة من البايتات داخل متن العمود، ترمّز مكوّناً فرعياً منطقياً واحداً (خريطة القيم الفارغة، أو مصفوفة الإزاحات، أو دفق القيم). وتضمّ الأنواع متعددة التدفقات دفقين أو أكثر متتاليين لكل عمود.

​نظرة عامة

​العناصر الأولية للتمثيل الثنائي

​VarUInt

​الأعداد الصحيحة ذات العرض الثابت

​String

​Bool

​بنية الكتلة والأعمدة

​تخطيط wire للكتلة

​BlockInfo

​تخطيط wire للعمود

​kind_stack والترميز المتناثر

​بدائل الكتلة

​أمثلة على مستوى البايت

​revision البروتوكول وصيغة Native

​ما الذي تتحكم فيه المراجعة (revision)

​مصدر الـ revision بحسب طريقة انتقال البيانات

​بروتوكول TCP الأصلي — قيمة متفاوض عليها، في كلا الاتجاهين

​إخراج FORMAT Native — revision 0 افتراضيًا، مع إمكانية رفعها عبر HTTP

​إدخال FORMAT Native — دائمًا بـ revision 0

​تداعيات الكتابة ثم القراءة

​أنواع البيانات

​الأنواع ذات العرض الثابت

​أنواع الأعداد الصحيحة

​Float32 و Float64

​BFloat16

​Bool

​Date و Date32

​DateTime

​DateTime64(scale[, timezone])

​Time و Time64(scale)

​Interval

​UUID

​IPv4 وIPv6

​Enum8 و Enum16

​Decimal(P, S)

​Nothing

​الأنواع ذات الطول المتغير

​String

​FixedString(N)

​الأنواع المركبة

​Nullable(T)

​Array(T)

​Tuple(T1, T2, …)

​Map(K, V)

​Nested(name1 T1, name2 T2, …)

​الأسماء البديلة للأنواع

​الأنواع ذات الإصدارات

​إصدار التسلسل: المفهوم

​مرجع إصدارات التسلسل

​LowCardinality(T)

​JSON (Tier 1: String fallback)

​Variant(T1, T2, …)

​Dynamic

​JSON (Tier 2: FLATTENED Object)

​JSON غير المسطّح (V1/V2)

​إطار الضغط

​صيغة الإطار

​قيم بايت الطريقة

​قيمة التحقق

​حدود كل كتلة

​التفاوض

​مسرد المصطلحات

نظرة عامة

العناصر الأولية للتمثيل الثنائي

VarUInt

الأعداد الصحيحة ذات العرض الثابت

String

Bool

بنية الكتلة والأعمدة

تخطيط wire للكتلة

BlockInfo

تخطيط wire للعمود

kind_stack والترميز المتناثر

بدائل الكتلة

أمثلة على مستوى البايت

revision البروتوكول وصيغة Native

ما الذي تتحكم فيه المراجعة (revision)

مصدر الـ revision بحسب طريقة انتقال البيانات

بروتوكول TCP الأصلي — قيمة متفاوض عليها، في كلا الاتجاهين

إخراج `FORMAT Native` — revision 0 افتراضيًا، مع إمكانية رفعها عبر HTTP

إدخال `FORMAT Native` — دائمًا بـ revision 0

تداعيات الكتابة ثم القراءة

أنواع البيانات

الأنواع ذات العرض الثابت

أنواع الأعداد الصحيحة

Float32 و Float64

BFloat16

Bool

Date و Date32

DateTime

DateTime64(scale[, timezone])

Time و Time64(scale)

Interval

UUID

IPv4 وIPv6

Enum8 و Enum16

Decimal(P, S)

Nothing

الأنواع ذات الطول المتغير

String

FixedString(N)

الأنواع المركبة

Nullable(T)

Array(T)

Tuple(T1, T2, …)

Map(K, V)

Nested(name1 T1, name2 T2, …)

الأسماء البديلة للأنواع

الأنواع ذات الإصدارات

إصدار التسلسل: المفهوم

مرجع إصدارات التسلسل

LowCardinality(T)

JSON (Tier 1: String fallback)

Variant(T1, T2, …)

Dynamic

JSON (Tier 2: FLATTENED Object)

JSON غير المسطّح (V1/V2)

إطار الضغط

صيغة الإطار

قيم بايت الطريقة

قيمة التحقق

حدود كل كتلة

التفاوض

مسرد المصطلحات