Table Store Java SDK 地理位置查詢 - Tablestore

使用 Tablestore Java SDK 的地理位置查詢可按與中心點的距離、長方形範圍或多邊形範圍篩選資料。

前提條件

安裝Tablestore Java SDK並初始化用戶端。

功能說明

地理位置查詢用於按 GEO_POINT 類型索引欄位的地理位置篩選資料，支援以下查詢方式。

地理距離查詢（GeoDistanceQuery）：查詢與指定中心點的距離小於或等於指定值的資料。
地理長方形範圍查詢（GeoBoundingBoxQuery）：查詢位於指定長方形範圍內的資料。長方形由左上方和右下角的座標確定。
地理多邊形範圍查詢（GeoPolygonQuery）：查詢位於指定多邊形範圍內的資料。多邊形由多個座標點確定。

調用 search 方法時，根據要查詢的地理範圍，將查詢類型設定為 GeoDistanceQuery、GeoBoundingBoxQuery 或 GeoPolygonQuery。

SearchResponse search(SearchRequest request)

以下樣本查詢 location 欄位與中心點 0,0 的距離不超過 120000 米的資料，返回最多 10 行資料及匹配總行數。

String tableName = "example_table";
String indexName = "example_index";

GeoDistanceQuery geoDistanceQuery = new GeoDistanceQuery();
geoDistanceQuery.setFieldName("location");
geoDistanceQuery.setCenterPoint("0,0");
geoDistanceQuery.setDistanceInMeter(120000);

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(geoDistanceQuery);
searchQuery.setLimit(10);
searchQuery.setTrackTotalCount(SearchQuery.TRACK_TOTAL_COUNT);

SearchRequest request = new SearchRequest(tableName, indexName, searchQuery);
SearchRequest.ColumnsToGet columnsToGet = new SearchRequest.ColumnsToGet();
columnsToGet.setReturnAll(true);
request.setColumnsToGet(columnsToGet);

SearchResponse response = client.search(request);
System.out.println(response.getTotalCount());
System.out.println(response.getRows());

參數說明

查詢請求

request 的類型為 SearchRequest，包含以下參數。

名稱	類型	說明
tableName（必選）	String	資料表名稱。
indexName（必選）	String	多元索引名稱。
searchQuery（必選）	SearchQuery	查詢條件和通用查詢配置。
columnsToGet（可選）	SearchRequest.ColumnsToGet	返回列配置。未設定時只返回主鍵列。
timeoutInMillisecond（可選）	int	請求級查詢逾時時間，單位為毫秒。預設值為 `-1`，表示不單獨設定查詢逾時時間。
routingValues（可選）	`List<PrimaryKey>`	自訂路由欄位對應的主索引值列表。未配置自訂路由時無需設定。

查詢配置

request.searchQuery 的類型為 SearchQuery，包含以下參數。

名稱	類型	說明
query（必選）	Query	查詢條件。根據查詢方式設定為 `GeoDistanceQuery`、`GeoBoundingBoxQuery` 或 `GeoPolygonQuery`。
offset（可選）	Integer	本次查詢的起始位置。
limit（可選）	Integer	本次查詢返回的最大行數。設定為 `0` 時不返回具體行。
collapse（可選）	Collapse	結果摺疊配置，用於按指定列對返回結果去重。有關配置方法，請參見摺疊（去重）。
sort（可選）	Sort	返回結果的排序方式。有關配置方法，請參見排序和翻頁。
trackTotalCount（可選）	int	期望統計的最大匹配行數。預設值為 `TRACK_TOTAL_COUNT_DISABLED`，表示不統計；設定為 `TRACK_TOTAL_COUNT` 時統計全部匹配行。值越小，查詢效能越高。
filter（可選）	SearchFilter	對 `query` 的查詢結果進行過濾。
aggregationList（可選）	`List<Aggregation>`	統計彙總配置。有關配置方法，請參見統計彙總。
groupByList（可選）	`List<GroupBy>`	分組配置。有關配置方法，請參見統計彙總。
token（可選）	byte[]	翻頁憑證。將上一次響應的 `nextToken` 設定為該參數可繼續讀取後續資料。設定 `token` 時，SDK 會清除 `sort`，因為翻頁憑證中已包含排序條件。

