Azure Cognitive Search での Lucence クエリ構文Lucene query syntax in Azure Cognitive Search

特殊なクエリ形式 (ワイルドカード、あいまい検索、近接検索、正規表現などその他多数) に対し、高度な Lucene Query Parser 構文に基づいて Azure Cognitive Search に対するクエリを作成できます。You can write queries against Azure Cognitive Search based on the rich Lucene Query Parser syntax for specialized query forms: wildcard, fuzzy search, proximity search, regular expressions are a few examples. Lucene Query Parser 構文の多くは、Azure Cognitive Search でそのまま実装されています。ただし、範囲検索は例外で、これは Azure Cognitive Search では $filter 式を介して構築されます。Much of the Lucene Query Parser syntax is implemented intact in Azure Cognitive Search, with the exception of range searches which are constructed in Azure Cognitive Search through $filter expressions.

完全な解析を呼び出す方法How to invoke full parsing

queryType 検索パラメーターを設定して、使用するパーサーを指定します。Set the queryType search parameter to specify which parser to use. 有効な値には simple|full が含まれます。simple が既定値で、full が Lucene の値です。Valid values include simple|full, with simple as the default, and full for Lucene.

完全な構文を示す例Example showing full syntax

次の例は、queryType=full パラメーターで明らかなように、Lucence クエリ構文を使用してインデックスでドキュメントを検出します。The following example finds documents in the index using the Lucene query syntax, evident in the queryType=full parameter. このクエリは、カテゴリ フィールドに "budget" (低料金) が含まれ、すべての検索可能なフィールドに "recently renovated" (最近改修済み) というフレーズが含まれるホテルを返します。This query returns hotels where the category field contains the term "budget" and all searchable fields containing the phrase "recently renovated". "recently renovated (最近改修済み)" というフレーズを含むドキュメントは、用語ブースト値 (3) の結果、高いランキングになります。Documents containing the phrase "recently renovated" are ranked higher as a result of the term boost value (3).

searchMode=all パラメーターは、この例で関連しています。The searchMode=all parameter is relevant in this example. クエリに演算子があるときは、通常 searchMode=all を設定して、すべての条件が確実に一致するようにします。Whenever operators are on the query, you should generally set searchMode=all to ensure that all of the criteria is matched.

GET /indexes/hotels/docs?search=category:budget AND \"recently renovated\"^3&searchMode=all&api-version=2019-05-06&querytype=full

または、次のように POST を使用します。Alternatively, use POST:

POST /indexes/hotels/docs/search?api-version=2019-05-06
{
  "search": "category:budget AND \"recently renovated\"^3",
  "queryType": "full",
  "searchMode": "all"
}

その他の例については、Azure Cognitive Search でクエリを作成するための Lucene クエリ構文例に関する記事を参照してください。For additional examples, see Lucene query syntax examples for building queries in Azure Cognitive Search. すべての可能なクエリ パラメーターの指定に関する詳細については、「ドキュメントの検索 (Azure Cognitive Search REST API)」を参照してください。For details about specifying the full contingent of query parameters, see Search Documents (Azure Cognitive Search REST API).

注意

Azure Cognitive Search では、簡潔なキーワード検索に使用できる単純で堅牢なクエリ言語である、単純なクエリ構文もサポートされます。Azure Cognitive Search also supports Simple Query Syntax, a simple and robust query language that can be used for straightforward keyword search.

構文の基礎Syntax fundamentals

次の構文の基礎は、Lucene 構文を使用するすべてのクエリに適用されます。The following syntax fundamentals apply to all queries that use the Lucene syntax.

コンテキストでの演算子評価Operator evaluation in context

配置によって、記号を演算子と解釈するか、または文字列内の 1 つの文字と解釈するかが決まります。Placement determines whether a symbol is interpreted as an operator or just another character in a string.

たとえば、Lucene の完全構文では、チルダ (~) はあいまい検索と近接検索の両方に使用されます。For example, in Lucene full syntax, the tilde (~) is used for both fuzzy search and proximity search. 引用符で囲まれた語句の後に配置されると、~ は近接検索を呼び出します。When placed after a quoted phrase, ~ invokes proximity search. 用語の末尾に配置されると、~ はあいまい検索を呼び出します。When placed at the end of a term, ~ invokes fuzzy search.

