منشئ الاستعلامات

استخدام منشئ الاستعلامات في الإضافة ClickHouse لـ Grafana

يمكن تشغيل أي query باستخدام إضافة ClickHouse. يُعد منشئ الاستعلامات خيارًا مناسبًا للاستعلامات الأبسط، لكنك ستحتاج إلى استخدام محرر SQL عند التعامل مع الاستعلامات المعقدة.

تتضمن جميع الاستعلامات في منشئ الاستعلامات نوع استعلام، كما تتطلب تحديد عمود واحد على الأقل.

أنواع الاستعلامات المتاحة هي:

• الجدول: أبسط أنواع الاستعلامات لعرض البيانات بتنسيق جدول. وهو مناسب كخيار عام للاستعلامات البسيطة والمعقدة التي تتضمن دوالًا تجميعية.
• السجلات: مُحسَّن لإنشاء استعلامات السجلات. ويعمل بأفضل شكل في عرض Explore مع تهيئة الإعدادات الافتراضية.
• السلاسل الزمنية: الأنسب لإنشاء استعلامات السلاسل الزمنية. ويتيح تحديد عمود زمني مخصص وإضافة دوال تجميعية.
• التتبعات: مُحسَّن للبحث في التتبعات وعرضها. ويعمل بأفضل شكل في عرض Explore مع تهيئة الإعدادات الافتراضية.
• محرر SQL: يمكن استخدام محرر SQL عندما تريد تحكمًا كاملاً في الاستعلام. في هذا الوضع، يمكن تنفيذ أي SQL query.

​

أنواع الاستعلامات

سيؤدي إعداد نوع الاستعلام إلى تغيير تخطيط أداة إنشاء الاستعلامات ليتوافق مع نوع الاستعلام الذي يتم إنشاؤه. ويحدد نوع الاستعلام أيضًا اللوحة المستخدمة عند عرض البيانات بصريًا.

​

جدول

أكثر أنواع الاستعلامات مرونة هو استعلام الجدول. وهو بمثابة نوع عام يشمل منشئات الاستعلامات الأخرى المصممة للتعامل مع الاستعلامات البسيطة والتجميعية.

حقل	الوصف
وضع المُنشئ	تستبعد الاستعلامات البسيطة التجميعات وGroup By، بينما تتضمن الاستعلامات التجميعية هذين الخيارين.
الأعمدة	الأعمدة المحددة. يمكن إدخال Raw SQL في هذا الحقل لإتاحة استخدام الدوال والأسماء المستعارة للأعمدة.
التجميعات	قائمة من الدوال التجميعية. تتيح تحديد قيم مخصصة للدالة والعمود. لا تظهر إلا في وضع Aggregate.
Group By	قائمة من تعبيرات GROUP BY. لا تظهر إلا في وضع Aggregate.
Order By	قائمة من تعبيرات ORDER BY.
Limit	يُضيف عبارة LIMIT إلى نهاية الاستعلام. إذا تم ضبطه على 0 فسيتم استبعاده. قد تحتاج بعض المرئيات إلى ضبطه على 0 لعرض جميع البيانات.
عوامل تصفية	قائمة بعوامل تصفية ستُطبَّق في عبارة WHERE.

سيعرض نوع الاستعلام هذا البيانات في شكل جدول.

​

السجلات

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

تُضاف عوامل التصفية Time وLevel افتراضيًا، إلى جانب Order By لعمود Time. وترتبط عوامل التصفية هذه بالحقول المقابلة لها، ويتم تحديثها عند تغيير الأعمدة. ويُستبعَد عامل التصفية Level من SQL افتراضيًا، وسيؤدي تغييره من الخيار IS ANYTHING إلى تمكينه.

يدعم نوع استعلام السجلات روابط البيانات.

الحقل	الوصف
Use OTel	يفعّل أعمدة OpenTelemetry. وسيستبدل الأعمدة المحددة لاستخدام الأعمدة المعرّفة بواسطة إصدار مخطط OTel المحدد (ويعطّل تحديد الأعمدة).
الأعمدة	أعمدة إضافية تُضاف إلى صفوف السجل. ويمكن إدخال Raw SQL في هذا الحقل للسماح باستخدام الدوال وcolumn aliasing.
Time	عمود الطابع الزمني الأساسي للسجل. يعرض الأنواع الشبيهة بالوقت، كما يتيح استخدام قيم/دوال مخصّصة.
مستوى السجل	اختياري. المستوى أو الشدّة الخاصة بالسجل. تكون القيم عادةً مثل INFO وerror وDebug وما إلى ذلك.
الرسالة	محتوى رسالة السجل.
Order By	قائمة بتعبيرات ORDER BY.
الحد	يضيف عبارة LIMIT إلى نهاية الاستعلام. وإذا ضُبطت القيمة على 0، فسيُستبعَد، لكن لا يُنصح بذلك مع مجموعات بيانات السجلات الكبيرة.
عوامل التصفية	قائمة بعوامل التصفية التي ستُطبَّق في عبارة WHERE.
تصفية الرسالة	حقل إدخال نصي لتصفية السجلات بسهولة باستخدام LIKE %value%. ويُستبعَد عندما يكون الإدخال فارغًا.

