共用方式為

關鍵字搜尋中的篩選條件

  • 發行項

篩選條件提供以值為基礎的準則，以便在關鍵字搜尋的查詢執行之前或在向量搜尋的查詢執行之前或之後包含或排除內容。 篩選條件會套用至非向量欄位，但如果文件包含非向量欄位，則可在向量搜尋中使用。 例如，對於以區塊化內容為依據組織的索引，您可能有可篩選的父層級欄位或中繼資料欄位。

本文說明關鍵字搜尋的篩選。 如需向量的詳細資訊，請參閱在向量查詢中新增篩選條件。

使用 OData 篩選條件運算式語法來指定篩選條件。 相較於關鍵字和向量搜尋，只有在項目完全相符時，篩選條件才會成功。

使用篩選條件的時機

篩選條件是數個搜尋體驗的基礎，包括 "find near me"、地理空間搜尋、多面向導覽和安全性篩選，以便只顯示允許使用者查看的文件。 如果您實作這其中任一個體驗，則篩選條件是必要的。 它是搜尋查詢附加的篩選條件，這類查詢可提供地理位置座標、使用者所選取的 Facet 類別或要求者的安全性識別碼。

常見情況包括：

  • 根據索引中的內容配量搜尋結果。 鑒於包含旅館位置、類別和便利設施的結構描述，您可以建立篩選條件來明確地對比條件 (位於西雅圖、在水上、有景觀)。

  • 實作搜尋體驗會隨附篩選相依性：

    • 多面向導覽會使用篩選條件，傳回使用者所選取的 Facet 類別。
    • 地理空間搜尋會使用篩選條件來傳遞「尋找靠近我」應用程式中目前位置的座標，以及符合區域內或距離的函式。
    • 安全性篩選條件會傳遞安全性識別碼作為篩選條件準則，索引中的相符項目則會作為用以存取文件權限的 Proxy。

  • 進行「數位搜尋」。 數值欄位可擷取且可出現在搜尋結果中，但不可單獨加以搜尋 (受限於全文檢索搜尋)。 如果您需要以數值資料為基礎的選取準則，請使用篩選條件。

如何執行篩選條件

查詢時，篩選條件剖析器會接受準則作為輸入、將運算式轉換為不可部分完成的布林運算式，以樹狀結構代表，然後在索引中針對可篩選欄位進行對樹狀結構的評估。

篩選會與搜尋同時發生，限定下游處理程序中要包含哪些文件來進行文件擷取及相關的評分。 與搜尋字串配對時，篩選條件會有效地縮減重新叫用集合作業的介面區。 單獨使用時 (例如，當查詢字串空白時，其中 search=*)，篩選條件準則會是唯一的輸入。

如何定義篩選條件

篩選條件會套用至屬性為 filterable 之欄位上的英數字元內容。

篩選條件是 OData 運算式，以 Azure AI 搜尋服務所支援的篩選語法表達。

您可以針對每個搜尋作業指定一個篩選條件，但篩選條件本身可以包含多個欄位、多個條件，而且如果您使用 ismatch 函式，則可包含多個全文檢索搜尋運算式。 在多組件篩選條件運算式中，您可以依任何順序指定述詞，(受限於運算子優先順序規則)。 如果您嘗試以特定序列重新整理述詞，則不會有任何顯著的效能改善。

篩選條件運算式的其中一個限制是要求的大小上限。 整個要求 (包含篩選條件) 針對 POST 最多可有 16 MB，針對 GET 則是 8 KB。 篩選條件運算式中的子句數目也有限制。 最佳經驗法則是，如果您有數百個子句，則必須承擔達到限制的風險。 我們建議以這類不會產生無大小限制之篩選條件的方式來設計您的應用程式。

下列範例會呈現數個 API 中的典型篩選條件定義。

POST https://[service name].search.windows.net/indexes/hotels/docs/search?api-version=2024-07-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" 分隔)，每個均有自己的篩選條件準則 (例如，'dog' 中的 'beagles' 或 'cat' 中的 'siamese')。 與 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 和 $filter 參數。 例如，下列兩項查詢將產生相同的結果：

    $filter=search.ismatchscoring('pool') and Rating ge 4

search=pool&$filter=Rating ge 4

進行篩選的欄位需求

在 REST API 中，簡單欄位的可供篩選選項預設為開啟。 可篩選的欄位會增加索引大小；請務必針對您不打算在篩選條件中實際使用的欄位設定 "filterable": false。 如需適用於欄位定義之設定的詳細資訊，請參閱建立索引 \(英文\)。

在 Azure SDK 中，可篩選預設會關閉。 您可以將對應 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 包含 "sunny day"，則 $filter=f eq 'sunny' 不相符，但 $filter=f eq 'sunny day' 將會符合。

文字字串區分大小寫，這表示文字篩選條件預設會區分大小寫。 例如，輸入 $filter=f eq 'Sunny day' 不會找到 "sunny day"。 不過，您可以使用正規化程式，讓篩選時不區分大小寫。

篩選文字的方法

方法 描述 使用時機
search.in 將欄位與字串分隔清單進行對比的函數。 建議用於安全性篩選條件，以及需要與字串欄位比對許多原始文字值的任何篩選條件。 search.in 函式是針對速度而設計，而且比使用 eq 和 or 明確比較欄位與每個字串還要快速。
search.ismatch 此函式可讓您在相同的篩選條件運算式中，混用全文檢索搜尋作業以及純布林值篩選作業。 當您想要在一個要求中使用多個搜尋篩選條件組合時，請使用 search.ismatch (或其評分對等的 search.ismatchscoring)。 您也可以將它用於 contains 篩選條件，以篩選較大字串內的部分字串。
$filter=field operator string 使用者定義的運算式，由欄位、運算子和值所組成。 當您想要尋找字串欄位與字串值之間的完全相符項目時，請使用此選項。

數值篩選條件基本概念

數值欄位在全文檢索搜尋的內容中不是 searchable。 只有字串才能進行全文檢索搜尋。 例如，如果您輸入 99.99 作為搜尋字詞，則將不會得到價格為 $ 99.99 美元的項目。 相反地，您會看到在文件的字串欄位中有數字 99 的項目。 因此，如果您有數值資料，則假設您會將其用於篩選條件，包括範圍、Facet、群組等。

包含數值欄位 (價格、大小、SKU、識別碼) 的文件會在搜尋結果中提供那些值，但前提是已將該欄位標記為 retrievable。 此處的重點是全文檢索搜尋本身不適用於數值欄位類型。

下一步

首先，嘗試使用入口網站中的 [搜尋總管]，提交含有 $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 篩選條件運算式語法 > 範例。

另請參閱