نظرة عامة على لغة OData ل $filterو $orderbyو $select في Azure الذكاء الاصطناعي Search
توفر هذه المقالة نظرة عامة على لغة تعبير OData المستخدمة في تعبيرات $filter $order وتعبيرات $select في Azure الذكاء الاصطناعي Search. يتم تقديم اللغة "من أسفل إلى أعلى" بدءا من العناصر الأساسية. تتراوح تعبيرات OData التي يمكنك إنشاؤها في طلب استعلام من بسيطة إلى معقدة للغاية، ولكنها تشترك جميعا في عناصر مشتركة. تتضمن العناصر المشتركة ما يلي:
- مسارات الحقول، التي تشير إلى حقول معينة من الفهرس.
- الثوابت، وهي قيم حرفية لنوع بيانات معين.
بمجرد فهم هذه المفاهيم الشائعة، يمكنك متابعة بناء جملة المستوى الأعلى لكل تعبير:
- يتم تقييم التعبيرات $filter أثناء تحليل الاستعلام، أو تقييد البحث في حقول معينة أو إضافة معايير المطابقة المستخدمة أثناء عمليات فحص الفهرس.
- يتم تطبيق تعبيرات $orderby كخطوة ما بعد المعالجة عبر مجموعة نتائج لفرز المستندات التي يتم إرجاعها.
- تحدد تعبيرات $select حقول المستندات المضمنة في مجموعة النتائج.
يختلف بناء جملة هذه التعبيرات عن بناء جملة الاستعلام البسيط أو الكامل المستخدم في معلمة البحث، على الرغم من وجود بعض التداخل في بناء الجملة لحقول الرجوع.
إشعار
تختلف المصطلحات في Azure الذكاء الاصطناعي Search عن معيار OData بعدة طرق. يسمى ما نسميه حقلا في Azure الذكاء الاصطناعي Search خاصية في OData، وبالمثل لمسار الحقل مقابل مسار الخاصية. يشار إلى فهرس يحتوي على مستندات في Azure الذكاء الاصطناعي Search بشكل عام في OData كمجوعة كيان تحتوي على كيانات. يتم استخدام مصطلحات Azure الذكاء الاصطناعي Search في هذا المرجع.
مسارات الحقول
يحدد EBNF التالي (نموذج Backus-Naur الموسع) التدقيق النحوي لمسارات الحقول.
field_path ::= identifier('/'identifier)*
identifier ::= [a-zA-Z_][a-zA-Z_0-9]*
يتوفر أيضا رسم تخطيطي تفاعلي لبناء الجملة:
إشعار
راجع مرجع بناء جملة تعبير 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 من النوع Collection(Edm.ComplexType) ومن Address النوع Edm.ComplexType في هذا المثال |
room/Type |
يشير إلى Type الحقل الفرعي لمتغير room النطاق، على سبيل المثال في تعبير عامل التصفية 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الحقل . في عامل تصفية، يشير هذا إلى مدينة واحدة للمستند الحالي، مثل "سان فرانسيسكو". في المقابل، Rooms/Type يشير إلى Type الحقل الفرعي للعديد من الغرف (مثل "قياسي" للغرفة الأولى، و"فاخر" للغرفة الثانية، وما إلى ذلك). نظرا إلى Rooms/Type أنه لا يشير إلى مثيل واحد من الحقل Typeالفرعي ، فلا يمكن استخدامه مباشرة في عامل تصفية. بدلا من ذلك، للتصفية على نوع الغرفة، يمكنك استخدام تعبير lambda مع متغير نطاق، مثل هذا:
Rooms/any(room: room/Type eq 'deluxe')
في هذا المثال، يظهر متغير room النطاق في room/Type مسار الحقل. وبهذه الطريقة، room/Type تشير إلى نوع الغرفة الحالية في المستند الحالي. هذا مثيل واحد من Type الحقل الفرعي، لذلك يمكن استخدامه مباشرة في عامل التصفية.
استخدام مسارات الحقول
يتم استخدام مسارات الحقول في العديد من معلمات واجهات برمجة تطبيقات AZURE الذكاء الاصطناعي Search REST. يسرد الجدول التالي جميع الأماكن التي يمكن استخدامها فيها، بالإضافة إلى أي قيود على استخدامها:
| API | اسم المعلمة | القيود |
|---|---|---|
| إنشاء فهرس أو تحديثه | suggesters/sourceFields |
بلا |
| إنشاء فهرس أو تحديثه | scoringProfiles/text/weights |
يمكن الرجوع إلى الحقول القابلة للبحث فقط |
| إنشاء فهرس أو تحديثه | scoringProfiles/functions/fieldName |
يمكن الرجوع إلى الحقول القابلة للتصفية فقط |
| Search | search عندما queryType يكون full |
يمكن الرجوع إلى الحقول القابلة للبحث فقط |
| Search | facet |
يمكن الرجوع إلى حقول قابلة للواجهة فقط |
| Search | highlight |
يمكن الرجوع إلى الحقول القابلة للبحث فقط |
| Search | searchFields |
يمكن الرجوع إلى الحقول القابلة للبحث فقط |
| الاقتراح والإكمال التلقائي | searchFields |
يمكن الإشارة فقط إلى الحقول التي تعد جزءا من مقترح |
| البحث والاقتراح والإكمال التلقائي | $filter |
يمكن الرجوع إلى الحقول القابلة للتصفية فقط |
| البحث والاقتراح | $orderby |
يمكن الرجوع إلى الحقول القابلة للفرز فقط |
| البحث والاقتراح والبحث | $select |
يمكن الرجوع فقط إلى الحقول القابلة للاسترداد |
الثوابت
الثوابت في OData هي قيم حرفية لنوع نموذج بيانات الكيان (EDM) معين. راجع أنواع البيانات المدعومة للحصول على قائمة بالأنواع المدعومة في Azure الذكاء الاصطناعي Search. ثوابت أنواع المجموعات غير مدعومة.
يعرض الجدول التالي أمثلة على الثوابت لكل نوع من أنواع البيانات التي يدعمها Azure الذكاء الاصطناعي 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 الذكاء الاصطناعي 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 الذكاء الاصطناعي البحث عن EBNF الكامل.
إنشاء تعبيرات من مسارات الحقول والثوابت
مسارات الحقول والثوابت هي الجزء الأساسي من تعبير OData، ولكنها بالفعل تعبيرات كاملة نفسها. في الواقع، المعلمة $select في Azure الذكاء الاصطناعي Search ليست سوى قائمة مفصولة بفواصل من مسارات الحقول، $orderby ليست أكثر تعقيدا من $select. إذا كان لديك حقل من النوع Edm.Boolean في الفهرس الخاص بك، يمكنك حتى كتابة عامل تصفية لا يعدو أن يكون مسار هذا الحقل. الثوابت true و false هي أيضا عوامل تصفية صالحة.
ومع ذلك، ستحتاج في معظم الأحيان إلى تعبيرات أكثر تعقيدا تشير إلى أكثر من حقل واحد وثابت. يتم إنشاء هذه التعبيرات بطرق مختلفة اعتمادا على المعلمة .
يحدد 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 الذكاء الاصطناعي البحث عن EBNF الكامل.
الخطوات التالية
المعلمتان $orderby و $select هما قوائم مفصولة بفواصل للتعبيرات الأبسط. المعلمة $filter هي تعبير منطقي يتكون من تعبيرات فرعية أبسط. يتم دمج هذه التعبيرات الفرعية باستخدام عوامل التشغيل المنطقية مثل andو orو notعوامل المقارنة مثلeq و ltgtو وهكذا، وعوامل تشغيل المجموعة مثلanyو.all
يتم استكشاف المعلمات $filter $orderby $select بمزيد من التفصيل في المقالات التالية: