GraphQL 聚合查询

GraphQL 聚合查询允许在服务端直接完成统计计算——计数、求和、平均值、最大值、最小值——不需要把所有数据拉到客户端再算。聚合操作由数据库执行，只返回统计结果。

IMPORTANT

聚合查询仅 SQL Server 支持，且只在 GraphQL 中可用。REST 不支持聚合。

基本语法

聚合查询使用 aggregate 字段，指定要统计的实体和聚合函数：

{
  books_aggregate {
    count
  }
}

响应：

{
  "data": {
    "books_aggregate": {
      "count": 42
    }
  }
}

支持的聚合函数

函数	说明	适用字段类型
count	记录总数	任意
sum	数值求和	数字
avg	平均值	数字
min	最小值	数字、日期
max	最大值	数字、日期

单个聚合

count — 计数

{
  books_aggregate {
    count
  }
}

统计 books 表的总记录数。

sum — 求和

{
  books_aggregate {
    sum { pages }
  }
}

计算所有书的页数总和：

{
  "data": {
    "books_aggregate": {
      "sum": { "pages": 12500 }
    }
  }
}

avg — 平均

{
  books_aggregate {
    avg { pages year }
  }
}

计算页数和年份的平均值：

{
  "data": {
    "books_aggregate": {
      "avg": { "pages": 298, "year": 1995 }
    }
  }
}

min / max — 极值

{
  books_aggregate {
    min { year pages }
    max { year pages }
  }
}

{
  "data": {
    "books_aggregate": {
      "min": { "year": 1951, "pages": 120 },
      "max": { "year": 2024, "pages": 800 }
    }
  }
}

多个聚合组合

可以在一次查询中组合多个聚合函数：

{
  books_aggregate {
    count
    avg { pages }
    sum { pages }
    min { year }
    max { year }
  }
}

响应中每个函数的结果并列返回：

{
  "data": {
    "books_aggregate": {
      "count": 42,
      "avg": { "pages": 298 },
      "sum": { "pages": 12500 },
      "min": { "year": 1951 },
      "max": { "year": 2024 }
    }
  }
}

带筛选的聚合

聚合查询支持 filter 参数，只对符合条件的记录进行统计：

{
  books_aggregate(
    filter: { year: { gte: 2000 } }
  ) {
    count
    avg { pages }
  }
}

筛选语法与普通查询的 filter 完全一致——支持比较运算符、逻辑组合、字符串函数和 null 判断。

{
  books_aggregate(
    filter: {
      and: [
        { year: { gte: 2000 } }
        { pages: { gt: 200 } }
      ]
    }
  ) {
    count
    avg { pages year }
  }
}

分组聚合

分组聚合按某个字段的值分组，对每组分别统计：

{
  books_group_by(
    groupBy: { category_id: true }
  ) {
    items {
      category_id
      count
      avg { pages }
    }
  }
}

分组查询返回 items 数组，每条包含分组字段的值和该组的统计结果。分组字段必须出现在查询中。

聚合 vs 客户端统计

方式	优点	缺点
服务端聚合	数据库计算、只传输结果、速度快	需要数据库支持
客户端统计	不依赖数据库能力	需要传输全部数据、内存消耗大

对于数据量大的场景，服务端聚合的优势非常明显——数据库在索引上直接计算，只返回几个数字，网络传输极低。

限制

• 仅 SQL Server 支持聚合查询。
• 聚合查询不支持排序和分页（结果只有一行或一个分组数组）。
• 分组聚合的 groupBy 只支持单字段。
• REST 端点不支持聚合操作。

下一步

• GraphQL 关系查询 — 嵌套关联数据。
• GraphQL 多重变更 — 批量变更操作。