Kusto Query Language ‏(KQL) في ClickHouse

ما تدعمه لهجة KQL التجريبية وما لا تدعمه عمدًا

يمكن لـ ClickHouse تحليل مجموعة فرعية من Kusto Query Language بدلًا من SQL. هذه اللهجة تجريبية وتكون معطلة افتراضيًا:

SET allow_experimental_kusto_dialect = 1;
SET dialect = 'kusto';

StormEvents
| where State == 'FLORIDA' and DamageProperty > 0
| summarize Total = sum(DamageProperty) by EventType
| top 5 by Total

يُعيد SET dialect = 'clickhouse' التبديل إلى ClickHouse. تُعد SET عبارة SQL الوحيدة التي يُتعرّف عليها أثناء تفعيل لهجة KQL، لذا يمكن للجلسة دائمًا الخروج من هذا الوضع.

​

العناصر المدعومة

هذه مجموعة فرعية محدودة عمدًا. يُترجَم أي تركيب في KQL وفق الدلالات التي يوثّقها Kusto، أو يُرفَض بالاسم مع ظهور خطأ تحليل — ولا تُجرى أي تقريبـات بصمت. إذا أمكن تحليل استعلام، فيُفترض أن تطابق نتيجته نتيجة Kusto’s.

المصادر: اسم جدول، وprint، وdatatable، وrange، وخط أنابيب بين قوسين، وunion. يمتد range من رقم بزيادة رقم، أو من قيمة datetime بزيادة timespan، أو من قيمة timespan بزيادة timespan.

العوامل: where / filter، وextend، وproject، وproject-away، وproject-keep، وproject-rename، وsummarize، وsort by / order by، وtake / limit، وtop، وdistinct، وcount، وmv-expand، وjoin، وunion، وas، وrender.

العوامل القياسية: ==، و!=، و<، و<=، و>، و>=، و=~، و!~، وin، وin~، وbetween، وcontains، وstartswith، وendswith، وhas، وhasprefix، وhassuffix، وصيغها ذات اللاحقة _cs (الحساسة لحالة الأحرف) و! (المنفية)، وhas_any، وhas_all، وmatches regex. يقبل in و!in أيضًا تعبيرًا جدوليًا يوفّر عموده الأول القيم (x in (T | project key))، بينما يقبل in~ قائمة فقط. ويُفسَّر الاسم المنفرد داخل in (...) الذي لا يرتبط بأي let على أنه عمود، لأن المحلّل لا يملك مخططًا يميّز العمود من الجدول؛ اربط الجدول باستخدام let، أو حدده (db.table)، أو أضف خط أنابيب للحصول على الصيغة الجدولية.

العبارات: let، لربط قيمة قياسية، أو تعبير جدولي كامل، أو دالة:

let MultiplyByN = (val: long, n: long = 2) { val * n };
let RecentErrors = (since: timespan) { Logs | where Level == 'Error' and Timestamp > ago(since) };

RecentErrors(1h) | summarize Count = count() by Component

تأخذ الدوال معاملات قياسية بقيم افتراضية حرفية اختيارية، ومعاملات جدولية معلنة بصيغة T: (*) أو T: (col: type, ...) يجب أن ترد أولًا. لا يتيح المعامل الجدولي الذي يُسمّي أعمدته للنص سوى أعمدة الوسيط تلك، لذلك يُرفض نص يقرأ عمودًا غير مُعلن، حتى لو كان الوسيط الفعلي يحتويه؛ أما T: (*) فيمرر الوسيط كما هو. تُفرض الأنواع المعلنة عند حد الاستدعاء: يُرفض وسيط (أو عمود مُعلن لوسيط جدولي) لا يندرج نوعه ضمن نوع KQL المعلن، ويُطبّق تحويل بلا فقدان، مثل تحويل long إلى real، وتُعد القيمة التي لا تلائم النوع المعلن — كتجاوز سعة int مثلًا — خطأً بدلًا من اقتطاعها بصمت. يمكن تمرير الوسائط حسب الاسم وبأي ترتيب (f(c = 7, a = 12)). يتكون النص من أي عدد من عبارات let تتبعها عبارة واحدة، ويمكنه الوصول إلى الارتباطات المحيطة به. الدالة التي يكون نصها خط أنابيب تكون جدولًا لا قيمة، لذا تُرفض حيث يُتوقع تعبير - في extend أو where أو print. يمكن استدعاء الدالة بلا معاملات بأقواس أو بدونها. يُقبل view ()، وبما أنه لا يوجد هنا ما يحل أحرف البدل في union *، فإنه يحمل المعنى نفسه لـ (). يُرفض الاستدعاء الذاتي، كما في Kusto.

يرتبط let بالعبارة التي تليه فقط، لأن عبارة KQL واحدة تقابل استعلام ClickHouse واحدًا — وهذا أيضًا ما يمنع تسرّب الارتباط إلى استعلام متزامن. يجب ربط الاسم الذي تحتاجه عبارتان مرتين.

