نظرة عامة على لغة OData ل $filter، $orderbyوفي $select البحث المعرفي في Azure

  • مقالة
  • قراءة خلال 7 دقائق

يدعم Azure Cognitive Search مجموعة فرعية من بناء جملة تعبير OData للتعبيرات $filter$orderby$select . يتم تقييم تعبيرات التصفية أثناء تحليل الاستعلام، أو تقييد البحث في حقول معينة أو إضافة معايير مطابقة مستخدمة أثناء عمليات فحص الفهرس. يتم تطبيق تعبيرات الترتيب حسب كخطوة ما بعد المعالجة على مجموعة نتائج لفرز المستندات التي تم إرجاعها. تحدد التعبيرات المحددة حقول الوثيقة المضمنة في مجموعة النتائج. يختلف بناء جملة هذه التعبيرات عن بناء جملة الاستعلام البسيط أو الكامل المستخدم في معلمة البحث ، على الرغم من وجود بعض التداخل في بناء الجملة للحقول المرجعية.

توفر هذه المقالة نظرة عامة على لغة تعبير OData المستخدمة في عوامل التصفية والترتيب حسب وتعبيرات التحديد. يتم تقديم اللغة "من أسفل إلى أعلى" ، بدءا من العناصر الأساسية والبناء عليها. يتم وصف بناء جملة المستوى الأعلى لكل معلمة في مقالة منفصلة:

تتراوح تعبيرات OData من بسيطة إلى معقدة للغاية ، ولكنها جميعا تشترك في عناصر مشتركة. الأجزاء الأساسية لتعبير OData في البحث المعرفي في Azure هي:

  • مسارات الحقول، التي تشير إلى حقول محددة من الفهرس.
  • الثوابت ، وهي قيم حرفية لنوع بيانات معين.

ملاحظة

تختلف المصطلحات في Azure Cognitive Search عن معيار OData بعدة طرق. ما نسميه حقلا في Azure Cognitive Search يسمى خاصية في OData، وبالمثل لمسار الحقل مقابل مسار الخصائص. يشار إلى فهرس يحتوي على مستندات في Azure Cognitive Search بشكل عام في OData كمجموعة كيانات تحتوي على كيانات. يتم استخدام مصطلحات البحث المعرفي Azure في هذا المرجع.

المسارات الميدانية

يعرف EBNF التالي (نموذج Backus-Naur الموسعة) قواعد مسارات الحقول.

field_path ::= identifier('/'identifier)*

identifier ::= [a-zA-Z_][a-zA-Z_0-9]*

يتوفر أيضا رسم تخطيطي تفاعلي لبناء الجملة:

مخطط بناء جملة OData للبحث المعرفي في Azure

ملاحظة

راجع مرجع بناء جملة تعبير OData للبحث المعرفي Azure للحصول على EBNF الكامل.

يتكون مسار الحقل من معرف واحد أو أكثر مفصول بشرطة مائلة. كل معرف عبارة عن سلسلة من الأحرف التي يجب أن تبدأ بحرف ASCII أو تسطير سفلي، وتحتوي فقط على أحرف ASCII أو أرقام أو شرطة سفلية. يمكن أن تكون الحروف كبيرة أو صغيرة.

يمكن أن يشير المعرف إما إلى اسم حقل، أو إلى متغير نطاق في سياق تعبير مجموعة (any أو all) في عامل تصفية. يشبه متغير النطاق متغير حلقة يمثل العنصر الحالي للمجموعة. بالنسبة للمجموعات المعقدة، يمثل هذا المتغير كائنا، ولهذا السبب يمكنك استخدام مسارات الحقول للإشارة إلى الحقول الفرعية للمتغير. هذا مشابه للتدوين النقطي في العديد من لغات البرمجة.

يتم عرض أمثلة لمسارات الحقول في الجدول التالي:

مسار الحقل الوصف
HotelName يشير إلى حقل المستوى الأعلى من الفهرس
Address/City يشير إلى الحقل City الفرعي لحقل معقد في الفهرس؛ Address وهو من النوع Edm.ComplexType في هذا المثال
Rooms/Type يشير إلى الحقل Type الفرعي لحقل تجميع معقد في الفهرس؛ Rooms وهو من النوع Collection(Edm.ComplexType) في هذا المثال
Stores/Address/Country يشير إلى الحقل Country الفرعي للحقل Address الفرعي لحقل تجميع معقد في الفهرس؛ Stores وهو من النوع ومن Address النوع Collection(Edm.ComplexType)Edm.ComplexType في هذا المثال
room/Type يشير إلى الحقل Typeroom الفرعي لمتغير النطاق، على سبيل المثال في تعبير عامل التصفية Rooms/any(room: room/Type eq 'deluxe')
store/Address/Country يشير إلى الحقل Country الفرعي للحقل Addressstore الفرعي لمتغير النطاق، على سبيل المثال في تعبير عامل التصفية Stores/any(store: store/Address/Country eq 'Canada')

