دالة in() في DQL: الترشيح على قائمة أو مصفوفة أو استعلام فرعي

دالة in() في DQL وعامل in: الترشيح على قائمة أو مصفوفة أو استعلام فرعي، واستبعاد القيم، وحالات الاستخدام التشغيلية والفخاخ.
DQL fonction in() : filtrer sur une liste, un tableau ou une sous-requête

تجيب دالة in() في DQL وعامل in عن السؤال نفسه: هل هذه القيمة من ضمن قائمة؟ تختبر الدالة قائمة مكتوبة في الاستعلام أو مصفوفة يحملها السجل؛ ويقارن العامل قيمة بنتيجة استعلام فرعي (subquery). واختيار الأنسب منهما يجنّبك سلاسل or غير المقروءة وقوائم المعرّفات المنسوخة يدويًا أثناء الحادثة.

يفصّل هذا الدليل الصياغة الموثقة، والمصفوفات، والنفي، والاستعلامات الفرعية، والحالة الخاصة classicEntitySelector، مع حالات استخدام تشغيلية. كل الصياغات المذكورة مأخوذة من وثائق DQL الرسمية، التي اطُّلع عليها في أكتوبر 2026.

يصلح المحتوى لـ Dynatrace SaaS (Grail). أما Dynatrace Managed فلا يملك DQL: يتم الترشيح فيه بمحدِّد الكيانات (entity selector) وmetric selector. وللنظرة العامة على الأوامر، راجع أوامر DQL مشروحة التي تعرض in() في بضعة أمثلة؛ أما هذا الدليل فيذهب أبعد.

دالة in() في DQL: الصياغة والقيمة المعادة

التوقيع الموثق هو:

in(needle, haystack, …)
  • needle: العنصر المطلوب (أو العناصر، إن كان مصفوفة)؛
  • haystack: القيم التي يُبحث فيها. تقبل الدالة عدة haystacks ومصفوفات في جميع الوسائط؛
  • النتيجة قيمة منطقية (boolean)، وبالتالي قابلة للاستخدام مباشرة في filter وfilterOut وfieldsAdd وcountIf.
مثال من وثائق DQL: fieldsAdd مع in(a، قائمة java وgo وrust) على أربعة سجلات، والنتيجة true لـ java وrust وfalse لـ python وdotnet
Source : docs.dynatrace.com

تشمل الأنواع المقبولة السلاسل النصية والأعداد والمدد وعناوين IP والأختام الزمنية والقيم المنطقية والسجلات: يمكنك اختبار قائمة عناوين IP كما تختبر قائمة أسماء خدمات.

خطوة بخطوة: الترشيح على قائمة

الخطوة 1: استبدل سلسلة or

// before
fetch logs
| filter loglevel == "ERROR" or loglevel == "WARN"

// after
fetch logs
| filter in(loglevel, {"ERROR", "WARN"})

القائمة بين أقواس معقوصة هي الشكل الذي تستخدمه الوثائق. وتعمل أيضًا سلسلة قيم: in(technologies, "Python", "Hibernate") ضمن الأمثلة الرسمية.

الخطوة 2: استبعد قائمة

يُكتب النفي بـ not أمام الدالة، أو بالأمر filterOut:

fetch logs
| filterOut in(k8s.namespace.name, {"kube-system", "monitoring"})
| summarize nb = count(), by:{k8s.namespace.name}

مفيد لإزالة ضجيج مساحات الأسماء (namespaces) التقنية قبل البحث عن أصل ارتفاع حجم السجلات.

الخطوة 3: اختبر حقل مصفوفة

حين يكون needle مصفوفة، تعيد in() القيمة true إذا ورد عنصر واحد على الأقل منها في haystack. المثال الرسمي:

data record(technologies = array("Java", "Spring", "Jetty")),
     record(technologies = array("Python", "Flask")),
     record(technologies = array("Java", "Hibernate"))
| fieldsAdd in(technologies, "Python", "Hibernate"),
            in(technologies, array("Spring", "Flask"))

يعطي السجل الأول false ثم true: ليس بين عناصره Python ولا Hibernate، لكن Spring موجود في haystack الثاني.

وللتحقق من أن مصفوفة محتواة بالكامل في أخرى، تقترح وثائق العوامل نفيًا مزدوجًا مع iAny:

| fieldsAdd not iAny(not in(needle[], haystack))

تساوي not in(needle[], haystack) القيمة true لكل عنصر غائب؛ ويكشف iAny هل يوجد واحد منها؛ ولذلك يعيد not الخارجي true فقط إذا لم ينقص أي عنصر. وتوضح الوثائق أن مصفوفة كل عناصرها null تعطي null، فلا تجتاز أي مرشح أبدًا.

الاستعلامات الفرعية: العامل in

حين لا تكون القائمة معروفة مسبقًا، استخدم العامل in مع استعلام فرعي بين أقواس مربعة. الصياغة الموثقة:

expression in [execution block]

القيد: يجب أن يعيد الاستعلام الفرعي حقلًا واحدًا يوفّر قائمة القيم.

مثال من وثائق DQL: timeseries مع avg(dt.host.cpu.usage) مرشَّحة بـ dt.entity.host in استعلام فرعي fetch dt.entity.host يُبقي المضيفين الحاملين للوسم ServiceNow، مع الصياغة expression in execution block
Source : docs.dynatrace.com

يرشّح المثال الرسمي مقياس المعالج (CPU) للمضيفين الذين يحملون وسمًا معينًا. ويصلح المبدأ نفسه على السجلات:

