Azure AI 搜尋中的 OData 地理空間函式 - geo.distance 和 geo.intersects

  • 發行項

Azure AI 搜尋可透過 geo.distance 和 geo.intersects 函式，在 OData 篩選表示式中支援地理空間查詢。 函 geo.distance 式會傳回兩個點之間的公里距離，一個是字段或範圍變數，另一個是作為篩選條件一部分傳遞的常數。 geo.intersects如果指定的點位於指定的多邊形內，則函式會true傳回 ，其中該點是欄位或範圍變數，而且多邊形會指定為篩選條件一部分傳遞的常數。

函geo.distance式也可以在 $orderby 參數中使用，依距離指定點的距離來排序搜尋結果。 $orderby 的語法與$filter中的語法geo.distance相同。 在 $orderby中使用 geo.distance 時，其套用的欄位必須是類型Edm.GeographyPoint，而且也必須可排序。

注意

在 $orderby 參數中使用 geo.distance 時，您傳遞給函式的字段必須只包含單一地理點。 換句話說，它必須是 類型 Edm.GeographyPoint ，而不是 Collection(Edm.GeographyPoint)。 無法在 Azure AI 搜尋服務中排序集合欄位。

語法

下列 EBNF （Extended Backus-Naur Form） 會定義 和 geo.intersects 函式的geo.distance文法，以及其運作所在的地理空間值：

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

您也可以使用互動式語法圖表：

Azure AI 搜尋的 OData 語法圖表

注意

如需完整的EBNF，請參閱 Azure AI 搜尋 的 OData 表達式語法參考。

geo.distance

函 geo.distance 式會採用類型的 Edm.GeographyPoint 兩個 Edm.Double 參數，並傳回以公里為單位的距離值。 這與其他支援 OData 地理空間作業的服務不同，這些作業通常會以公尺為單位傳回距離。

其中一個參數 geo.distance 必須是 geography 點常數，另一個參數必須是欄位路徑（或在篩選逐一查看類型 Collection(Edm.GeographyPoint)字段的情況下的範圍變數）。 這些參數的順序並不重要。

geography 點常數的格式 geography'POINT(<longitude> <latitude>)'為 ，其中經度和緯度是數值常數。

注意

geo.distance在篩選中使用 時，您必須使用 lt、le、 gt或 ge來比較函式所傳回的距離與常數。 比較距離時不支援 和 ne 運算符eq。 例如，這是的正確用法 geo.distance： $filter=geo.distance(location, geography'POINT(-122.131577 47.678581)') le 5。

geo.intersects

函geo.intersects式會採用 類型的Edm.GeographyPoint變數和常數Edm.GeographyPolygon，如果點位於多邊形的範圍內，則傳回 ，false否則傳回Edm.Boolean -- true 。

多邊形是一個二維表面，儲存為定義周框環形的點序列（請參閱 下列範例 ）。 多邊形必須關閉，這表示第一個和最後一個點集合必須相同。 多邊形中的點必須以逆時針順序排列。

跨越第180個經線的地理空間查詢和多邊形

對於許多地理空間查詢連結庫，制定包含第180個子午線（接近日期線）的查詢是非限制，或需要因應措施，例如將多邊形分割成兩個，一個在子午線的任一端。

在 Azure AI 搜尋服務中，如果查詢圖形是矩形，且您的座標會沿著經度和緯度對齊網格線配置（例如， geo.intersects(location, geography'POLYGON((179 65, 179 66, -179 66, -179 65, 179 65))'），包含 180 度經度的地理空間查詢會如預期般運作。 否則，針對非矩形或未對齊的圖形，請考慮分割多邊形方法。

地理空間函式和 null

就像 Azure AI 搜尋中所有其他非集合欄位一樣，類型的 Edm.GeographyPoint 欄位可以包含 null 值。 當 Azure AI 搜尋評估 geo.intersects 為 的 null欄位時，結果一律為 false。 在此情況下的行為 geo.distance 取決於內容：

  • 在篩選中null，geo.distance欄位的結果為 null。 這表示檔案不會相符，因為 null 與任何非 Null 值相較之下會評估為 false。
  • 使用 $orderby排序結果時， geo.distancenull 欄位會產生最大可能距離。 使用排序方向 asc 時，具有這類欄位的檔會比所有其他欄位都低排序（預設值），而當方向為 desc時，則高於所有其他欄位。

範例

篩選範例

指定參考點的 10 公里內尋找所有酒店（其中位置是類型的 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

依 和 rating以遞減順序search.score排序旅館，然後依與指定座標的距離遞增順序排序酒店，使兩家酒店之間的評分相同，最接近的會先列出：

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

下一步