OData geo-térbeli függvények az Azure AI Searchben – geo.distance és geo.intersects

  • Cikk

Az Azure AI Search a függvényeken keresztül támogatja az geo.distancegeo.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.

Megjegyzé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ő:

OData szintaxisdiagram az Azure AI Searchhöz

Megjegyzé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ó.

Megjegyzé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 ltaz , le, gtvagy 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 adtrueEdm.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 nulleredmé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 egy null mező eredménye a nullkövetkező lesz: . Ez azt jelenti, hogy a dokumentum nem fog egyezni, mert null a nem null értékű értékekhez képest a program a következőre értékeli a falsefájlt.
  • Az eredmények $orderbygeo.distance használatával történő rendezésekor egy null mező a lehető legnagyobb távolságot eredményezi. Az ilyen mezővel rendelkező dokumentumok a rendezési irány asc használata esetén (az alapértelmezett) és a többinél magasabb lesz, ha az irány az desc.

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 , ratingmajd 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

Következő lépések