表格存储 Java SDK 地理位置查询-表格存储 Tablestore(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);