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

إنشاء تصورات باستخدام استعلامات SQL في ClickStack

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

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

​

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

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

ومن هناك:

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

​

معلمات الاستعلام

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

​

المعلمات المتاحة

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

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

المعلمة	النوع	الوصف
{startDateMilliseconds:Int64}	Int64	بداية النطاق الزمني للوحة المعلومات (بالمللي ثانية منذ epoch)
{endDateMilliseconds:Int64}	Int64	نهاية النطاق الزمني للوحة المعلومات (بالمللي ثانية منذ epoch)
{intervalSeconds:Int64}	Int64	حجم الفئة الزمنية بالثواني (استنادًا إلى مستوى التفصيل)
{intervalMilliseconds:Int64}	Int64	حجم الفئة الزمنية بالمللي ثانية (استنادًا إلى مستوى التفصيل)

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

المعلمة	النوع	الوصف
{startDateMilliseconds:Int64}	Int64	بداية النطاق الزمني للوحة المعلومات (بالمللي ثانية منذ epoch)
{endDateMilliseconds:Int64}	Int64	نهاية النطاق الزمني للوحة المعلومات (بالمللي ثانية منذ epoch)

​

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

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

​

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

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

الماكرو	يتم توسيعه إلى	نوع العمود
$__fromTime	toDateTime(fromUnixTimestamp64Milli({startDateMilliseconds:Int64}))	DateTime
$__toTime	toDateTime(fromUnixTimestamp64Milli({endDateMilliseconds:Int64}))	DateTime
$__fromTime_ms	fromUnixTimestamp64Milli({startDateMilliseconds:Int64})	DateTime64
$__toTime_ms	fromUnixTimestamp64Milli({endDateMilliseconds:Int64})	DateTime64
$__interval_s	{intervalSeconds:Int64}	Int64

​

وحدات الماكرو لتصفية الوقت

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

Macro	Description
$__timeFilter(column)	يصفّي عمود DateTime وفقًا للنطاق الزمني في لوحة المعلومات
$__timeFilter_ms(column)	يصفّي عمود DateTime64 (بالملي ثانية) وفقًا للنطاق الزمني في لوحة المعلومات
$__dateFilter(column)	يصفّي عمود Date وفقًا للنطاق الزمني في لوحة المعلومات
$__dateTimeFilter(dateCol, timeCol)	يصفّي باستخدام عمودي Date وDateTime منفصلين
$__dt(dateCol, timeCol)	اسم مستعار لـ $__dateTimeFilter

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

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

​

وحدات ماكرو للفواصل الزمنية

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

Macro	Description
$__timeInterval(column)	يُجمِّع عمود DateTime ضمن فواصل زمنية بقيمة intervalSeconds
$__timeInterval_ms(column)	يُجمِّع عمود DateTime64 ضمن فواصل زمنية بقيمة intervalMilliseconds

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

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

​

ماكرو تصفية لوحة المعلومات

الماكرو	الوصف
$__filters	يُستبدل بشروط التصفية على مستوى لوحة المعلومات (يتطلب تحديد مصدر)

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

​

كيفية عرض نتائج الاستعلام بيانيًا

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

​

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

الدور	نوع العمود	الوصف
الطابع الزمني	أول عمود Date أو DateTime	يُستخدم بوصفه المحور السيني.
قيمة السلسلة	جميع الأعمدة الرقمية	يُرسَم كل عمود رقمي كسلسلة منفصلة. وعادةً ما تكون هذه قيمًا مُجمَّعة.
أسماء المجموعات	أعمدة String أو Map أو Array	اختياري. تُرسَم الصفوف التي تختلف فيها قيم المجموعات كسلاسل منفصلة.

​

المخطط الدائري

الدور	نوع العمود	الوصف
قيمة الشريحة	أول عمود رقمي	يحدد حجم كل شريحة.
تسمية الشريحة	أعمدة String أو Map أو Array	اختياري. تتحول كل قيمة فريدة إلى تسمية لشريحة.

​

مخطط عددي

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

​

مخطط جدولي

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

​

أمثلة

مطلوب الوصول إلى جدول النظام

ستحتاج إلى تحديد otel_v2.otel_logs أو otel_v2.otel_traces إذا كنت تشغّل الأمثلة التالية على play-clickstack.clickhouse.com.

​

مخطط خطي — عدد السجلات عبر الزمن حسب الخدمة

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

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

​

مخطط أعمدة مكدّس — عدد الأخطاء حسب مستوى الخطورة

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

​

مخطط جدولي — أبطأ 10 نقاط نهاية

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. وينبغي أن يطابق المصدر الجدول الذي يُجرى عليه الاستعلام لضمان دقة التصفية.