Funkcje geoprzestrzenne OData w IQ usługi Foundry (Wyszukiwanie AI platformy Azure) — geo.distance i geo.intersects

Uwaga

Foundry IQ (Wyszukiwanie AI platformy Azure) udostępnia bezpośrednie interfejsy API indeksowania i zapytań, a także interfejsy API wyższego poziomu dla źródeł wiedzy i baz wiedzy do zarządzanego pobierania. Użyj portalu Azure, interfejsów API REST lub Azure SDKs, aby skonfigurować te możliwości lub połączyć agentów z bazami wiedzy w portalu Microsoft Foundry.

Usługa Foundry IQ (Wyszukiwanie AI platformy Azure) obsługuje zapytania geoprzestrzenne w wyrażeniach filtrów OData za pośrednictwem funkcji geo.distance i geo.intersects. Funkcja geo.distance zwraca odległość w kilometrach między dwoma punktami, z których jeden jest polem lub zmienną zakresu, a drugą stałą przekazywaną jako część filtra. Funkcja geo.intersects zwraca true , jeśli dany punkt znajduje się w danym wielokącie, gdzie punkt jest polem lub zmienną zakresu, a wielokąt jest określony jako stała przekazywana jako część filtru.

Funkcja geo.distance może być również używana w parametrze $orderby do sortowania wyników wyszukiwania według odległości od danego punktu. Składnia dla geo.distance w $orderby jest taka sama jak w $filter. W przypadku użycia geo.distance w $orderby pole, do którego ma zastosowanie, musi być typu Edm.GeographyPoint i musi być również sortowalne.

Uwaga

W przypadku użycia geo.distance w parametrze $orderby pole przekazywane do funkcji musi zawierać tylko jeden punkt geograficzny. Innymi słowy, musi być typu Edm.GeographyPoint , a nie Collection(Edm.GeographyPoint). Nie można sortować według pól kolekcji w usłudze Foundry IQ.

Składnia

Następująca EBNF (Rozszerzona Forma Backus-Naur) definiuje gramatykę funkcji geo.distance i geo.intersects, a także wartości geoprzestrzenne, na których działają:

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

Dostępny jest również interakcyjny diagram składni:

geo.distance

Funkcja geo.distance przyjmuje dwa parametry typu Edm.GeographyPoint i zwraca Edm.Double wartość, która jest odległością między nimi w kilometrach. Różni się to od innych usług, które obsługują operacje geoprzestrzewne OData, które zwykle zwracają odległości w metrach.

Jeden z parametrów w geo.distance musi być stałą punktu geograficznego, a drugi musi być ścieżką pola (lub zmienną zakresu w przypadku iteracji filtru po polu typu Collection(Edm.GeographyPoint)). Kolejność tych parametrów nie ma znaczenia.

Stała punktu geograficznego ma postać geography'POINT(<longitude> <latitude>)', gdzie długość geograficzna i szerokość geograficzna są stałymi liczbowymi.

Uwaga

W przypadku użycia geo.distance w filtrze należy porównać odległość zwracaną przez funkcję ze stałą przy użyciu lt, le, gt lub ge. Operatory eq i ne nie są obsługiwane podczas porównywania odległości. Na przykład jest to poprawne użycie elementu geo.distance: $filter=geo.distance(location, geography'POINT(-122.131577 47.678581)') le 5.

geo.intersects

Funkcja geo.intersects przyjmuje zmienną typu Edm.GeographyPoint i stałą Edm.GeographyPolygon i zwraca Edm.Boolean -- wartość, jeśli punkt znajduje się w granicach wielokąta true, false w przeciwnym razie.

Wielokąt jest dwuwymiarową powierzchnią przechowywaną jako sekwencja punktów definiujących pierścień ograniczenia (zobacz poniższe przykłady ). Wielokąt musi być zamknięty, co oznacza, że pierwsze i ostatnie zestawy punktów muszą być takie same. Punkty w wielokącie muszą być ułożone w kolejności przeciwnej do ruchu wskazówek zegara.

Zapytania geoprzestrzenne i wielokąty obejmujące południk 180.

W przypadku wielu bibliotek zapytań geoprzestrzennych formułowanie zapytania zawierającego 180-ty południk (w pobliżu linii daty) jest często niemożliwe lub wymaga obejścia, takiego jak podzielenie wielokąta na dwa, po jednym po każdej stronie południka.

W zapytaniu IQ usługi Foundry zapytania geoprzestrzenne zawierające długość geograficzną 180 stopni będą działać zgodnie z oczekiwaniami, jeśli kształt zapytania jest prostokątny, a współrzędne są wyrównane do układu siatki wzdłuż długości i szerokości geograficznej (na przykład geo.intersects(location, geography'POLYGON((179 65, 179 66, -179 66, -179 65, 179 65))'). W przeciwnym razie, w przypadku kształtów nieprostokątnych lub niewyrównanych, należy wziąć pod uwagę podejście rozdzielania wielokąta.

Funkcje geoprzestrzenne i null

Podobnie jak wszystkie inne pola niezwiązane z kolekcją w Foundry IQ, pola typu Edm.GeographyPoint mogą zawierać wartości null. Gdy Foundry IQ oblicza geo.intersects dla pola, które jest null, wynik będzie zawsze wynosić false. Zachowanie geo.distance w tym przypadku zależy od kontekstu:

  • W filtrach pole geo.distancenull skutkuje null. Oznacza to, że dokument nie będzie zgodny, ponieważ null w porównaniu z dowolną wartością inną niż null daje wynik false.
  • Podczas sortowania wyników przy użyciu $orderby, posortowanie według pola geo.distance skutkuje maksymalną możliwą odległością. Dokumenty z takim polem będą sortowane niżej niż wszystkie inne, gdy używany jest kierunek sortowania asc (wartość domyślna), i wyżej niż wszystkie inne, gdy kierunek to desc.

Przykłady

Przykłady filtrów

Znajdź wszystkie hotele w ciągu 10 kilometrów od danego punktu odniesienia (gdzie lokalizacja jest polem typu Edm.GeographyPoint):

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

Znajdź wszystkie hotele w danym widoku opisanym jako wielokąt (gdzie lokalizacja jest polem typu Edm.GeographyPoint). Należy pamiętać, że wielokąt jest zamknięty (pierwszy i ostatni zestaw punktów musi być taki sam), a punkty muszą być wymienione w kolejności odwrotnej.

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

Przykłady sortowania

Sortuj hotele malejące według rating, a następnie rosnąco według odległości od podanych współrzędnych:

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

Sortuj hotele w kolejności malejącej według search.score i rating, a następnie w kolejności rosnącej według odległości od podanych współrzędnych, tak aby między dwoma hotelami o identycznych ocenach, najbliższy jest wymieniony jako pierwszy:

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

Następne kroki