OData الدوال الجغرافية المكانية في Azure Cognitive Search - geo.distance و geo.intersects
يدعم Azure Cognitive Search الاستعلامات الجغرافية المكانية في تعبيرات عامل تصفية OData عبر geo.distance الوظائف والوظائف geo.intersects . ترجع geo.distance الدالة المسافة بالكيلومترات بين نقطتين، إحداهما متغير مجال أو نطاق، والأخرى ثابتة تمر كجزء من المرشح. ترجع true الدالة إذا كانت geo.intersects نقطة معينة داخل مضلع معين، حيث تكون النقطة متغير حقل أو نطاق ويتم تحديد المضلع كثابت تم تمريره كجزء من المرشح.
يمكن أيضا استخدام الوظيفة geo.distance في المعلمة $orderby لفرز نتائج البحث حسب المسافة من نقطة معينة. بناء الجملة ل geo.distance في $orderby هو نفسه كما هو في $filter. عند استخدامه geo.distance في $orderby ، يجب أن يكون الحقل الذي ينطبق عليه من النوع Edm.GeographyPoint ويجب أن يكون قابلا للفرز أيضا.
ملاحظة
عند الاستخدام geo.distance في معلمة $orderby ، يجب أن يحتوي الحقل الذي تمرره إلى الدالة على نقطة جغرافية واحدة فقط. بمعنى آخر ، يجب أن يكون من النوع Edm.GeographyPoint وليس Collection(Edm.GeographyPoint). لا يمكن الفرز في حقول المجموعة في البحث المعرفي في Azure.
بناء الجملة
يحدد EBNF (نموذج Backus-Naur الموسع) التالي قواعد اللغة geo.distance والدوال geo.intersects ، بالإضافة إلى القيم الجغرافية المكانية التي تعمل عليها:
geo_distance_call ::=
'geo.distance(' variable ',' geo_point ')'
| 'geo.distance(' geo_point ',' variable ')'
geo_point ::= "geography'POINT(" lon_lat ")'"
lon_lat ::= float_literal ' ' float_literal
geo_intersects_call ::=
'geo.intersects(' variable ',' geo_polygon ')'
/* You need at least four points to form a polygon, where the first and
last points are the same. */
geo_polygon ::=
"geography'POLYGON((" lon_lat ',' lon_lat ',' lon_lat ',' lon_lat_list "))'"
lon_lat_list ::= lon_lat(',' lon_lat)*
يتوفر أيضا رسم تخطيطي تفاعلي لبناء الجملة:
ملاحظة
راجع مرجع بناء جملة تعبير OData للبحث المعرفي Azure للحصول على EBNF الكامل.
geo.distance
تأخذ الدالة geo.distance معلمتين من النوع Edm.GeographyPoint وترجع Edm.Double قيمة هي المسافة بينهما بالكيلومترات. ويختلف هذا عن الخدمات الأخرى التي تدعم عمليات OData الجغرافية المكانية، التي عادة ما تعيد المسافات بالأمتار.
يجب أن يكون أحد المعلمات ثابتا لنقطة geo.distance الجغرافيا ، والآخر يجب أن يكون مسار حقل (أو متغير نطاق في حالة تكرار مرشح فوق حقل من النوع Collection(Edm.GeographyPoint)). ترتيب هذه المعلمات لا يهم.
ثابت النقطة الجغرافية هو من الشكل geography'POINT(<longitude> <latitude>)'، حيث خطوط الطول والعرض هي ثوابت رقمية.
ملاحظة
عند الاستخدام geo.distance في عامل تصفية، يجب مقارنة المسافة التي تم إرجاعها بواسطة الدالة بثابت باستخدام lt، ، le، gtأو ge. المشغلين وغير مدعومين eqne عند مقارنة المسافات. على سبيل المثال ، هذا هو الاستخدام الصحيح ل geo.distance: $filter=geo.distance(location, geography'POINT(-122.131577 47.678581)') le 5.
geo.intersects
تأخذ الدالة متغيرا من النوع Edm.GeographyPoint وثابتا Edm.GeographyPolygon وترجع إذا Edm.Boolean -- true كانت geo.intersects النقطة ضمن حدود المضلع ، false وإلا.
المضلع هو سطح ثنائي الأبعاد مخزن كسلسلة من النقاط التي تحدد حلقة محيطة (انظر الأمثلة أدناه). يجب إغلاق المضلع ، مما يعني أن مجموعتي النقاط الأولى والأخيرة يجب أن تكونا متماثلتين. يجب أن تكون النقاط في المضلع بترتيب عكس اتجاه عقارب الساعة.
الاستعلامات الجغرافية المكانية والمضلعات التي تمتد عبر خط الطول 180
بالنسبة للعديد من مكتبات الاستعلام الجغرافي المكاني، فإن صياغة استعلام يتضمن خط الطول 180 (بالقرب من خط التاريخ) إما خارج الحدود أو يتطلب حلا بديلا، مثل تقسيم المضلع إلى قسمين، أحدهما على جانبي خط الزوال.
في Azure Cognitive Search، ستعمل الاستعلامات الجغرافية المكانية التي تتضمن خط طول 180 درجة كما هو متوقع إذا كان شكل الاستعلام مستطيلا وتمت محاذاة إحداثياتك مع تخطيط شبكة على طول خطي الطول والعرض (على سبيل المثال، geo.intersects(location, geography'POLYGON((179 65, 179 66, -179 66, -179 65, 179 65))'). خلاف ذلك ، بالنسبة للأشكال غير المستطيلة أو غير المحاذاة ، فكر في نهج المضلع المنقسم.
الوظائف الجغرافية المكانية و null
مثل جميع الحقول الأخرى غير المتعلقة بالمجموعات في Azure Cognitive Search، يمكن أن تحتوي حقول النوع Edm.GeographyPoint على null قيم. عندما يقوم geo.intersects Azure Cognitive Search بتقييم حقل موجود null، ستكون falseالنتيجة دائما . يعتمد سلوك geo.distance في هذه الحالة على السياق:
- في عوامل التصفية ،
geo.distanceينتج عنnullحقل ما .nullهذا يعني أن المستند لن يتطابق لأنهnullبالمقارنة مع أي قيمة غير فارغة يتم تقييمها إلىfalse. - عند فرز النتائج باستخدام $orderby،
geo.distanceينتج عن حقل ماnullأقصى مسافة ممكنة. سيتم فرز المستندات التي تحتوي على مثل هذا الحقل أقل من جميع المستندات الأخرى عند استخدام اتجاهascالفرز (الافتراضي) ، وأعلى من جميع المستندات الأخرى عندما يكون الاتجاهdesc.
أمثلة
أمثلة على الفلاتر
ابحث عن جميع الفنادق على بعد 10 كيلومترات من نقطة مرجعية معينة (حيث يكون الموقع مجالا من النوع Edm.GeographyPoint):
geo.distance(location, geography'POINT(-122.131577 47.678581)') le 10
ابحث عن جميع الفنادق ضمن إطار عرض معين موصوف بأنه مضلع (حيث يكون الموقع حقل نوع Edm.GeographyPoint). لاحظ أن المضلع مغلق (يجب أن تكون مجموعتا النقاط الأولى والأخيرة متماثلتين) ويجب إدراج النقاط بترتيب عكس اتجاه عقارب الساعة.
geo.intersects(location, geography'POLYGON((-122.031577 47.578581, -122.031577 47.678581, -122.131577 47.678581, -122.031577 47.578581))')
أمثلة حسب الترتيب
فرز الفنادق تنازليا ثم ratingصعودا حسب المسافة من الإحداثيات المحددة:
rating desc,geo.distance(location, geography'POINT(-122.131577 47.678581)') asc
فرز الفنادق بترتيب تنازلي حسب و rating، ثم بترتيب تصاعدي حسب search.score المسافة من الإحداثيات المعطاة بحيث يتم سرد أقرب فندق بين فندقين بتصنيفات متطابقة أولا:
search.score() desc,rating desc,geo.distance(location, geography'POINT(-122.131577 47.678581)') asc