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_allow_variable_number_of_columns): تُملأ الأعمدة المفقودة بالقيم الافتراضية في الصفوف التي تحتوي على حقول أقل من عدد حقول الجدول، وتُتجاوز الحقول الزائدة اللاحقة في الصفوف التي تحتوي على حقول إضافية.

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

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

1,3
3,5,9

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

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;

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

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

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

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

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;

┌─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.

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