GraphQL 聚合参考

数据墙DBW 的 GraphQL 端点支持聚合查询，可在服务端直接完成统计计算。聚合操作由数据库执行，只返回统计结果，不需要传输原始数据。

IMPORTANT

聚合查询仅 SQL Server 支持。PostgreSQL 和 MySQL 不支持。

数据库支持

数据库	聚合支持
SQL Server	✓
PostgreSQL	✗
MySQL	✗

聚合函数

函数	适用字段	说明
count	任意字段	非空值的计数
sum	数字字段	所有值的总和
avg	数字字段	所有值的算术平均值
min	数字字段	最小值
max	数字字段	最大值

NOTE

如果实体没有任何数字列，引擎不会为该实体生成聚合节点。count 仍然可用但无法在聚合节点中使用（需通过分组查询的 count 实现）。

基本聚合

count — 计数

{
  books_aggregate {
    count
  }
}

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

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

带筛选的聚合

聚合查询支持 filter 参数，只统计满足条件的记录：

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

筛选语法与普通查询的 filter 完全一致，支持所有比较运算符和逻辑组合：

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

distinct 修饰符

distinct: true 仅统计唯一值：

{
  books_aggregate {
    count(distinct: true)
  }
}

适用于 count 函数。计算去重后的非空值数量。

groupBy 分组查询

按指定字段分组，分别统计各组：

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

分组查询返回 items 数组，每条包含：

字段	说明
{分组字段}	分组字段的值
聚合函数	该组的统计结果

NOTE

当前分组聚合的 groupBy 仅支持单字段。分组字段必须在查询中显式列出。

having 过滤

having 在分组聚合之后过滤结果（类似 SQL HAVING）：

{
  books_group_by(
    groupBy: { category_id: true }
    having: { pages: { sum: { gt: 1000 } } }
  ) {
    items {
      category_id
      count
      sum { pages }
    }
  }
}

having 作用于聚合结果——只保留满足条件的分组。支持对聚合函数值的比较（gt、gte、lt、lte、eq、neq）。

MCP aggregate-records 超时

MCP 中的 aggregate_records 工具有独立的查询超时配置：

{
  "runtime": {
    "mcp": {
      "dml-tools": {
        "aggregate-records": {
          "enabled": true,
          "query-timeout": 60
        }
      }
    }
  }
}

字段	说明	默认值	范围
query-timeout	聚合查询超时秒数	30	1–600

聚合查询在大数据量下可能比普通查询更耗时，适当调高此值可避免超时。MCP 聚合超时与数据库连接字符串超时取更短者。

聚合不支持的能力

不支持	说明
排序	聚合查询结果不支持 orderBy
分页	聚合结果不支持 first/after（只有一行或一个分组数组）
多字段 groupBy	当前仅支持单字段分组
PostgreSQL/MySQL	聚合功能不适用于这两个数据库

下一步

• GraphQL 查询 — 查询语法和参数完全参考。
• GraphQL 变更 — 创建、更新和删除操作。
• GraphQL 端点 — 端点配置。