سيعرض نوع الاستعلام هذا البيانات في لوحة السجلات، إلى جانب لوحة المدرج التكراري للسجلات في الأعلى.

يمكن عرض الأعمدة الإضافية المحددة في الاستعلام ضمن صف السجل الموسّع:

​

سلاسل زمنية

يشبه نوع استعلام السلاسل الزمنية الجدول، لكنه يركز على بيانات السلاسل الزمنية.

العرضان متشابهان إلى حد كبير، مع هذه الاختلافات البارزة:

• حقل Time مخصص.
• في وضع Aggregate mode، يُطبَّق تلقائيًا ماكرو للفاصل الزمني مع Group By لحقل Time.
• في وضع Aggregate mode، يكون حقل “Columns” مخفيًا.
• يُضاف تلقائيًا عامل تصفية للنطاق الزمني وOrder By لحقل Time.

هل ينقص التصور البياني بعض البيانات؟

في بعض الحالات، قد تبدو لوحة السلاسل الزمنية وكأنها مقصوصة لأن القيمة الافتراضية للحد هي 1000.

جرّب إزالة عبارة LIMIT بتعيينها إلى 0 (إذا كانت مجموعة البيانات لديك تسمح بذلك).

الحقل	الوصف
Builder Mode	تستبعد الاستعلامات البسيطة Aggregates وGroup By، بينما تتضمن الاستعلامات التجميعية هذين الخيارين.
Time	عمود الوقت الأساسي للاستعلام. يعرض الأنواع الشبيهة بالوقت، كما يتيح استخدام قيم/دوال مخصصة.
Columns	الأعمدة المحددة. يمكن كتابة Raw SQL في هذا الحقل للسماح باستخدام الدوال والأسماء المستعارة للأعمدة. يظهر فقط في Simple mode.
Aggregates	قائمة من aggregate functions. تتيح قيمًا مخصصة للدالة والعمود. تظهر فقط في Aggregate mode.
Group By	قائمة من تعبيرات GROUP BY. تظهر فقط في Aggregate mode.
Order By	قائمة من تعبيرات ORDER BY.
Limit	يضيف عبارة LIMIT إلى نهاية الاستعلام. وإذا ضُبطت قيمته على 0، فسيُستبعد، ويُنصح بذلك لبعض مجموعات بيانات السلاسل الزمنية لعرض التصور البياني كاملًا.
عوامل تصفية	قائمة بعوامل تصفية ستُطبَّق في عبارة WHERE.

يعرض نوع الاستعلام هذا البيانات باستخدام لوحة السلاسل الزمنية.

​

التتبعات

يوفّر نوع استعلام التتبّع منشئ الاستعلامات لتسهيل البحث في التتبعات وعرضها. وهو مصمَّم لبيانات OpenTelemetry، لكن يمكن تحديد الأعمدة لعرض التتبعات من مخطط مختلف. يمكن تهيئة القيم الافتراضية في إعدادات التتبّع الخاصة بمصدر البيانات، بحيث يتم تحميل منشئ الاستعلامات مسبقًا بقاعدة بيانات/جدول وأعمدة افتراضية. وإذا تم تكوين القيم الافتراضية، فسيُطوى قسم اختيار الأعمدة افتراضيًا. كما يمكن تفعيل OpenTelemetry لتحديد الأعمدة تلقائيًا وفقًا لإصدار المخطط.

تُضاف عوامل التصفية الافتراضية بهدف إظهار spans ذات المستوى الأعلى فقط. ويتم أيضًا تضمين ORDER BY لعمودي Time وDuration Time. وترتبط عوامل التصفية هذه بالحقول المقابلة لها، وستتحدّث عند تغيير الأعمدة. ويُستبعَد عامل التصفية Service Name من SQL افتراضيًا، وسيؤدي تغييره من الخيار IS ANYTHING إلى تفعيله.

يدعم نوع استعلام التتبّع روابط البيانات.

