Azure AI Search での $filter、$orderby、$select 用の OData 言語の概要
この記事では、Azure AI Search の $filter、$order-by、$select 式で数値および文字列 (非ベクトル) フィールドにわたってキーワード検索.で使用される OData 式言語の概要を説明します。
この言語は、最も基本的な要素から始まって "ボトムアップ" で提示されます。 クエリ要求で構築できる OData 式は単純なものから非常に複雑なものまで幅がありますが、そのすべてで共通の要素が共有されます。 共有される要素は次のとおりです。
- フィールド パス: インデックスの特定のフィールドを参照します。
- 定数: 特定のデータ型のリテラル値です。
これらの一般的な概念を理解したら、続けて各式の最上位レベルの構文を理解できます。
- $filter 式はクエリの構文解析中に評価され、検索が特定のフィールドに制約されるか、インデックス スキャン中に使用される一致条件が追加されます。
- $orderby 式は、返されたドキュメントを並べ替えるために、結果セットに対する後処理手順として適用されます。
- $select 式は、ドキュメントのどのフィールドが結果セットに含まれるかを決定します。
これらの式の構文は、search パラメーターで使用される単純な、または完全なクエリ構文とは異なりますが、フィールドを参照するための構文には多少の重複があります。
Python や C# などの他の言語の例については、azure-search-vector-samples リポジトリの例を参照してください。
Note
Azure AI Search の用語は、いくつかの点で OData 標準とは異なります。 Azure AI Search でフィールドと呼ばれているものは OData ではプロパティと呼ばれています。同様に、フィールド パスはプロパティ パスに相当します。 Azure AI Search におけるドキュメントを含むインデックスは、OData においてはエンティティを含むエンティティ セットとして、より広い意味で使用されています。 このリファレンス全体では、Azure AI Search の用語が使用されています。
フィールド パス
次の EBNF (拡張バッカスナウア記法) によって、フィールド パスの文法が定義されます。
field_path ::= identifier('/'identifier)*
identifier ::= [a-zA-Z_][a-zA-Z_0-9]*
対話型の構文ダイアグラムも利用できます。
Note
完全な EBNF については、「Azure AI Search の OData 式構文リファレンス」をご覧ください。
フィールド パスは、スラッシュで区切られた 1 つ以上の識別子で構成されます。 各識別子は、ASCII 文字またはアンダースコアで始まり、ASCII 文字、数字、またはアンダースコアのみを含む文字のシーケンスです。 文字には、大文字または小文字を指定できます。
識別子は、フィールドの名前を参照するか、フィルター内の コレクション式 (any または all) のコンテキストで範囲変数を参照できます。 範囲変数は、コレクションの現在の要素を表すループ変数に似ています。 複雑なコレクションでは、その変数はオブジェクトを表します。フィールド パスを使用して変数のサブフィールドを参照できるのはこれが理由です。 これは、多くのプログラミング言語で使用されるドット表記に似ています。
フィールド パスの例を次の表に示します。
| フィールド パス | 説明 |
|---|---|
HotelName |
インデックスの最上位レベルのフィールドを参照します。 |
Address/City |
インデックス内の複雑なフィールドの City サブフィールドを参照します。この例では、Address は Edm.ComplexType 型です |
Rooms/Type |
インデックス内の複雑なコレクション フィールドの Type サブフィールドを参照します。この例では、Rooms は Collection(Edm.ComplexType) 型です |
Stores/Address/Country |
インデックス内の複雑なコレクション フィールドの Address サブフィールドの Country サブフィールドを参照します。この例では、Stores は Collection(Edm.ComplexType) 型であり、Address は Edm.ComplexType 型です |
room/Type |
room 範囲変数の Type サブフィールドを参照します。たとえば、フィルター式 Rooms/any(room: room/Type eq 'deluxe') の内部です |
store/Address/Country |
store 範囲変数の Address サブフィールドの Country サブフィールドを参照します。たとえば、フィルター式 Stores/any(store: store/Address/Country eq 'Canada') の内部です |
フィールド パスの意味はコンテキストによって異なります。 フィルターでは、フィールド パスは、現在のドキュメント内の 1 つのフィールドの "単一のインスタンス" の値を参照します。 $orderby、$select、完全な Lucene 構文でのフィールド検索などの他のコンテキストでは、フィールド パスはフィールドそのものを参照します。 これらの違いは、フィルターでのフィールド パスの使用方法に多少の影響を与えます。
Address/City というフィールド パスを検討します。 フィルターでは、これは現在のドキュメントの単一の都市、たとえば "San Francisco" (サンフランシスコ) を参照します。 一方、Rooms/Type は、多数の客室の Type サブフィールド (第 1 室は "standard"、第 2 室は "deluxe"、以下同様) を参照します。 Rooms/Type では、サブフィールド Type の "単一のインスタンス" は参照されないため、フィルター内で直接使用することはできません。 代わりに、客室の種類でフィルター処理するには、次のようにラムダ式と範囲変数を使用します。
Rooms/any(room: room/Type eq 'deluxe')
この例では、範囲変数 room が room/Type フィールド パスで使用されます。 これにより、room/Type で、現在のドキュメント内の現在の客室の種類が参照されます。 これは Type サブ フィールドの単一のインスタンスであるため、フィルター内で直接使用することができます。
フィールド パスの使用
フィールド パスは、Azure AI Search REST API の多数のパラメーターの中で使用されています。 次の表に、これらを使用できるすべての場所とその使用に関する制限を示します。
| API | パラメーター名 | 制限 |
|---|---|---|
| インデックスの作成または更新 | suggesters/sourceFields |
なし |
| インデックスの作成または更新 | scoringProfiles/text/weights |
検索可能フィールドのみを参照できます |
| インデックスの作成または更新 | scoringProfiles/functions/fieldName |
フィルター処理できるフィールドのみを参照できます |
| Search | queryType が full の場合の search |
検索可能フィールドのみを参照できます |
| Search | facet |
ファセット可能フィールドのみを参照できます |
| Search | highlight |
検索可能フィールドのみを参照できます |
| Search | searchFields |
検索可能フィールドのみを参照できます |
| Suggest と Autocomplete | searchFields |
suggester の一部であるフィールドのみを参照できます |
| Search、Suggest、および Autocomplete | $filter |
フィルター処理できるフィールドのみを参照できます |
| Search と Suggest | $orderby |
並べ替え可能フィールドのみを参照できます |
| Search、Suggest、および Lookup | $select |
取得可能フィールドのみを参照できます |
定数
OData では、定数は特定の Entity Data Model (EDM) 型のリテラル値です。 Azure AI Search でサポートされる型の一覧については、「サポートされるデータ型」を参照してください。 コレクション型の定数はサポートされていません。
次の表に、OData 式をサポートする各非ベクトル データ型の定数の例を示します。
| データの種類 | 定数の例 |
|---|---|
Edm.Boolean |
true、false |
Edm.DateTimeOffset |
2019-05-06T12:30:05.451Z |
Edm.Double |
3.14159、-1.2e7、NaN、INF、-INF |
Edm.GeographyPoint |
geography'POINT(-122.131577 47.678581)' |
Edm.GeographyPolygon |
geography'POLYGON((-122.031577 47.578581, -122.031577 47.678581, -122.131577 47.678581, -122.031577 47.578581))' |
Edm.Int32 |
123、-456 |
Edm.Int64 |
283032927235 |
Edm.String |
'hello' |
文字列定数での特殊文字のエスケープ
OData 内の文字列定数は単一引用符で区切ります。 一重引用符を含む可能性のある文字列定数を使用してクエリを作成する必要がある場合は、埋め込まれた引用符を 2 つ入力することによってエスケープすることができます。
たとえば、"Alice's car" のような書式設定されていないアポストロフィを含む語句は、OData で文字列定数 'Alice''s car' として表現されます。
重要
プログラムによってフィルターを構築する場合は、ユーザー入力に含まれる文字列定数を忘れずにエスケープすることが重要です。 これは、特にフィルターを使用してセキュリティによるトリミングを実装する場合に、インジェクション攻撃の可能性が低減されるようにするためです。
定数の構文
次の EBNF (拡張バッカスナウア記法フォーム) によって、上記の表に示されている定数の大部分に対する文法が定義されます。 地理空間型の文法については、Azure AI Search の OData 地理空間関数に関する記事を参照してください。
constant ::=
string_literal
| date_time_offset_literal
| integer_literal
| float_literal
| boolean_literal
| 'null'
string_literal ::= "'"([^'] | "''")*"'"
date_time_offset_literal ::= date_part'T'time_part time_zone
date_part ::= year'-'month'-'day
time_part ::= hour':'minute(':'second('.'fractional_seconds)?)?
zero_to_fifty_nine ::= [0-5]digit
digit ::= [0-9]
year ::= digit digit digit digit
month ::= '0'[1-9] | '1'[0-2]
day ::= '0'[1-9] | [1-2]digit | '3'[0-1]
hour ::= [0-1]digit | '2'[0-3]
minute ::= zero_to_fifty_nine
second ::= zero_to_fifty_nine
fractional_seconds ::= integer_literal
time_zone ::= 'Z' | sign hour':'minute
sign ::= '+' | '-'
/* In practice integer literals are limited in length to the precision of
the corresponding EDM data type. */
integer_literal ::= digit+
float_literal ::=
sign? whole_part fractional_part? exponent?
| 'NaN'
| '-INF'
| 'INF'
whole_part ::= integer_literal
fractional_part ::= '.'integer_literal
exponent ::= 'e' sign? integer_literal
boolean_literal ::= 'true' | 'false'
対話型の構文ダイアグラムも利用できます。
Note
完全な EBNF については、「Azure AI Search の OData 式構文リファレンス」をご覧ください。
フィールド パスと定数からの式の構築
フィールド パスと定数は OData 式の最も基本的なパーツですが、それら自体が既に完全な式です。 実際、Azure AI Search での $select パラメーターは単なるフィールド パスのコンマ区切りの一覧であり、$orderby が $select よりもはるかに複雑ということはありません。 インデックスに Edm.Boolean 型のフィールドが含まれている場合でも、そのフィールドのパスにすぎないフィルターを記述できます。 同様に、true 定数と false 定数も有効なフィルターです。
ただし、多くの場合、複数のフィールドと定数を参照するより複雑な式を使用します。 これらの式は、パラメーターに応じてさまざまな方法で構築されます。
次の EBNF (拡張バッカスナウア記法) によって、$filter、$orderby、および $select の各パラメーターの文法が定義されます。 これらは、フィールド パスと定数を参照する単純な式から構築されています。
filter_expression ::= boolean_expression
order_by_expression ::= order_by_clause(',' order_by_clause)*
select_expression ::= '*' | field_path(',' field_path)*
対話型の構文ダイアグラムも利用できます。
Note
完全な EBNF については、「Azure AI Search の OData 式構文リファレンス」をご覧ください。
次のステップ
$orderby パラメーターと $select パラメーターは、どちらも単純な式のコンマ区切りの一覧です。 $filter パラメーターは、単純なサブ式で構成されるブール式です。 これらのサブ式が、and、or、not などの論理演算子、eq、lt、gt などの比較演算子、any や all などのコレクション演算子を使用して結合されます。
$filter、$orderby、および $select の各パラメーターの詳細を、次の記事で確認できます。