聚合查询（分组、聚合、运算） POST

通过以下接口，您可以进行数据处理、转换、筛选、统计、排序、分组、联接，支持复杂逻辑运算；注意聚合查询是一个相对复杂的概念。

http://您已备案域名/v5/classes/<collection_name>/aggregate

操作符

方法	描述
$project	重命名、增加或删除字段。
$match	过滤数据，只返回符合条件的数据。
$group	分组聚合操作，对数据进行分组并应用聚合函数。
$sort	对数据进行排序。
$limit	限制结果集中返回的数据数量。
$skip	跳过指定数量的数据，返回剩余的数据。
$unwind	展开数组，将数组字段拆分为多个数据，每个数据包含数组中的一个元素。
$group	对分组的数据执行累加、求平均值等聚合操作。
$lookup	执行左连接，从其他集合中获取匹配的数据。
$addFields	增加新的字段到数据中。
$replaceRoot	用指定的数据替换结果集中的数据。
$out	将结果集写入新的集合。
$facet	允许在同一次查询中执行多个独立的聚合操作，并返回多个结果集。

聚合函数

函数	描述
$sum	计算指定字段的总和。
$avg	计算指定字段的平均值。
$min	找出指定字段的最小值。
$max	找出指定字段的最大值。
$push	将指定字段的值添加到数组中。
$addToSet	将指定字段的唯一值添加到集合中。
$first	返回指定字段的第一个文档值。
$last	返回指定字段的最后一个文档值。
$stdDevPop	计算指定字段的总体标准差。
$stdDevSamp	计算指定字段的样本标准差。
$meta	在文本搜索中返回文档的元数据，例如文本匹配的分数。
$size	返回数组字段的长度。
$slice	从数组中返回指定范围的元素。
$filter	根据条件过滤数组中的元素。
$regexMatch	使用正则表达式匹配文本字段。
$expr	允许在聚合管道中使用表达式。

ID & Date 类型

在聚合查询中同样也支持 ID 和 Date 类型数据，但需要使用系统内置的 ObjectID 和 Date 函数进行转换。

• 通过 _id 字段查询指定数据时，不能直接传递 ID 值，而是需要通过系统内置 ObjectID 函数，将 ID 字符串转换为 ObjectID 类型（⚠️ 注意：一定要是正确的 ID 才能被转换）。

• 由于 JSON 数据中只存在字符串类型，不存在 Date 类型数据。因此，您可以使用系统内置 Date 函数，将 RFC3339 格式的日期时间类型的字符串转换为 Date 类型（⚠️ 注意：一定要是 RFC3339 规范的才能被正确转换）。

请求示例

注意修改大括号中的内容。App ID、API Key、Secret Key 请前往仪表盘获取。sign 为签名，签名方式详见请求签名。

cURL

curl --location --request POST 'http://您已备案域名/v5/classes/<collection_name>/aggregate' \
--header 'X-T1Y-Application-ID: {{app_id}}' \
--header 'X-T1Y-Api-Key: {{api_key}}' \
--header 'X-T1Y-Safe-NonceStr: {{客户端随机生成的32位随机码}}' \
--header 'X-T1Y-Safe-Timestamp: {{Unix时间戳，精确到秒}}' \
--header 'X-T1Y-Safe-Sign: {{MD5(path+app_id+api_key+客户端随机生成的32位随机码+Unix时间戳+Secret_Key)}}' \
--header 'Content-Type: application/json' \
--data-raw '[{"$group" : {"_id" : "$name", "count" : {"$sum" : 1}}}]'

cURL-Windows

curl --location --request POST "http://您已备案域名/v5/classes/<collection_name>/aggregate" ^
--header "X-T1Y-Application-ID: {{app_id}}" ^
--header "X-T1Y-Api-Key: {{api_key}}" ^
--header "X-T1Y-Safe-NonceStr: {{客户端随机生成的32位随机码}}" ^
--header "X-T1Y-Safe-Timestamp: {{Unix时间戳，精确到秒}}" ^
--header "X-T1Y-Safe-Sign: {{MD5(path+app_id+api_key+客户端随机生成的32位随机码+Unix时间戳+Secret_Key)}}" ^
--header "Content-Type: application/json" ^
--data-raw "[{\"$group\" : {\"_id\" : \"$name\", \"count\" : {\"$sum\" : 1}}}]"

请求体 --data-raw 中的数组元素解析：$group 为管道分组阶段，_id 为分组条件（根据 name 字段进行分组），count 为求和返回字段名（使用$sum 函数进行求和，1 表示每条数据都会被计数一次）。以上则是表示统计 name 值一样的数据总数。

聚合函数示例

• $match 匹配

[
    {
        "$match": {
            "name": "王华",
            "age": { "$lt": 18 }
        }
    }
]

• $sum 计算总和

[
    {
        "$group": {
            "_id": "$name",
            "num_tutorial": { "$sum": "$age" }
        }
    }
]

• $avg 计算平均值

[
    {
        "$group": {
            "_id": "$name",
            "num_tutorial": { "$avg": "$age" }
        }
    }
]

• $min 获取最小值

[
    {
        "$group": {
            "_id": "$name",
            "num_tutorial": { "$min": "$age" }
        }
    }
]

• $max 获取最大值

[
    {
        "$group": {
            "_id": "$name",
            "num_tutorial": { "$max": "$age" }
        }
    }
]

• $push 将值加入一个数组中，不会判断是否有重复的值

[
    {
        "$group": {
            "_id": "$name",
            "num_tutorial": { "$push": "$array" }
        }
    }
]

• $addToSet 将值加入一个数组中，会判断是否有重复的值，若相同的值在数组中已经存在了，则不加入

[
    {
        "$group": {
            "_id": "$name",
            "num_tutorial": { "$addToSet": "$array" }
        }
    }
]

• $first 根据数据的排序获取第一条数据

[
    {
        "$group": {
            "_id": "$name",
            "num_tutorial": { "$first": "$array" }
        }
    }
]

• $last 根据数据的排序获取最后一条数据

[
    {
        "$group": {
            "_id": "$name",
            "num_tutorial": { "$last": "$array" }
        }
    }
]

响应示例

操作成功时 http 状态码以及 code 永远是 200。若需校验响应数据请参考响应签名校验（可选）。

成功示例

{
    "code": 200,
    "data": {
        "data": [
            {
                "_id": "王华华",
                "sum": 1
            },
            {
                "_id": "王华",
                "sum": 6
            }
        ]
    },
    "message": "ok"
}

异常示例

{
    "code": 400,
    "data": null,
    "message": "This is an exception message."
}

txt