Geoprostorové funkce OData ve službě Azure AI Search – geo.distance a geo.intersects

  • Článek

Azure AI Search podporuje geoprostorové dotazy ve výrazech filtru OData prostřednictvím geo.distance a geo.intersects funkcí. Funkce geo.distance vrátí vzdálenost v kilometrech mezi dvěma body, jedna je pole nebo proměnná oblasti a jedna je konstantou předanou jako součást filtru. Funkce geo.intersects vrátí true , pokud je daný bod v daném mnohoúhelníku, kde bod je pole nebo proměnná oblasti a mnohoúhelník je určen jako konstanta předaná jako součást filtru.

Funkci geo.distance lze také použít v parametru$orderby k seřazení výsledků hledání podle vzdálenosti od daného bodu. Syntaxe pro geo.distance $orderby je stejná jako v $filter. Při použití geo.distance v $orderby musí být pole, na které se vztahuje, typu Edm.GeographyPoint a musí být také seřazené.

Poznámka:

Při použití geo.distance v parametru $orderby musí pole, které funkci předáte, obsahovat pouze jeden geografický bod. Jinými slovy, musí být typu Edm.GeographyPoint , nikoli Collection(Edm.GeographyPoint). V Azure AI Search není možné řadit podle polí kolekce.

Syntaxe

Následující ebNF (Extended Backus-Naur Form) definuje gramatiku geo.distance funkcí a geo.intersects také geoprostorové hodnoty, na kterých pracují:

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)*

K dispozici je také interaktivní diagram syntaxe:

Diagram syntaxe OData pro Azure AI Search

Poznámka:

Úplný soubor EBNF najdete v referenčních informacích k syntaxi výrazů OData pro Azure AI Search .

geo.distance

Funkce geo.distance přebírá dva parametry typu Edm.GeographyPoint a vrací Edm.Double hodnotu, která je vzdáleností mezi nimi v kilometrech. To se liší od jiných služeb, které podporují geoprostorové operace OData, což obvykle vrací vzdálenosti v metrech.

Jeden z parametrů geo.distance musí být konstanta zeměpisného bodu a druhý musí být cesta k poli (nebo proměnná oblasti v případě iterace filtru přes pole typu Collection(Edm.GeographyPoint)). Pořadí těchto parametrů nezáleží.

Zeměpisná bodová konstanta je ve tvaru geography'POINT(<longitude> <latitude>)', kde zeměpisná délka a zeměpisná šířka jsou číselné konstanty.

Poznámka:

Při použití geo.distance ve filtru je nutné porovnat vzdálenost vrácenou funkcí pomocí konstanty pomocí lt, le, gt, nebo ge. Operátory eq a ne nejsou podporovány při porovnávání vzdáleností. Jedná se například o správné použití geo.distance: $filter=geo.distance(location, geography'POINT(-122.131577 47.678581)') le 5.

geo.intersects

Funkce geo.intersects přebírá proměnnou typu Edm.GeographyPoint a konstantu Edm.GeographyPolygon a vrátítrueEdm.Boolean -- hodnotu, pokud je bod v mezích mnohoúhelníku, false jinak.

Mnohoúhelník je dvourozměrný povrch uložený jako posloupnost bodů definujících ohraničující prstenec (viz příklady níže). Mnohoúhelník musí být uzavřen, což znamená, že první a poslední množiny bodů musí být stejné. Body v mnohoúhelníku musí být v proti směru hodinových ručiček.

Geoprostorové dotazy a mnohoúhelníky, které pokrývají 180. poledník

U mnoha knihoven geoprostorových dotazů, které označují dotaz, který obsahuje 180. poledník (poblíž data) je buď mimo limity, nebo vyžaduje alternativní řešení, například rozdělení mnohoúhelníku na dvě, jednu na obou stranách poledníku.

Ve službě Azure AI Search budou geografické dotazy, které obsahují délku 180 stupňů, fungovat podle očekávání, pokud je tvar dotazu obdélníkový a souřadnice odpovídají rozložení mřížky podél délky a zeměpisné šířky (například geo.intersects(location, geography'POLYGON((179 65, 179 66, -179 66, -179 65, 179 65))'). V opačném případě u neúhelníkových nebo nezarovnaných obrazců zvažte přístup rozděleného mnohoúhelníku.

Geoprostorové funkce a null

Stejně jako všechna ostatní pole mimo kolekci ve službě Azure AI Search můžou pole typu Edm.GeographyPoint obsahovat null hodnoty. Když Azure AI Search vyhodnotí geo.intersects pole, které je null, výsledek bude vždy false. Chování geo.distance v tomto případě závisí na kontextu:

  • Ve filtrech geo.distancenull je výsledkem nullpole . To znamená, že dokument se neshoduje, protože null v porovnání s žádnou hodnotou, která není null, se vyhodnotí jako false.
  • Při řazení výsledků pomocí $orderbygeo.distancenull má pole maximální možnou vzdálenost. Dokumenty s tímto polem budou řadit nižší než všechny ostatní, když se použije směr asc řazení (výchozí) a vyšší než všechny ostatní, pokud je descsměr .

Příklady

Příklady filtrů

Najděte všechny hotely v okruhu 10 kilometrů od daného referenčního bodu (kde umístění je pole typu Edm.GeographyPoint):

    geo.distance(location, geography'POINT(-122.131577 47.678581)') le 10

Najděte všechny hotely v daném oblasti zobrazení popsané jako mnohoúhelník (kde umístění je pole typu Edm.GeographyPoint). Všimněte si, že mnohoúhelník je uzavřen (první a poslední množiny bodů musí být stejné) a body musí být uvedeny v pořadí proti směru hodinových ručiček.

    geo.intersects(location, geography'POLYGON((-122.031577 47.578581, -122.031577 47.678581, -122.131577 47.678581, -122.031577 47.578581))')

Příklady seřazené podle

Seřaďte hotely sestupně podle rating, potom vzestupně podle vzdálenosti od daných souřadnic:

    rating desc,geo.distance(location, geography'POINT(-122.131577 47.678581)') asc

Seřaďte hotely v sestupném pořadí podle search.score a ratingpotom ve vzestupném pořadí podle vzdálenosti od daných souřadnic tak, aby mezi dvěma hotely s identickými hodnoceními byla uvedena jako první:

    search.score() desc,rating desc,geo.distance(location, geography'POINT(-122.131577 47.678581)') asc

Další kroky