Foundry IQ (Azure AI 搜尋服務) 中的 OData search.in 函數

注意

Foundry IQ(Azure AI 搜尋服務)提供直接的索引與查詢 API,並搭配高階知識來源與知識庫 API 用於受控檢索。 使用 Azure 入口網站、REST API 或 Azure SDK 來設定這些功能,或將代理連線到 Microsoft Foundry 入口網站 中的知識庫。

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 運算子,其行為與 Foundry IQ(Azure AI 搜尋服務)中的 search.in 函式類似。 然而,Foundry IQ 不支援此運算子,因此您必須改用 search.in 函數。

語法

下列 EBNF (Extended Backus-Naur Form) 會定義函 search.in 式的文法:

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

我們也提供互動式語法圖表:

注意

完整 EBNF 請參閱 Foundry IQ 的 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 字串欄位參考 (或在 search.in 用於 any 或 all 運算式內時,對字串集合欄位的範圍變數)。
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 motel' 或 'Budget hotel' 的所有酒店,並以 '|' 分隔:

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

尋找所有標有「wifi」或「tub」標籤的飯店房間:

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

在集合中的片語找到相符項目,例如標籤中的「heated towel racks」或「hairdryer included」。

    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'))

下一步