在 GraphQL 中篩選資料（`filter`）

篩選會將大型資料集縮小到僅您需要的記錄。在 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`	logical 和
`or`	邏輯或
`contains`	子字串比對
`notContains`	不是子字串比對
`startsWith`	前綴匹配
`endsWith`	後綴匹配
`in`	成員資格
`isNull`	空值檢查

`eq`

等於。傳回欄位值與提供的常值完全相符的記錄，或如果使用 isNull則為 null 。

備註

篩選日期或日期時間欄位時，請使用 未加引號的 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`

邏輯 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`

子字串比對。傳回欄位包含所提供子字串的記錄（區分大小寫取決於資料庫定序）。

在這個例子中，我們得到的書名包含“沙丘”一詞。

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`

後綴匹配。傳回欄位以提供的字串結尾的記錄。

在這個例子中，我們得到的書名以「編年史」結尾。

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

概念性 SQL

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

`in`

會員匹配。傳回欄位值存在於所提供清單中的記錄。

在這個例子中，我們得到的書籍類型是“科幻”或“奇幻”。

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 的記錄，視布林值常值而定。

在此範例中，我們取得的書籍評分為空。

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	目標
Projection	$select	項目	選擇要傳回的欄位
篩選	$filter	篩選	依條件限制資料列
排序	$orderby	orderBy	定義排序順序
頁面大小	$first	first	限制每頁的項目數
繼續	$after	後	使用游標從最後一頁繼續

備註

REST 關鍵字會遵循 OData 慣例，以開 $頭。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-10-15

共用方式為

在 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`