统计聚合

查询请求

查询配置

指标聚合

分组

指标聚合结果

分组结果

使用子聚合和子分组

以下示例按类别分组，在每个类别中计算最高价格，并继续按状态分组。

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

使用多字段分组并翻页

GroupByComposite 以扁平组合键返回多字段分组结果，并通过 NextToken 连续读取后续分组。

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
    }
}

按范围、距离和过滤条件分组

以下示例在同一个查询中按价格范围、地理距离和过滤条件分别分组。

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)

生成数值和日期直方图

以下示例按固定价格间隔生成数值直方图，并按月生成日期直方图。

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)

按地理网格分组

以下示例按约 39 km × 19 km 的 GeoHash 网格统计地理位置字段。

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)

获取分组内的行

以下示例按类别分组，并返回每个类别中价格最高的一行。

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