Azure Cognitive Search での $filter、$orderby、および $select 用の OData 言語の概要OData language overview for $filter, $orderby, and $select in Azure Cognitive Search

• 02/10/2020
• • b
  • o
  • h
  • y

Azure Cognitive Search では、 $filter 式、 $orderby 式、および $select 式で OData 式の構文のサブセットがサポートされています。Azure Cognitive Search supports a subset of the OData expression syntax for $filter, $orderby, and $select expressions. filter 式はクエリの構文解析中に評価され、検索が特定のフィールドに制約されるか、インデックス スキャン中に使用される一致条件が追加されます。Filter expressions are evaluated during query parsing, constraining search to specific fields or adding match criteria used during index scans. order-by 式は、返されたドキュメントを並べ替えるために、結果セットに対する後処理手順として適用されます。Order-by expressions are applied as a post-processing step over a result set to sort the documents that are returned. select 式は、ドキュメントのどのフィールドが結果セットに含まれるかを決定します。Select expressions determine which document fields are included in the result set. これらの式の構文は、search パラメーターで使用される 単純なまたは 完全なクエリ構文とは異なりますが、参照フィールドの構文には多少の重複があります。The syntax of these expressions is distinct from the simple or full query syntax that is used in the search parameter, although there's some overlap in the syntax for referencing fields.

この記事では、filter 式、order-by 式、および select 式で使用される OData 式の言語の概要を示します。This article provides an overview of the OData expression language used in filters, order-by, and select expressions. この言語は "ボトムアップ" で提示され、最も基本的な要素から始まり、その上に構築されていきます。The language is presented "bottom-up", starting with the most basic elements and building on them. 各パラメーターの最上位レベルの構文は、別の記事で説明しています。The top-level syntax for each parameter is described in a separate article:

• $filter 構文$filter syntax
• $orderby 構文$orderby syntax
• $select 構文$select syntax

OData 式は単純なものから複雑なものまで幅がありますが、すべての式で共通の要素が共有されます。OData expressions range from simple to highly complex, but they all share common elements. Azure Cognitive Search での OData 式の最も基本的な部分は次のとおりです。The most basic parts of an OData expression in Azure Cognitive Search are:

• フィールド パス: インデックスの特定のフィールドを参照します。Field paths, which refer to specific fields of your index.
• 定数: 特定のデータ型のリテラル値です。Constants, which are literal values of a certain data type.

フィールド パスField paths

次の EBNF (拡張バッカスナウア記法) によって、フィールド パスの文法が定義されます。The following EBNF (Extended Backus-Naur Form) defines the grammar of field paths.

field_path ::= identifier('/'identifier)*

identifier ::= [a-zA-Z_][a-zA-Z_0-9]*

対話型の構文ダイアグラムも利用できます。An interactive syntax diagram is also available:

フィールド パスは、スラッシュで区切られた 1 つ以上の 識別子 で構成されます。A field path is composed of one or more identifiers separated by slashes. 各識別子は、ASCII 文字またはアンダースコアで始まり、ASCII 文字、数字、またはアンダースコアのみを含む文字のシーケンスです。Each identifier is a sequence of characters that must start with an ASCII letter or underscore, and contain only ASCII letters, digits, or underscores. 文字には、大文字または小文字を指定できます。The letters can be upper- or lower-case.

識別子は、フィールドの名前を参照するか、フィルター内の コレクション式 (any または all) のコンテキストで 範囲変数 を参照できます。An identifier can refer either to the name of a field, or to a range variable in the context of a collection expression (any or all) in a filter. 範囲変数は、コレクションの現在の要素を表すループ変数に似ています。A range variable is like a loop variable that represents the current element of the collection. 複雑なコレクションでは、その変数はオブジェクトを表します。フィールド パスを使用して変数のサブフィールドを参照できるのはこれが理由です。For complex collections, that variable represents an object, which is why you can use field paths to refer to sub-fields of the variable. これは、多くのプログラミング言語で使用されるドット表記に似ています。This is analogous to dot notation in many programming languages.