用語内に配置される ("business~analyst" など) と、この文字は演算子と評価されません。Within a term, such as "business~analyst", the character is not evaluated as an operator. この場合は、このクエリが用語または語句のクエリであると想定して、字句解析を使用するフル テキスト検索によって ~ が削除され、"business~analyst" という用語は 2 つに分割されて、business OR analyst になります。In this case, assuming the query is a term or phrase query, full text search with lexical analysis strips out the ~ and breaks the term "business~analyst" in two: business OR analyst.

上記の例ではチルダ (~) ですが、すべての演算子に同じ原則が適用されます。The example above is the tilde (~), but the same principle applies to every operator.

特殊文字のエスケープEscaping special characters

特殊文字を検索テキストの一部として使用するには、エスケープする必要があります。Special characters must be escaped to be used as part of the search text. 特殊文字の前に円記号 (\) 付けることでエスケープできます。You can escape them by prefixing them with backslash (\). エスケープが必要な特殊文字としては、以下の文字があります。Special characters that need to be escaped include the following:
+ - && || ! ( ) { } [ ] ^ " ~ * ? : \ /

たとえば、ワイルドカード文字をエスケープするには、\* を使用します。For example, to escape a wildcard character, use \*.

URL での安全でない文字および予約文字のエンコードEncoding unsafe and reserved characters in URLs

安全でない文字および予約文字はすべて、URL でエンコードするようにしてください。Please ensure all unsafe and reserved characters are encoded in a URL. たとえば、'#' は、URL 内のフラグメント ID またはアンカー ID のため、安全でない文字です。For example, '#' is an unsafe character because it is a fragement/anchor identifier in a URL. この文字を URL で使用する場合は、%23 にエンコードする必要があります。The character must be encoded to %23 if used in a URL. '&' と '=' は、予約文字の例です。これらの文字は、Azure Cognitive Search でパラメーターを区切り、値を指定します。'&' and '=' are examples of reserved characters as they delimit parameters and specify values in Azure Cognitive Search. 詳細については、「RFC1738: Uniform Resource Locators (URL)」を参照してください。Please see RFC1738: Uniform Resource Locators (URL) for more details.