يختلف معنى مسار الحقل باختلاف السياق. في عوامل التصفية، يشير مسار الحقل إلى قيمة مثيل واحد لحقل في المستند الحالي. في سياقات أخرى، مثل $orderbyأو $select أو في البحث الميداني في بناء جملة Lucene الكامل، يشير مسار الحقل إلى الحقل نفسه. هذا الاختلاف له بعض العواقب على كيفية استخدام مسارات الحقول في عوامل التصفية.

النظر في مسار Address/Cityالحقل . في مرشح ، يشير هذا إلى مدينة واحدة للوثيقة الحالية ، مثل "سان فرانسيسكو". في المقابل ، يشير إلى الحقل Type الفرعي للعديد من الغرف (مثل "قياسي" للغرفة الأولى ، و "ديلوكس" للغرفة الثانية ، Rooms/Type وما إلى ذلك). نظرا لأنه Rooms/Type لا يشير إلى مثيل واحد من الحقل Typeالفرعي ، فلا يمكن استخدامه مباشرة في عامل تصفية. بدلا من ذلك ، للتصفية على نوع الغرفة ، يمكنك استخدام تعبير lambda مع متغير نطاق ، مثل هذا:

Rooms/any(room: room/Type eq 'deluxe')

في هذا المثال، يظهر متغير room النطاق في مسار الحقل room/Type . وبهذه الطريقة، room/Type يشير إلى نوع الغرفة الحالية في المستند الحالي. هذا مثيل واحد للحقل Type الفرعي ، لذلك يمكن استخدامه مباشرة في عامل التصفية.

استخدام مسارات الحقول

يتم استخدام المسارات الميدانية في العديد من معلمات واجهات برمجة تطبيقات Azure للبحث المعرفي REST. يسرد الجدول التالي جميع الأماكن التي يمكن استخدامها فيها، بالإضافة إلى أي قيود على استخدامها:

واجهة برمجة التطبيقات (API) اسم المعلمة القيود
إنشاء فهرس أو تحديثه suggesters/sourceFields بلا
إنشاء فهرس أو تحديثه scoringProfiles/text/weights يمكن أن تشير فقط إلى الحقول القابلة للبحث
إنشاء فهرس أو تحديثه scoringProfiles/functions/fieldName يمكن أن تشير فقط إلى الحقول القابلة للتصفية
بحث search متى queryType يكون full يمكن أن تشير فقط إلى الحقول القابلة للبحث
بحث facet يمكن أن تشير فقط إلى حقول facetable
بحث highlight يمكن أن تشير فقط إلى الحقول القابلة للبحث
بحث searchFields يمكن أن تشير فقط إلى الحقول القابلة للبحث
اقتراحوإكمال تلقائي searchFields يمكن أن تشير فقط إلى الحقول التي تشكل جزءا من مقترح
البحثوالاقتراحوالإكمال التلقائي $filter يمكن أن تشير فقط إلى الحقول القابلة للتصفية
البحثوالاقتراح $orderby يمكن أن تشير فقط إلى الحقول القابلة للفرز
البحثوالاقتراحوالبحث $select يمكن أن تشير فقط إلى الحقول القابلة للاسترداد

الثوابت

الثوابت في OData هي قيم حرفية لنوع معين من نموذج بيانات الكيان (EDM). راجع أنواع البيانات المعتمدة للحصول على قائمة بالأنواع المدعومة في البحث المعرفي في Azure. ثوابت أنواع المجموعات غير مدعومة.

يوضح الجدول التالي أمثلة على الثوابت لكل نوع من أنواع البيانات التي يدعمها Azure Cognitive Search:

نوع البيانات مثال على الثوابت
Edm.Boolean true, false
Edm.DateTimeOffset 2019-05-06T12:30:05.451Z
Edm.Double 3.14159, -1.2e7, NaN, INF, -INF
Edm.GeographyPoint geography'POINT(-122.131577 47.678581)'
Edm.GeographyPolygon geography'POLYGON((-122.031577 47.578581, -122.031577 47.678581, -122.131577 47.678581, -122.031577 47.578581))'
Edm.Int32 123, -456
Edm.Int64 283032927235
Edm.String 'hello'

الهروب من الأحرف الخاصة في ثوابت السلسلة

