دليل تشغيل: مخطط JSON

تصل بياناتك بصيغة JSON. يوفّر ClickHouse عدة طرق لتخزينها، بدءًا من الأعمدة ذات الأنواع المحددة بالكامل وصولًا إلى String الخام. ويعتمد الاختيار المناسب على مدى ثبات مخططك، وما إذا كنت تحتاج إلى استعلامات على مستوى الحقول.

النطاق: تغطي هذه الصفحة قرارات تصميم المخطط الخاصة بتخزين بيانات JSON. ولا تغطي تنسيقات إدخال/إخراج JSON، أو دوال JSON، أو بنية الاستعلام. وللاطلاع على مزيد من المعلومات حول نوع العمود JSON نفسه، راجع استخدم JSON حيثما كان مناسبًا.

يفترض: الإلمام بـ إنشاء جداول ClickHouse، وأساسيات MergeTree، وبنية أنواع الأعمدة.

• إذا كان لكل حقل نوع معروف ومستقر، وكان المخطط نادر التغيّر → أعمدة محددة النوع
• إذا كانت معظم الحقول مستقرة، لكن بعض الأجزاء ديناميكيًا أو غير متوقع → هجين (أعمدة محددة النوع + JSON)
• إذا كانت البنية بأكملها ديناميكية، مع مفاتيح تظهر وتختفي بين السجلات → عمود JSON أصلي
• إذا كانت الحقول الديناميكية أزواج مفتاح-قيمة ذات نوع قيمة متسق (مثل tags النصية وmetrics الرقمية) → Map بدلًا من JSON
• إذا كنت تخزّن وتسترجع blob ‏JSON فقط من دون استعلامات على مستوى الحقل → تخزين String غير مُفسَّر

متى تُستخدم: تكون بنية JSON معروفة بالكامل وقت التصميم. ولا تتغير الحقول والأنواع من سجل إلى آخر. ويمكن حتى تمثيل البُنى المتداخلة المعقدة (مثل مصفوفات الكائنات والخرائط المتداخلة) باستخدام الأنواع Array وTuple وNested.

الاعتبارات: تتطلب تغييرات المخطط استخدام ALTER TABLE. كما تُهمَل الحقول غير المتوقعة بصمت عند الإدراج ما لم يتم تحديث المخطط.

CREATE TABLE events
(
    `timestamp` DateTime,
    `service`   LowCardinality(String),
    `level`     Enum8('DEBUG' = 1, 'INFO' = 2, 'WARN' = 3, 'ERROR' = 4),
    `message`   String,
    `host`      LowCardinality(String),
    `duration_ms` UInt32
)
ENGINE = MergeTree
ORDER BY (service, timestamp)

-- تأكد من أن أنواع الأعمدة تطابق المتوقع
DESCRIBE TABLE events FORMAT Vertical

-- أدرِج بيانات واستعلم للتحقق من أن المخطط يتعامل مع بياناتك
INSERT INTO events FORMAT JSONEachRow
{"timestamp":"2025-03-19 10:00:00","service":"api","level":"INFO","message":"request handled","host":"node-1","duration_ms":42}

SELECT service, level, duration_ms FROM events WHERE service = 'api'

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

المفاضلات: تحصل على الأداء الكامل في الأعمدة محددة النوع، مع مرونة في عمود JSON. لكن عمود JSON يظل يضيف عبئًا عند insert وتكلفة تخزين لجزئه الديناميكي.

CREATE TABLE events
(
    `timestamp`  DateTime,
    `service`    LowCardinality(String),
    `level`      Enum8('DEBUG' = 1, 'INFO' = 2, 'WARN' = 3, 'ERROR' = 4),
    `message`    String,
    `host`       LowCardinality(String),
    `duration_ms` UInt32,
    `attributes` JSON(
        max_dynamic_paths = 256,
        `http.status_code` UInt16,
        `http.method` LowCardinality(String),
        SKIP REGEXP 'debug\..*'
    )
)
ENGINE = MergeTree
ORDER BY (service, timestamp)

-- أدرج بيانات نموذجية وافحص المسارات المستنتجة
INSERT INTO events FORMAT JSONEachRow
{"timestamp":"2025-03-19 10:00:00","service":"api","level":"INFO","message":"request handled","host":"node-1","duration_ms":42,"attributes":{"http.status_code":200,"http.method":"GET","user.region":"eu-west","custom_tag":"abc"}}

SELECT JSONAllPathsWithTypes(attributes)
FROM events
FORMAT PrettyJSONEachRow

متى يُستخدم: عندما تكون البنية غير قابلة للتنبؤ فعلًا، مع مفاتيح تظهر وتختفي بين السجلات. مثل المخططات التي ينشئها المستخدمون، أو أنظمة الملحقات، أو استيعاب البيانات في data lake عندما لا تتحكم في المخطط upstream.