安全でない文字は " ` < > # % { } | \ ^ ~ [ ] です。Unsafe characters are " ` < > # % { } | \ ^ ~ [ ]. 予約文字は ; / ? : @ = + & です。Reserved characters are ; / ? : @ = + &.

優先順位の演算子: グループ化とフィールドのグループ化Precedence operators: grouping and field grouping

かっこを使用して、かっこで囲まれたステートメント内に演算子を含むサブクエリを作成できます。You can use parentheses to create subqueries, including operators within the parenthetical statement. たとえば、motel+(wifi||luxury) を指定すると、"motel" という用語と "wifi" または "luxury" (あるいはその両方) を含むドキュメントが検索されます。For example, motel+(wifi||luxury) will search for documents containing the "motel" term and either "wifi" or "luxury" (or both).

フィールドのグループ化は似ていますが、グループ化のスコープを 1 つのフィールドに設定します。Field grouping is similar but scopes the grouping to a single field. たとえば、hotelAmenities:(gym+(wifi||pool)) を指定すると、"hotelAmenities" のフィールドで "gym" と "wifi"、または "gym" と "pool" が検索されます。For example, hotelAmenities:(gym+(wifi||pool)) searches the field "hotelAmenities" for "gym" and "wifi", or "gym" and "pool".

SearchMode パラメーターに関する考慮事項SearchMode parameter considerations

Azure Cognitive Search での単純なクエリ構文」で説明されているように、クエリに対する searchMode の影響は、Lucene クエリ構文にも同様に適用されます。The impact of searchMode on queries, as described in Simple query syntax in Azure Cognitive Search, applies equally to the Lucene query syntax. つまり、searchMode を NOT 演算子と組み合わせて使用した場合、パラメーターの設定による影響が明確でなければ異常と思えるクエリ結果になることがあります。Namely, searchMode in conjunction with NOT operators can result in query outcomes that might seem unusual if you aren't clear on the implications of how you set the parameter. 既定値の searchMode=any を保持して、NOT 演算子を使用すると、演算は OR アクションとして計算されます。たとえば、"New York" NOT "Seattle" を指定すると、Seattle 以外のすべての都市が返されます。If you retain the default, searchMode=any, and use a NOT operator, the operation is computed as an OR action, such that "New York" NOT "Seattle" returns all cities that are not Seattle.

ブール演算子 (AND、OR、NOT)Boolean operators (AND, OR, NOT)

テキスト ブール演算子 (AND、OR、NOT) は、常に大文字で指定します。Always specify text boolean operators (AND, OR, NOT) in all caps.

OR 演算子 OR または ||OR operator OR or ||

OR 演算子は、縦棒、つまりパイプ文字です。The OR operator is a vertical bar or pipe character. たとえば、wifi || luxury を指定すると、"wifi" または "luxury" (あるいはその両方) を含むドキュメントが検索されます。For example: wifi || luxury will search for documents containing either "wifi" or "luxury" or both. OR は、既定の結合演算子のため、除外することもできます。たとえば、wifi luxurywifi || luxuery と同等です。Because OR is the default conjunction operator, you could also leave it out, such that wifi luxury is the equivalent of wifi || luxuery.

AND 演算子 AND&&、または +AND operator AND, && or +

AND 演算子は、アンパサンドまたはプラス記号です。The AND operator is an ampersand or a plus sign. たとえば、wifi && luxury と指定すると、"wifi" と "luxury" の両方を含むドキュメントが検索されます。For example: wifi && luxury will search for documents containing both "wifi" and "luxury". プラス記号 (+) は、必要な用語に使用されます。The plus character (+) is used for required terms. たとえば、+wifi +luxury は、両方の用語が 1 つのドキュメントのフィールド内のどこかに表示されている必要があることを規定します。For example, +wifi +luxury stipulates that both terms must appear somewhere in the field of a single document.

NOT 演算子 NOT!、または -NOT operator NOT, ! or -

NOT 演算子は、感嘆符またはマイナス記号です。The NOT operator is an exclamation point or the minus sign. たとえば、wifi !luxury を指定すると、"wifi" という用語を含む、および/または"luxury" を含まないドキュメントが検索されます。For example: wifi !luxury will search for documents that have the "wifi" term and/or do not have "luxury". searchMode オプションは、+ 演算子または || 演算子が指定されていない場合、NOT 演算子を持つ用語で、クエリ内の他の用語との論理積または論理和をとるかどうかを制御します。The searchMode option controls whether a term with the NOT operator is ANDed or ORed with the other terms in the query in the absence of a + or || operator. searchMode は、any(既定値) または all のどちらにも設定できることを思い出してください。Recall that searchMode can be set to either any(default) or all.

searchMode=any を使用すると、より多くの結果を含めることによりクエリの再現率が増加し、既定で - は "OR NOT" と解釈されます。Using searchMode=any increases the recall of queries by including more results, and by default - will be interpreted as "OR NOT". たとえば、wifi -luxury は、wifi という用語を含むドキュメント、または luxury という用語を含まないドキュメントのどちらにも一致します。For example, wifi -luxury will match documents that either contain the term wifi or those that do not contain the term luxury.

searchMode=all を使用すると、より少ない結果を含めることによりクエリの精度が上がり、既定で - は "AND NOT" と解釈されます。Using searchMode=all increases the precision of queries by including fewer results, and by default - will be interpreted as "AND NOT". たとえば、wifi -luxury は、wifi という用語を含み、かつ luxury という用語を含まないドキュメントに一致します。For example, wifi -luxury will match documents that contain the term wifi and do not contain the term luxury. これはほぼ間違いなく、- 演算子にとってより直感的な動作です。This is arguably a more intuitive behavior for the - operator. したがって、再現率ではなく精度で検索を最適化する場合、そしてユーザーが検索で - 演算子を頻繁に使用する場合は、searchMode=any よりも searchMode=all を選択することを検討してください。Therefore, you should consider choosing searchMode=all over searchMode=any if you want to optimize searches for precision instead of recall and your users frequently use the - operator in searches.

クエリ サイズの制限Query size limitations

Azure Cognitive Search に送信できるクエリのサイズには制限があります。There is a limit to the size of queries that you can send to Azure Cognitive Search. 具体的には、最大で 1024 句 (AND、OR、その他で区切られた式) を持つことができます。Specifically, you can have at most 1024 clauses (expressions separated by AND, OR, and so on). クエリ内の個々の用語のサイズにも約 32 KB の制限があります。There is also a limit of approximately 32 KB on the size of any individual term in a query. アプリケーションがプログラムで検索クエリを生成する場合は、無制限のサイズのクエリが生成されないように設計することをお勧めします。If your application generates search queries programmatically, we recommend designing it in such a way that it does not generate queries of unbounded size.

ワイルドカード クエリと正規表現クエリのスコアリングScoring wildcard and regex queries

Azure Cognitive Search は、テキスト クエリで、頻度に基づいたスコアリング (TF-IDF) を使用します。Azure Cognitive Search uses frequency-based scoring (TF-IDF) for text queries. ただし、用語のスコープが広くなる可能性があるワイルドカード クエリと正規表現クエリでは、出現頻度が低い用語の一致に対する優先度付けに偏りが発生するのを避けるために、頻度の係数は無視されます。However, for wildcard and regex queries where scope of terms can potentially be broad, the frequency factor is ignored to prevent the ranking from biasing towards matches from rarer terms. すべての一致は、ワイルドカード検索と正規表現検索で同等に扱われます。All matches are treated equally for wildcard and regex searches.

フィールド検索Fielded search

fieldName:searchExpression 構文を使用して、フィールド検索操作を定義できます。検索式は、単一の単語、単一の語句、またはかっこで囲まれた複雑な式が可能であり、必要に応じてブール演算子も使用できますYou can define a fielded search operation with the fieldName:searchExpression syntax, where the search expression can be a single word or a phrase, or a more complex expression in parentheses, optionally with Boolean operators. たとえば、次のようになります。Some examples include the following:

  • genre:jazz NOT historygenre:jazz NOT history

  • artists:("Miles Davis" "John Coltrane")artists:("Miles Davis" "John Coltrane")

複数の文字列を 1 つのエンティティとして評価する場合は、必ず両方の文字列を引用符で囲んでください。この場合は、artists フィールドで 2 人の異なるアーティストを検索します。Be sure to put multiple strings within quotation marks if you want both strings to be evaluated as a single entity, in this case searching for two distinct artists in the artists field.

fieldName:searchExpression に指定されるフィールドは、searchable フィールドでなければなりません。The field specified in fieldName:searchExpression must be a searchable field. フィールド定義におけるインデックス属性の利用方法の詳細については、「インデックスの作成」を参照してください。See Create Index for details on how index attributes are used in field definitions.

注意

各フィールド検索式にはフィールド名が明示的に指定されるため、フィールド検索式を使用する際は searchFields パラメーターを使用する必要はありません。When using fielded search expressions, you do not need to use the searchFields parameter because each fielded search expression has a field name explicitly specified. ただし、いくつかの部分で特定のフィールドをスコープにし、他の部分は複数のフィールドに適用できるクエリを実行する場合は、searchFields パラメーターを引き続き使用できます。However, you can still use the searchFields parameter if you want to run a query where some parts are scoped to a specific field, and the rest could apply to several fields. たとえば、クエリ search=genre:jazz NOT history&searchFields=description は、genre フィールドの jazz のみと一致し、description フィールドの NOT history と一致します。For example, the query search=genre:jazz NOT history&searchFields=description would match jazz only to the genre field, while it would match NOT history with the description field. fieldName:searchExpression に指定されたフィールド名は常に searchFields パラメーターに優先するため、この例では searchFields パラメーターに genre を含める必要はありません。The field name provided in fieldName:searchExpression always takes precedence over the searchFields parameter, which is why in this example, we do not need to include genre in the searchFields parameter.

あいまい検索Fuzzy search

あいまい検索では、似たような構造の言い回しの一致が検索されます。A fuzzy search finds matches in terms that have a similar construction. Lucene ドキュメントによると、あいまい検索は Damerau-Levenshtein Distance を基盤としています。Per Lucene documentation, fuzzy searches are based on Damerau-Levenshtein Distance. あいまい検索では、距離の条件を満たす最大 50 個の用語まで用語を展開できます。Fuzzy searches can expand a term up to the maximum of 50 terms that meet the distance criteria.

あいまい検索を実行するには、1 つの単語の終わりにチルダ記号 "~" を使用し、編集距離を指定する任意のパラメーターである 0 から 2 (既定値) の値を指定します。To do a fuzzy search, use the tilde "~" symbol at the end of a single word with an optional parameter, a number between 0 and 2 (default), that specifies the edit distance. たとえば、"blue~" または "blue~1" を指定すると、"blue"、"blues"、および "glue" が返されます。For example, "blue~" or "blue~1" would return "blue", "blues", and "glue".

あいまい検索を適用できるのは用語だけであり、語句には適用できませんが、複数の部分から成る名前または語句の各用語に個別にチルダを追加できます。Fuzzy search can only be applied to terms, not phrases, but you can append the tilde to each term individually in a multi-part name or phrase. たとえば、"Unviersty~ of~ "Wshington~" は "University of Washington" と一致します。For example, "Unviersty~ of~ "Wshington~" would match on "University of Washington".

近接検索Proximity search

近接検索は、ある文書で互いに近くにある言葉を検索します。Proximity searches are used to find terms that are near each other in a document. 言葉の終わりにチルダ記号 "~" を挿入し、近接境界となる語数を続けます。Insert a tilde "~" symbol at the end of a phrase followed by the number of words that create the proximity boundary. たとえば、"hotel airport"~5 を指定すると、ドキュメント内で互いに 5 語以内にある "hotel" と "airport" という用語が検索されます。For example, "hotel airport"~5 will find the terms "hotel" and "airport" within 5 words of each other in a document.

用語ブーストTerm boosting

用語ブーストでは、指定用語を含む文書に含まない文書より高い順位が設定されます (ブーストされます)。Term boosting refers to ranking a document higher if it contains the boosted term, relative to documents that do not contain the term. これはスコアリング プロファイルとは違います。スコアリング プロファイルは、特定の用語ではなく、特定のフィールドをブーストします。This differs from scoring profiles in that scoring profiles boost certain fields, rather than specific terms.

次の例はその違いを示しています。The following example helps illustrate the differences. 特定のフィールドの一致をブーストするスコアリング プロファイルがあるとします。たとえば、musicstoreindex の例genre です。Suppose that there's a scoring profile that boosts matches in a certain field, say genre in the musicstoreindex example. 用語ブーストでは、特定の用語に他の用語より高い順位を与えます。Term boosting could be used to further boost certain search terms higher than others. たとえば、rock^2 electronic を指定すると、genre フィールドに検索用語を含むドキュメントに、インデックスの他の検索可能フィールドより高い順位が与えられます。For example, rock^2 electronic will boost documents that contain the search terms in the genre field higher than other searchable fields in the index. さらに、用語のブースト値 (2) の結果、rock という検索用語を含むドキュメントには、electronic というもう 1 つの用語よりも高い順位が与えられます。Further, documents that contain the search term rock will be ranked higher than the other search term electronic as a result of the term boost value (2).

用語をブーストするには、キャレット記号 "^" とブースト係数 (数字) を、検索する用語の終わりに使用します。To boost a term use the caret, "^", symbol with a boost factor (a number) at the end of the term you are searching. 語句をブーストすることもできます。You can also boost phrases. ブースト係数が高ければ高いほど、その語句の関連性が他の検索語句に比べて大きくなります。The higher the boost factor, the more relevant the term will be relative to other search terms. 既定のブースト係数は 1 です。By default, the boost factor is 1. ブースト係数は正数にする必要がありますが、1 未満 (0.20 など) の数字にすることができます。Although the boost factor must be positive, it can be less than 1 (for example, 0.20).

正規表現検索Regular expression search

正規表現検索では、スラッシュ "/" の間のコンテンツに基づいて一致が検索されます。RegExp クラスに詳細があります。A regular expression search finds a match based on the contents between forward slashes "/", as documented in the RegExp class.

たとえば、"motel" または "hotel" を含むドキュメントを検索するには、/[mh]otel/ を指定します。For example, to find documents containing "motel" or "hotel", specify /[mh]otel/. 正規表現検索では、単一の単語に対して照合が行われます。Regular expression searches are matched against single words.

ワイルドカード検索Wildcard search

複数 (*) または単数 (?) の文字のワイルドカード検索で、一般に認識されている構文を使用できます。You can use generally recognized syntax for multiple (*) or single (?) character wildcard searches. Lucene Query Parser では、これらの文字を語句ではなく 1 つの用語に利用することにご注意ください。Note the Lucene query parser supports the use of these symbols with a single term, and not a phrase.

たとえば、"note" のプレフィックスを持つ単語 ("notebook" や "notepad") を含むドキュメントを検索するには、"note*" と指定します。For example, to find documents containing the words with the prefix "note", such as "notebook" or "notepad", specify "note*".

注意

検索の最初の文字として * または ?You cannot use a * or ? を使用することはできません。symbol as the first character of a search.
ワイルドカード検索のクエリでは、テキスト分析は実行されません。No text analysis is performed on wildcard search queries. クエリ時、ワイルドカード クエリの用語は、検索インデックス内の分析済みの用語と比較されて、展開されます。At query time, wildcard query terms are compared against analyzed terms in the search index and expanded.

関連項目See also