التصورات المستندة إلى SQL

يدعم ClickStack التصورات المستندة إلى استعلامات SQL الخام. ويمنحك هذا تحكمًا كاملًا في منطق الاستعلام، مع الحفاظ على التكامل مع النطاقات الزمنية وعوامل التصفية وعرض المخططات على مستوى لوحة المعلومات.

تكون التصورات المستندة إلى SQL مفيدة عندما تحتاج إلى تجاوز الإمكانات المضمنة في Chart Explorer — على سبيل المثال، لضم الجداول أو إنشاء تجميعات معقدة لا تدعمها أداة إنشاء المخططات.

لإنشاء تصور مستند إلى SQL، افتح محرر بلاطة لوحة المعلومات وحدد علامة التبويب SQL.

ومن هناك:

1. حدد اتصال ClickHouse لتشغيل الاستعلام من خلاله.
2. ويمكنك اختياريًا تحديد مصدر — ما يتيح تطبيق عوامل التصفية على مستوى لوحة المعلومات على تصورك عبر الماكرو $__filters.
3. اكتب استعلام SQL في المحرر، باستخدام معلمات الاستعلام ووحدات الماكرو للتكامل مع النطاق الزمني للوحة المعلومات وعوامل التصفية والمتغيرات.
4. انقر زر play لمعاينة النتائج، ثم Save.

تتيح معلمات الاستعلام لاستعلام SQL الخاص بك الإشارة إلى النطاق الزمني الحالي ومستوى الدقة الحالي في لوحة المعلومات. وهي تستخدم صيغة الاستعلامات ذات المعلمات في ClickHouse: {paramName:Type}.

تعتمد المعلمات المتاحة على نوع المخطط:

المخططات الخطية ومخطط الأعمدة المتراكم:

مخططات الجدول والدائري والرقمي:

وحدات الماكرو هي اختصارات تُستبدل بتعبيرات شائعة في ClickHouse SQL. وتبدأ بالبادئة $__، ويجري استبدالها قبل إرسال الاستعلام إلى ClickHouse.

تعيد وحدات الماكرو هذه تعبيرًا في ClickHouse يمثّل وقت بداية لوحة المعلومات أو وقت انتهائها. ولا تأخذ أي وسيطات.

تُنشئ وحدات الماكرو هذه جزءًا من عبارة WHERE لتصفية عمود وفقًا للنطاق الزمني في لوحة المعلومات.

مثال على التوسيع لـ $__timeFilter(TimestampTime):

TimestampTime >= toDateTime(fromUnixTimestamp64Milli({startDateMilliseconds:Int64}))
AND TimestampTime <= toDateTime(fromUnixTimestamp64Milli({endDateMilliseconds:Int64}))

تُجمِّع وحدات الماكرو هذه عمود طابع زمني ضمن فواصل زمنية تتوافق مع مستوى الدقة في لوحة المعلومات. وتُستخدم عادةً في عبارتي SELECT وGROUP BY لمخططات السلاسل الزمنية. وهي متاحة فقط لتصورات Line وStacked-bar.

مثال على التوسيع لـ $__timeInterval(TimestampTime):

toStartOfInterval(toDateTime(TimestampTime), INTERVAL {intervalSeconds:Int64} second)

عند تحديد مصدر في المخطط وتفعيل عوامل تصفية لوحة المعلومات، يتم توسيع $__filters ليصبح شروط SQL WHERE المقابلة. وعند عدم تحديد أي مصدر أو عدم تطبيق أي عوامل تصفية، يتم توسيعه إلى (1=1)، لذا يكون تضمينه في عبارة WHERE آمنًا دائمًا.

لا يطبق $__filters إلا عوامل التصفية المفعّل فيها شرط عامل تصفية البث. ويُشار صراحةً إلى عوامل التصفية المعروضة كمتغيرات، كما هو موضح أدناه.

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

يمكن أيضًا تضمين قيم المتغير مباشرةً بصيغة $name أو ${name}، مع تنسيق اختياري: ${name:sqlstring} (الافتراضي)، أو ${name:csv}، أو ${name:regex}. في التنسيق الافتراضي، يُنتج المرجع المباشر القيمة NULL قبل تحديد أي قيمة، لذا يُفضَّل استخدام وحدات الماكرو المذكورة أعلاه كلما كان متوقعًا وجود شرط.

يربط ClickStack تلقائيًا أعمدة النتائج بعناصر الرسم البياني استنادًا إلى أنواع الأعمدة. وتختلف قواعد هذا الربط باختلاف نوع الرسم البياني.