الحقل	الوصف
وضع التتبّع	يغيّر الاستعلام من Trace Search إلى lookup لمعرّف التتبّع معرّف التتبّع.
Use OTel	يفعّل أعمدة OpenTelemetry. وسيستبدل الأعمدة المحددة لاستخدام الأعمدة المعرّفة بواسطة إصدار مخطط OTel المحدد (ويعطّل اختيار الأعمدة).
عمود معرّف التتبّع	معرّف التتبّع.
عمود معرّف span	معرّف span.
عمود معرّف span الأب	معرّف span الأب. ويكون هذا عادةً فارغًا في التتبعات ذات المستوى الأعلى.
عمود اسم الخدمة	اسم الخدمة.
عمود اسم العملية	اسم العملية.
عمود وقت البدء	عمود الوقت الأساسي لـ trace span. وهو الوقت الذي بدأ فيه span.
عمود مدة الزمن	مدة span. يتوقع Grafana افتراضيًا أن تكون هذه قيمة float بالمللي ثانية. ويُطبَّق التحويل تلقائيًا عبر القائمة المنسدلة Duration Unit.
وحدة المدة	وحدة الزمن المستخدمة للمدة. تكون النانوثانية افتراضيًا. وستُحوَّل الوحدة المحددة إلى قيمة float بالمللي ثانية كما يتطلب Grafana.
عمود Tags	Tags الخاصة بـ span. استبعد هذا إذا كنت لا تستخدم مخططًا قائمًا على OTel، لأنه يتوقع نوع عمود Map محددًا.
عمود Tags الخدمة	Tags الخاصة بالخدمة. استبعد هذا إذا كنت لا تستخدم مخططًا قائمًا على OTel، لأنه يتوقع نوع عمود Map محددًا.
ORDER BY	قائمة من expressions الخاصة بـ ORDER BY.
Limit	يُلحِق statement ‏LIMIT بنهاية الاستعلام. وإذا ضُبطت القيمة على 0 فسيُستبعَد، لكن لا يُنصح بذلك مع مجموعات بيانات التتبّع الكبيرة.
عوامل التصفية	قائمة بعوامل التصفية التي ستُطبَّق في clause ‏WHERE.
معرّف التتبّع	معرّف التتبّع المطلوب التصفية وفقه. يُستخدم فقط في وضع معرّف التتبّع، وعند فتح رابط بيانات لمعرّف التتبّع.

سيعرض نوع الاستعلام هذا البيانات باستخدام عرض الجدول في وضع Trace Search، وباستخدام لوحة التتبّع في وضع معرّف التتبّع.

​

محرر SQL

بالنسبة إلى الاستعلامات شديدة التعقيد التي لا تناسب منشئ الاستعلامات، يمكنك استخدام محرر SQL. يمنحك ذلك تحكمًا كاملًا في الاستعلام، إذ يتيح لك كتابة ClickHouse SQL مباشرةً وتشغيله.

يمكن فتح محرر SQL باختيار “SQL Editor” من أعلى محرر الاستعلامات.

لا يزال بإمكانك استخدام دوال الماكرو في هذا الوضع.

يمكنك التبديل بين أنواع الاستعلامات للحصول على العرض المرئي الأنسب لاستعلامك. ويؤثر هذا التبديل أيضًا في عرض لوحة المعلومات، ولا سيما عند التعامل مع بيانات السلاسل الزمنية.

​

روابط البيانات

يمكن استخدام روابط البيانات في Grafana للربط باستعلامات جديدة. تم تمكين هذه الميزة ضمن إضافة ClickHouse لربط trace بالسجلات والعكس صحيح. وهي تعمل بأفضل شكل عند تهيئة OpenTelemetry لكلٍّ من السجلات وtraces في إعدادات مصدر البيانات

مثال على روابط trace في جدول

مثال على روابط trace في السجلات

​

كيفية إنشاء رابط بيانات

يمكنك إنشاء رابط بيانات عبر تحديد عمود باسم traceID في الاستعلام. هذا الاسم لا يميّز بين الأحرف الكبيرة والصغيرة، كما يدعم إضافة شرطة سفلية قبل “ID”. على سبيل المثال: traceId وTraceId وTRACE_ID وtracE_iD كلها صيغ صالحة.

إذا كان OpenTelemetry مفعّلًا في استعلام السجلات أو التتبّع، فسيُدرج عمود معرّف التتبّع تلقائيًا.

عند وجود عمود لمعرّف التتبّع، يمكن للإضافة إرفاق رابطَي “عرض التتبّع” و”عرض السجلات” بالبيانات.

تكون أزرار التبديل مفعّلة افتراضيًا. لا يتطلب رابط نوع الاستعلام الحالي إعدادات افتراضية مهيّأة، بينما لا يظهر الرابط بين الإشارات إلا إذا كانت الإعدادات الافتراضية لإشارة الهدف مهيّأة في مصدر البيانات. يمكنك إخفاؤها باستخدام زري التبديل إظهار روابط “عرض التتبّع” وإظهار روابط “عرض السجلات” في قسمي تهيئة التتبّع والسجلات لمصدر البيانات.

​

قدرات الربط