フィールド パスの例を次の表に示します。Examples of field paths are shown in the following table:

フィールド パスの意味はコンテキストによって異なります。The meaning of a field path differs depending on the context. フィルターでは、フィールド パスは、現在のドキュメント内の 1 つのフィールドの "単一のインスタンス" の値を参照します。In filters, a field path refers to the value of a single instance of a field in the current document. $orderby、 $select、完全な Lucene 構文でのフィールド検索などの他のコンテキストでは、フィールド パスはフィールドそのものを参照します。In other contexts, such as $orderby, $select, or in fielded search in the full Lucene syntax, a field path refers to the field itself. これらの違いは、フィルターでのフィールド パスの使用方法に多少の影響を与えます。This difference has some consequences for how you use field paths in filters.

Address/City というフィールド パスを検討します。Consider the field path Address/City. フィルターでは、これは現在のドキュメントの単一の都市、たとえば "San Francisco" (サンフランシスコ) を参照します。In a filter, this refers to a single city for the current document, like "San Francisco". 一方、Rooms/Type は、多数の客室の Type サブフィールド (第 1 室は "標準"、第 2 室は "デラックス"、以下同様) を参照します。In contrast, Rooms/Type refers to the Type sub-field for many rooms (like "standard" for the first room, "deluxe" for the second room, and so on). Rooms/Type では、Type サブフィールドの "単一のインスタンス" は参照されないため、フィルター内で直接使用することはできません。Since Rooms/Type doesn't refer to a single instance of the sub-field Type, it can't be used directly in a filter. 代わりに、客室の種類でフィルター処理するには、次のようにラムダ式と範囲変数を使用します。Instead, to filter on room type, you would use a lambda expression with a range variable, like this:

Rooms/any(room: room/Type eq 'deluxe')

この例では、範囲変数 room が room/Type フィールド パスで使用されます。In this example, the range variable room appears in the room/Type field path. これにより、room/Type で、現在のドキュメント内の現在の客室の種類が参照されます。That way, room/Type refers to the type of the current room in the current document. これは Type サブ フィールドの単一のインスタンスであるため、フィルター内で直接使用することができます。This is a single instance of the Type sub-field, so it can be used directly in the filter.

フィールド パスの使用Using field paths

フィールド パスは、Azure Cognitive Search REST API の多数のパラメーターの中で使用されます。Field paths are used in many parameters of the Azure Cognitive Search REST APIs. 次の表に、これらを使用できるすべての場所とその使用に関する制限を示します。The following table lists all the places where they can be used, plus any restrictions on their usage:

定数Constants

OData では、定数は特定の Entity Data Model (EDM) 型のリテラル値です。Constants in OData are literal values of a given Entity Data Model (EDM) type. Azure Cognitive Search でサポートされる型の一覧については、「サポートされるデータ型」を参照してください。See Supported data types for a list of supported types in Azure Cognitive Search. コレクション型の定数はサポートされていません。Constants of collection types aren't supported.

次の表に、Azure Cognitive Search でサポートされている各データ型の定数の例を示します。The following table shows examples of constants for each of the data types supported by Azure Cognitive Search:

文字列定数での特殊文字のエスケープEscaping special characters in string constants

OData 内の文字列定数は単一引用符で区切ります。String constants in OData are delimited by single quotes. 一重引用符を含む可能性のある文字列定数を使用してクエリを作成する必要がある場合は、埋め込まれた引用符を 2 つ入力することによってエスケープすることができます。If you need to construct a query with a string constant that might itself contain single quotes, you can escape the embedded quotes by doubling them.

たとえば、"Alice's car" のような書式設定されていないアポストロフィを含む語句は、OData で文字列定数 'Alice''s car' として表現されます。For example, a phrase with an unformatted apostrophe like "Alice's car" would be represented in OData as the string constant 'Alice''s car'.

