HiveText

وثائق تنسيق HiveText

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

​

الوصف

يقرأ HiveText ويكتب تنسيق التسلسل النصي المستخدم في جداول Apache Hive (وهو التنسيق الذي ينتجه LazySimpleSerDe في Hive). وهو تنسيق نصي مفصول بمحددات، يشبه CSV، وتُفصل فيه الحقول باستخدام محدد Hive الافتراضي \x01 (Ctrl-A). ويمكن تهيئة محدد الحقول عبر input_format_hive_text_fields_delimiter.

عند استخدامه كتنسيق إدخال، لا تحتوي البيانات على صف ترويسة: إذ تُسنَد القيم موضعيًا إلى أعمدة الجدول الوجهة، لذلك تُؤخذ أسماء الأعمدة وأنواعها من الجدول (أو من البنية المقدَّمة صراحةً) بدلًا من استنتاجها من البيانات. وأثناء القراءة، يعالج ClickHouse التواريخ والأوقات في وضع أفضل جهد (راجع date_time_input_format)، ويملأ الحقول اللاحقة المحذوفة بالقيم الافتراضية للأعمدة، ويتجاوز الحقول التي لا يتعرف عليها.

داخل الحقل، تُحلَّل القيم باستخدام قواعد الإفلات نفسها الخاصة بـ CSV بدلًا من محددات Hive المتداخلة. وعلى وجه الخصوص، يُقرأ العمود من النوع Array من التمثيل المحاط بأقواس (على سبيل المثال، "['a','b','c']")، وليس من القيم المفصولة بمحدد مجموعة Hive وهو \x02.

إعدادات المحددات المتداخلة ليس لها أي تأثير على الإدخال

يتم قبول الإعدادين input_format_hive_text_collection_items_delimiter و input_format_hive_text_map_keys_delimiter لأغراض التوافق، لكن لا يُستخدمان حاليًا أثناء التحليل. ومع ذلك، يُستخدمان عند كتابة القيم المتداخلة في جانب الإخراج.

بشكل افتراضي، يُسمح بأن تحتوي الصفوف على عدد متغير من الحقول (راجع input_format_hive_text_allow_variable_number_of_columns): تُملأ الأعمدة المفقودة بالقيم الافتراضية في الصفوف التي تحتوي على حقول أقل من عدد حقول الجدول، وتُتجاوز الحقول الزائدة اللاحقة في الصفوف التي تحتوي على حقول إضافية.

​

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

تستخدم الأمثلة أدناه input_format_hive_text_fields_delimiter لاستبدال محدد الحقول الافتراضي بفاصلة (,) حتى تكون ملفات الإدخال أسهل قراءةً.

​

قراءة ملف HiveText

لنفترض وجود ملف hive_data.txt يحتوي على حقول مفصولة بفواصل:

hive_data.txt

1,3
3,5,9

ننشئ جدولًا يحدّد أسماء الأعمدة وأنواعها، ثم نُدخل الملف فيه باستخدام FORMAT HiveText:

Query

CREATE TABLE test_tbl (a UInt16, b UInt32, c UInt32) ENGINE = MergeTree ORDER BY a;

INSERT INTO test_tbl FROM INFILE 'hive_data.txt'
SETTINGS input_format_hive_text_fields_delimiter = ','
FORMAT HiveText;

SELECT * FROM test_tbl;

Response

┌─a─┬─b─┬─c─┐
│ 1 │ 3 │ 0 │
│ 3 │ 5 │ 9 │
└───┴───┴───┘

لاحظ أن الصف الأول، 1,3، يحتوي على حقلين فقط، لذا يُملأ العمود المفقود c بقيمةِه الافتراضية 0.

​

عدد متغيّر من الأعمدة

مع الإعداد الافتراضي input_format_hive_text_allow_variable_number_of_columns = 1، فإن الصفوف التي تحتوي على حقول أكثر مما يحتويه الجدول تُتخطّى فيها ببساطة الحقول الزائدة في النهاية:

hive_extras.txt

1,2,3,4,5
6,7,8

Query

CREATE TABLE test_extras (a UInt16, b UInt32, c UInt32) ENGINE = MergeTree ORDER BY a;

INSERT INTO test_extras FROM INFILE 'hive_extras.txt'
SETTINGS input_format_hive_text_fields_delimiter = ','
FORMAT HiveText;

SELECT * FROM test_extras ORDER BY a;

Response

┌─a─┬─b─┬─c─┐
│ 1 │ 2 │ 3 │
│ 6 │ 7 │ 8 │
└───┴───┴───┘

يؤدي تعيين input_format_hive_text_allow_variable_number_of_columns = 0 بدلًا من ذلك إلى فرض عدد صارم من الحقول، ويؤدي وجود صف بعدد حقول أقل من عدد حقول الجدول إلى حدوث استثناء أثناء التحليل.

