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

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

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

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

حدد اتصال ClickHouse لتشغيل الاستعلام من خلاله.
ويمكنك اختياريًا تحديد مصدر — ما يتيح تطبيق عوامل التصفية على مستوى لوحة المعلومات على تصورك عبر الماكرو $__filters.
اكتب استعلام SQL في المحرر، باستخدام معلمات الاستعلام ووحدات الماكرو للتكامل مع النطاق الزمني للوحة المعلومات وعوامل التصفية والمتغيرات.
انقر زر 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 آمنًا دائمًا. لا يطبق $__filters إلا عوامل التصفية المفعّل فيها شرط عامل تصفية البث. ويُشار صراحةً إلى عوامل التصفية المعروضة كمتغيرات، كما هو موضح أدناه.

ماكرو متغيرات لوحة المعلومات

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

الماكرو	الوصف
`$__filter($<variable>)`	يتوسع إلى `toString(<filter expression>) IN ($variable)` عند تحديد قيم للمتغير `variable`، وإلى `1=1` في غير ذلك.
`$__filter(<expression>, $<variable>)`	يتوسع إلى `<expression> IN ($variable)` عند تحديد قيم للمتغير `variable`، وإلى `1=1` في غير ذلك.
`$__conditionalAll(<condition>, $<variable>)`	يتوسع إلى `<condition>` عندما تكون للمتغير قيم محددة، وإلى `1=1` في غير ذلك.

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

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

يربط 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

مخطط خطي — باستخدام متغيرات لوحة المعلومات

بالنسبة إلى لوحة معلومات تتضمن المتغير 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

مخطط جدولي — أبطأ 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. وينبغي أن يطابق المصدر الجدول الذي يُجرى عليه الاستعلام لضمان دقة التصفية.
لا تحتاج متغيرات لوحة المعلومات إلى مصدر — إذ تأتي القيم من القوائم المنسدلة لعوامل تصفية لوحة المعلومات، لا من مصدر البلاطة نفسه.
تُقيَّم التنبيهات على بلاطة SQL الذي يشير إلى متغير في لوحة المعلومات بحيث تكون جميع المتغيرات في حالتها الفارغة، لا بالقيم المحددة في لوحة المعلومات.

Get started

Features

Managing ClickStack

Guides

Integration partners

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

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

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

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

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

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

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

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

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

ماكرو متغيرات لوحة المعلومات

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

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

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

مخطط عددي

مخطط جدولي

أمثلة

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

مخطط خطي — باستخدام الماكرو

مخطط خطي — باستخدام متغيرات لوحة المعلومات

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

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

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

مخطط عددي — إجمالي عدد الأخطاء

ملاحظات

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

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

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

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

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

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

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

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

​ماكرو متغيرات لوحة المعلومات

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

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

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

​مخطط عددي

​مخطط جدولي

​أمثلة

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

​مخطط خطي — باستخدام الماكرو

​مخطط خطي — باستخدام متغيرات لوحة المعلومات

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

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

​مخطط دائري — توزيع الطلبات حسب الخدمة

​مخطط عددي — إجمالي عدد الأخطاء

​ملاحظات

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

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

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

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

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

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

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

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

ماكرو متغيرات لوحة المعلومات

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

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

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

مخطط عددي

مخطط جدولي

أمثلة

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

مخطط خطي — باستخدام الماكرو

مخطط خطي — باستخدام متغيرات لوحة المعلومات

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

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

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

مخطط عددي — إجمالي عدد الأخطاء

ملاحظات