JSONObjectEachRow

وثائق تنسيق JSONObjectEachRow

إدخال	إخراج	اسم بديل
✔	✔

​

الوصف

في هذا التنسيق، تُمثَّل جميع البيانات على شكل كائن JSON واحد، ويُمثَّل كل صف كحقل منفصل ضمن هذا الكائن، على غرار تنسيق JSONEachRow.

​

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

​

مثال بسيط

إذا كانت لدينا بعض بيانات JSON:

{
  "row_1": {"num": 42, "str": "hello", "arr":  [0,1]},
  "row_2": {"num": 43, "str": "hello", "arr":  [0,1,2]},
  "row_3": {"num": 44, "str": "hello", "arr":  [0,1,2,3]}
}

لاستخدام اسم كائن كقيمة لعمود، يمكنك استخدام الإعداد الخاص format_json_object_each_row_column_for_object_name. تُعيَّن قيمة هذا الإعداد إلى اسم عمود، ويُستخدم هذا الاسم كمفتاح JSON للصف في الكائن الناتج.

​

المخرجات

لنفترض أن لدينا الجدول test ويحتوي على عمودين:

┌─object_name─┬─number─┐
│ first_obj   │      1 │
│ second_obj  │      2 │
│ third_obj   │      3 │
└─────────────┴────────┘

لنُخرج الناتج بتنسيق JSONObjectEachRow ونستخدم الإعداد format_json_object_each_row_column_for_object_name:

Query

SELECT * FROM test SETTINGS format_json_object_each_row_column_for_object_name='object_name'

Response

{
    "first_obj": {"number": 1},
    "second_obj": {"number": 2},
    "third_obj": {"number": 3}
}

​

الإدخال

لنفترض أننا خزّنا ناتج المثال السابق في ملف باسم data.json:

Query

SELECT * FROM file('data.json', JSONObjectEachRow, 'object_name String, number UInt64') SETTINGS format_json_object_each_row_column_for_object_name='object_name'

Response

┌─object_name─┬─number─┐
│ first_obj   │      1 │
│ second_obj  │      2 │
│ third_obj   │      3 │
└─────────────┴────────┘

ويعمل أيضًا مع استدلال المخطط:

Query

DESCRIBE file('data.json', JSONObjectEachRow) SETTING format_json_object_each_row_column_for_object_name='object_name'

Response

┌─name────────┬─type────────────┐
│ object_name │ String          │
│ number      │ Nullable(Int64) │
└─────────────┴─────────────────┘

​

إدخال البيانات

Query

INSERT INTO UserActivity FORMAT JSONEachRow {"PageViews":5, "UserID":"4324182021466249494", "Duration":146,"Sign":-1} {"UserID":"4324182021466249494","PageViews":6,"Duration":185,"Sign":1}

يسمح ClickHouse بما يلي:

• أي ترتيب لأزواج المفتاح والقيمة داخل الكائن.
• حذف بعض القيم.

يتجاهل ClickHouse المسافات بين العناصر والفواصل بعد الكائنات. يمكنك تمرير جميع الكائنات في سطر واحد. ولا يلزم فصلها بأسطر جديدة.

​

معالجة القيم المحذوفة

يستبدل ClickHouse القيم المحذوفة بالقيم الافتراضية لأنواع البيانات المقابلة.

إذا جرى تحديد DEFAULT expr، يستخدم ClickHouse قواعد استبدال مختلفة وفقًا للإعداد input_format_defaults_for_omitted_fields.

تأمل الجدول التالي:

Query

CREATE TABLE IF NOT EXISTS example_table
(
    x UInt32,
    a DEFAULT x * 2
) ENGINE = Memory;

• إذا كانت input_format_defaults_for_omitted_fields = 0، فإن القيمة الافتراضية لكلٍّ من x وa هي 0 (لأنها القيمة الافتراضية لنوع البيانات UInt32).
• إذا كانت input_format_defaults_for_omitted_fields = 1، فإن القيمة الافتراضية لـ x هي 0، لكن القيمة الافتراضية لـ a هي x * 2.

