文档中心

向量数据库VikingDB

数据面SDK

aggregate

概述

聚合统计用于对索引中的数据做统计计算，适合在不拉取明细数据的情况下查看数据规模、字段分布和数值汇总结果，或对指定主键对应的向量做加权求和。

当前 aggregate 方法支持以下聚合算子：

聚合类型	支持算子	说明
标量计数聚合	`count`	统计命中数据量。设置 `groupBy` 时按字段分桶；不设置时统计全局数量。
标量计算聚合	`sum`、`avg`、`min`、`max`	对 `calcValueOn` 指定的数值字段计算求和、平均值、最小值或最大值，也可按 `groupBy` 分桶。
向量计算聚合	`vector_weighted_sum`	对 `ids` 对应的向量按 `weights` 加权求和。

标量聚合可通过 filter 缩小统计范围。groupBy 对应 SQL 的 GROUP BY，filter 对应 SQL 的 WHERE。

接口升级说明

对应的 V1 接口为：https://www.volcengine.com/docs/84313/1399339

功能	V2 SDK	V1 SDK
子索引	性能和易用性更强的分片能力研发中，敬请期待。	通过 `partition` 参数指定。

方法定义

public DataApiResponse<AggregateResult> aggregate(AggregateRequest request)
        throws ApiClientException, VectorApiException

请求参数

AggregateRequest 包含以下字段：

参数名	类型	必选	说明
`resourceId`	`String`	与 `collectionName` 二选一	Collection 的资源 ID。
`collectionName`	`String`	与 `resourceId` 二选一	Collection 名称。
`projectName`	`String`	否	项目名称。通过 Collection 名称定位时可用于限定项目。
`indexName`	`String`	是	Index 名称。
`op`	`String`	是	聚合算子。支持 `count`、`sum`、`avg`、`min`、`max`、`vector_weighted_sum`。
`filter`	`Map<String, Object>`	否	过滤条件。仅标量聚合支持；语法与检索接口一致，不设置时聚合当前索引内的全部数据。
`groupBy`	`String`	否	分桶字段。仅标量聚合支持；不设置时执行全局聚合。
`calcValueOn`	`String`	条件必选	标量计算字段。`op` 为 `sum`、`avg`、`min` 或 `max` 时必填。
`order`	`String`	否	分桶结果排序方向，支持 `desc` 和 `asc`，默认 `desc`。仅分桶标量聚合生效。
`ids`	`List<Object>`	条件必选	参与向量加权求和的主键列表。`op` 为 `vector_weighted_sum` 时必填，最多 2000 个。元素类型需与 Collection 主键类型一致。
`weights`	`List<Double>`	条件必选	与 `ids` 一一对应的权重列表。`op` 为 `vector_weighted_sum` 时必填，长度必须与 `ids` 相同。

field 是 groupBy 的已废弃兼容字段，新代码应使用 groupBy。cond 是旧版分桶计数的兼容字段，新代码不建议使用。

过滤条件的结构和支持的算子参见检索公共参数。

算子参数

`op`	必填参数	可选参数	说明
`count`	无	`groupBy`、`filter`、`order`	统计全局数据量或按字段分桶计数。
`sum`	`calcValueOn`	`groupBy`、`filter`、`order`	对指定数值字段求和。
`avg`	`calcValueOn`	`groupBy`、`filter`、`order`	对指定数值字段求平均值。
`min`	`calcValueOn`	`groupBy`、`filter`、`order`	返回指定数值字段的最小值。
`max`	`calcValueOn`	`groupBy`、`filter`、`order`	返回指定数值字段的最大值。
`vector_weighted_sum`	`ids`、`weights`	无	对指定主键对应的向量做加权求和。

字段和索引要求：

参数	支持的字段类型	索引要求
`groupBy`	`string`、`int64`、`bool`	字段需要已建立枚举索引。
`calcValueOn`	`int64`、`float32`	字段需要已建立范围索引。

使用 count 时，索引中需要至少存在一个可用于聚合的标量索引字段。使用 vector_weighted_sum 时，Collection 需要包含向量字段，或在创建 Collection 时配置 Vectorize。

返回参数

方法返回 DataApiResponse<AggregateResult>。公共响应字段如下：

字段	类型	说明
`requestId`	`String`	请求链路 ID，可用于问题排查。
`code`	`String`	响应状态码。
`message`	`String`	响应信息。
`result`	`AggregateResult`	聚合结果。

AggregateResult 结构：

属性	类型	说明
`op`	`String`	本次执行的聚合算子。
`groupBy`	`String`	分桶字段。全局标量聚合时为 `__NONE__`。
`calcValueOn`	`String`	标量计算字段，仅 `sum`、`avg`、`min`、`max` 返回。
`agg`	`Map<String, Object>`	标量聚合结果。全局聚合使用 `__TOTAL__` 作为结果键。
`vectorWeightedSum`	`VectorWeightedSumResult`	向量加权求和结果，仅 `vector_weighted_sum` 返回。

