الانتقال إلى المحتوى الرئيسي

​
الوصف

المواصفة الرسمية الكاملة لتنسيق Native متاحة هنا، كما تتوفر هنا المواصفة المرافقة لبروتوكول Native — أي بروتوكول TCP الذي ينقله.
جرى توليد كلتا المواصفتين بواسطة نماذج لغوية كبيرة انطلاقًا من الشيفرة المصدرية لـ ClickHouse. وتبقى الشيفرة المصدرية هي المرجع الأساسي: إذا وُجد اختلاف بين المواصفة والشيفرة، فالشيفرة هي الصحيحة.
يُعد تنسيق Native أكثر تنسيقات ClickHouse كفاءة لأنه “عمودي” بالفعل إذ لا يحوّل الأعمدة إلى صفوف. في هذا التنسيق، تُكتب البيانات وتُقرأ على شكل كتل بتنسيق ثنائي. ولكل كتلة، يُسجَّل عدد الصفوف، وعدد الأعمدة، وأسماء الأعمدة وأنواعها، وأجزاء الأعمدة في الكتلة، واحدًا تلو الآخر. وهذا هو التنسيق المستخدم في الواجهة الأصلية للتفاعل بين الخوادم، ولاستخدام عميل سطر الأوامر، ولعملاء C++.
يمكنك استخدام هذا التنسيق لإنشاء dump بسرعة، ولا يمكن قراءته إلا بواسطة نظام إدارة قواعد البيانات ClickHouse. وقد لا يكون من العملي التعامل مع هذا التنسيق بنفسك.

​
تنسيق أنواع البيانات wire

تُرسَل البيانات أثناء النقل بتنسيق عمودي، ما يعني أن كل عمود يُرسَل على حدة، وتُرسَل جميع قيم العمود معًا في مصفوفة واحدة. يحتوي كل عمود في كتلة على ترويسة مشابهة لـ RowBinaryWithNamesAndTypes.
عند استخدام بروتوكول TCP الثنائي الأصلي (أو عندما تتلقى نقطة نهاية HTTP القيمة ?client_protocol_version=<n>)، تُكتَب بنية BlockInfo قبل عدد الأعمدة والصفوف. وتستخدم الأمثلة في هذا القسم واجهة HTTP العادية من دون إصدار للبروتوكول، ولذلك لا تتضمن BlockInfo.

​
بنية الكتلة

يعرض الاستعلام التالي عمودين، number وstr، في ثلاثة صفوف:
تندرج بيانات الإخراج ضمن كتلة واحدة في ClickHouse، وستبدو على النحو التالي:

​
كتل متعددة

ومع ذلك، في كثير من الحالات، لا تتسع البيانات ضمن كتلة واحدة، لذا سيرسل ClickHouse البيانات على شكل عدة كتل. انظر إلى الاستعلام التالي الذي يجلب صفّين مع تقليل حجم الكتلة لفرض تقسيم البيانات بحيث يكون كل صف في كتلة منفصلة:
الناتج:

​
أنواع البيانات البسيطة

يشبه تنسيق wire لقيمة مفردة من أحد أنواع البيانات الأبسط تنسيق RowBinary/RowBinaryWithNamesAndTypes. تتضمن القائمة الكاملة للأنواع التي ينطبق عليها هذا الوصف ما يلي:
  • (U)Int8, (U)Int16, (U)Int32, (U)Int64, (U)Int128, (U)Int256
  • Float32, Float64
  • Bool
  • String
  • FixedString(N)
  • Date
  • Date32
  • DateTime
  • DateTime64
  • IPv4
  • IPv6
  • UUID
ارجع إلى أوصاف الأنواع أعلاه في “تنسيق wire لأنواع بيانات RowBinary” لمزيد من التفاصيل.

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

يختلف ترميز الأنواع التالية عن ترميز RowBinary وRowBinaryWithNamesAndTypes.
  • Nullable
  • LowCardinality
  • Array
  • Map
  • Variant
  • Dynamic
  • JSON

​
Nullable