عند إدراج البيانات باستخدام input_format_defaults_for_omitted_fields = 1، يستهلك ClickHouse موارد حوسبة أكبر مقارنةً بالإدراج باستخدام input_format_defaults_for_omitted_fields = 0.

​

استعلام البيانات

لنأخذ جدول UserActivity مثالًا:

┌──────────────UserID─┬─PageViews─┬─Duration─┬─Sign─┐
│ 4324182021466249494 │         5 │      146 │   -1 │
│ 4324182021466249494 │         6 │      185 │    1 │
└─────────────────────┴───────────┴──────────┴──────┘

يُرجع الاستعلام SELECT * FROM UserActivity FORMAT JSONEachRow ما يلي:

{"UserID":"4324182021466249494","PageViews":5,"Duration":146,"Sign":-1}
{"UserID":"4324182021466249494","PageViews":6,"Duration":185,"Sign":1}

على عكس تنسيق JSON، لا تُستبدل تسلسلات UTF-8 غير الصالحة. تُفلت القيم بالطريقة نفسها كما في JSON.

يمكن إخراج أي مجموعة من البايتات في السلاسل النصية. استخدم تنسيق JSONEachRow إذا كنت متأكدًا من أن البيانات الموجودة في الجدول يمكن تنسيقها بصيغة JSON من دون فقدان أي معلومات.

​

استخدام البُنى Nested

إذا كان لديك جدول يحتوي على أعمدة من نوع البيانات Nested، فيمكنك إدراج بيانات JSON بالبنية نفسها. فعِّل هذه الميزة باستخدام الإعداد input_format_import_nested_json.

على سبيل المثال، تأمل الجدول التالي:

Query

CREATE TABLE json_each_row_nested (n Nested (s String, i Int32) ) ENGINE = Memory

كما ترى في وصف نوع البيانات Nested، يتعامل ClickHouse مع كل مكوّن من البنية المتداخلة على أنه عمود منفصل (n.s و n.i في جدولنا). يمكنك إدراج البيانات بالطريقة التالية:

Query

INSERT INTO json_each_row_nested FORMAT JSONEachRow {"n.s": ["abc", "def"], "n.i": [1, 23]}

لإدراج البيانات ككائن JSON هرمي، اضبط input_format_import_nested_json=1.

{
    "n": {
        "s": ["abc", "def"],
        "i": [1, 23]
    }
}

بدون هذا الإعداد، يُطلق ClickHouse استثناءً.

Query

SELECT name, value FROM system.settings WHERE name = 'input_format_import_nested_json'

Response

┌─name────────────────────────────┬─value─┐
│ input_format_import_nested_json │ 0     │
└─────────────────────────────────┴───────┘

Query

INSERT INTO json_each_row_nested FORMAT JSONEachRow {"n": {"s": ["abc", "def"], "i": [1, 23]}}

Response

Code: 117. DB::Exception: Unknown field found while parsing JSONEachRow format: n: (at row 1)

Query

SET input_format_import_nested_json=1
INSERT INTO json_each_row_nested FORMAT JSONEachRow {"n": {"s": ["abc", "def"], "i": [1, 23]}}
SELECT * FROM json_each_row_nested

Response

┌─n.s───────────┬─n.i────┐
│ ['abc','def'] │ [1,23] │
└───────────────┴────────┘

​

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