عند توفر روابط البيانات، يمكنك فتح التتبّعات والسجلات باستخدام معرّف التتبّع المتاح.

سيؤدي “عرض التتبّع” إلى فتح لوحة منقسمة تتضمن التتبّع، بينما سيؤدي “عرض السجلات” إلى فتح استعلام سجلات مُرشَّحًا بحسب معرّف التتبّع. إذا نُقر على الرابط من لوحة معلومات بدلًا من عرض Explore، فسيُفتح الرابط في علامة تبويب جديدة ضمن عرض Explore.

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

مثال على عرض تتبّع (اللوحة اليمنى) من استعلام سجلات (اللوحة اليسرى)

​

وحدات الماكرو

تُعد وحدات الماكرو طريقة بسيطة لإضافة SQL ديناميكي إلى استعلامك. وقبل إرسال الاستعلام إلى خادم ClickHouse، تعمل الإضافة على توسيع الماكرو واستبداله بالتعبير الكامل.

يمكن للاستعلامات الواردة من كلٍّ من SQL Editor وQuery Builder استخدام وحدات الماكرو.

​

استخدام وحدات الماكرو

يمكن استخدام وحدات الماكرو في أي مكان داخل الاستعلام، وتكرارها عند الحاجة.

فيما يلي مثال على استخدام الماكرو $__timeFilter:

الإدخال:

SELECT log_time, log_message
FROM logs
WHERE $__timeFilter(log_time)

ناتج الاستعلام النهائي:

SELECT log_time, log_message
FROM logs
WHERE log_time >= toDateTime(1415792726) AND log_time <= toDateTime(1447328726)

في هذا المثال، يُطبَّق النطاق الزمني في لوحة معلومات Grafana على العمود log_time.

يدعم المكوّن الإضافي أيضًا الصياغة باستخدام الأقواس المعقوفة {}. استخدم هذه الصياغة عندما تحتاج إلى استعلامات داخل المعلمات.

​

قائمة وحدات الماكرو

هذه قائمة بجميع وحدات الماكرو المتاحة في المكوّن الإضافي:

Macro	الوصف	مثال على المخرجات
$__dateFilter(columnName)	يُستبدل بمرشّح نطاق زمني على العمود المحدد باستخدام النطاق الزمني للوحة Grafana كـ Date.	columnName >= toDate('2022-10-21') AND columnName <= toDate('2022-10-23')
$__timeFilter(columnName)	يُستبدل بمرشّح نطاق زمني على العمود المحدد باستخدام النطاق الزمني للوحة Grafana كـ DateTime.	columnName >= toDateTime(1415792726) AND time <= toDateTime(1447328726)
$__timeFilter_ms(columnName)	يُستبدل بمرشّح نطاق زمني على العمود المحدد باستخدام النطاق الزمني للوحة Grafana كـ DateTime64.	columnName >= fromUnixTimestamp64Milli(1415792726123) AND columnName <= fromUnixTimestamp64Milli(1447328726456)
$__dateTimeFilter(dateColumn, timeColumn)	صيغة مختصرة تجمع بين $__dateFilter() و$__timeFilter() باستخدام عمودَي Date وDateTime منفصلين. الاسم البديل: $__dt()	$__dateFilter(dateColumn) AND $__timeFilter(timeColumn)
$__fromTime	يُستبدل بوقت بداية نطاق لوحة Grafana بعد تحويله إلى DateTime.	toDateTime(1415792726)
$__fromTime_ms	يُستبدل بوقت بداية نطاق اللوحة بعد تحويله إلى DateTime64.	fromUnixTimestamp64Milli(1415792726123)
$__toTime	يُستبدل بوقت نهاية نطاق لوحة Grafana بعد تحويله إلى DateTime.	toDateTime(1447328726)
$__toTime_ms	يُستبدل بوقت نهاية نطاق اللوحة بعد تحويله إلى DateTime64.	fromUnixTimestamp64Milli(1447328726456)
$__timeInterval(columnName)	يُستبدل بدالة تحسب الفاصل الزمني استنادًا إلى حجم النافذة بالثواني.	toStartOfInterval(toDateTime(columnName), INTERVAL 20 second)
$__timeInterval_ms(columnName)	يُستبدل بدالة تحسب الفاصل الزمني استنادًا إلى حجم النافذة بالمللي ثانية.	toStartOfInterval(toDateTime64(columnName, 3), INTERVAL 20 millisecond)
$__interval_s	يُستبدل بفاصل لوحة المعلومات بالثواني.	20
$__conditionalAll(condition, $templateVar)	يُستبدل بالمعامل الأول عندما لا يحدّد متغير القالب في المعامل الثاني جميع القيم، ويُستبدل بـ 1=1 عندما يحدّد متغير القالب جميع القيم.	condition أو 1=1