المفاضلات: تكون عمليات الإدراج أبطأ من الأعمدة محددة النوع. كما أن قراءات الكائن الكامل أبطأ من String. وهناك عبء تخزيني إضافي ناتج عن إدارة الأعمدة الفرعية. لكنه يعمل جيدًا مع الاستعلامات على مستوى الحقول لمسارات محددة.

CREATE TABLE dynamic_events
(
    `id`   UInt64,
    `ts`   DateTime DEFAULT now(),
    `data` JSON(
        max_dynamic_paths = 512,
        `event_type` LowCardinality(String),
        `version` UInt8
    )
)
ENGINE = MergeTree
ORDER BY (data.event_type, ts)

INSERT INTO dynamic_events (id, data) FORMAT JSONEachRow
{"id": 1, "data": {"event_type": "click", "version": 2, "page": "/home", "button_id": "cta-1"}}
{"id": 2, "data": {"event_type": "purchase", "version": 1, "item_id": "SKU-99", "amount": 49.99, "currency": "USD"}}

-- تحقّق من المسارات التي اكتشفها ClickHouse وأنواعها
SELECT JSONAllPathsWithTypes(data) FROM dynamic_events FORMAT PrettyJSONEachRow

-- الاستعلام عن مسار محدد
SELECT data.page FROM dynamic_events WHERE data.event_type = 'click'

متى يُستخدم: تُخزَّن مستندات JSON وتُسترجَع كاملةً، ثم تُمرَّر إلى تطبيق، أو تُؤرشف، أو تُوجَّه إلى أنظمة لاحقة. لا توجد تصفية على مستوى الحقول أو تجميع داخل ClickHouse.

المفاضلات: أسرع عمليات إدراج وأبسط مخطط. لا توجد استعلامات على مستوى الحقول من دون تحليل وقت التشغيل (عائلة JSONExtract)، وهذا يكون بطيئًا عند التوسّع.

CREATE TABLE raw_events
(
    `id`        UInt64,
    `received`  DateTime DEFAULT now(),
    `payload`   String
)
ENGINE = MergeTree
ORDER BY (received)

INSERT INTO raw_events (id, payload) VALUES
(1, '{"type":"click","page":"/home"}'),
(2, '{"type":"purchase","item":"SKU-99","amount":49.99}')

-- تأكيد سلامة البيانات بعد الكتابة ثم القراءة
SELECT payload FROM raw_events WHERE id = 1

-- التحقق من أنه لا يزال بإمكانك تحليل الحقول عند الحاجة بشكل مخصص
SELECT JSONExtractString(payload, 'type') AS event_type FROM raw_events

إذا كانت حقولك الديناميكية تتكوّن من أزواج مفتاح-قيمة متجانسة — أي إن جميع القيم من النوع نفسه — فإن Map(String, T) أبسط وأكثر كفاءة من عمود JSON. ومن الأمثلة الشائعة: الوسوم النصية (Map(String, String))، والمقاييس العددية (Map(String, Float64))، أو مفاتيح تفعيل الميزات (Map(String, Bool)).

CREATE TABLE tagged_events
(
    `timestamp` DateTime,
    `service`   LowCardinality(String),
    `tags`      Map(String, String)  -- e.g., {"env": "prod", "region": "us-east-1", "team": "platform"}
)
ENGINE = MergeTree
ORDER BY (service, timestamp)

يدعم Map التصفية على مستوى المفاتيح (tags['env'] = 'prod')، وتكلفة تخزينه أقل من JSON، كما يتجنب الكلفة الإضافية للأعمدة الفرعية في نوع JSON. لاحظ أن عمليات البحث عن المفاتيح تفحص الخريطة خطيًا افتراضيًا — وهذا مناسب لمجموعات الوسوم الصغيرة، ولكن إذا كانت خرائط Map تحتوي على أكثر من 100 مفتاح، ففكّر في استخدام تسلسل with_buckets. استخدم JSON عندما تكون القيم من أنواع مختلطة أو عندما تكون البنية متداخلة — واستخدم Map عندما تكون البيانات أزواج مفتاح-قيمة مسطحة ذات نوع قيم موحّد.

• استخدم JSON حيثما كان مناسبًا — متى تستخدم نوع عمود JSON بدلًا من الخيارات الأخرى
• مرجع نوع بيانات JSON — الصياغة الكاملة لتلميحات الأنواع، وSKIP، وmax_dynamic_paths، ودوال الاستبطان
• اختيار أنواع البيانات — إرشادات عامة لاختيار النوع المناسب
• A New Powerful JSON Data Type for ClickHouse — شرح متعمق لمعمارية تخزين نوع JSON
• مرجع تنسيقات JSON — تنسيقات الإدخال/الإخراج لبيانات JSON ‏(JSONEachRow وJSONAsObject وما إلى ذلك)