筛选 GraphQL 中的数据（`filter`）

2025-10-15

筛选将大型数据集缩小为仅所需的记录。在 GraphQL 中，数据 API 生成器（DAB）支持实体查询的结构化 filter 参数。每个筛选器编译为参数化 SQL，以确保安全性和一致性。

注释

GraphQL 筛选支持比较、逻辑、字符串模式、成员资格和 null 运算符。 GraphQL 筛选器使用结构化输入对象： { fieldName: { operator: value } }. 日期必须是有效的 ISO 8601 UTC 字符串。 Null 检查使用 isNull 而不是 eq null。

快速浏览

Operator	Meaning
`eq`	平等
`neq`	不等于
`gt`	大于
`gte`	大于或等于
`lt`	小于
`lte`	小于或等于
`and`	逻辑 AND
`or`	逻辑 OR
`contains`	子字符串匹配
`notContains`	非子字符串匹配
`startsWith`	前缀匹配
`endsWith`	后缀匹配
`in`	成员资格
`isNull`	null 检查

`eq`

等于。返回字段的值与提供的文字完全匹配的记录;如果使用，则返回 isNullnull。

注释

筛选日期或日期/时间字段时，请使用 无引号 的 ISO 8601 UTC 格式（yyyy-MM-ddTHH:mm:ssZ）。带引号或 OData 样式的格式无效。

错误： $filter=Date ge '2025-01-01'
错误： $filter=Date ge datetime'2025-01-01'
正确：$filter=Date ge 2025-01-01T00:00:00Z

在此示例中，我们获取标题所在 'Dune'书籍，可用标志为 true，价格为 20，发布日期为 2024 年 1 月 1 日，评级为 null。

query {
  books(filter: {
    and: [
      { title: { eq: "Dune" } }
      { available: { eq: true } }
      { price: { eq: 20 } }
      { publishedOn: { eq: "2024-01-01T00:00:00Z" } }
      { rating: { isNull: true } }
    ]
  }) {
    items { id title available price publishedOn rating }
  }
}

概念 SQL

SELECT id, title, available, price, publishedOn, rating
FROM Books
WHERE title = 'Dune'
  AND available = 1
  AND price = 20
  AND publishedOn = '2024-01-01T00:00:00Z'
  AND rating IS NULL;

`neq`

不等于。返回字段的值与文本不匹配或与文本组合 isNull: false时不为 null 的记录。

在此示例中，我们将获取标题不 'Foundation'为、可用标志不为 false、价格不为零、发布日期不是 2023 年 12 月 31 日且分级不为 null 的书籍。

query {
  books(filter: {
    and: [
      { title: { neq: "Foundation" } }
      { available: { neq: false } }
      { price: { neq: 0 } }
      { publishedOn: { neq: "2023-12-31T00:00:00Z" } }
      { rating: { isNull: false } }
    ]
  }) {
    items { id title available price publishedOn rating }
  }
}

概念 SQL

SELECT id, title, available, price, publishedOn, rating
FROM Books
WHERE title <> 'Foundation'
  AND available <> 0
  AND price <> 0
  AND publishedOn <> '2023-12-31T00:00:00Z'
  AND rating IS NOT NULL;

`gt`

大于。返回字段值严格高于提供的文字的记录。

在此示例中，我们获取的书籍标题按字母顺序 'A'排序，可用标志为 true，价格大于 10，发布日期在 2020 年 1 月 1 日之后。

query {
  books(filter: {
    and: [
      { title: { gt: "A" } }
      { available: { gt: false } }
      { price: { gt: 10 } }
      { publishedOn: { gt: "2020-01-01T00:00:00Z" } }
    ]
  }) {
    items { id title available price publishedOn }
  }
}

概念 SQL

SELECT id, title, available, price, publishedOn
FROM Books
WHERE title > 'A'
  AND available > 0
  AND price > 10
  AND publishedOn > '2020-01-01T00:00:00Z';

`gte`

大于或等于。返回字段值高于或等于给定文本的记录。

在此示例中，我们获取的书籍标题 'A' 为或更高版本，可用标志为 true，价格至少为 10，发布日期为 2020 年 1 月 1 日或之后。

query {
  books(filter: {
    and: [
      { title: { gte: "A" } }
      { available: { gte: false } }
      { price: { gte: 10 } }
      { publishedOn: { gte: "2020-01-01T00:00:00Z" } }
    ]
  }) {
    items { id title available price publishedOn }
  }
}

概念 SQL

SELECT id, title, available, price, publishedOn
FROM Books
WHERE title >= 'A'
  AND available >= 0
  AND price >= 10
  AND publishedOn >= '2020-01-01T00:00:00Z';

`lt`

小于。返回字段值严格低于给定文本的记录。

在此示例中，我们获取其标题排序之前的 'Z'书籍，可用标志为 false，价格小于 50，发布日期在 2030 年 1 月 1 日之前。

query {
  books(filter: {
    and: [
      { title: { lt: "Z" } }
      { available: { lt: true } }
      { price: { lt: 50 } }
      { publishedOn: { lt: "2030-01-01T00:00:00Z" } }
    ]
  }) {
    items { id title available price publishedOn }
  }
}

概念 SQL

SELECT id, title, available, price, publishedOn
FROM Books
WHERE title < 'Z'
  AND available < 1
  AND price < 50
  AND publishedOn < '2030-01-01T00:00:00Z';

`lte`

小于或等于。返回字段值小于或等于给定文本的记录。

在此示例中，我们获取的书籍的标题排序之前或等于 'Z'，可用标志为 true，价格为 100 或更少，发布日期在 2030 年 1 月 1 日或之前。

