GraphQL 查询参考

数据墙DBW 为每个实体自动生成查询入口。本文档完整描述 GraphQL 查询的所有参数和语法。

查询类型

每个实体自动生成两种查询：

查询类型	语法	返回
列表查询	{entity-plural}	匹配条件的记录列表，带分页
按主键查询	{entity-singular}_by_pk	单条记录或 null

列表查询

{
  books {
    items {
      id
      title
      year
      pages
    }
  }
}

所有字段必须显式声明——GraphQL 没有 SELECT * 通配符。

按主键查询

{
  book_by_pk(id: 1) {
    id
    title
    year
  }
}

主键不存在的记录返回 null 和 errors（而非空列表）。

filter 参数

filter 用于条件筛选，支持字段级运算符和逻辑组合：

比较运算符

{
  books(filter: { year: { gte: 2000 }, pages: { gt: 300 } }) {
    items { id title }
  }
}

运算符	含义
eq	等于
neq	不等于
gt	大于
gte	大于等于
lt	小于
lte	小于等于
contains	字符串包含
startswith	字符串开头
endswith	字符串结尾
isNull	是否为 null（值为 true 或 false）

逻辑组合

{
  books(filter: {
    and: [
      { year: { gte: 2000 } }
      { pages: { gt: 300 } }
    ]
  }) {
    items { id title }
  }
}

逻辑运算符	说明
and	所有条件同时满足
or	至少一个条件满足

and 和 or 可以嵌套实现复杂逻辑：

{
  books(filter: {
    and: [
      { year: { gte: 2000 } }
      {
        or: [
          { title: { contains: "Dune" } }
          { title: { contains: "Foundation" } }
        ]
      }
    ]
  }) { items { id title year } }
}

orderBy 参数

{
  books(orderBy: { year: DESC, title: ASC }) {
    items { id title year }
  }
}

方向	说明
ASC	升序（默认，可省略）
DESC	降序

多字段排序按参数书写顺序依次应用。

分页参数

first

{
  books(first: 5) {
    items { id title }
    hasNextPage
    endCursor
  }
}

参数	说明
first	每页返回的记录数。-1 返回配置的 max-page-size

after

{
  books(first: 5, after: "eyJpZCI6NX0=") {
    items { id title }
    hasNextPage
    endCursor
  }
}

参数	说明
after	上一页返回的 endCursor 值，用于翻页

字段别名

在查询中可以为字段指定别名：

{
  books {
    items {
      bookId: id
      bookTitle: title
    }
  }
}

响应中字段使用别名：

{ "bookId": 1, "bookTitle": "示例书名" }

关系查询

实体间配置的关系自动在 GraphQL 架构中体现为嵌套字段：

多对一（单对象）

{
  books {
    items {
      title
      category {
        name
      }
    }
  }
}

一对一和多对一关系返回单个对象。

一对多（列表）

{
  categories {
    items {
      name
      books {
        items { title }
      }
    }
  }
}

一对多和多对多关系返回 items 数组，同样支持分页。

嵌套别名

{
  books {
    items {
      title
      bookCategory: category { catName: name }
    }
  }
}

字段选择

GraphQL 原生支持精确字段选择——查询中声明哪些字段，响应就只返回哪些字段。这与 REST API 中 $select 参数的功能对等，但更灵活（支持嵌套和别名）。

分页响应字段

字段	类型	说明
items	[T]	当前页的记录数组
hasNextPage	Boolean	是否还有下一页
endCursor	String	分页游标，传 after 参数获取下一页

GraphQL 特有的能力

能力	GraphQL	REST
按需字段选择	原生支持	$select 参数
嵌套关联查询	支持（关系）	不支持
字段别名	支持	不支持
聚合查询	支持	不支持
多重变更	支持	不支持
缓存	不支持	支持（L1/L2）

下一步

• GraphQL 端点 — 端点配置和架构生成。
• GraphQL 变更 — 创建、更新和删除操作。
• GraphQL 聚合 — 聚合函数和分组查询。