共用方式為

Azure AI 搜尋中的 OData search.in 函式

  • 發行項

OData 篩選表示式中的常見案例是檢查每個檔中的單一字段是否等於許多可能值的其中一個。 例如，這是某些應用程式 實作安全性修剪 的方式-- 藉由根據代表發出查詢之使用者之主體標識碼清單檢查包含一或多個主體標識元的字段。 撰寫類似下列查詢的其中一種方式是使用 eq 和 or 運算符：

    group_ids/any(g: g eq '123' or g eq '456' or g eq '789')

不過，使用函 search.in 式撰寫此程式的方式較短：

    group_ids/any(g: search.in(g, '123, 456, 789'))

重要

除了較短且更容易閱讀，使用 search.in 也提供 效能優點 ，並避免 在篩選 中包含數百或甚至數千個值時，篩選的特定大小限制。 基於這個理由，我們強烈建議使用 ， search.in 而不是更複雜的相等表達式分離。

注意

OData 標準的 4.01 版最近引進 in 了 運算符，其行為與 search.in Azure AI 搜尋中的函式類似。 不過，Azure AI 搜尋不支援此運算符，因此您必須改用 函式 search.in 。

語法

下列 EBNF （Extended Backus-Naur Form） 會定義函 search.in 式的文法：

search_in_call ::=
    'search.in(' variable ',' string_literal(',' string_literal)? ')'

您也可以使用互動式語法圖表：

Azure AI 搜尋的 OData 語法圖表

注意

如需完整的EBNF，請參閱 Azure AI 搜尋 的 OData 表達式語法參考。

函式 search.in 會測試指定的字串字段或範圍變數是否等於其中一個指定的值清單。 變數與清單中的每個值之間的相等會以區分大小寫的方式決定，與 eq 運算符相同。 因此， 之類的 search.in(myfield, 'a, b, c') 表達式相當於 myfield eq 'a' or myfield eq 'b' or myfield eq 'c'，不同 search.in 之處在於會產生更好的效能。

函式有兩個 search.in 多載：

  • search.in(variable, valueList)
  • search.in(variable, valueList, delimiters)

參數定義於下表中：

參數名稱 類型 描述
variable Edm.String 字串欄位參考（或字串集合欄位上的範圍變數，在 或 all 表示式內any使用的情況下search.in）。
valueList Edm.String 字串，包含要與 variable 參數相符的分隔值清單。 delimiters如果未指定 參數，則預設分隔符為空格和逗號。
delimiters Edm.String 剖析參數時，每個字元都會被視為分隔符的 valueList 字串。 這個參數的預設值表示 ' ,' ，其之間具有空格和/或逗號的任何值都會分隔。 如果您需要使用空格和逗號以外的分隔符，因為您的值包含這些字元，您可以指定替代分隔符，例如 '|' 在此參數中。

的效能 search.in

如果您使用 search.in，當第二個參數包含數百或數千個值的清單時，您可以預期次秒響應時間。 雖然您仍然受限於要求大小上限，但您可以傳遞至 search.in的項目數目沒有明確限制。 不過，延遲將會隨著值數目成長而成長。

範例

尋找名稱等於 「海景汽車旅館」或「預算酒店」的所有酒店。 片語包含空格，這是預設分隔符。 您可以將單引號中的替代分隔符指定為第三個字串參數：

    search.in(HotelName, 'Sea View motel,Budget hotel', ',')

尋找名稱等於 'Sea View hotel' 或以 '|' 分隔的 'Budget hotel' 的所有酒店：

    search.in(HotelName, 'Sea View motel|Budget hotel', '|')

尋找具有 'wifi' 或 'tub' 卷標的所有旅館：

    Rooms/any(room: room/Tags/any(tag: search.in(tag, 'wifi, tub')))

在集合內的片語上尋找相符專案，例如標籤中的「加熱毛巾架」或「隨附的」等。

    Rooms/any(room: room/Tags/any(tag: search.in(tag, 'heated towel racks,hairdryer included', ','))

尋找沒有標籤 'motel' 或 'cabin' 的所有旅館：

    Tags/all(tag: not search.in(tag, 'motel, cabin'))

下一步