الإعداد	الوصف	القيمة الافتراضية	ملاحظات
input_format_import_nested_json	ربط بيانات JSON المتداخلة بالجداول المتداخلة (يعمل ذلك مع تنسيق JSONEachRow).	false
input_format_json_read_bools_as_numbers	السماح بقراءة القيم المنطقية كأرقام في تنسيقات إدخال JSON.	true
input_format_json_read_bools_as_strings	السماح بتفسير القيم المنطقية على أنها سلاسل نصية في تنسيقات إدخال JSON.	true
input_format_json_read_numbers_as_strings	السماح بتفسير الأرقام على أنها سلاسل نصية في تنسيقات إدخال JSON.	true
input_format_json_read_arrays_as_strings	السماح بتفسير مصفوفات JSON على أنها سلاسل نصية في تنسيقات إدخال JSON.	true
input_format_json_read_objects_as_strings	السماح بتفسير كائنات JSON على أنها سلاسل نصية في تنسيقات إدخال JSON.	true
input_format_json_named_tuples_as_objects	تحليل أعمدة named tuple على أنها كائنات JSON.	true
input_format_json_try_infer_numbers_from_strings	محاولة استنتاج الأرقام من الحقول النصية أثناء استنتاج المخطط.	false
input_format_json_try_infer_named_tuples_from_objects	محاولة استنتاج named tuple من كائنات JSON أثناء استنتاج المخطط.	true
input_format_json_infer_incomplete_types_as_strings	استخدم النوع String للمفاتيح التي لا تحتوي أثناء استدلال المخطط في تنسيقات إدخال JSON إلا على قيم NULL أو كائنات/مصفوفات فارغة.	true
input_format_json_defaults_for_missing_elements_in_named_tuple	أدرِج القيم الافتراضية للعناصر المفقودة في كائن JSON أثناء تحليل named tuple.	true
input_format_json_ignore_unknown_keys_in_named_tuple	تجاهل المفاتيح غير المعروفة في كائن JSON للـ named Tuples.	false
input_format_json_compact_allow_variable_number_of_columns	السماح بعدد متغيّر من الأعمدة في تنسيق JSONCompact/JSONCompactEachRow، مع تجاهل الأعمدة الإضافية واستخدام القيم الافتراضية للأعمدة المفقودة.	false
input_format_json_throw_on_bad_escape_sequence	إطلاق استثناء إذا كانت سلسلة JSON تحتوي على تسلسل إفلات غير صالح. وإذا كان هذا الخيار معطّلاً، فستبقى تسلسلات الإفلات غير الصالحة كما هي في البيانات.	true
input_format_json_empty_as_default	اعتبار الحقول الفارغة في إدخال JSON قيماً افتراضية.	false.	بالنسبة إلى التعبيرات الافتراضية المعقدة، يجب أيضًا تفعيل input_format_defaults_for_omitted_fields.
output_format_json_quote_64bit_integers	يتحكم في إحاطة الأعداد الصحيحة ذات 64 بت بعلامات اقتباس في تنسيق إخراج JSON.	true
output_format_json_quote_64bit_floats	يتحكم في إحاطة الأعداد ذات الفاصلة العائمة 64 بت بعلامات اقتباس في تنسيق إخراج JSON.	false
output_format_json_quote_denormals	يُمكّن إخراج القيم ‘+nan’ و’-nan’ و’+inf’ و’-inf’ في تنسيق إخراج JSON.	false
output_format_json_quote_decimals	يتحكم في وضع القيم العشرية بين علامتَي اقتباس في تنسيق إخراج JSON.	false
output_format_json_escape_forward_slashes	يتحكم في تهريب الشرطات المائلة للأمام في مخرجات السلاسل النصية ضمن تنسيق إخراج JSON.	true
output_format_json_named_tuples_as_objects	يُسلسِل أعمدة named tuple ككائنات JSON.	true
output_format_json_array_of_rows	يُخرج مصفوفة JSON تضم جميع الصفوف بتنسيق JSONEachRow(Compact).	false
output_format_json_validate_utf8	يُمكّن من التحقق من تسلسلات UTF-8 في تنسيقات إخراج JSON (لاحظ أن هذا لا يؤثر في التنسيقات JSON/JSONCompact/JSONColumnsWithMetadata، إذ تتحقق هذه التنسيقات دائمًا من UTF-8).	false