تُعرض جميع أعمدة النتائج مباشرةً كأعمدة في الجدول.

يحصي هذا الاستعلام أحداث السجل لكل خدمة، ويجمعها ضمن فترات زمنية تتوافق مع درجة الدقة في لوحة المعلومات.

SELECT
  toStartOfInterval(TimestampTime, INTERVAL {intervalSeconds:Int64} second) AS ts,
  ServiceName,
  count() AS count
FROM otel_logs
WHERE TimestampTime >= fromUnixTimestamp64Milli({startDateMilliseconds:Int64})
  AND TimestampTime < fromUnixTimestamp64Milli({endDateMilliseconds:Int64})
  AND $__filters
GROUP BY ServiceName, ts
ORDER BY ts ASC

• يُستخدَم ts ‏(DateTime) كطابع زمني للمحور السيني.
• تُرسَم count ‏(رقمية) باعتبارها قيمة السلسلة.
• يُنشئ ServiceName ‏(نصي) خطًا منفصلًا لكل خدمة.

الاستعلام نفسه مكتوب باستخدام الماكرو اختصارًا:

SELECT
  $__timeInterval(TimestampTime) AS ts,
  ServiceName,
  count() AS count
FROM otel_logs
WHERE $__timeFilter(TimestampTime)
  AND $__filters
GROUP BY ServiceName, ts
ORDER BY ts ASC

بالنسبة إلى لوحة معلومات تتضمن المتغير service لـ ServiceName والمتغير severity لـ SeverityText، يحصر هذا الاستعلام المخطط في اختيار الخدمة الحالي ويستبعد مستويات الخطورة المحددة. يتوسع كلا الماكروين إلى 1=1 عندما لا تكون لمتغيراتهما قيمة محددة، لذا يُعرض المخطط دون تصفية إلى أن يختار المستخدم قيمة.

SELECT
  $__timeInterval(TimestampTime) AS ts,
  count() AS count
FROM otel_logs
WHERE $__timeFilter(TimestampTime)
  AND $__filter(ServiceName, $service)
  AND $__conditionalAll(SeverityText NOT IN ($severity), $severity)
GROUP BY ts
ORDER BY ts ASC

SELECT
  $__timeInterval(TimestampTime) AS ts,
  lower(SeverityText),
  count() AS count
FROM otel_logs
WHERE $__timeFilter(TimestampTime)
  AND lower(SeverityText) IN ('error', 'warn')
  AND $__filters
GROUP BY SeverityText, ts
ORDER BY ts ASC

SELECT
  SpanName AS endpoint,
  avg(Duration) / 1000 AS avg_duration_ms,
  count() AS request_count
FROM otel_traces
WHERE $__timeFilter(Timestamp)
  AND $__filters
GROUP BY SpanName
ORDER BY avg_duration_ms DESC
LIMIT 10

SELECT
  ServiceName,
  count() AS request_count
FROM otel_traces
WHERE $__timeFilter(Timestamp)
  AND $__filters
GROUP BY ServiceName

• request_count (رقمي) يحدّد حجم كل شريحة.
• ServiceName (سلسلة نصية) يحدّد تسمية كل شريحة.

SELECT
  count() AS total_errors
FROM otel_logs
WHERE $__timeFilter(TimestampTime)
  AND SeverityText = 'error'
  AND $__filters

تُعرض القيمة الرقمية الوحيدة total_errors من الصف الأول.

• تُنفَّذ التصورات المستندة إلى SQL مع تفعيل وضع readonly — ولا يُسمح إلا باستعلامات SELECT.
• يجب أن تكون التصورات المستندة إلى SQL عبارة عن استعلام SQL واحد فقط - فالاستعلامات المتعددة غير مدعومة.
• يوفّر محرر SQL اقتراحات للإكمال التلقائي لكلٍّ من معلمات الاستعلام ووحدات الماكرو.
• يجب تحديد مصدر لتطبيق عوامل تصفية لوحة المعلومات على التصورات المستندة إلى SQL. وينبغي أن يطابق المصدر الجدول الذي يُجرى عليه الاستعلام لضمان دقة التصفية.
• لا تحتاج متغيرات لوحة المعلومات إلى مصدر — إذ تأتي القيم من القوائم المنسدلة لعوامل تصفية لوحة المعلومات، لا من مصدر البلاطة نفسه.
• تُقيَّم التنبيهات على بلاطة SQL الذي يشير إلى متغير في لوحة المعلومات بحيث تكون جميع المتغيرات في حالتها الفارغة، لا بالقيم المحددة في لوحة المعلومات.