Tablestore:Aggregation

Query request

Query configuration

Metric aggregations

Grouping

Metric aggregation results

Grouping results

Use subaggregations and subgroups

The following example groups rows by category, calculates the maximum price in each category, and further groups the rows by status.

groupBy := search.NewGroupByField("category_group", "category").
    Size(10).
    SubAggregation(search.NewMaxAggregation("max_price", "price")).
    SubGroupBy(search.NewGroupByField("status_group", "status").Size(10))

searchQuery := search.NewSearchQuery().
    SetQuery(&search.MatchAllQuery{}).
    SetLimit(0).
    GroupBy(groupBy)
response, err := client.Search(&tablestore.SearchRequest{
    TableName:   "example_table",
    IndexName:   "example_index",
    SearchQuery: searchQuery,
})
if err != nil {
    log.Fatal(err)
}

result, err := response.GroupByResults.GroupByField("category_group")
if err != nil {
    log.Fatal(err)
}
for _, item := range result.Items {
    maxPrice, err := item.SubAggregations.Max("max_price")
    if err != nil {
        log.Fatal(err)
    }
    statuses, err := item.SubGroupBys.GroupByField("status_group")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(item.Key, maxPrice.Value, statuses.Items)
}

Group by multiple fields and paginate results

GroupByComposite returns multi-field grouping results as flat composite keys and uses NextToken to read subsequent groups.

composite := search.NewGroupByComposite("category_status_group").
    SourceGroupBys(
        search.NewGroupByField("category", "category"),
        search.NewGroupByField("status", "status"),
    ).
    SetSize(100)

var nextToken *string
for {
    if nextToken != nil {
        composite.SetNextToken(nextToken)
    }
    searchQuery := search.NewSearchQuery().
        SetQuery(&search.MatchAllQuery{}).
        SetLimit(0).
        GroupBy(composite)
    response, err := client.Search(&tablestore.SearchRequest{
        TableName:   "example_table",
        IndexName:   "example_index",
        SearchQuery: searchQuery,
    })
    if err != nil {
        log.Fatal(err)
    }

    result, err := response.GroupByResults.GroupByComposite(
        "category_status_group",
    )
    if err != nil {
        log.Fatal(err)
    }
    for _, item := range result.Items {
        fmt.Println(item.Keys, item.RowCount)
    }

    nextToken = result.NextToken
    if nextToken == nil || *nextToken == "" {
        break
    }
}

Group by range, distance, and filter

The following example groups results by price range, geographic distance, and filter in the same query.

priceRanges := search.NewGroupByRange("price_ranges", "price").
    Range(0, 200).
    Range(200, 500)
distanceRanges := search.NewGroupByGeoDistance(
    "distance_ranges",
    "location",
    search.GeoPoint{Lat: 30.2741, Lon: 120.1551},
).
    Range(0, 100000).
    Range(100000, 1500000)
categoryFilters := search.NewGroupByFilter("category_filters").
    Query(&search.TermQuery{FieldName: "category", Term: "book-go"}).
    Query(&search.TermQuery{FieldName: "category", Term: "game"})

searchQuery := search.NewSearchQuery().
    SetQuery(&search.MatchAllQuery{}).
    SetLimit(0).
    GroupBy(priceRanges, distanceRanges, categoryFilters)
response, err := client.Search(&tablestore.SearchRequest{
    TableName:   "example_table",
    IndexName:   "example_index",
    SearchQuery: searchQuery,
})
if err != nil {
    log.Fatal(err)
}

priceResult, err := response.GroupByResults.GroupByRange("price_ranges")
if err != nil {
    log.Fatal(err)
}
distanceResult, err := response.GroupByResults.GroupByGeoDistance(
    "distance_ranges",
)
if err != nil {
    log.Fatal(err)
}
filterResult, err := response.GroupByResults.GroupByFilter("category_filters")
if err != nil {
    log.Fatal(err)
}
fmt.Println(priceResult.Items)
fmt.Println(distanceResult.Items)
fmt.Println(filterResult.Items)

