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

Az Azure AI Keresés támogatja a térinformatikai lekérdezéseket az OData szűrőkifejezéseken keresztül a geo.distance és geo.intersects függvények használatával. 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 geo.distance szintaxisa az $orderby-ban ugyanaz, mint a $filter-ben. A geo.distance használatakor a mező, amelyre vonatkozik, típusú kell legyen, és Edm.GeographyPoint rendezhető is kell legyen.

Szintaxis

A következő EBNF (Extended Backus-Naur Form) határozza meg a geo.distance és geo.intersects függvények 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ő:

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 alak geography'POINT(<longitude> <latitude>)', ahol a hosszúság és a szélesség numerikus állandó.

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 adEdm.Boolean -- truevissza, 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 Keresésben 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 igazított alakzatok esetében fontolja meg a többszög közelítését.

Geo-térbeli függvények és null

Az Azure AI Keresés 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 Keresés 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 a geo.distance egy null mezőben null eredményez. Ez azt jelenti, hogy a dokumentum nem fog egyezni, mert a null bármelyik nem-null értékhez viszonyítva false-re értékelődik.
• Amikor az eredményeket a $orderby alapján rendezzük, egy geo.distance mező esetén a lehető legnagyobb távolságot kapjuk. Az ilyen mezővel rendelkező dokumentumok az összes többi alá rendeződnek, amikor a rendezési irány asc (az alapértelmezett) és az összes többi fölé kerülnek, amikor az irány 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

• Szűrők az Azure AI Keresésben
• Az Azure AI Keresés OData-kifejezési nyelvének áttekintése
• OData-kifejezések szintaxisának referenciája az Azure AI Keresés számára
• Dokumentumok keresése (Azure AI Keresés REST API)