> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> استخدام منشئ الاستعلامات في الإضافة ClickHouse لـ Grafana
# منشئ الاستعلامات
export const ClickHouseSupportedBadge = () => {
return ;
};
export const Image = ({img, alt, size}) => {
return
;
};
يمكن تشغيل أي query باستخدام إضافة ClickHouse.
يُعد منشئ الاستعلامات خيارًا مناسبًا للاستعلامات الأبسط، لكنك ستحتاج إلى استخدام [SQL Editor](#sql-editor) عند التعامل مع الاستعلامات المعقدة.
تتضمن جميع الاستعلامات في منشئ الاستعلامات [نوع استعلام](#query-types)، كما تتطلب تحديد عمود واحد على الأقل.
أنواع الاستعلامات المتاحة هي:
* [الجدول](#table): أبسط أنواع الاستعلامات لعرض البيانات بتنسيق جدول. وهو مناسب كخيار عام للاستعلامات البسيطة والمعقدة التي تتضمن دوالًا تجميعية.
* [السجلات](#logs): مُحسَّن لإنشاء استعلامات السجلات. ويعمل بأفضل شكل في عرض Explore مع [تهيئة الإعدادات الافتراضية](/ar/integrations/connectors/data-visualization/grafana/config#logs).
* [السلاسل الزمنية](#time-series): الأنسب لإنشاء استعلامات السلاسل الزمنية. ويتيح تحديد عمود زمني مخصص وإضافة دوال تجميعية.
* [التتبعات](#traces): مُحسَّن للبحث في التتبعات وعرضها. ويعمل بأفضل شكل في عرض Explore مع [تهيئة الإعدادات الافتراضية](/ar/integrations/connectors/data-visualization/grafana/config#traces).
* [SQL Editor](#sql-editor): يمكن استخدام SQL Editor عندما تريد تحكمًا كاملاً في الاستعلام. في هذا الوضع، يمكن تنفيذ أي SQL query.
## أنواع الاستعلامات
سيؤدي إعداد *نوع الاستعلام* إلى تغيير تخطيط أداة إنشاء الاستعلامات ليتوافق مع نوع الاستعلام الذي يتم إنشاؤه.
ويحدد نوع الاستعلام أيضًا اللوحة المستخدمة عند عرض البيانات بصريًا.
### جدول
أكثر أنواع الاستعلامات مرونة هو استعلام الجدول. وهو بمثابة نوع عام يشمل مُنشئات الاستعلام الأخرى المصممة للتعامل مع الاستعلامات البسيطة والتجميعية.
| حقل | الوصف |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| وضع المُنشئ | تستبعد الاستعلامات البسيطة التجميعات وGroup By، بينما تتضمن الاستعلامات التجميعية هذين الخيارين. |
| الأعمدة | الأعمدة المحددة. يمكن إدخال Raw SQL في هذا الحقل لإتاحة استخدام الدوال والأسماء المستعارة للأعمدة. |
| التجميعات | قائمة من [الدوال التجميعية](/ar/reference/functions/aggregate-functions/index). تتيح تحديد قيم مخصصة للدالة والعمود. لا تظهر إلا في وضع Aggregate. |
| Group By | قائمة من تعبيرات [GROUP BY](/ar/reference/statements/select/group-by). لا تظهر إلا في وضع Aggregate. |
| Order By | قائمة من تعبيرات [ORDER BY](/ar/reference/statements/select/order-by). |
| Limit | يُضيف عبارة [LIMIT](/ar/reference/statements/select/limit) إلى نهاية الاستعلام. إذا تم ضبطه على `0` فسيتم استبعاده. قد تحتاج بعض المرئيات إلى ضبطه على `0` لعرض جميع البيانات. |
| Filters | قائمة بعوامل التصفية التي ستُطبَّق في عبارة `WHERE`. |
سيعرض نوع الاستعلام هذا البيانات في شكل جدول.
### السجلات
يوفّر نوع استعلام السجلات أداة إنشاء استعلامات تركّز على الاستعلام عن بيانات السجلات.
يمكن تهيئة القيم الافتراضية في [إعدادات السجلات](/ar/integrations/connectors/data-visualization/grafana/config#logs) الخاصة بمصدر البيانات، بحيث تُحمَّل أداة إنشاء الاستعلامات مسبقًا بقاعدة بيانات/جدول وأعمدة افتراضية.
يمكن أيضًا تمكين OpenTelemetry لتحديد الأعمدة تلقائيًا وفقًا لإصدار المخطط.
تُضاف عوامل التصفية **Time** و**Level** افتراضيًا، إلى جانب ORDER BY لعمود Time.
وترتبط عوامل التصفية هذه بالحقول المقابلة لها، ويتم تحديثها عند تغيير الأعمدة.
ويُستبعَد عامل التصفية **Level** من SQL افتراضيًا، وسيؤدي تغييره من الخيار `IS ANYTHING` إلى تمكينه.
يدعم نوع استعلام السجلات [روابط البيانات](#data-links).
| الحقل | الوصف |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Use OTel | يفعّل أعمدة OpenTelemetry. وسيستبدل الأعمدة المحددة لاستخدام الأعمدة المعرّفة بواسطة إصدار مخطط OTel المحدد (ويعطّل تحديد الأعمدة). |
| الأعمدة | أعمدة إضافية تُضاف إلى صفوف السجل. ويمكن إدخال Raw SQL في هذا الحقل للسماح باستخدام الدوال وcolumn aliasing. |
| Time | عمود الطابع الزمني الأساسي للسجل. يعرض الأنواع الشبيهة بالوقت، كما يتيح استخدام قيم/دوال مخصّصة. |
| مستوى السجل | اختياري. *المستوى* أو *الشدّة* الخاصة بالسجل. تكون القيم عادةً مثل `INFO` و`error` و`Debug` وما إلى ذلك. |
| الرسالة | محتوى رسالة السجل. |
| الترتيب حسب | قائمة بتعبيرات [ORDER BY](/ar/reference/statements/select/order-by). |
| الحد | يضيف عبارة [LIMIT](/ar/reference/statements/select/limit) إلى نهاية الاستعلام. وإذا ضُبطت القيمة على `0`، فسيُستبعَد، لكن لا يُنصح بذلك مع مجموعات بيانات السجلات الكبيرة. |
| عوامل التصفية | قائمة بعوامل التصفية التي ستُطبَّق في عبارة `WHERE`. |
| تصفية الرسالة | حقل إدخال نصي لتصفية السجلات بسهولة باستخدام `LIKE %value%`. ويُستبعَد عندما يكون الإدخال فارغًا. |
سيعرض نوع الاستعلام هذا البيانات في لوحة السجلات، إلى جانب لوحة المدرج التكراري للسجلات في الأعلى.
يمكن عرض الأعمدة الإضافية المحددة في الاستعلام ضمن صف السجل الموسّع:
### سلاسل زمنية
يشبه نوع استعلام السلاسل الزمنية [الجدول](#table)، لكنه يركز على بيانات السلاسل الزمنية.
العرضان متشابهان إلى حد كبير، مع هذه الاختلافات البارزة:
* حقل *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](/ar/reference/functions/aggregate-functions/index). تتيح قيمًا مخصصة للدالة والعمود. تظهر فقط في Aggregate mode. |
| Group By | قائمة من تعبيرات [GROUP BY](/ar/reference/statements/select/group-by). تظهر فقط في Aggregate mode. |
| Order By | قائمة من تعبيرات [ORDER BY](/ar/reference/statements/select/order-by). |
| Limit | يضيف عبارة [LIMIT](/ar/reference/statements/select/limit) إلى نهاية الاستعلام. وإذا ضُبطت قيمته على `0`، فسيُستبعد، ويُنصح بذلك لبعض مجموعات بيانات السلاسل الزمنية لعرض التصور البياني كاملًا. |
| Filters | قائمة بعوامل التصفية التي ستُطبَّق في عبارة `WHERE`. |
يعرض نوع الاستعلام هذا البيانات باستخدام لوحة السلاسل الزمنية.
### التتبعات
يوفّر نوع استعلام التتبّع أداة إنشاء استعلامات لتسهيل البحث في التتبعات وعرضها.
وهو مصمَّم لبيانات OpenTelemetry، لكن يمكن تحديد الأعمدة لعرض التتبعات من مخطط مختلف.
يمكن تهيئة القيم الافتراضية في [إعدادات التتبّع](/ar/integrations/connectors/data-visualization/grafana/config#traces) الخاصة بمصدر البيانات، بحيث يتم تحميل أداة إنشاء الاستعلامات مسبقًا بقاعدة بيانات/جدول وأعمدة افتراضية. وإذا تم تكوين القيم الافتراضية، فسيُطوى قسم اختيار الأعمدة افتراضيًا.
كما يمكن تفعيل OpenTelemetry لتحديد الأعمدة تلقائيًا وفقًا لإصدار المخطط.
تُضاف عوامل التصفية الافتراضية بهدف إظهار spans ذات المستوى الأعلى فقط.
ويتم أيضًا تضمين ORDER BY لعمودي Time وDuration Time.
وترتبط عوامل التصفية هذه بالحقول المقابلة لها، وستتحدّث عند تغيير الأعمدة.
ويُستبعَد عامل تصفية **اسم الخدمة** من SQL افتراضيًا، وسيؤدي تغييره من الخيار `IS ANYTHING` إلى تفعيله.
يدعم نوع استعلام التتبّع [روابط البيانات](#data-links).
| الحقل | الوصف |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| وضع التتبّع | يغيّر الاستعلام من Trace Search إلى lookup لمعرّف التتبّع Trace ID. |
| 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](/ar/reference/statements/select/order-by). |
| Limit | يُلحِق statement [LIMIT](/ar/reference/statements/select/limit) بنهاية الاستعلام. وإذا ضُبطت القيمة على `0` فسيُستبعَد، لكن لا يُنصح بذلك مع مجموعات بيانات التتبّع الكبيرة. |
| عوامل التصفية | قائمة بعوامل التصفية التي ستُطبَّق في clause `WHERE`. |
| معرّف التتبّع | معرّف التتبّع المطلوب التصفية وفقه. يُستخدم فقط في وضع Trace ID، وعند فتح [رابط بيانات](#data-links) لمعرّف تتبّع. |
سيعرض نوع الاستعلام هذا البيانات باستخدام عرض الجدول في وضع Trace Search، وباستخدام لوحة التتبّع في وضع Trace ID.
## محرر SQL
بالنسبة إلى الاستعلامات شديدة التعقيد التي لا تناسب أداة إنشاء الاستعلامات، يمكنك استخدام محرر SQL.
يمنحك ذلك تحكمًا كاملًا في الاستعلام، إذ يتيح لك كتابة ClickHouse SQL مباشرةً وتشغيله.
يمكن فتح محرر SQL باختيار "SQL Editor" من أعلى محرر الاستعلامات.
لا يزال بإمكانك استخدام [دوال الماكرو](#macros) في هذا الوضع.
يمكنك التبديل بين أنواع الاستعلامات للحصول على العرض المرئي الأنسب لاستعلامك.
ويؤثر هذا التبديل أيضًا في عرض لوحة المعلومات، ولا سيما عند التعامل مع بيانات السلاسل الزمنية.
## روابط البيانات
يمكن استخدام [روابط البيانات](https://grafana.com/docs/grafana/latest/panels-visualizations/configure-data-links)
في Grafana للربط باستعلامات جديدة.
تم تمكين هذه الميزة ضمن إضافة ClickHouse لربط trace بـ logs والعكس صحيح. وهي تعمل بأفضل شكل عند تهيئة OpenTelemetry لكلٍّ من logs وtraces في [إعدادات مصدر البيانات](/ar/integrations/connectors/data-visualization/grafana/config#opentelemetry)
مثال على روابط trace في جدول
مثال على روابط trace في logs
### كيفية إنشاء رابط بيانات
يمكنك إنشاء رابط بيانات عبر تحديد عمود باسم `traceID` في الاستعلام. هذا الاسم لا يميّز بين الأحرف الكبيرة والصغيرة، كما يدعم إضافة شرطة سفلية قبل "ID". على سبيل المثال: `traceId` و`TraceId` و`TRACE_ID` و`tracE_iD` كلها صيغ صالحة.
إذا كان OpenTelemetry مفعّلًا في استعلام [السجلات](#logs) أو [التتبّع](#traces)، فسيُدرج عمود معرّف التتبّع تلقائيًا.
عند تضمين عمود لمعرّف التتبّع، سيُرفق بالبيانات رابطا "**عرض التتبّع**" و"**عرض السجلات**".
### قدرات الربط
عند توفر روابط البيانات، يمكنك فتح التتبّعات والسجلات باستخدام معرّف التتبّع المتاح.
سيؤدي "**عرض التتبّع**" إلى فتح لوحة منقسمة تتضمن التتبّع، بينما سيؤدي "**عرض السجلات**" إلى فتح استعلام سجلات مُرشَّحًا بحسب معرّف التتبّع.
إذا نُقر على الرابط من لوحة معلومات بدلًا من عرض Explore، فسيُفتح الرابط في علامة تبويب جديدة ضمن عرض Explore.
يلزم إعداد القيم الافتراضية لكل من [السجلات](/ar/integrations/connectors/data-visualization/grafana/config#logs) و[التتبّعات](/ar/integrations/connectors/data-visualization/grafana/config#traces) عند الانتقال بين أنواع الاستعلامات (من السجلات إلى التتبّعات ومن التتبّعات إلى السجلات). ولا تكون القيم الافتراضية مطلوبة عند فتح رابط من نوع الاستعلام نفسه، إذ يمكن ببساطة نسخ الاستعلام.
مثال على عرض تتبّع (اللوحة اليمنى) من استعلام سجلات (اللوحة اليسرى)
## وحدات الماكرو
تُعد وحدات الماكرو طريقة بسيطة لإضافة SQL ديناميكي إلى استعلامك.
وقبل إرسال الاستعلام إلى خادم ClickHouse، تعمل الإضافة على توسيع الماكرو واستبداله بالتعبير الكامل.
يمكن للاستعلامات الواردة من كلٍّ من SQL Editor وQuery Builder استخدام وحدات الماكرو.
### استخدام وحدات الماكرو
يمكن استخدام وحدات الماكرو في أي مكان داخل الاستعلام، وتكرارها عند الحاجة.
فيما يلي مثال على استخدام الماكرو `$__timeFilter`:
الإدخال:
```sql theme={null}
SELECT log_time, log_message
FROM logs
WHERE $__timeFilter(log_time)
```
ناتج الاستعلام النهائي:
```sql theme={null}
SELECT log_time, log_message
FROM logs
WHERE log_time >= toDateTime(1415792726) AND log_time <= toDateTime(1447328726)
```
في هذا المثال، يُطبَّق النطاق الزمني في لوحة معلومات Grafana على العمود `log_time`.
يدعم المكوّن الإضافي أيضًا الصياغة باستخدام الأقواس المعقوفة `{}`. استخدم هذه الصياغة عندما تحتاج إلى استعلامات داخل [المعلمات](/ar/reference/syntax#defining-and-using-query-parameters).
### قائمة وحدات الماكرو
هذه قائمة بجميع وحدات الماكرو المتاحة في المكوّن الإضافي:
| Macro | الوصف | مثال على المخرجات |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `$__dateFilter(columnName)` | يُستبدل بمرشّح نطاق زمني على العمود المحدد باستخدام النطاق الزمني للوحة Grafana كـ [Date](/ar/reference/data-types/date). | `columnName >= toDate('2022-10-21') AND columnName <= toDate('2022-10-23')` |
| `$__timeFilter(columnName)` | يُستبدل بمرشّح نطاق زمني على العمود المحدد باستخدام النطاق الزمني للوحة Grafana كـ [DateTime](/ar/reference/data-types/datetime). | `columnName >= toDateTime(1415792726) AND time <= toDateTime(1447328726)` |
| `$__timeFilter_ms(columnName)` | يُستبدل بمرشّح نطاق زمني على العمود المحدد باستخدام النطاق الزمني للوحة Grafana كـ [DateTime64](/ar/reference/data-types/datetime64). | `columnName >= fromUnixTimestamp64Milli(1415792726123) AND columnName <= fromUnixTimestamp64Milli(1447328726456)` |
| `$__dateTimeFilter(dateColumn, timeColumn)` | صيغة مختصرة تجمع بين `$__dateFilter()` و`$__timeFilter()` باستخدام عمودَي Date وDateTime منفصلين. الاسم البديل: `$__dt()` | `$__dateFilter(dateColumn) AND $__timeFilter(timeColumn)` |
| `$__fromTime` | يُستبدل بوقت بداية نطاق لوحة Grafana بعد تحويله إلى [DateTime](/ar/reference/data-types/datetime). | `toDateTime(1415792726)` |
| `$__fromTime_ms` | يُستبدل بوقت بداية نطاق اللوحة بعد تحويله إلى [DateTime64](/ar/reference/data-types/datetime64). | `fromUnixTimestamp64Milli(1415792726123)` |
| `$__toTime` | يُستبدل بوقت نهاية نطاق لوحة Grafana بعد تحويله إلى [DateTime](/ar/reference/data-types/datetime). | `toDateTime(1447328726)` |
| `$__toTime_ms` | يُستبدل بوقت نهاية نطاق اللوحة بعد تحويله إلى [DateTime64](/ar/reference/data-types/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` |