​

الإخراج

عند استخدامه كتنسيق إخراج، يكتب HiveText كل صف دون أي علامات اقتباس: تُفصل الحقول ذات المستوى الأعلى بمحدد الحقول (افتراضيًا \x01)، وتُفصل الصفوف بمحدد الصفوف (افتراضيًا \n، ويمكن ضبطه عبر format_hive_text_rows_delimiter). تُكتب قيم الأنواع المتداخلة (Array، Map وTuple) دون أقواس، وتُفصل بفاصل Hive الخاص بمستوى تداخلها، بالطريقة نفسها التي يستخدمها LazySimpleSerDe في Hive. الفواصل الثلاثة الأولى هي محدد الحقول القابل للضبط، input_format_hive_text_collection_items_delimiter (افتراضيًا \x02، ويُستخدم لعناصر المصفوفات وإدخالات الخرائط وعناصر الصفوف) وinput_format_hive_text_map_keys_delimiter (افتراضيًا \x03، ويُستخدم بين مفتاح الخريطة وقيمته)؛ أما المستويات الأعمق فتستخدم افتراضيًا أحرف تحكم متتالية (\x04، \x05، وهكذا، حتى ثمانية مستويات). تُرفض شجرة أنواع متداخلة بعمق يتطلب فاصلًا يتجاوز تلك المستويات الثمانية مع استثناء NOT_IMPLEMENTED، إذ لا يوفّر LazySimpleSerDe في Hive فاصلًا لها أيضًا. أنواع البيانات التي لا تمتلك تمثيلًا نصيًا طبيعيًا في Hive غير مدعومة للإخراج وتُطلق استثناء NOT_IMPLEMENTED. يشمل ذلك AggregateFunction وDynamic وVariant وLowCardinality وObject، بالإضافة إلى الأنواع المدعومة عدديًا Enum وTime وTime64 وInterval — لا يملك Hive نوعًا مطابقًا لهذه الأنواع، لذا تُرفض بدلًا من كتابتها كأرقامها الأساسية الخام. تُرفض الأنواع الرقمية العريضة Int128 وUInt128 وInt256 وUInt256 للسبب نفسه: أوسع عدد صحيح في Hive هو BIGINT (64 بت)، وحتى DECIMAL في Hive، بدقته القصوى البالغة 38، لا يمكنه استيعاب نطاق قيمها. وبالمثل، تتجاوز قيم Decimal ذات دقة أعلى من 38 (أي Decimal256) الدقة القصوى لـ DECIMAL في Hive، ولذلك تُرفض. وبالمثل، يجب أن تكون مفاتيح Map من نوع بدائي: يعرّف Hive الخرائط على أنها MAP<primitive_type, data_type>، لذا فإن Map الذي يكون نوع مفتاحه Array أو Map أو Tuple (وهو ما يسمح به ClickHouse) يُرفض مع استثناء NOT_IMPLEMENTED، إذ لا يمكن لأي مخطط Hive قراءة هذه القيم مرة أخرى. تُرفض القيمة الحرفية للخريطة الفارغة map() للسبب نفسه: فنوعها هو Map(Nothing, Nothing)، وNothing ليس نوعًا يمكن لتصريح Hive MAP<key_type, data_type> تسميته. تُطبّق جميع هذه الفحوصات مسبقًا على أنواع الأعمدة المعلنة، قبل كتابة أي صف: يُرفض الاستعلام الذي يحتوي رأسه على نوع غير مدعوم في أي موضع من شجرة أنواعه، حتى عندما لا تصل القيم الفعلية مطلقًا إلى التسلسل غير المدعوم (على سبيل المثال، Nullable لنوع غير مدعوم لا يحتوي إلا على قيم NULL، أو Array/Map فارغة بعنصر من نوع غير مدعوم)، لأن مخطط الملف المعلن لا يمكن أن ينتمي إلى أي جدول Hive.

تُكتب Date وDate32 وDateTime وDateTime64 دائمًا بتنسيق النص العادي لتاريخ وطابع زمني Hive (yyyy-MM-dd وyyyy-MM-dd HH:mm:ss[.fffffffff])، بغض النظر عن إعداد date_time_output_format، بحيث يبقى الإخراج قابلاً للقراءة بواسطة Hive حتى عندما يكون هذا الإعداد unix_timestamp أو iso.

للسبب نفسه، تُكتب قيم Bool دائمًا على هيئة true/false، بغض النظر عن إعدادَي bool_true_representation وbool_false_representation، وتُكتب قيم NULL دائمًا كتسلسل القيمة الخالية الافتراضي في Hive، \N، بغض النظر عن إعداد format_csv_null_representation. ويضمن ذلك أن يبقى الإخراج قابلاً للقراءة بواسطة LazySimpleSerDe في Hive بغض النظر عن هذه الإعدادات النصية العامة. وبالمثل، يقرأ تنسيق الإدخال HiveText دائمًا \N باعتبارها NULL، بغض النظر أيضًا عن إعداد format_csv_null_representation، لذا لا تعتمد عملية الذهاب والإياب للقيم القياسية ذات المستوى الأعلى عليه.