في تنسيق Native، يسبق البيانات الفعلية في العمود القابل لأن تكون قيمته NULL عددٌ من البايتات يساوي عدد الصفوف في الكتلة. ويشير كل بايت من هذه البايتات إلى ما إذا كانت القيمة NULL أم لا. على سبيل المثال، في هذا الاستعلام، ستكون كل قيمة فردية NULL بدلًا من ذلك:
سيكون الإخراج على النحو التالي:
يعمل ذلك بالطريقة نفسها مع Nullable(String). يأتي مؤشر null دائمًا من بايت قناع nullable — فقيمة القناع 0x01 تعني أن الصف هو NULL بغضّ النظر عن محتوى السلسلة. بالنسبة إلى الصفوف ذات القيمة NULL، تُخزَّن السلسلة الأساسية كسلسلة فارغة (طول LEB128 يساوي 0). لاحظ أن السلسلة الفارغة غير NULL يكون طول LEB128 لها أيضًا 0، لذا فإن بايت القناع وحده هو ما يميّز بين الحالتين. على سبيل المثال، الاستعلام التالي:
سيكون الناتج كما يلي:

​
LowCardinality

على عكس RowBinary، حيث يكون LowCardinality شفافًا، يستخدم تنسيق Native ترميزًا عموديًا قائمًا على القاموس. ويُرمَّز العمود على هيئة بادئة إصدار، ثم قاموس للقيم الفريدة، ثم Array من فهارس الأعداد الصحيحة التي تشير إلى ذلك القاموس.
يمكن تعريف العمود على أنه LowCardinality(Nullable(T))، لكن لا يمكن تعريفه على أنه Nullable(LowCardinality(T)) — إذ يؤدي ذلك دائمًا إلى خطأ من الخادم.
بادئة الإصدار هي UInt64(LE) بقيمة 1، وتُكتب مرة واحدة لكل عمود. ثم، لكل كتلة، يُكتب ما يلي:
  • UInt64(LE) — حقل بتات IndexesSerializationType. ترمّز البتات 0–7 عرض الفهرس (0 = UInt8، 1 = UInt16، 2 = UInt32، 3 = UInt64). ولا يُضبط البت 8 (NeedGlobalDictionaryBit) مطلقًا في تنسيق Native (ويُطلق الخادم استثناءً إذا تمت مصادفته). ويشير البت 9 إلى وجود مفاتيح إضافية في القاموس. ويشير البت 10 إلى أنه ينبغي إعادة تعيين القاموس.
  • UInt64(LE) — عدد مفاتيح القاموس، تليه المفاتيح مُسلسلةً دفعةً واحدة باستخدام ترميز النوع الداخلي.
  • UInt64(LE) — عدد الصفوف، تليه قيم الفهارس مُسلسلةً دفعةً واحدة باستخدام عرض UInt المناسب.
يحتوي القاموس دائمًا على قيمة default عند الفهرس 0 (على سبيل المثال، سلسلة فارغة لـ String و0 للأنواع الرقمية). وبالنسبة إلى LowCardinality(Nullable(T))، يمثّل الفهرس 0 القيمة NULL، وتُسلسَل المفاتيح من دون الغلاف Nullable. على سبيل المثال، LowCardinality(String) مع 5 صفوف ['foo', 'bar', 'baz', 'foo', 'bar']:
مع LowCardinality(Nullable(String))، تكون القيمة عند الفهرس 0 هي NULL:

​
Array

بخلاف RowBinary، حيث تُسبق كل مصفوفة بعدد عناصر مُرمَّز بـ LEB128، يشفّر التنسيق Native المصفوفات على شكل تدفقين فرعيين عموديين:
  • عدد N من إزاحات UInt64 التراكمية (بترتيب little-endian، 8 بايت لكل إزاحة). يحتوي الصف i على offset[i] - offset[i-1] عنصرًا، مع اعتبار offset[-1] مساويًا ضمنيًا لـ 0.
  • جميع العناصر المتداخلة عبر كل الصفوف، مُسلسلة دفعةً واحدة وبشكل متجاور.