定数の構文Constants syntax

次の EBNF (拡張バッカスナウア記法フォーム) によって、上記の表に示されている定数の大部分に対する文法が定義されます。The following EBNF (Extended Backus-Naur Form) defines the grammar for most of the constants shown in the above table. 地理空間型の文法については、Azure Cognitive Search での OData 地理空間関数に関する記事を参照してください。The grammar for geo-spatial types can be found in OData geo-spatial functions in Azure Cognitive Search.

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'

対話型の構文ダイアグラムも利用できます。An interactive syntax diagram is also available:

フィールド パスと定数からの式の構築Building expressions from field paths and constants

フィールド パスと定数は OData 式の最も基本的なパーツですが、それら自体が既に完全な式です。Field paths and constants are the most basic part of an OData expression, but they're already full expressions themselves. 実際、Azure Cognitive Search での $select パラメーターは単なるフィールド パスのコンマ区切りの一覧であり、 $orderby が $select よりもはるかに複雑ということはありません。In fact, the $select parameter in Azure Cognitive Search is nothing but a comma-separated list of field paths, and $orderby isn't much more complicated than $select. インデックスに Edm.Boolean 型のフィールドが含まれている場合でも、そのフィールドのパスにすぎないフィルターを記述できます。If you happen to have a field of type Edm.Boolean in your index, you can even write a filter that is nothing but the path of that field. 同様に、true 定数と false 定数も有効なフィルターです。The constants true and false are likewise valid filters.

ただし、ほとんどの場合、複数のフィールドと定数を参照するより複雑な式が必要になります。However, most of the time you'll need more complex expressions that refer to more than one field and constant. これらの式は、パラメーターに応じてさまざまな方法で構築されます。These expressions are built in different ways depending on the parameter.

次の EBNF (拡張バッカスナウア記法) によって、 $filter、 $orderby、および $select の各パラメーターの文法が定義されます。The following EBNF (Extended Backus-Naur Form) defines the grammar for the $filter, $orderby, and $select parameters. これらは、フィールド パスと定数を参照する単純な式から構築されています。These are built up from simpler expressions that refer to field paths and constants:

filter_expression ::= boolean_expression

order_by_expression ::= order_by_clause(',' order_by_clause)*

select_expression ::= '*' | field_path(',' field_path)*

対話型の構文ダイアグラムも利用できます。An interactive syntax diagram is also available:

$orderby パラメーターと $select パラメーターは、どちらも単純な式のコンマ区切りの一覧です。The $orderby and $select parameters are both comma-separated lists of simpler expressions. $filter パラメーターは、単純なサブ式で構成されるブール式です。The $filter parameter is a Boolean expression that is composed of simpler sub-expressions. これらのサブ式が、and、or、not などの論理演算子、eq、lt、gt などの比較演算子、any や all などのコレクション演算子を使用して結合されます。These sub-expressions are combined using logical operators such as and, or, and not, comparison operators such as eq, lt, gt, and so on, and collection operators such as any and all.

$filter、 $orderby、および $select の各パラメーターの詳細を、次の記事で確認できます。The $filter, $orderby, and $select parameters are explored in more detail in the following articles:

• Azure Cognitive Search での OData $filter 構文OData $filter syntax in Azure Cognitive Search
• Azure Cognitive Search での OData $orderby 構文OData $orderby syntax in Azure Cognitive Search
• Azure Cognitive Search での OData $select 構文OData $select syntax in Azure Cognitive Search

関連項目See also

• Azure Cognitive Search のファセット ナビゲーションFaceted navigation in Azure Cognitive Search
• Azure Cognitive Search のフィルターFilters in Azure Cognitive Search
• ドキュメントの検索 (Azure Cognitive Search REST API)Search Documents (Azure Cognitive Search REST API)
• Lucene クエリ構文Lucene query syntax
• Azure Cognitive Search でのシンプルなクエリ構文Simple query syntax in Azure Cognitive Search