OData geo-térbeli függvények az Azure AI Searchben – geo.distance
és geo.intersects
Az Azure AI Search a függvényeken keresztül támogatja az geo.distance
geo.intersects
OData-szűrőkifejezések térbeli lekérdezéseit. A geo.distance
függvény két pont közötti kilométerben adja vissza a távolságot, az egyik mező- vagy tartományváltozó, a másik pedig a szűrő részeként átadott állandó. A geo.intersects
függvény akkor ad vissza true
, ha egy adott pont egy adott sokszögön belül van, ahol a pont egy mező- vagy tartományváltozó, a sokszög pedig a szűrő részeként átadott állandóként van megadva.
A geo.distance
függvény a $orderby paraméterben is használható a keresési eredmények egy adott ponttól való távolság szerinti rendezéséhez. A $orderby szintaxisa geo.distance
megegyezik a $filter. A $orderby használatakor geo.distance
a mezőnek, amelyre vonatkozik, típusnak Edm.GeographyPoint
kell lennie, és rendezhetőnek is kell lennie.
Feljegyzés
A $orderby paraméter használatakor geo.distance
a függvénynek átadott mezőnek csak egyetlen geopontot kell tartalmaznia. Más szóval a típusnak Edm.GeographyPoint
kell lennie, és nem Collection(Edm.GeographyPoint)
. Az Azure AI Search gyűjteménymezői nem rendezhetők.
Syntax
A következő EBNF (Extended Backus-Naur Form) határozza meg a függvények és geo.intersects
függvények geo.distance
nyelvtanát, valamint azokat a geo-térbeli értékeket, amelyeken működnek:
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)*
Interaktív szintaxisdiagram is elérhető:
Feljegyzés
A teljes EBNF-hez tekintse meg az Azure AI Search OData-kifejezésszintaxis-hivatkozását.
geo.distance
A geo.distance
függvény két típusparamétert Edm.GeographyPoint
vesz fel, és egy Edm.Double
olyan értéket ad vissza, amely a távolságuk kilométerben van. Ez eltér az OData geotéri műveleteit támogató egyéb szolgáltatásoktól, amelyek általában méterben adnak vissza távolságokat.
Az egyik paraméternek geo.distance
földrajzi pont állandónak kell lennie, a másiknak mezőútvonalnak (vagy tartományváltozónak kell lennie egy olyan szűrő esetében, amely egy adott típusú Collection(Edm.GeographyPoint)
mezőn halad át). Ezeknek a paramétereknek a sorrendje nem számít.
A földrajzi pont állandója az űrlap geography'POINT(<longitude> <latitude>)'
, ahol a hosszúság és a szélesség numerikus állandó.
Feljegyzés
Szűrő használata geo.distance
esetén össze kell hasonlítania a függvény által visszaadott távolságot egy állandóval, amely lt
az , le
, gt
vagy ge
. Az operátorok eq
, és ne
nem támogatottak a távolságok összehasonlításakor. Ez például a következő helyes használata geo.distance
: $filter=geo.distance(location, geography'POINT(-122.131577 47.678581)') le 5
.
geo.intersects
A geo.intersects
függvény egy típusváltozót Edm.GeographyPoint
és egy állandót Edm.GeographyPolygon
vesz fel, és egy olyan értéket adtrue
Edm.Boolean
-- vissza, ha a pont a sokszög határán belül van, false
ellenkező esetben.
A sokszög egy kétdimenziós felület, amely a határoló gyűrűt meghatározó pontok sorozataként van tárolva (lásd az alábbi példákat ). A sokszöget be kell zárni, ami azt jelenti, hogy az első és az utolsó ponthalmaznak azonosnak kell lennie. A sokszögben lévő pontoknak az óramutató járásával ellentétes sorrendben kell lenniük.
Geo-térbeli lekérdezések és sokszögek a 180. meridiánon
Számos geo-térbeli lekérdezéstár esetében a 180. meridiánt (a dátumvonal közelében) tartalmazó lekérdezések korláton kívül esnek, vagy kerülő megoldást igényelnek, például a sokszöget két részre osztják, a meridián mindkét oldalán.
Az Azure AI Searchben a 180 fokos hosszúságot tartalmazó térbeli lekérdezések a várt módon működnek, ha a lekérdezés alakja téglalap alakú, és a koordináták a hosszúság és a szélesség mentén egy rácselrendezéshez igazodnak (például geo.intersects(location, geography'POLYGON((179 65, 179 66, -179 66, -179 65, 179 65))'
). Ellenkező esetben a nem téglalap alakú vagy a nem elválasztó alakzatok esetében fontolja meg a többszög felosztását.
Geo-térbeli függvények és null
Az Azure AI Search többi nem gyűjteménymezőjéhez hasonlóan a típusmezők Edm.GeographyPoint
is tartalmazhatnak null
értékeket. Amikor az Azure AI Search kiértékel geo.intersects
egy mezőt, az null
eredmény mindig az lesz false
. Ebben az esetben a geo.distance
viselkedés a környezettől függ:
- A szűrőkben
geo.distance
egynull
mező eredménye anull
következő lesz: . Ez azt jelenti, hogy a dokumentum nem fog egyezni, mertnull
a nem null értékű értékekhez képest a program a következőre értékeli afalse
fájlt. - Az eredmények $orderby
geo.distance
használatával történő rendezésekor egynull
mező a lehető legnagyobb távolságot eredményezi. Az ilyen mezővel rendelkező dokumentumok a rendezési irányasc
használata esetén (az alapértelmezett) és a többinél magasabb lesz, ha az irány azdesc
.
Példák
Példák szűrése
Keresse meg az összes szállodát egy adott referenciaponttól számított 10 kilométeren belül (ahol a hely egy típusmező Edm.GeographyPoint
):
geo.distance(location, geography'POINT(-122.131577 47.678581)') le 10
Keresse meg az összes szállodát egy adott nézetportban, amely sokszögként van leírva (ahol a hely egy típusmező Edm.GeographyPoint
). Vegye figyelembe, hogy a sokszög be van zárva (az első és az utolsó ponthalmaznak azonosnak kell lennie), és a pontoknak az óramutató járásával ellentétes sorrendben kell szerepelnie.
geo.intersects(location, geography'POLYGON((-122.031577 47.578581, -122.031577 47.678581, -122.131577 47.678581, -122.031577 47.578581))')
Példák sorrend szerint
Rendezze a szállodákat csökkenő sorrendbe rating
, majd a megadott koordinátáktól való távolság alapján növekvő sorrendbe:
rating desc,geo.distance(location, geography'POINT(-122.131577 47.678581)') asc
Rendezze a szállodákat csökkenő sorrendben search.score
, rating
majd növekvő sorrendben a megadott koordinátáktól való távolság alapján úgy, hogy két azonos minősítéssel rendelkező szálloda között a legközelebbi legyen a lista elsőként:
search.score() desc,rating desc,geo.distance(location, geography'POINT(-122.131577 47.678581)') asc