Azure AI 搜尋服務中的關鍵字搜尋篩選器

Note

Azure AI 搜尋服務可透過 Azure 入口網站、REST API 及 Azure SDK 取得。它同時也是 Foundry IQ 的基礎，這是一個管理式知識層，能將企業內容轉化為可重複使用、權限感知的知識庫，供 Microsoft Foundry 入口網站中的代理使用。

篩選器提供基於價值的條件，用於關鍵字搜尋前或向量搜尋執行前或之後包含或排除內容。過濾器會套用在非向量場上，但如果文件包含非向量場，也可以用於向量搜尋。例如，對於圍繞分塊式內容組織的索引，你可能會有父級欄位或中繼資料欄位可以用來過濾。

本文說明關鍵字搜尋的篩選方法。欲了解更多關於向量的資訊，請參閱向量查詢中新增篩選器。

過濾器是使用 OData 過濾器表達式語法來指定。與關鍵字與向量搜尋不同，過濾器只有在匹配完全一致時才會成功。

何時使用濾網

篩選器是多種搜尋體驗的基礎，包括「尋找附近」地理空間搜尋、分面導覽，以及只顯示使用者可查看文件的安全篩選器。如果你實施其中任何一項經驗，就必須加個篩選器。附加在搜尋查詢上的篩選器負責提供地理位置座標、使用者選擇的面向類別或請求者的安全 ID。

常見情境包括：

根據索引中的內容對搜尋結果進行切片。給定一個包含飯店位置、分類和設施的架構，你可以建立一個篩選器，明確依照條件匹配（在西雅圖、在水邊、有景觀）。
實作帶有篩選條件依賴的搜尋體驗：
- 分面導航會使用篩選器回傳使用者所選的分面類別。
- 地理空間搜尋會在「尋找我附近」應用程式中，使用篩選來傳遞目前位置的座標，並找出在某個區域內或符合特定距離的結果。
- 安全過濾器將安全識別碼作為過濾條件傳遞，索引中的匹配作為文件存取權的代理。
進行「數字搜尋」。數值欄位可檢索並出現在搜尋結果中，但無法單獨搜尋（需全文搜尋）。如果你需要基於數值資料的篩選標準，可以使用篩選器。

過濾器的執行方式

在查詢時，過濾器解析器接受條件作為輸入，將表達式轉換為以樹狀表示的原子布林表達式，然後在索引中對可過濾欄位評估過濾樹。

篩選與搜尋同時進行，以限定哪些文件應納入下游處理，以便文件檢索及相關性評分。搭配搜尋字串時，篩選可有效縮小後續搜尋作業的召回集。單獨使用時（例如查詢字串為空 search=*且），過濾條件為唯一輸入。

濾波器的定義方式

過濾器適用於欄位中歸屬 filterable為的文字與數值（非向量）內容。

過濾器是 OData 表達式，以 filter 語法表達，並由 Azure AI 搜尋服務支援。

你可以為每個搜尋操作指定一個篩選器，但這個篩選器本身可以包含多個欄位、多個條件，如果你使用函 ismatch 式，還能包含多個全文搜尋表達式。在多部分過濾器表達式中，你可以以任意順序指定謂詞（受運算子優先順序規則約束）。如果你嘗試在特定序列中重新排列謂詞，效能並沒有明顯提升。

過濾器表達式的限制之一是請求的最大大小限制。整個請求（包含過濾器）最多可為 POST 16 MB，GET 最多可為 8 KB。過濾器表達式的子句數量也有限制。一個實用經驗法則是，如果您有數百個子句，就可能有達到限制的風險。我們建議設計你的應用程式，避免產生無限大小的篩選器。

以下範例代表了多個 API 中的典型濾波器定義。

POST https://[service name].search.windows.net/indexes/hotels/docs/search?api-version=2026-04-01
{
    "search": "*",
    "filter": "Rooms/any(room: room/BaseRate lt 150.0)",
    "select": "HotelId, HotelName, Rooms/Description, Rooms/BaseRate"
}

options = new SearchOptions()
{
    Filter = "Rating gt 4",
    OrderBy = { "Rating desc" }
};

濾波器模式

以下範例說明了多種過濾場景的使用模式。更多想法請參見 OData 表達式語法 > 範例。

獨立 $filter，無需查詢字串，當篩選表達式能完整限定感興趣的文件時非常有用。沒有查詢字串，就沒有詞彙或語言分析，沒有評分，也沒有排名。請注意，搜尋字串只是一個星號，意思是「所有文件都匹配」。
```
{
  "search": "*",
  "filter": "Rooms/any(room: room/BaseRate ge 60 and room/BaseRate lt 300) and Address/City eq 'Honolulu"
}
```
查詢字串與 $filter的組合，其中過濾器建立子集，查詢字串則提供詞彙輸入，用於過濾後子集的全文搜尋。新增詞彙（步行距離劇院）會在結果中引入搜尋分數，且最符合這些詞彙的文件會被排名較高。使用帶有查詢字串的過濾器是最常見的使用模式。
```
{
  "search": "walking distance theaters",
  "filter": "Rooms/any(room: room/BaseRate ge 60 and room/BaseRate lt 300) and Address/City eq 'Seattle'"
}
```
複合查詢，以「或」分隔，每個查詢都有自己的篩選條件（例如，在「犬」中查找「比格犬」，或在「貓」中查找「暹羅貓」）。以 or 組合的運算式會個別評估，並在回應中傳回符合每個運算式的文件聯集。這種使用模式是透過函 search.ismatchscoring 式來實現的。你也可以使用非計分版本。 search.ismatch
```
# Match on hostels rated higher than 4 OR 5-star motels.
$filter=search.ismatchscoring('hostel') and Rating ge 4 or search.ismatchscoring('motel') and Rating eq 5

# Match on 'luxury' or 'high-end' in the description field OR on category exactly equal to 'Luxury'.
$filter=search.ismatchscoring('luxury | high-end', 'Description') or Category eq 'Luxury'&$count=true
```
也可以將全文搜尋 search.ismatchscoring 與篩選器結合，使用 and 代替 or，但這在功能上等同於在搜尋請求中使用 search and $filter 參數。例如，以下兩個查詢會產生相同的結果：
```
$filter=search.ismatchscoring('pool') and Rating ge 4

search=pool&$filter=Rating ge 4
```