تُكتب قيم Float32 وFloat64 غير المنتهية باستخدام صيغ Java التي يستخدمها Hive، وهي NaN وInfinity و-Infinity، بدلاً من الرموز المعتادة في ClickHouse، وهي nan/inf/-inf، كي يعيد محلّل FLOAT/DOUBLE في Hive قراءتها بالقيم نفسها بدلاً من NULL.

مخرجات متوافقة مع Hive، وليست دعماً كاملاً للذهاب والإياب عبر تنسيق الإدخال

يستهدف جانب الإخراج LazySimpleSerDe الافتراضي في Hive، ولا يتماثل مع إدخال HiveText الخاص بـ ClickHouse:

• تُكتب قيم Array وMap وTuple المتداخلة باستخدام الفواصل المتداخلة في Hive (من دون أقواس)، لكن تنسيق الإدخال يحلّل كل حقل وفق قواعد CSV/الأقواس ويتجاهل input_format_hive_text_collection_items_delimiter / input_format_hive_text_map_keys_delimiter. لذلك، لا يمكن قراءة مخرجات متداخلة مثل SELECT [1, 2] FORMAT HiveText مجدداً باستخدام INSERT ... FORMAT HiveText — فالحقول القياسية في المستوى الأعلى وحدها تدعم الذهاب والإياب، وفقط مع محدد الصفوف الافتراضي \n (انظر النقطة التالية).
• يتطلب الذهاب والإياب أيضاً محدد الصفوف الافتراضي \n. عند تغيير format_hive_text_rows_delimiter، تفصل المخرجات الصفوف بالبايت المُعدّ، لكن جانب الإدخال يظل CSVRowInputFormat المستند إلى السطر الجديد، ولا يوجد input_format_hive_text_rows_delimiter مطابق. لذلك، فإن مخرجات القيم القياسية متعددة الصفوف مثل SELECT number FROM numbers(3) FORMAT HiveText SETTINGS format_hive_text_rows_delimiter=';' (التي تنتج 0;1;2;) لا تُقرأ مجدداً باستخدام INSERT ... FORMAT HiveText كثلاثة صفوف.
• لا يُنفَّذ إلا الجزء الافتراضي غير المُفلَت من LazySimpleSerDe. تُكتب الحقول من دون إفلات (لا يوجد ما يعادل خيار Hive ROW FORMAT DELIMITED ... ESCAPED BY)، وتُكتب NULL دائماً بالشكل \N (لا يوجد ما يعادل NULL DEFINED AS). لذلك، تُكتب قيمة String التي تحتوي على فاصل حقل أو صف أو فاصل متداخل نشط كما هي، وستُفسَّر بشكل خاطئ عند قراءتها مجدداً — وهذا يطابق سلوك Hive نفسه مع serde لا يستخدم الإفلات. وللسبب نفسه، فإن String التي تكون قيمتها حرفياً \N (مثلاً SELECT '\\N'::String FORMAT HiveText) تُكتب بالبايتين نفسيهما اللذين تُمثَّل بهما قيمة NULL حقيقية، ولذلك لا يمكن التمييز بينهما من جانب Hive.

Query

SELECT '20240305', tuple(123567, 'e01001', map('action1', 33333, 'act2', 5555)) FORMAT HiveText;

​

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

الإعداد	الوصف	الافتراضي
input_format_hive_text_fields_delimiter	المحدد بين الحقول في Hive Text File	\x01
input_format_hive_text_collection_items_delimiter	المحدد بين عناصر المجموعة (array أو map) في Hive Text File. يُستخدم بواسطة تنسيق الإخراج؛ ويُقبل هذا الإعداد، لكنه لا يُستخدم حاليًا أثناء تحليل الإدخال.	\x02
input_format_hive_text_map_keys_delimiter	المحدد بين كل زوج مفتاح/قيمة في map في Hive Text File. يُستخدم بواسطة تنسيق الإخراج؛ ويُقبل هذا الإعداد، لكنه لا يُستخدم حاليًا أثناء تحليل الإدخال.	\x03
input_format_hive_text_allow_variable_number_of_columns	تجاهل الأعمدة الإضافية في مُدخل Hive Text (إذا كان الملف يحتوي على أعمدة أكثر من المتوقع)، واعتبار الحقول المفقودة قيماً افتراضية	1
format_hive_text_rows_delimiter	المحدد في نهاية كل صف في مخرجات Hive Text	\n