查询、筛选与排序

数据墙DBW 的 REST 和 GraphQL API 都提供了丰富的筛选和排序能力。两者功能对等，语法形式不同——REST 使用 URL 查询参数，GraphQL 使用查询对象。

筛选（REST）

REST 通过 $filter 参数实现条件筛选，语法遵循 OData 规范。

比较运算符

?$filter={field} {op} {value}

运算符	含义	示例
eq	等于	title eq 'Dune'
ne	不等于	year ne 2000
gt	大于	pages gt 300
ge	大于等于	year ge 2000
lt	小于	pages lt 100
le	小于等于	year le 2020
not	非	not year lt 2000

字符串值用单引号包裹，数字直接书写：

curl "http://localhost:5000/api/Book?\$filter=year ge 2000 and pages gt 300"

逻辑组合

and  — 且
or   — 或
not  — 非

# 年份大于 2000 且 页数大于 300
?$filter=year ge 2000 and pages gt 300

# 标题等于 Dune 或 Foundation
?$filter=title eq 'Dune' or title eq 'Foundation'

# 年份不小于 2000
?$filter=not year lt 2000

括号控制优先级：

?$filter=(year ge 2000 or title eq 'Dune') and pages gt 300

字符串函数

函数	说明	示例
contains	包含子字符串	contains(title,'Foundation')
startswith	以某字符串开头	startswith(title,'The')
endswith	以某字符串结尾	endswith(title,'Wakes')

?$filter=contains(title,'Dune')
?$filter=startswith(title,'The')

null 值判断

?$filter=description eq null
?$filter=description ne null

完整示例

# 综合查询：2000 年后出版、页数大于 200、标题包含 "Dune" 的书
curl "http://localhost:5000/api/Book?\$filter=year%20ge%202000%20and%20pages%20gt%20200%20and%20contains(title,%27Dune%27)"

NOTE

URL 中空格需编码为 %20，单引号编码为 %27。大多数 HTTP 客户端会自动处理编码。

筛选（GraphQL）

GraphQL 通过 filter 参数筛选，使用对象嵌套语法而非 URL 查询字符串。

比较运算符

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

运算符	含义
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 包裹：

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

嵌套逻辑：

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

null 判断

{ books(filter: { description: { isNull: true } }) { items { id } } }
{ books(filter: { description: { isNull: false } }) { items { id } } }

排序（REST）

$orderby 参数定义排序规则，多字段用逗号分隔：

# 单字段升序（默认）
?$orderby=title

# 单字段降序
?$orderby=year desc

# 多字段：先按年份降序，再按标题升序
?$orderby=year desc,title asc

curl "http://localhost:5000/api/Book?\$orderby=year%20desc,title%20asc"

asc（升序）是默认方向，可以省略。desc 必须显式写出。

排序（GraphQL）

orderBy 参数使用键值对指定字段和方向：

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

方向为 ASC 或 DESC（大写）。省略方向默认为 ASC。

# 等同于 orderBy: { year: ASC }
{
  books(orderBy: { year: ASC }) {
    items { id title year }
  }
}

筛选 + 排序 + 分页组合

三个参数可以同时使用：

REST

curl "http://localhost:5000/api/Book?\$filter=year%20ge%202000&\$orderby=pages%20desc&\$first=10"

GraphQL

{
  books(
    filter: { year: { gte: 2000 } }
    orderBy: { pages: DESC }
    first: 10
  ) {
    items { id title year pages }
  }
}

REST vs GraphQL 对照

操作	REST	GraphQL
等于	$filter=title eq 'Dune'	filter: { title: { eq: "Dune" } }
大于	$filter=year gt 2000	filter: { year: { gt: 2000 } }
包含	$filter=contains(title,'Dune')	filter: { title: { contains: "Dune" } }
逻辑与	and	and: [...]
逻辑或	or	or: [...]
null	eq null	isNull: true
排序	$orderby=year desc	orderBy: { year: DESC }

下一步

• 分页与游标 — 处理大量数据的翻页机制。
• 字段选择 — 控制返回哪些字段。