篩選的欄位需求

在 REST API 中，簡單欄位預設會將可篩選設為開啟。篩選欄位會增加索引大小；請務必設定 "filterable": false 對於那些您實際上不打算在篩選器中使用的欄位。欲了解更多欄位定義設定的資訊，請參閱建立索引。

在 Azure SDK 中，「可過濾」的預設狀態為off。你可以透過將對應 SearchField 物件的 IsFilterable 屬性設定為 true，讓欄位可篩選。在下一個例子中，屬性被設置在一個模型類別的 Rating 屬性上，該類別映射到索引定義。

[SearchField(IsFilterable = true, IsSortable = true, IsFacetable = true)]
public double? Rating { get; set; }

讓現有欄位可過濾

你無法修改現有欄位使其可過濾。相反地，你需要新增一個欄位，或重建索引。欲了解更多關於重建索引或重新填充欄位的資訊，請參見如何重建Azure AI 搜尋服務索引。

文字過濾器的基本原理

文字過濾器會將字串欄位與你在篩選器中提供的字串匹配： $filter=Category eq 'Resort and Spa'

與全文搜尋不同，文字篩選沒有詞彙分析或詞彙分割，因此比較僅限於精確匹配。例如，假設一個欄位f包含「晴天」，與$filter=f eq 'sunny'不符合，但與$filter=f eq 'sunny day'相符合。

文字字串是區分大小寫的，也就是說文字過濾器預設是區分大小寫的。例如， $filter=f eq 'Sunny day' 找不到「晴天」這個詞。不過，你可以用正規化器讓濾波器不區分大小寫。

文字過濾的方法

方法	描述	何時使用
`search.in`	一個將欄位與分隔字串列表匹配的函數。	推薦用於安全過濾器，以及任何需要用字串欄位匹配大量原始文字值的過濾器。 search.in 函數經過速度優化，相較於使用 `eq` 和 `or` 明確比較欄位與每個字串，效率快得多。
`search.ismatch`	一個函式，允許你在同一個過濾表達式中混合全文搜尋操作和嚴格布林過濾操作。	當你想在同一請求中使用多種搜尋篩選組合時，請使用 search.ismatch（或其評分對應的 search.ismatchscoring）。你也可以使用包含過濾器來在較大的字串中過濾部分字串。
`$filter=field operator string`	一個由欄位、運算子和值組成的使用者定義表達式。	當你想找到字串欄位和字串值之間的精確匹配時，可以使用這個方法。

數值濾波器基本原理

數值欄位不 searchable 屬於全文搜尋的範疇。只有字串可進行全文搜尋。例如，如果你輸入 99.99 作為搜尋詞，你不會拿回價值 99.99 美元的商品。相反地，你會看到文件中字串欄位中數字為 99 的項目。因此，如果你有數值資料，假設你會用它們來做篩選，包括範圍、面、群組等等。

包含數字欄位（價格、大小、SKU、ID）的文件，若欄位標記 retrievable為，則會在搜尋結果中提供這些值。重點是，全文搜尋本身不適用於數字欄位類型。

下一步

首先，請在Azure入口網站使用 Search explorer，以 $filter 參數提交查詢。當你將以下篩選查詢貼上到搜尋欄時，房地產樣本索引會提供有趣的結果：

# Geo-filter returning documents within 5 kilometers of Redmond, Washington state
# Use $count=true to get a number of hits returned by the query
# Use $select to trim results, showing values for named fields only
# Use search=* for an empty query string. The filter is the sole input

search=*&$count=true&$select=description,city,postCode&$filter=geo.distance(location,geography'POINT(-122.121513 47.673988)') le 5

# Numeric filters use comparison like greater than (gt), less than (lt), not equal (ne)
# Include "and" to filter on multiple fields (baths and bed)
# Full text search is on John Leclerc, matching on John or Leclerc

search=John Leclerc&$count=true&$select=source,city,postCode,baths,beds&$filter=baths gt 3 and beds gt 4

# Text filters can also use comparison operators
# Wrap text in single or double quotes and use the correct case
# Full text search is on John Leclerc, matching on John or Leclerc

search=John Leclerc&$count=true&$select=source,city,postCode,baths,beds&$filter=city gt 'Seattle'

如需更多範例，請參閱 OData 濾波表達式語法 > 範例。

參見

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-07-03