على سبيل المثال، Array(UInt32) مع 3 صفوف [[0, 10], [1, 11], [2, 12]]:
للمصفوفة الفارغة الإزاحة نفسها الموجودة في الصف السابق. على سبيل المثال، Array(String) مع 4 صفوف [[], ['0'], ['0','1'], ['0','1','2']]:

​
Map

يُرمَّز Map(K, V) على شكل Array(Tuple(K, V)) — إزاحات المصفوفة، تليها جميع المفاتيح، ثم جميع القيم. ويختلف ذلك عن RowBinary، حيث تتعاقب المفاتيح والقيم في كل عنصر. على سبيل المثال، Map(String, UInt64) مع 3 صفوف [{'a':0,'b':10}, {'a':1,'b':11}, {'a':2,'b':12}]:

​
Variant

بخلاف RowBinary، حيث يحمل كل صف بايت المميِّز الخاص به متبوعًا بالقيمة بشكل Inline، يفصل تنسيق Native بين المميِّزات والبيانات.
كما في RowBinary، تُرتَّب الأنواع في التعريف دائمًا ترتيبًا أبجديًا، ويكون المميِّز هو الفهرس ضمن تلك القائمة المرتبة. وتمثل القيمة 0xFF (255) القيمة NULL.
يُرمَّز عمود Variant على النحو التالي:
  • بادئة وضع المميِّزات UInt64(LE) (0 = BASIC، 1 = COMPACT). يستخدم خرج تنسيق Native عادةً BASIC (0)؛ وقد يظهر وضع COMPACT عند قراءة بيانات مخزَّنة مع تفعيل use_compact_variant_discriminators_serialization.
  • N من المميِّزات UInt8، واحد لكل صف.
  • بيانات كل variant type كـ عمود مجمّع منفصل لا يحتوي إلا على الصفوف المطابقة، وفق ترتيب المميِّزات.
على سبيل المثال، Variant(String, UInt32) مع 5 صفوف [0::UInt32, 'hello', NULL, 3::UInt32, 'hello'] (مرتبة: String = 0، UInt32 = 1):

​
Dynamic

على عكس RowBinary، حيث تكون كل قيمة موصوفة ذاتيًا (بادئة النوع + القيمة)، فإن تنسيق Native يُسلسِل Dynamic كبادئة بنية تتبعها عمود Variant. تحتوي بادئة البنية على إصدار التسلسل من نوع UInt64(LE)، ثم عدد الأنواع الديناميكية (بصيغة VarUInt)، ثم type names كسلاسل نصية. في الإصدار V1، يُكتَب عدد الأنواع مرتين لأغراض التوافق. أما البيانات التي تلي ذلك فهي عمود Variant تكون قائمة أنواعه هي الأنواع الديناميكية بالإضافة إلى النوع الداخلي SharedVariant، مرتبةً أبجديًا. على سبيل المثال، Dynamic مع 5 صفوف [0::UInt32, 'hello', NULL, 3::UInt32, 'hello']:

​
JSON

على عكس RowBinary، حيث يكون كل صف ذاتي الوصف بأسماء المسارات والقيم، فإن تنسيق Native يُسلسل JSON ببنية عمودية. ويكون هذا الترميز معقدًا ومعتمدًا على الإصدار: إذ يتكون من بادئة بنية تتضمن إصدار التسلسل، وأسماء المسارات الديناميكية، وتخطيط البيانات المشتركة، ثم تليها مسارات محددة النوع (كل منها على هيئة عمود مجمّع)، ومسارات ديناميكية (كل منها عمود Dynamic)، وبيانات مشتركة لمسارات overflow. لتحقيق توافقية أبسط، يُنصح باستخدام الإعداد output_format_native_write_json_as_string=1، الذي يُسلسل أعمدة JSON كسلاسل نصية عادية بتنسيق JSON (قيمة String واحدة لكل صف).
آخر تعديل في ٢ يوليو ٢٠٢٦