Azure AI Search での $filter、$orderby、$select 用の OData 言語の概要

  • [アーティクル]

この記事では、Azure AI Search の $filter 式、$order-by 式、$select 式で使用される OData 式の言語の概要を説明します。 この言語は、最も基本的な要素から始まって "ボトムアップ" で提示されます。 クエリ要求で構築できる OData 式は単純なものから非常に複雑なものまで幅がありますが、そのすべてで共通の要素が共有されます。 共有される要素は次のとおりです。

  • フィールド パス: インデックスの特定のフィールドを参照します。
  • 定数: 特定のデータ型のリテラル値です。

これらの一般的な概念を理解したら、続けて各式の最上位レベルの構文を理解できます。

  • $filter 式はクエリの構文解析中に評価され、検索が特定のフィールドに制約されるか、インデックス スキャン中に使用される一致条件が追加されます。
  • $orderby 式は、返されたドキュメントを並べ替えるために、結果セットに対する後処理手順として適用されます。
  • $select 式は、ドキュメントのどのフィールドが結果セットに含まれるかを決定します。

これらの式の構文は、search パラメーターで使用される単純な、または完全なクエリ構文とは異なりますが、フィールドを参照するための構文には多少の重複があります。

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]*

対話型の構文ダイアグラムも利用できます。

Azure AI Searchの OData 構文図

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 フィルター処理できるフィールドのみを参照できます
検索する queryType が full の場合の search 検索可能フィールドのみを参照できます
検索する facet ファセット可能フィールドのみを参照できます
検索する highlight 検索可能フィールドのみを参照できます
検索する searchFields 検索可能フィールドのみを参照できます
Suggest と Autocomplete searchFields suggester の一部であるフィールドのみを参照できます
Search、Suggest、および Autocomplete $filter フィルター処理できるフィールドのみを参照できます
Search と Suggest $orderby 並べ替え可能フィールドのみを参照できます
Search、Suggest、および Lookup $select 取得可能フィールドのみを参照できます

定数

OData では、定数は特定の Entity Data Model (EDM) 型のリテラル値です。 Azure AI Search でサポートされる型の一覧については、「サポートされるデータ型」を参照してください。 コレクション型の定数はサポートされていません。

次の表に、Azure AI Search でサポートされている各データ型の定数の例を示します。

データ型 定数の例
Edm.Boolean $
Edm.DateTimeOffset 2019-05-06T12:30:05.451Z
Edm.Double
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 $
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'

対話型の構文ダイアグラムも利用できます。

Azure AI Searchの OData 構文図

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

対話型の構文ダイアグラムも利用できます。

Azure AI Searchの OData 構文図

Note

完全な EBNF については、「Azure AI Search の OData 式構文リファレンス」をご覧ください。

次のステップ

$orderby パラメーターと $select パラメーターは、どちらも単純な式のコンマ区切りの一覧です。 $filter パラメーターは、単純なサブ式で構成されるブール式です。 これらのサブ式が、and、or、not などの論理演算子、eq、lt、gt などの比較演算子、any や all などのコレクション演算子を使用して結合されます。

$filter、$orderby、および $select の各パラメーターの詳細を、次の記事で確認できます。