fetch logs
| filter loglevel == "ERROR"
| filter dt.entity.host in [fetch dt.entity.host
    | fieldsAdd tags
    | expand tags
    | filter tags == "ServiceNow"
    | fields id]
| summarize erreurs = count(), by:{dt.entity.host}

يعيد الاستعلام الفرعي الحقل id لكيانات المضيف؛ ويضمن fields id الأخير وجود حقل واحد فقط. ثم تُجمَّع النتيجة بـ summarize: راجع التجميع في DQL.

حالة classicEntitySelector

تعيد الدالة classicEntitySelector() معرّفات الكيانات المطابقة لمحدِّد كيانات كلاسيكي. وتوضح الوثائق أنها غير مدعومة إلا بالشكل in(field, classicEntitySelector("..")) وأنها تشترط الصلاحية storage:entities:read. وهي تتيح إعادة استخدام محدِّد قائم بعلاقاته:

fetch logs
| filter in(dt.entity.cloud_application_instance,
    classicEntitySelector("type(CLOUD_APPLICATION_INSTANCE),toRelationShip.IS_NAMESPACE_OF_CAI(type(CLOUD_APPLICATION_NAMESPACE), entityId(CLOUD_APPLICATION_NAMESPACE-1B6CFC8C542A2273))"))

لا يدعم Smartscape on Grail الدالة classicEntitySelector: تستبدل الوثائق هناك الاختيار بالعلاقات بالأمر traverse الذي يجتاز الطوبولوجيا مباشرة في DQL: راجع DQL وSmartscape.

حالات الاستخدام في التشغيل

  • نطاق حادثة: حصر السجلات في الخدمات المتأثرة، المسرودة مرة واحدة في الاستعلام.
  • قائمة استبعاد: إزالة مجسّات المراقبة أو عناوين IP الداخلية بـ filterOut in(...).
  • ترشيح ديناميكي: استعلام فرعي يختار المضيفين بحسب الوسم، بدل قائمة معرّفات تهرم بسرعة.
  • عدّاد شرطي: countIf(in(loglevel, {"ERROR", "WARN"})) داخل summarize لمؤشر الأخطاء.

كل قائمة مكتوبة صراحةً مصدر للعمل اليدوي المتكرر (toil): يجب تحديثها مع كل خدمة جديدة. أما الاستعلام الفرعي القائم على وسم فيتبع البيئة دون تدخل، مما يقلّل خطر مرشح خاطئ في اللحظة التي يهم فيها متوسط زمن الإصلاح (MTTR).

كيف تتحقق من صحة المرشح

  1. اعرض القيمة المنطقية قبل الترشيح: | fieldsAdd match = in(champ, {...}) ثم | summarize count(), by:{match}. ترى كم سجلًا يمر.
  2. نفّذ الاستعلام الفرعي وحده: يجب أن يعيد عمودًا واحدًا والقيم المتوقعة.
  3. اسرد القيم الفعلية للحقل بـ | summarize count(), by:{champ}: قيمة خاطئة الإملاء في القائمة لا تطابق شيئًا ولا تطلق أي خطأ.

أفضل الممارسات

  • فضّل in() على أكثر من or واحدين على الحقل نفسه: يُقرأ الاستعلام ويُعدَّل في سطر واحد.
  • أنهِ كل استعلام فرعي بـ fields على حقل واحد.
  • استبدل قوائم المعرّفات باستعلام فرعي على وسم أو خاصية ثابتة.
  • احتفظ بـ classicEntitySelector لترحيل المحدِّدات القائمة؛ وللطوبولوجيا استخدم Smartscape.
  • وثّق في تعليق // سبب استبعاد قيمة ما.

الأسئلة الشائعة

ما الفرق بين الدالة in() والعامل in؟

تختبر الدالة in(needle, haystack) قائمة معروفة أو مصفوفة. ويختبر العامل expression in [sous-requête] نتيجة استعلام DQL آخر، يجب أن يعيد حقلًا واحدًا.

كيف أكتب «not in» في DQL؟

بـ not in(champ, {...}) داخل filter، أو بـ filterOut in(champ, {...}). كلا الشكلين يستبعد قيم القائمة.

هل تعمل in() في Dynatrace Managed؟

لا: يقوم DQL على Grail المتوفر في Dynatrace SaaS. في Managed رشّح بمحدِّد الكيانات وmetric selector؛ راجع مسار Dynatrace Managed.

الخلاصة

في DQL، الدالة in() لقائمة أو مصفوفة، والعامل in لاستعلام فرعي: هاتان الأداتان تحلان محل الشروط الطويلة والقوائم الجامدة. ومع summarize تعطيان استعلامات قصيرة وصحيحة تواكب تطور البيئة. وللمزيد من الاستعلامات الجاهزة، راجع استعلامات DQL التشغيلية لدينا.

span.observer مدوّنة مجتمعية مستقلة وغير تابعة لشركة Dynatrace LLC. العلامات التجارية المذكورة ملك لأصحابها. صياغة DQL تتطور: تحقق منها في الوثائق الرسمية قبل استخدامها في الإنتاج.

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

Previous Post
DQL group by : regrouper avec summarize et by:{}, l'équivalent du GROUP BY SQL

التجميع في DQL: summarize وby:{} مقابل GROUP BY في SQL

Next Post
DQL Smartscape : interroger la topologie avec smartscapeNodes, smartscapeEdges et traverse

DQL Smartscape: استعلام الطوبولوجيا بالأوامر smartscapeNodes وsmartscapeEdges وtraverse

Related Posts