Геопространствовые функции OData в Azure ИИ Поиск - geo.distance и geo.intersects

Поиск Azure AI поддерживает геопространственные запросы в выражениях фильтров OData с помощью функций и geo.distance. Функция geo.distance возвращает расстояния в километрах между двумя точками, одна из которых представляет собой поле или переменную диапазона, а другая — константу, переданную как часть фильтра. Функция geo.intersects возвращает значение true, если заданная точка находится в пределах указанного многоугольника, где точка представляет собой поле или переменную диапазона, а многоугольник указывается в качестве константы, переданной как часть фильтра.

Функцию geo.distance также можно использовать в параметре $orderby для сортировки результатов поиска по расстоянию от заданной точки. Синтаксис для geo.distance в $orderby такой же, как и в $filter. При использовании элемента geo.distance в $orderby поле, к которому оно применяется, должно принадлежать к типу Edm.GeographyPoint и также должно быть sortable.

Синтаксис

Следующая EBNF (Расширенная форма Бэкуса-Наура) определяет грамматику функций geo.distance и geo.intersects, а также геопространственные значения, с которыми они работают.

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

Кроме того, вам может помочь интерактивная схема синтаксиса:

geo.distance

Функция geo.distance принимает два параметра типа Edm.GeographyPoint и возвращает значение Edm.Double, которое представляет собой расстояние между ними в километрах. В отличие от других служб, которые поддерживают геопространственные операции OData, он обычно возвращает расстояние в метрах.

Один из параметров geo.distance должен быть константой географической точки, а другой — путем поля (или переменной диапазона при итерации с использованием фильтра по полю типа Collection(Edm.GeographyPoint)). Порядок этих параметров не имеет значения.

Константа географической точки имеет форму geography'POINT(<longitude> <latitude>)', где долгота и широта являются числовыми константами.

geo.intersects

Функция geo.intersects принимает переменную типа Edm.GeographyPoint и константу Edm.GeographyPolygon и возвращает Edm.Boolean -- true, если точка находится внутри границ многоугольника. В противном случае возвращается значение false.

Многоугольник — это двумерная поверхность, которая хранится в виде последовательности точек, определяющих ограничивающее кольцо (см. примеры ниже). Многоугольник должен быть замкнут, то есть первая и конечная точки должны совпадать. Точки многоугольника должны быть расположены в порядке против часовой стрелки.

Геопространственные запросы и многоугольники, охватывающие 180-й меридиан

Для многих библиотек геопространственных запросов формирование запроса, включающего 180-й меридиан (около линии перемены даты), либо запрещено, либо требует обходного пути, такого как разделение многоугольника на два, по одному с каждой стороны меридиана.

В поиске Azure AI геопространственные запросы, включающие 180-градусную долготу, будут работать должным образом, если фигура запроса прямоугольная, а координаты выравниваются по сетке вдоль долготы и широты (например, geo.intersects(location, geography'POLYGON((179 65, 179 66, -179 66, -179 65, 179 65))'). В противном случае для непрямоугольных или невыровненных фигур используйте подход с разделенным многоугольником.

Геопространственные функции и null

Как и все другие поля, не относящиеся к коллекциям в службе "Поиск ИИ Azure", поля типа Edm.GeographyPoint могут содержать значения null. Если Поиск с использованием ИИ Azure вычисляет geo.intersects для поля, которое является null, результат всегда будет false. Поведение geo.distance в этом случае зависит от контекста:

• В фильтрах функция geo.distance для поля null в результате даст null. Это означает, что документ не будет соответствовать запросу, так как результатом вычисления при сравнении null с любым значением, отличным от NULL, будет false.
• При сортировке результатов с помощью $orderby результатом вычисления функции geo.distance для поля null будет максимально возможное расстояние. Документы с таким полем при сортировке будут располагаться ниже всех прочих, если направление сортировки — asc (по умолчанию), и выше всех остальных, если направление — desc.

Примеры

Примеры фильтров

Найти все отели в пределах 10 километров от заданного ориентира (где location — это поле типа Edm.GeographyPoint):

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

Найти все отели в заданном окне просмотра, описанном как многоугольник (где location — это поле типа Edm.GeographyPoint). Обратите внимание, что многоугольник замкнут (первая и последняя точки должны совпадать, и точки должны быть нанесены в порядке против часовой стрелки).

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

Примеры использования ORDER BY

Сортировать отели по убыванию параметра rating, а затем по возрастанию расстояния от заданных координат:

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

Сортировка отелей в порядке убывания по параметрам search.score и rating, а затем в порядке возрастания расстояния от заданных координат так, чтобы между двумя отелями с одинаковым рейтингом сначала отображался ближайший:

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

Следующие шаги

• Фильтры в поиске ИИ Azure
• Обзор языка выражений OData для поиска ИИ Azure
• Справочник по синтаксису выражений OData для поиска ИИ Azure
• Поиск в документах (REST API Поиск с использованием ИИ Azure)