القيم الحرفية: السلاسل النصية (بما فيها الصيغة الحرفية @'...')، والأرقام، وdatetime(...)، وguid(...)، والفترات الزمنية مثل 1d / 2.5h / 500ms، ومصفوفات dynamic([...]).

تُترجم نحو 130 دالة قياسية وتجميعية. وكما في Kusto، لا يجوز استدعاء الدوال التجميعية إلا في قائمة التجميع ضمن summarize؛ إذ يُرفض print count() بدلًا من تمريره إلى دالة ClickHouse التجميعية التي تحمل الاسم نفسه.

يمكن الوصول إلى دوال ClickHouse أيضًا. يُمرر الاسم الذي لا يعرفه سجل KQL إلى ClickHouse بالتهجئة التي كتبتها، لذا يمكن للاستعلام استخدام أي دالة يتيحها الخادم:

SET dialect = 'kusto';

StormEvents
| extend Bucket = toStartOfHour(StartTime), Fingerprint = cityHash64(EventType)
| summarize Events = count() by Bucket

الاستثناء هو الأسماء التي يعرّفها Kusto نفسه ولا تنفذها هذه اللهجة؛ إذ تُرفض بدلًا من تمريرها، لذلك لا يمكن أن يحمل اسم في Kusto معنى آخر دون تنبيه. وتُعد range أوضح مثال — فـrange(1, 3, 1) تساوي [1, 2, 3] في Kusto و[1, 2] في ClickHouse، لذا فإن استخدامها في KQL يُعد خطأً بدلًا من أن ينتج إجابة خاطئة.

​

مدى التغطية مقارنةً بمرجع Kusto

بالقياس إلى فهارس Microsoft الخاصة (العوامل الجدولية، الدوال القياسية، دوال التجميع):

	مستندات Kusto	المدعوم هنا
العوامل الجدولية	52	20
الدوال القياسية ودوال التجميع	307	162
الدوال المعرّفة من قبل المستخدم	نعم	نعم

تشمل العوامل المدعومة تلك التي يشرحها دليل Microsoft العملي Learn common operators، إضافةً إلى datatable وrange وprint وunion وjoin، وهي كافية لبنية الاستعلامات التي يتدرج في بنائها ذلك الدليل ومرجع KQL السريع.

​

ما لا تدعمه الأداة

تُرفض هذه العناصر بخطأ تحليل بدلًا من ترجمتها ترجمة غير صحيحة:

• العوامل: search وparse وmv-apply وlookup وevaluate وinvoke وfacet، وtop-nested وmake-series وsample وserialize وpartition وrange عند استخدامها كعامل.
• الدوال: عائلة series_*، وbag_* / pack_*، وparse_url وparse_csv، وparse_json وtodynamic وtoscalar وformat_timespan وformat_datetime وextract_all، وrange، وعائلة percentiles* ودوال النافذة row_*. (يُرفض format_datetime وextract_all بدلًا من تقريب سلوكهما: إذ إن محددات التنسيق yyyy-MM-dd في Kusto تختلف عن تلك في ClickHouse، كما أن extract_all في Kusto يعيد مصفوفة لكل مجموعة التقاط.)
• أسماء Kusto التي تتعارض مع دالة في ClickHouse ذات معنى مختلف: range (المذكورة أعلاه)، وrepeat وreplace وtranslate وmaterialize. فتمريرها سيؤدي بصمت إلى حساب شيء مختلف — إذ إن repeat(1, 3) في Kusto هي المصفوفة [1, 1, 1]، بينما تكرر repeat في ClickHouse سلسلة نصية — لذا يُرفض كل منها بالاسم.
• الدوال الجغرافية المكانية التي تأخذ GeoJSON أو تعيده — كل geo_*_to_central_point، وكل ما يعمل على المضلعات والخطوط. دوال النقاط وgeohash وH3 التي تعمل باستخدام خط الطول/خط العرض العاديين مدعومة. أما geo_point_to_s2cell فغير مدعومة: لا يوفّر ClickHouse صيغة رموز S2.
• كائنات dynamic (dynamic({"a": 1}))، والوصول إلى الأعضاء (x.y) والبحث بالمفتاح (x['k']). لا تُعيّن سوى مصفوفات dynamic إلى Array في ClickHouse. كما أن dynamic باعتباره نوعًا مُعلنًا — في مخطط datatable أو typeof(...) أو وسيطة دالة — يُرفض أيضًا: إذ لا يحمل التعليق التوضيحي نوع العنصر، ولذلك لا يوجد ما يمكن تعيينه إليه بدقة.
• المراجع عبر المجموعات وعبر قواعد البيانات، مثل cluster(...) وdatabase(...).
• تلميحات الاستعلام وjoin (hint.strategy وhint.shufflekey و…).
• خيارات العامل: mv-expand ... to typeof(T) / limit N / bagexpansion، وتلميحات summarize، وunion kind= / withsource= / isfuzzy=، وjoin hint.*.
• أنماط الأعمدة ذات المحارف البديلة في project-away وproject-keep (project-away Tmp*): يتطلب توسيعها معرفة المخطط، وهو غير مرئي أثناء التحليل. اذكر الأعمدة صراحةً.
• آلية المكونات الإضافية evaluate بالكامل، ومعها bag_unpack وpivot وnarrow وpython وR وغيرها.
• عبارات التطبيق: alias database وdeclare pattern، وdeclare query_parameters وrestrict access to.
• القيم الحرفية للسلاسل النصية المموهة (h"...") والقيم الحرفية متعددة الأسطر (ثلاث علامات اقتباس عكسية).