Generate numeric and date histograms

The following example generates a numeric histogram by using fixed price intervals and a monthly date histogram.

groupKeyAscending := []search.GroupBySorter{
    &search.GroupKeyGroupBySort{Order: search.SortOrder_ASC.Enum()},
}
priceHistogram := search.NewGroupByHistogram("price_histogram", "price").
    SetInterval(int64(200)).
    SetFiledRange(int64(0), int64(600)).
    SetMinDocCount(1).
    SetGroupBySorters(groupKeyAscending)
dateHistogram := search.NewGroupByDateHistogram(
    "date_histogram",
    "event_time",
).
    SetInterval(model.DateTimeValue{
        Value: proto.Int32(1),
        Unit:  model.DateTimeUnit_MONTH.Enum(),
    }).
    SetFiledRange("2026-01-01T00:00:00", "2026-05-01T00:00:00").
    SetTimeZone("+08:00").
    SetMinDocCount(1).
    SetGroupBySorters(groupKeyAscending)

searchQuery := search.NewSearchQuery().
    SetQuery(&search.MatchAllQuery{}).
    SetLimit(0).
    GroupBy(priceHistogram, dateHistogram)
response, err := client.Search(&tablestore.SearchRequest{
    TableName:   "example_table",
    IndexName:   "example_index",
    SearchQuery: searchQuery,
})
if err != nil {
    log.Fatal(err)
}

priceResult, err := response.GroupByResults.GroupByHistogram("price_histogram")
if err != nil {
    log.Fatal(err)
}
dateResult, err := response.GroupByResults.GroupByDateHistogram("date_histogram")
if err != nil {
    log.Fatal(err)
}
fmt.Println(priceResult.Items)
fmt.Println(dateResult.Items)

Group by geographic grid

The following example groups a geographic field by GeoHash grids of approximately 39 km × 19 km.

searchQuery := search.NewSearchQuery().
    SetQuery(&search.MatchAllQuery{}).
    SetLimit(0).
    GroupBy(
        search.NewGroupByGeoGrid("geo_grid", "location").
            SetPrecision(model.GHP_39KM_19KM_4).
            SetSize(100),
    )
response, err := client.Search(&tablestore.SearchRequest{
    TableName:   "example_table",
    IndexName:   "example_index",
    SearchQuery: searchQuery,
})
if err != nil {
    log.Fatal(err)
}

result, err := response.GroupByResults.GroupByGeoGrid("geo_grid")
if err != nil {
    log.Fatal(err)
}
fmt.Println(result.Items)

Retrieve rows within groups

The following example groups rows by category and returns the row with the highest price in each category.

topRows := search.NewTopRowsAggregation("top_price").
    SetLimit(1).
    SetSort(&search.Sort{Sorters: []search.Sorter{
        &search.FieldSort{
            FieldName: "price",
            Order:     search.SortOrder_DESC.Enum(),
        },
    }})
groupBy := search.NewGroupByField("category_group", "category").
    Size(10).
    SubAggregation(topRows)
searchQuery := search.NewSearchQuery().
    SetQuery(&search.MatchAllQuery{}).
    SetLimit(0).
    GroupBy(groupBy)

response, err := client.Search(&tablestore.SearchRequest{
    TableName:   "example_table",
    IndexName:   "example_index",
    SearchQuery: searchQuery,
    ColumnsToGet: &tablestore.ColumnsToGet{
        Columns: []string{"category", "price"},
    },
})
if err != nil {
    log.Fatal(err)
}

groups, err := response.GroupByResults.GroupByField("category_group")
if err != nil {
    log.Fatal(err)
}
for _, item := range groups.Items {
    rows, err := item.SubAggregations.TopRows("top_price")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(item.Key, rows.Value)
}