Geo query

A geo query with the Tablestore SDK for Java filters data by distance from a center point, a bounding box, or a polygon.

Prerequisites

Install the Tablestore SDK for Java and initialize a client.

Feature description

A geo query filters data based on the geographic locations in an GEO_POINT indexed field. The following query types are supported:

Geo-distance query (GeoDistanceQuery): queries locations whose distance from a specified center point is less than or equal to a specified value.
Geo-bounding box query (GeoBoundingBoxQuery): queries locations within a bounding box. The bounding box is defined by its top-left and bottom-right coordinates.
Geo-polygon query (GeoPolygonQuery): queries locations within a polygon. The polygon is defined by multiple coordinate points.

When you call search, set the query type to GeoDistanceQuery, GeoBoundingBoxQuery, or GeoPolygonQuery based on the geographic area to query.

SearchResponse search(SearchRequest request)

The following example queries rows in which the location field is within 120,000 meters of the 0,0 center point. The query returns up to 10 rows and the total number of matches.

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());

Parameters

Search request

request is a SearchRequest object that contains the following parameters.

Name	Type	Description
tableName (required)	String	The name of the data table.
indexName (required)	String	The name of the search index.
searchQuery (required)	SearchQuery	The query condition and general query settings.
columnsToGet (optional)	SearchRequest.ColumnsToGet	The columns to return. If this parameter is not configured, only primary key columns are returned.
timeoutInMillisecond (optional)	int	The request-level query timeout in milliseconds. The default value is `-1`, which does not configure a separate query timeout.
routingValues (optional)	`List<PrimaryKey>`	The primary key values that correspond to custom routing fields. Leave this parameter unset if custom routing is not configured.

Query settings

request.searchQuery is a SearchQuery object that contains the following parameters.

Name	Type	Description
query (required)	Query	The query condition. Set this parameter to a `GeoDistanceQuery`, `GeoBoundingBoxQuery`, or `GeoPolygonQuery` object based on the query type.
offset (optional)	Integer	The starting position of the query.
limit (optional)	Integer	The maximum number of rows to return. Set this parameter to `0` to return no rows.
collapse (optional)	Collapse	The field collapse settings, which deduplicate results by a specified field. For configuration details, see Collapse query results.
sort (optional)	Sort	The result sort order. For configuration details, see Sort and paginate results.
trackTotalCount (optional)	int	The expected maximum number of matching rows to count. The default value is `TRACK_TOTAL_COUNT_DISABLED`, which disables counting. Set this parameter to `TRACK_TOTAL_COUNT` to count all matching rows. A smaller value improves query performance.
filter (optional)	SearchFilter	A filter that is applied to the results of `query`.
aggregationList (optional)	`List<Aggregation>`	The aggregation settings. For configuration details, see Aggregation.
groupByList (optional)	`List<GroupBy>`	The grouping settings. For configuration details, see Aggregation.
token (optional)	byte[]	The pagination token. Set this parameter to the `nextToken` value from the previous response to continue reading rows. When you set `token`, the SDK clears `sort` because the token already contains the sort conditions.

For all three geo query types, specify coordinates in the latitude,longitude format. Place the latitude before the longitude. The latitude range is [-90,+90] and the longitude range is [-180,+180]. Example: 35.8,-45.91.

Geo-distance condition

For a geo-distance query, request.searchQuery.query is a GeoDistanceQuery object that contains the following parameters.

Name	Type	Description
fieldName (required)	String	The name of the `GEO_POINT` indexed field to query.
centerPoint (required)	String	The coordinates of the center point.
distanceInMeter (required)	double	The maximum distance from the center point, in meters.

Bounding box condition

For a geo-bounding box query, request.searchQuery.query is a GeoBoundingBoxQuery object that contains the following parameters.

Name	Type	Description
fieldName (required)	String	The name of the `GEO_POINT` indexed field to query.
topLeft (required)	String	The coordinates of the top-left corner of the bounding box.
bottomRight (required)	String	The coordinates of the bottom-right corner of the bounding box.

Polygon condition

For a geo-polygon query, request.searchQuery.query is a GeoPolygonQuery object that contains the following parameters.

Name	Type	Description
fieldName (required)	String	The name of the `GEO_POINT` indexed field to query.
points (required)	`List<String>`	The coordinate points that define the polygon.

Returned columns

request.columnsToGet is a SearchRequest.ColumnsToGet object that contains the following parameters.

Name	Type	Description
columns (optional)	`List<String>`	The attribute columns to return. Set this parameter only if `returnAll` and `returnAllFromIndex` are both `false`. If you omit this parameter, only primary key columns are returned.
returnAll (optional)	boolean	Specifies whether to return all attribute columns from the data table. The default value is `false`.
returnAllFromIndex (optional)	boolean	Specifies whether to return all indexed attribute columns. The default value is `false`. Do not set both `returnAll` and `returnAllFromIndex` to `true`.

Return values

search returns a SearchResponse object. The following table describes the core fields.

Name	Type	Description
totalCount	long	The number of matching rows. Call `getTotalCount()` to obtain the value. The returned value depends on the `trackTotalCount` setting.
rows	`List<Row>`	The rows returned by this query. Call `getRows()` to obtain the value. The number of rows does not exceed `limit`.
searchHits	`List<SearchHit>`	The query hits. Call `getSearchHits()` to obtain the value.
nextToken	byte[]	The next-page token. Call `getNextToken()` to obtain the value. If the value is not `null`, set it as `token` in the next request to continue reading rows.
isAllSuccess	boolean	Indicates whether all index partitions were queried successfully. Call `isAllSuccess()` to obtain the value. If the value is `false`, the response contains partial results and `totalCount` may be less than the actual number of matching rows.

Scenario examples

Query data within a bounding box

The following example queries rows in which the location field falls within the bounding box whose top-left coordinates are 2,-1 and bottom-right coordinates are -1,2.

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

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

Query data within a polygon

The following example queries rows in which the location field falls within the polygon defined by the -1,-1, -1,2, 2,2, and 2,-1 coordinate points.

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