يتم تحديد ثوابت السلسلة في OData بواسطة علامات اقتباس مفردة. إذا كنت بحاجة إلى إنشاء استعلام بثابت سلسلة قد يحتوي في حد ذاته على علامات اقتباس مفردة، فيمكنك الهروب من علامات الاقتباس المضمنة عن طريق مضاعفتها.

على سبيل المثال ، سيتم تمثيل عبارة ذات نهاية عظمية غير منسقة مثل "سيارة أليس" في OData كثابت 'Alice''s car'السلسلة .

هام

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

بناء جملة الثوابت

يعرف EBNF التالي (نموذج Backus-Naur الموسع) القواعد النحوية لمعظم الثوابت الموضحة في الجدول أعلاه. يمكن العثور على القواعد النحوية للأنواع الجغرافية المكانية في الدوال الجغرافية المكانية OData في Azure Cognitive Search.

constant ::=
    string_literal
    | date_time_offset_literal
    | integer_literal
    | float_literal
    | boolean_literal
    | 'null'

string_literal ::= "'"([^'] | "''")*"'"

date_time_offset_literal ::= date_part'T'time_part time_zone

date_part ::= year'-'month'-'day

time_part ::= hour':'minute(':'second('.'fractional_seconds)?)?

zero_to_fifty_nine ::= [0-5]digit

digit ::= [0-9]

year ::= digit digit digit digit

month ::= '0'[1-9] | '1'[0-2]

day ::= '0'[1-9] | [1-2]digit | '3'[0-1]

hour ::= [0-1]digit | '2'[0-3]

minute ::= zero_to_fifty_nine

second ::= zero_to_fifty_nine

fractional_seconds ::= integer_literal

time_zone ::= 'Z' | sign hour':'minute

sign ::= '+' | '-'

/* In practice integer literals are limited in length to the precision of
the corresponding EDM data type. */
integer_literal ::= digit+

float_literal ::=
    sign? whole_part fractional_part? exponent?
    | 'NaN'
    | '-INF'
    | 'INF'

whole_part ::= integer_literal

fractional_part ::= '.'integer_literal

exponent ::= 'e' sign? integer_literal

boolean_literal ::= 'true' | 'false'

يتوفر أيضا رسم تخطيطي تفاعلي لبناء الجملة:

مخطط بناء جملة OData للبحث المعرفي في Azure

ملاحظة

راجع مرجع بناء جملة تعبير OData للبحث المعرفي Azure للحصول على EBNF الكامل.

بناء التعبيرات من مسارات المجال والثوابت

مسارات الحقل والثوابت هي الجزء الأساسي من تعبير OData ، لكنها بالفعل تعبيرات كاملة نفسها. في الواقع ، فإن معلمة $select في Azure Cognitive Search ليست سوى قائمة مفصولة بفواصل من مسارات الحقول ، $orderby ليست أكثر تعقيدا من $select. إذا كان لديك حقل نوع Edm.Boolean في الفهرس الخاص بك ، فيمكنك حتى كتابة مرشح ليس سوى مسار هذا الحقل. الثوابت truefalse وهي أيضا مرشحات صالحة.

ومع ذلك ، ستحتاج في معظم الأحيان إلى تعبيرات أكثر تعقيدا تشير إلى أكثر من حقل واحد وثابت. يتم بناء هذه التعبيرات بطرق مختلفة اعتمادا على المعلمة.

يعرف EBNF (نموذج Backus-Naur الموسع) التالي القواعد النحوية للمعلمات $filter$orderby$select . يتم بناؤها من تعبيرات أبسط تشير إلى مسارات الحقل والثوابت:

filter_expression ::= boolean_expression

order_by_expression ::= order_by_clause(',' order_by_clause)*

select_expression ::= '*' | field_path(',' field_path)*

يتوفر أيضا رسم تخطيطي تفاعلي لبناء الجملة:

مخطط بناء جملة OData للبحث المعرفي في Azure

ملاحظة

راجع مرجع بناء جملة تعبير OData للبحث المعرفي Azure للحصول على EBNF الكامل.

المعلمات $orderbyو $select كلاهما قائمتان مفصولتان بفواصل من التعبيرات الأبسط. المعلمة $filter عبارة عن تعبير منطقي يتكون من تعبيرات فرعية أبسط. يتم دمج هذه التعبيرات الفرعية باستخدام عوامل تشغيل منطقية مثل ، و ، و ، عوامل تشغيل المقارنة مثل ، ، gt، وما إلى ذلك ، ltومشغلي التجميع مثلeqanyallandو not. or

يتم استكشاف $filter$orderby ومعلمات $select بمزيد من التفصيل في المقالات التالية:

راجع أيضًا