agg 中的 value 类型取决于算子和计算字段：

算子	结果类型
`count`	整数。
`sum`、`min`、`max`	`calcValueOn` 为 `int64` 时返回整数，为 `float32` 时返回浮点数。
`avg`	浮点数。

VectorWeightedSumResult 结构：

属性	类型	说明
`vector`	`List<Double>`	加权求和后的向量。
`foundIds`	`List<Object>`	实际命中并参与计算的主键列表，顺序与请求中的 `ids` 一致。
`foundCount`	`Long`	实际命中并参与计算的主键数量。
`weightSum`	`Double`	实际参与计算的权重和，未命中主键对应的权重不计入。

示例

以下示例分别执行分桶计数、分桶求和和向量加权求和。运行前请配置 AK、SK 环境变量，并将 Collection 和 Index 名称替换为实际值。

package org.example.vikingdb.data;

import com.volcengine.vikingdb.runtime.core.ClientConfig;
import com.volcengine.vikingdb.runtime.core.auth.AuthWithAkSk;
import com.volcengine.vikingdb.runtime.enums.Scheme;
import com.volcengine.vikingdb.runtime.vector.model.request.AggregateRequest;
import com.volcengine.vikingdb.runtime.vector.model.response.AggregateResult;
import com.volcengine.vikingdb.runtime.vector.model.response.DataApiResponse;
import com.volcengine.vikingdb.runtime.vector.service.VectorService;

import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;

public class AggregateExample {

    private static void printResult(
            String name,
            DataApiResponse<AggregateResult> response) {
        System.out.println(name + " requestId=" + response.getRequestId());
        System.out.println(response.getResult());
    }

    public static void main(String[] args) throws Exception {
        VectorService vectorService = new VectorService(
                Scheme.HTTPS,
                "api-vikingdb.vikingdb.cn-beijing.volces.com",
                "cn-beijing",
                new AuthWithAkSk(
                        System.getenv("AK"),
                        System.getenv("SK")),
                ClientConfig.builder().build()
        );

        Map<String, Object> filter = new HashMap<>();
        filter.put("op", "range");
        filter.put("field", "price");
        filter.put("gte", 10.0);

        AggregateRequest countRequest = AggregateRequest.builder()
                .collectionName("<YOUR_COLLECTION_NAME>")
                .indexName("<YOUR_INDEX_NAME>")
                .op("count")
                .filter(filter)
                .groupBy("category")
                .order("desc")
                .build();
        printResult("count", vectorService.aggregate(countRequest));

        AggregateRequest sumRequest = AggregateRequest.builder()
                .collectionName("<YOUR_COLLECTION_NAME>")
                .indexName("<YOUR_INDEX_NAME>")
                .op("sum")
                .calcValueOn("price")
                .groupBy("category")
                .order("desc")
                .build();
        printResult("sum", vectorService.aggregate(sumRequest));

        AggregateRequest vectorRequest = AggregateRequest.builder()
                .collectionName("<YOUR_COLLECTION_NAME>")
                .indexName("<YOUR_INDEX_NAME>")
                .op("vector_weighted_sum")
                .ids(Arrays.asList(101L, 102L, 103L))
                .weights(Arrays.asList(0.2, 0.3, 0.5))
                .build();
        printResult(
                "vector_weighted_sum",
                vectorService.aggregate(vectorRequest));
    }
}

空结果说明

场景	返回结果
全局 `count` 没有命中数据	`agg.get("__TOTAL__")` 为 `0`。
分桶 `count` 没有命中数据	`agg` 为空 Map。
全局 `sum`、`avg`、`min`、`max` 没有有效数值	`agg.get("__TOTAL__")` 为 `null`。
分桶 `sum`、`avg`、`min`、`max` 没有有效数值	`agg` 为空 Map。
`vector_weighted_sum` 的 `ids` 均未命中	`vector` 和 `foundIds` 为空，`foundCount` 和 `weightSum` 为 `0`。

sum、avg、min、max 不使用 0 表示空结果，因为 0 本身是合法的计算结果。

使用限制

分桶聚合最多返回 10000 个桶。分桶数量较多时，建议使用 filter 缩小统计范围，或选择低基数字段。
vector_weighted_sum 的 ids 不能包含重复主键；weights 只能包含有限数值。
vector_weighted_sum 不支持 filter、groupBy、calcValueOn 和 order。
未命中的主键不参与向量计算，其对应权重也不会计入 weightSum。
如需加权平均向量，可在业务侧计算 vector.get(i) / weightSum。当 foundCount 或 weightSum 为 0 时，不应直接做除法。

最近更新时间：2026.09.08 12:02:55

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

算子参数 #

算子参数