以下三類地理位置查詢涉及的座標均使用 緯度,經度 格式，緯度在前，經度在後。緯度範圍為 [-90,+90]，經度範圍為 [-180,+180]，例如 35.8,-45.91。

地理距離條件

地理距離查詢中，request.searchQuery.query 的類型為 GeoDistanceQuery，包含以下參數。

名稱	類型	說明
fieldName（必選）	String	要查詢的 `GEO_POINT` 類型索引欄位名稱。
centerPoint（必選）	String	查詢範圍的中心點座標。
distanceInMeter（必選）	double	與中心點的最大距離，單位為米。

長方形範圍條件

地理長方形範圍查詢中，request.searchQuery.query 的類型為 GeoBoundingBoxQuery，包含以下參數。

名稱	類型	說明
fieldName（必選）	String	要查詢的 `GEO_POINT` 類型索引欄位名稱。
topLeft（必選）	String	長方形左上方的座標。
bottomRight（必選）	String	長方形右下角的座標。

多邊形範圍條件

地理多邊形範圍查詢中，request.searchQuery.query 的類型為 GeoPolygonQuery，包含以下參數。

名稱	類型	說明
fieldName（必選）	String	要查詢的 `GEO_POINT` 類型索引欄位名稱。
points（必選）	`List<String>`	構成多邊形的座標點列表。

返回列

request.columnsToGet 的類型為 SearchRequest.ColumnsToGet，包含以下參數。

名稱	類型	說明
columns（可選）	`List<String>`	要返回的屬性列名稱。僅 `returnAll` 和 `returnAllFromIndex` 均為 `false` 時需要設定；未設定時只返回主鍵列。
returnAll（可選）	boolean	是否返回資料表中的全部屬性列。預設值為 `false`。
returnAllFromIndex（可選）	boolean	是否返回已建立索引的全部屬性列。預設值為 `false`。不能與 `returnAll` 同時設定為 `true`。

傳回值

search 方法返回 SearchResponse。核心欄位如下。

名稱	類型	說明
totalCount	long	匹配行數，通過 `getTotalCount()` 擷取。傳回值取決於 `trackTotalCount` 配置。
rows	`List<Row>`	本次查詢返回的行資料，通過 `getRows()` 擷取。返回數量不超過 `limit`。
searchHits	`List<SearchHit>`	查詢命中結果，通過 `getSearchHits()` 擷取。
nextToken	byte[]	下一頁憑證，通過 `getNextToken()` 擷取。值不為 `null` 時，將其設定到下一次請求的 `token` 中繼續讀取。
isAllSuccess	boolean	是否已成功查詢全部索引分割區，通過 `isAllSuccess()` 擷取。值為 `false` 時，返回的是部分結果，`totalCount` 可能小於實際匹配行數。

情境樣本

查詢長方形範圍內的資料

以下樣本查詢 location 欄位位於左上方 2,-1、右下角 -1,2 所確定的長方形範圍內的資料。

GeoBoundingBoxQuery geoBoundingBoxQuery = new GeoBoundingBoxQuery();
geoBoundingBoxQuery.setFieldName("location");
geoBoundingBoxQuery.setTopLeft("2,-1");
geoBoundingBoxQuery.setBottomRight("-1,2");

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(geoBoundingBoxQuery);

查詢多邊形範圍內的資料

以下樣本查詢 location 欄位位於 -1,-1、-1,2、2,2 和 2,-1 四個座標點所確定的多邊形範圍內的資料。

GeoPolygonQuery geoPolygonQuery = new GeoPolygonQuery();
geoPolygonQuery.setFieldName("location");
geoPolygonQuery.setPoints(
        Arrays.asList("-1,-1", "-1,2", "2,2", "2,-1"));

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(geoPolygonQuery);