Geo queries - Tablestore SDK for Go - Tablestore - Alibaba Cloud Documentation Center

Use the Tablestore SDK for Go to query a Geo-point field by circular, rectangular, or polygonal geographic ranges.

Prerequisites

Install the Tablestore Go SDK and initialize a client.

Description

A geo query matches Geo-point values within a specified geographic area. Geo distance, geo bounding box, and geo polygon queries are supported. All three query types use the latitude,longitude format. Latitude ranges from -90 to +90, and longitude ranges from -180 to +180. Example: 35.8,-45.91.

func (client *tablestore.TableStoreClient) Search(request *tablestore.SearchRequest) (*tablestore.SearchResponse, error)

Geo distance query

A geo distance query uses a coordinate as the center and matches points whose distance from the center does not exceed a specified value.

tableName := "example_table"
indexName := "example_index"

query := &search.GeoDistanceQuery{FieldName: "location", CenterPoint: "30.25,120.16", DistanceInMeter: 50000}
searchQuery := search.NewSearchQuery().
    SetQuery(query).
    SetLimit(10).
    SetGetTotalCount(true)

response, err := client.Search(&tablestore.SearchRequest{
    TableName:   tableName,
    IndexName:   indexName,
    SearchQuery: searchQuery,
    ColumnsToGet: &tablestore.ColumnsToGet{
        ReturnAllFromIndex: true,
    },
})
if err != nil {
    log.Fatal(err)
}

fmt.Println(response.TotalCount)
fmt.Println(response.Rows)

Geo bounding box query

A geo bounding box query defines a rectangle by its top-left and bottom-right coordinates.

tableName := "example_table"
indexName := "example_index"

query := &search.GeoBoundingBoxQuery{FieldName: "location", TopLeft: "32,119", BottomRight: "29,122"}
searchQuery := search.NewSearchQuery().
    SetQuery(query).
    SetLimit(10).
    SetGetTotalCount(true)

response, err := client.Search(&tablestore.SearchRequest{
    TableName:   tableName,
    IndexName:   indexName,
    SearchQuery: searchQuery,
    ColumnsToGet: &tablestore.ColumnsToGet{
        ReturnAllFromIndex: true,
    },
})
if err != nil {
    log.Fatal(err)
}

fmt.Println(response.TotalCount)
fmt.Println(response.Rows)

Geo polygon query

A geo polygon query connects multiple coordinates in order to form a polygon.

tableName := "example_table"
indexName := "example_index"

query := &search.GeoPolygonQuery{FieldName: "location", Points: []string{"29,119", "32,119", "32,122", "29,122"}}
searchQuery := search.NewSearchQuery().
    SetQuery(query).
    SetLimit(10).
    SetGetTotalCount(true)

response, err := client.Search(&tablestore.SearchRequest{
    TableName:   tableName,
    IndexName:   indexName,
    SearchQuery: searchQuery,
    ColumnsToGet: &tablestore.ColumnsToGet{
        ReturnAllFromIndex: true,
    },
})
if err != nil {
    log.Fatal(err)
}

fmt.Println(response.TotalCount)
fmt.Println(response.Rows)

Parameters

Query request

Name	Type	Description
TableName (required)	string	The name of the data table.
IndexName (required)	string	The name of the search index.
SearchQuery (required)	search.SearchQuery	The query condition and common query configurations.
ColumnsToGet (optional)	*tablestore.ColumnsToGet	The return-column configuration. If this parameter is omitted, only primary key columns are returned.
RoutingValues (optional)	[]*tablestore.PrimaryKey	Primary key values for custom routing fields. Omit this parameter if custom routing is not configured.
TimeoutMs (optional)	*int32	The request timeout period in milliseconds.

Query configuration

Name	Type	Description
SetQuery (required)	search.Query	Specifies the query condition.
SetOffset (optional)	int32	Specifies the start position. Default value: 0. For offset-based pagination, Offset + Limit cannot exceed 100,000.
SetLimit (optional)	int32	Specifies the maximum number of rows to return. Default value: 10. Maximum value: 100. A value of 0 returns no rows.
SetCollapse (optional)	*search.Collapse	Collapses query results. For more information, see Collapse query results.
SetSort (optional)	*search.Sort	Specifies the result sort order. For more information, see Sort and paginate results.
SetGetTotalCount (optional)	bool	Specifies whether to count all matched rows. Default value: false.
SetToken (optional)	[]byte	Specifies the NextToken value returned by the previous response. This method clears Sort because the token contains the previous-page sort conditions. Do not specify Offset when you use token-based pagination.
SetSearchFilter (optional)	*search.SearchFilter	Applies a post-query filter. For more information, see Use post-query filters.
Aggregation (optional)	...search.Aggregation	Configures aggregations. For more information, see Aggregation.
GroupBy (optional)	...search.GroupBy	Configures grouping. For more information, see Aggregation.

Geo distance query condition

Name	Type	Description
FieldName (required)	string	The name of the Geo-point field.
CenterPoint (required)	string	The center coordinate in the `latitude,longitude` format.
DistanceInMeter (required)	float64	The query radius in meters.

Geo bounding box query condition

Name	Type	Description
FieldName (required)	string	The name of the Geo-point field.
TopLeft (required)	string	The top-left coordinate.
BottomRight (required)	string	The bottom-right coordinate.

Geo polygon query condition

Name	Type	Description
FieldName (required)	string	The name of the Geo-point field.
Points (required)	[]string	The coordinates that form the polygon in order.

Columns to return

Name	Type	Description
Columns (optional)	[]string	The attribute columns to return. This parameter takes effect only when ReturnAll and ReturnAllFromIndex are both false.
ReturnAll (optional)	bool	Specifies whether to return all attribute columns in the data table. Default value: false.
ReturnAllFromIndex (optional)	bool	Specifies whether to return all indexed attribute columns. Default value: false. Do not set this parameter and ReturnAll to true at the same time.

Response

Name	Type	Description
TotalCount	int64	The total number of matched rows. The value depends on SetGetTotalCount.
Rows	[]*tablestore.Row	The rows returned by the current query. The number does not exceed the value specified by SetLimit.
SearchHits	[]*tablestore.SearchHit	The search hits. Read this field when you use highlighting, nested inner hits, or relevance scores.
NextToken	[]byte	The token for the next page. If the value is not empty, pass it to the next query.
IsAllSuccess	bool	Indicates whether all index partitions were queried. If the value is false, partial results are returned and TotalCount may be less than the actual number of matched rows.
AggregationResults	search.AggregationResults	The aggregation results.
GroupByResults	search.GroupByResults	The grouping results.