Azure コグニティブ検索での $filter$orderby、および $select 用の OData 言語の概要OData language overview for $filter, $orderby, and $select in Azure Cognitive Search

Azure コグニティブ検索では、 $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:

OData 式は単純なものから複雑なものまで幅がありますが、すべての式で共通の要素が共有されます。OData expressions range from simple to highly complex, but they all share common elements. Azure コグニティブ検索での 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.

注意

Azure コグニティブ検索の用語は、いくつかの点で OData 標準とは異なります。Terminology in Azure Cognitive Search differs from the OData standard in a few ways. Azure コグニティブ検索でフィールドと呼ばれているものは、OData ではプロパティと呼ばれています。同様に、フィールド パスプロパティ パスに相当します。What we call a field in Azure Cognitive Search is called a property in OData, and similarly for field path versus property path. Azure コグニティブ検索でのドキュメントを含むインデックスは、OData でのエンティティを含むエンティティ セットよりも広い意味で使用されています。An index containing documents in Azure Cognitive Search is referred to more generally in OData as an entity set containing entities. このリファレンス全体では、Azure コグニティブ検索の用語が使用されます。The Azure Cognitive Search terminology is used throughout this reference.

フィールド パス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:

注意

完全な EBNF については、Azure コグニティブ検索の OData 式構文リファレンスのページを参照してください。See OData expression syntax reference for Azure Cognitive Search for the complete EBNF.

フィールド パスは、スラッシュで区切られた 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:

フィールド パスField path 説明Description
HotelName インデックスの最上位レベルのフィールドを参照します。Refers to a top-level field of the index
Address/City インデックス内の複雑なフィールドの City サブフィールドを参照します。この例では、AddressEdm.ComplexType 型です。Refers to the City sub-field of a complex field in the index; Address is of type Edm.ComplexType in this example
Rooms/Type インデックス内の複雑なコレクション フィールドの Type サブフィールドを参照します。この例では、RoomsCollection(Edm.ComplexType) 型です。Refers to the Type sub-field of a complex collection field in the index; Rooms is of type Collection(Edm.ComplexType) in this example
Stores/Address/Country インデックス内の複雑なコレクション フィールドの Address サブフィールドの Country サブフィールドを参照します。この例では、StoresCollection(Edm.ComplexType) 型であり、AddressEdm.ComplexType 型です。Refers to the Country sub-field of the Address sub-field of a complex collection field in the index; Stores is of type Collection(Edm.ComplexType) and Address is of type Edm.ComplexType in this example
room/Type room 範囲変数の Type サブフィールドを参照します。例として、フィルター式内の Rooms/any(room: room/Type eq 'deluxe') があります。Refers to the Type sub-field of the room range variable, for example in the filter expression Rooms/any(room: room/Type eq 'deluxe')
store/Address/Country store 範囲変数の Address サブフィールドの Country サブフィールドを参照します。例として、フィルター式内の Stores/any(store: store/Address/Country eq 'Canada') があります。Refers to the Country sub-field of the Address sub-field of the store range variable, for example in the filter expression Stores/any(store: store/Address/Country eq 'Canada')

フィールド パスの意味はコンテキストによって異なります。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')

この例では、範囲変数 roomroom/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 コグニティブ検索 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:

APIAPI パラメーター名Parameter name 制限Restrictions
インデックスの作成または更新Create or Update Index suggesters/sourceFields なしNone
インデックスの作成または更新Create or Update Index scoringProfiles/text/weights 検索可能フィールドのみを参照できますCan only refer to searchable fields
インデックスの作成または更新Create or Update Index scoringProfiles/functions/fieldName フィルター処理できるフィールドのみを参照できますCan only refer to filterable fields
SearchSearch queryTypefull の場合の searchsearch when queryType is full 検索可能フィールドのみを参照できますCan only refer to searchable fields
SearchSearch facet ファセット可能フィールドのみを参照できますCan only refer to facetable fields
SearchSearch highlight 検索可能フィールドのみを参照できますCan only refer to searchable fields
SearchSearch searchFields 検索可能フィールドのみを参照できますCan only refer to searchable fields
SuggestAutocompleteSuggest and Autocomplete searchFields suggester の一部であるフィールドのみを参照できますCan only refer to fields that are part of a suggester
SearchSuggest、および AutocompleteSearch, Suggest, and Autocomplete $filter フィルター処理できるフィールドのみを参照できますCan only refer to filterable fields
SearchSuggestSearch and Suggest $orderby 並べ替え可能フィールドのみを参照できますCan only refer to sortable fields
SearchSuggest、および LookupSearch, Suggest, and Lookup $select 取得可能フィールドのみを参照できますCan only refer to retrievable fields

定数Constants

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

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

データ型Data type 定数の例Example constants
Edm.Boolean truefalsetrue, false
Edm.DateTimeOffset 2019-05-06T12:30:05.451Z
Edm.Double 3.14159-1.2e7NaNINF-INF3.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-456123, -456
Edm.Int64 283032927235
Edm.String 'hello'

次の EBNF (拡張バッカスナウア記法フォーム) によって、上記の表に示されている定数の大部分に対する文法が定義されます。The following EBNF (Extended Backus-Naur Form) defines the grammar for most of the constants shown in the above table. 地理空間型の文法については、Azure コグニティブ検索での 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:

注意

完全な EBNF については、Azure コグニティブ検索の OData 式構文リファレンスのページを参照してください。See OData expression syntax reference for Azure Cognitive Search for the complete EBNF.

フィールド パスと定数からの式の構築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 コグニティブ検索での $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:

注意

完全な EBNF については、Azure コグニティブ検索の OData 式構文リファレンスのページを参照してください。See OData expression syntax reference for Azure Cognitive Search for the complete EBNF.

$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. これらのサブ式が、andornot などの論理演算子、eqltgt などの比較演算子、anyall などのコレクション演算子を使用して結合されます。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:

関連項目See also