​

سلوكيات ينبغي معرفتها

• الفترات الزمنية هي قيم Interval. يتحول 1d إلى toIntervalNanosecond(86400000000000). اضبط interval_output_format = 'kusto' لعرضها بتنسيق Kusto (1.00:00:00) بدلًا من رقم.
• تتبع القسمة سلوك Kusto: تكون نتيجة 7 / 2 هي 3 لأن كلا المعاملين عددان صحيحان، بينما تكون قسمة فترة زمنية على أخرى هي النسبة ذات القيمة الحقيقية بينهما (15ms / 10ms تساوي 1.5). ينفّذ kqlDivide ذلك بالاستناد إلى أنواع الوسيطات.
• يؤدي طرح قيمتي تاريخ ووقت إلى عدد من الثواني، بينما ينتج عنه في Kusto فترة زمنية. وتعمل إضافة فترة زمنية أو طرحها كما هو متوقع.
• يكون sort تنازليًا افتراضيًا، بخلاف SQL، ويضع قيم null في الطرف الأصغر.
• ينقل project-rename العمود المعاد تسميته إلى نهاية الصف. يحتفظ Kusto بموضعه الأصلي؛ وستتطلب محاكاة ذلك معرفة المخطط أثناء التحليل.
• يتطلب union أن تكون للمُعاملات مخططات متوافقة. يوسّع Kusto النتيجة لتشمل اتحاد جميع الأعمدة ويملأ القيم المفقودة بـ null؛ أما UNION ALL في ClickHouse فلا يفعل ذلك.
• عوامل السلاسل النصية هي دوال مطابقة وليست أنماط LIKE. يبحث contains '50%' عن علامة نسبة مئوية حرفية.
• تأخذ geo_* خط الطول قبل خط العرض، كما يفعل Kusto. تستخدم geo_distance_2points دالة greatCircleDistance في ClickHouse، وهي تقريب سريع يختلف عن Kusto عند الرقم المعنوي الرابع — بنحو 600 م على مسافة 1500 كم — ويؤدي use_spheroid = true إلى اختيار geoDistance، وهي صيغة الإهليلج، كما في Kusto. لا يُقصد تحقيق تطابق تام: إذ تُستخدم هذه الدوال عادةً للتصفية لا لإعداد التقارير. لاحظ أن إحداثيًا خارج [-180, 180] أو [-90, 90] ينتج رقمًا بلا معنى بدلًا من قيمة null التي يعيدها Kusto: لا تتحقق أي من دالتي ClickHouse من نطاق وسيطاتها، وسيكلّف التحقق ثماني مقارنات لكل صف.
• تعيد dayofweek() فترة زمنية، لا رقمًا: يوم الاثنين هو 1.00:00:00.
• تعرض tohex() قيمة سالبة بعرض 64 بت. يعرضها Kusto بعرض نوع الوسيط نفسه، وهو ما لا يظهر أثناء التحليل.
• قيم التاريخ والوقت هي قيم DateTime64 حقيقية، لذا تُطبع بتنسيق ClickHouse (2017-01-01 00:00:00) بدلًا من تنسيق Kusto (2017-01-01T00:00:00.0000000). كان التنفيذ السابق ينتج سلسلة نصية منسقة تبدو مثل Kusto، لكنها لا تُقارن أو تُفرز كقيمة تاريخ ووقت.
• دوال التجميع ذات المعلمات في ClickHouse (quantileExact(0.5)(x)) ليس لها صياغة في KQL. استخدم بديلًا مُسمّى مثل medianExact(x).

​

الإبلاغ عن مشكلة

إذا كان الاستعلام يُحلَّل لكنه يُرجع نتيجة لا يُرجعها Kusto، فهذا خلل — يُرجى الإبلاغ عنه مع كلتا النتيجتين. أما الاستعلام الذي يُرفض وتحتاج إليه، فهو طلب ميزة؛ إذ توضح القوائم أعلاه الحدود العامة بدلًا من حصر كل اسم مرفوض — ورسالة خطأ التحليل نفسها هي المرجع النهائي لأي استعلام محدد — ولا شيء من ذلك دائم.