Azure AI Search の OData search.in 関数
OData フィルター式の一般的なシナリオは、各ドキュメントの 1 つのフィールドが多数の可能な値のいずれかと等しいかどうかを調べることです。 たとえば、一部のアプリケーションでは、1 つ以上のプリンシパル ID を含むフィールドを、クエリを発行するユーザーを表すプリンシパル ID のリストと照合することで、セキュリティによるトリミングを実装しています。 このようなクエリを記述する 1 つの方法として、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 を使用することを強くお勧めします。
Note
OData 標準のバージョン 4.01 では最近、 in 演算子が導入されました。この演算子は、Azure AI Search の search.in 関数と同様のビヘイビアーをしています。 ただし、Azure AI Search ではこの演算子はサポートされていないため、代わりに search.in 関数を使用する必要があります。
構文
次の EBNF (拡張バッカス・ナウア記法) では、search.in 関数の文法を定義しています。
search_in_call ::=
'search.in(' variable ',' string_literal(',' string_literal)? ')'
対話型の構文ダイアグラムも利用できます。
Note
完全な EBNF については、Azure AI Searchの OData 式構文参照 を参照してください。
search.in 関数では、指定された文字列フィールドまたは範囲変数が、指定されたリストの値のいずれかと等しいかどうかをテストします。 変数とリストの各値が等しいかどうかは、eq 演算子の場合と同様に、大文字と小文字を区別して判断されます。 そのため、search.in(myfield, 'a, b, c') のような式は、search.in の方がパフォーマンスが良いという点を除き、myfield eq 'a' or myfield eq 'b' or myfield eq 'c' に等しくなります。
search.in 関数には、次の 2 つのオーバーロードがあります。
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 を使用する場合で、2 つ目のパラメーターに数百または数千単位の値リストが含まれるとき、応答時間が 1 秒以下になることが期待できます。 search.in に渡すことができる項目の数は、最大要求サイズによって制限されますが、明示的な上限はありません。 ただし、値の数が増えると、それだけ待ち時間が長くなります。
例
"Sea View motel" または "Budget hotel" と同じ名前のすべてのホテルを探します。 語句には、既定の区切り記号であるスペースを含めます。 3 番目の文字列パラメーターとして、単一引用符で囲まれた代替区切り記号を指定できます。
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'))