Azure Cognitive Search での $filter
、$orderby
、および $select
用の OData 言語の概要OData language overview for $filter
, $orderby
, and $select
in Azure Cognitive Search
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:
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.
注意
Azure Cognitive Search の用語は、いくつかの点で OData 標準とは異なります。Terminology in Azure Cognitive Search differs from the OData standard in a few ways. Azure Cognitive Search で フィールド と呼ばれているものは、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 Cognitive Search での ドキュメント を含む インデックス は、OData での エンティティ を含む エンティティ セット よりも広い意味で使用されています。An index containing documents in Azure Cognitive Search is referred to more generally in OData as an entity set containing entities. このリファレンス全体では、Azure Cognitive Search の用語が使用されます。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 Cognitive Search の 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 サブフィールドを参照します。この例では、Address は Edm.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 サブフィールドを参照します。この例では、Rooms は Collection(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 サブフィールドを参照します。この例では、Stores は Collection(Edm.ComplexType) 型であり、Address は Edm.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')
この例では、範囲変数 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:
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 | queryType が full の場合の search search 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 |
Suggest と AutocompleteSuggest and Autocomplete | searchFields |
suggester の一部であるフィールドのみを参照できますCan only refer to fields that are part of a suggester |
Search、Suggest、および AutocompleteSearch, Suggest, and Autocomplete | $filter |
フィルター処理できる フィールドのみを参照できますCan only refer to filterable fields |
Search と SuggestSearch and Suggest | $orderby |
並べ替え可能 フィールドのみを参照できますCan only refer to sortable fields |
Search、Suggest、および 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 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:
データ型Data type | 定数の例Example constants |
---|---|
Edm.Boolean |
true , false true , false |
Edm.DateTimeOffset |
2019-05-06T12:30:05.451Z |
Edm.Double |
3.14159 , -1.2e7 , NaN , INF , -INF 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 123 , -456 |
Edm.Int64 |
283032927235 |
Edm.String |
'hello' |
文字列定数での特殊文字のエスケープ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'
.
重要
プログラムによってフィルターを構築する場合は、ユーザー入力に含まれる文字列定数を忘れずにエスケープすることが重要です。When constructing filters programmatically, it's important to remember to escape string constants that come from user input. これは、特にフィルターを使用してセキュリティによるトリミングを実装する場合に、インジェクション攻撃の可能性が低減されるようにするためです。This is to mitigate the possibility of injection attacks, especially when using filters to implement security trimming.
定数の構文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:
注意
完全な EBNF については、Azure Cognitive Search の 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 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:
注意
完全な EBNF については、Azure Cognitive Search の 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. これらのサブ式が、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