query {
  books(filter: {
    and: [
      { title: { lte: "Z" } }
      { available: { lte: true } }
      { price: { lte: 100 } }
      { publishedOn: { lte: "2030-01-01T00:00:00Z" } }
    ]
  }) {
    items { id title available price publishedOn }
  }
}

概念 SQL

SELECT id, title, available, price, publishedOn
FROM Books
WHERE title <= 'Z'
  AND available <= 1
  AND price <= 100
  AND publishedOn <= '2030-01-01T00:00:00Z';

`and`

逻辑 AND。合并多个谓词，这些谓词必须全部为 true 才能匹配记录。

在此示例中，我们获取的书籍可用、成本小于 30，并在 2022 年 1 月 1 日之后出版。

query {
  books(filter: {
    and: [
      { available: { eq: true } }
      { price: { lt: 30 } }
      { publishedOn: { gt: "2022-01-01T00:00:00Z" } }
    ]
  }) {
    items { id title available price publishedOn }
  }
}

概念 SQL

SELECT id, title, available, price, publishedOn
FROM Books
WHERE available = 1
  AND price < 30
  AND publishedOn > '2022-01-01T00:00:00Z';

`or`

逻辑或。返回数组中至少有一个谓词的计算结果为 true 的记录。

在此示例中，我们获取的书籍要么缺货，要么定价超过 50。

query {
  books(filter: {
    or: [
      { available: { eq: false } }
      { price: { gt: 50 } }
    ]
  }) {
    items { id title available price }
  }
}

概念 SQL

SELECT id, title, available, price
FROM Books
WHERE available = 0
   OR price > 50;

`contains`

子字符串匹配。返回字段包含提供的子字符串的记录（区分大小写取决于数据库排序规则）。

在此示例中，我们将获得标题包含“Dune”一词的书籍。

query {
  books(filter: { title: { contains: "Dune" } }) {
    items { id title }
  }
}

概念 SQL

SELECT id, title
FROM Books
WHERE title LIKE '%Dune%';

`notContains`

负子字符串匹配。返回字段 不包含 提供的子字符串的记录。

在此示例中，我们将获得其标题不包含“指南”的书籍。

query {
  books(filter: { title: { notContains: "Guide" } }) {
    items { id title }
  }
}

概念 SQL

SELECT id, title
FROM Books
WHERE title NOT LIKE '%Guide%';

`startsWith`

前缀匹配。返回字段以提供的字符串开头的记录。

在此示例中，我们获取其标题以“The”开头的书籍。

query {
  books(filter: { title: { startsWith: "The" } }) {
    items { id title }
  }
}

概念 SQL

SELECT id, title
FROM Books
WHERE title LIKE 'The%';

`endsWith`

后缀匹配。返回字段以提供的字符串结尾的记录。

在此示例中，我们将获得标题以“Chronicles”结尾的书籍。

query {
  books(filter: { title: { endsWith: "Chronicles" } }) {
    items { id title }
  }
}

概念 SQL

SELECT id, title
FROM Books
WHERE title LIKE '%Chronicles';

`in`

成员资格匹配。返回提供的列表中存在字段值的记录。

在此示例中，我们获得了其流派为“SciFi”或“幻想”的书籍。

query {
  books(filter: { genre: { in: ["SciFi", "Fantasy"] } }) {
    items { id title genre }
  }
}

概念 SQL

SELECT id, title, genre
FROM Books
WHERE genre IN ('SciFi', 'Fantasy');

`isNull`

Null 检查。返回字段的值为 null 或不为 null 的记录，具体取决于布尔文本。

在此示例中，我们将获取评级为 null 的书籍。

query {
  books(filter: { rating: { isNull: true } }) {
    items { id title rating }
  }
}

概念 SQL

SELECT id, title, rating
FROM Books
WHERE rating IS NULL;

示例配置

{
  "runtime": {
    "pagination": {
      "default-page-size": 100,
      "max-page-size": 100000
    }
  },
  "entities": {
    "Book": {
      "source": {
        "type": "table",
        "object": "dbo.books"
      },
      "mappings": {
        "sku_title": "title",
        "sku_price": "price"
      },
      "relationships": {
        "book_category": {
          "cardinality": "one",
          "target.entity": "Category",
          "source.fields": [ "category_id" ],
          "target.fields": [ "id" ]
        }
      }
    },
    "Category": {
      "source": {
        "type": "table",
        "object": "dbo.categories"
      },
      "relationships": {
        "category_books": {
          "cardinality": "many",
          "target.entity": "Book",
          "source.fields": [ "id" ],
          "target.fields": [ "category_id" ]
        }
      }
    }
  }
}

另请参阅

概念	REST	GraphQL	目的
投影	$select	物品	选择要返回的字段
Filtering	$filter	滤波器	按条件限制行
排序	$orderby	orderBy	定义排序顺序
页面大小	$first	first	限制每页的项数
延续	$after	后	使用光标从最后一页继续

注释

REST 关键字以 $遵循 OData 约定开头。

反馈

此页面是否有帮助？

通过

筛选 GraphQL 中的数据 （filter）

快速浏览

eq

概念 SQL

neq

概念 SQL

gt

概念 SQL

gte

概念 SQL

lt

概念 SQL

lte

概念 SQL

and

概念 SQL

or

概念 SQL

contains

概念 SQL

notContains

概念 SQL

startsWith

概念 SQL

endsWith

概念 SQL

in

概念 SQL

isNull

概念 SQL

示例配置

另请参阅

反馈

其他资源

筛选 GraphQL 中的数据（`filter`）

`eq`

`neq`

`gt`

`gte`

`lt`

`lte`

`and`

`or`

`contains`

`notContains`

`startsWith`

`endsWith`

`in`

`isNull`