Azure Cognitive Search のクエリQuerying in Azure Cognitive Search

Azure Cognitive Search には、フリー テキスト検索から高度に指定されたクエリ パターンまで、さまざまなシナリオをサポートする豊富なクエリ言語が用意されています。Azure Cognitive Search offers a rich query language to support a broad range of scenarios, from free text search, to highly-specified query patterns. この記事では、クエリ要求と、作成できるクエリの種類について説明します。This article describes query requests, and what kinds of queries you can create.

Cognitive Search では、クエリには、ラウンド トリップ search 操作がすべて指定されており、クエリの実行を通知し、返される応答を整形するパラメーターが含まれています。In Cognitive Search, a query is a full specification of a round-trip search operation, with parameters that both inform query execution and shape the response coming back. パラメーターとパーサーによって、クエリ要求の種類が決まります。Parameters and parsers determine the type of query request. 次のクエリ例は、ブール演算子を使用したフリー テキスト クエリであり、ドキュメントの検索 (REST API) を使用し、hotels-sample-index ドキュメント コレクションを対象としています。The following query example is a free text query with a boolean operator, using the Search Documents (REST API), targeting the hotels-sample-index documents collection.

POST https://[service name].search.windows.net/indexes/hotels-sample-index/docs/search?api-version=2020-06-30
{
    "queryType": "simple"
    "search": "`New York` +restaurant",
    "searchFields": "Description, Address/City, Tags",
    "select": "HotelId, HotelName, Description, Rating, Address/City, Tags",
    "top": "10",
    "count": "true",
    "orderby": "Rating desc"
}

クエリの実行時に使用されるパラメーターは次のとおりです。Parameters used during query execution include:

  • queryType にはパーサーを設定します。設定できるのは、既定の単純なクエリ パーサー (フル テキスト検索に最適) または、正規表現、近接検索、ファジー検索、ワイルドカード検索など高度なクエリ構成で使用される 完全な Lucene クエリ パーサーです。queryType sets the parser, which is either the default simple query parser (optimal for full text search), or the full Lucene query parser used for advanced query constructs like regular expressions, proximity search, fuzzy and wildcard search, to name a few.

  • search には一致条件を指定します。通常は用語全体またはフレーズですが、演算子が伴う場合も伴わない場合もあります。search provides the match criteria, usually whole terms or phrases, with or without operators. インデックス スキーマ内で "検索可能" の属性を持つフィールドは、このパラメーターの候補になります。Any field that is attributed as searchable in the index schema is a candidate for this parameter.

  • searchFields は、クエリの実行を特定の検索可能なフィールドに制限します。searchFields constrains query execution to specific searchable fields.

応答を形成するために使用するパラメーター:Parameters used to shape the response:

  • select : 応答で返すフィールドを指定します。select specifies which fields to return in the response. select ステートメントでは、インデックスで "取得可能" とマークされたフィールドのみを使用できます。Only fields marked as retrievable in the index can be used in a select statement.

  • top : 指定した数の最もよく一致するドキュメントを返します。top returns the specified number of best-matching documents. この例では、10 個のヒットのみが返されます。In this example, only 10 hits are returned. top と skip (ここには非表示) を使用して、結果のページを移動することができます。You can use top and skip (not shown) to page the results.

  • count : すべてのインデックス全体で一致するドキュメントの数を示します。これは、返されるものよりも大きくなる可能性があります。count tells you how many documents in the entire index match overall, which can be more than what are returned.

  • orderby : 評価や場所などの値によって結果を並べ替える場合に使用します。orderby is used if you want to sort results by a value, such as a rating or location. それ以外の場合、既定では、関連性スコアを使用して結果が順位付けされます。Otherwise, the default is to use the relevance score to rank results. このパラメーターの候補とするために、このフィールドには 並べ替え可能 の属性を付ける必要があります。A field must be attributed as sortable to be a candidate for this parameter.

上記の一覧は代表ですが、完全ではありません。The above list is representative but not exhaustive. クエリ要求のパラメーターの完全な一覧については、「ドキュメントの検索 (REST API)」をご覧ください。For the full list of parameters on a query request, see Search Documents (REST API).

クエリの種類Types of queries

いくつかの例外はありますが、クエリ要求では、任意の数の検索ドキュメント内で高速スキャンできるように構造化された逆インデックスを反復処理します。この場合、すべてのフィールドで一致が見つかる可能性があります。With a few notable exceptions, a query request iterates over inverted indexes that are structured for fast scans, where a match can be found in potentially any field, within any number of search documents. Cognitive Search では、一致を検索するための主要な方法として、フルテキスト検索やフィルターがありますが、オートコンプリートや地理的な位置検索など、その他のよく知られた検索エクスペリエンスを実装することもできます。In Cognitive Search, the primary methodology for finding matches is either full text search or filters, but you can also implement other well-known search experiences like autocomplete, or geo-location search. この記事の残りの部分では、Cognitive Search のクエリをまとめ、詳細情報と例へのリンクを示します。The rest of this article summarizes queries in Cognitive Search and provides links to more information and examples.

用語入力を収集する検索ボックスが検索アプリに含まれている場合、フルテキスト検索が、おそらくそのエクスペリエンスをサポートするクエリ操作になります。If your search app includes a search box that collects term inputs, then full text search is probably the query operation backing that experience. フルテキスト検索では、インデックス内の検索可能な すべての 検索可能な フィールドの search パラメーターに渡された用語または語句を使用できます。Full text search accepts terms or phrases passed in a search parameter in all searchable fields in your index. クエリ文字列内の省略可能なブール演算子は、一致条件または例外条件を指定できます。Optional boolean operators in the query string can specify inclusion or exclusion criteria. 単純なパーサーと完全なパーサーは、いずれもフルテキスト検索をサポートしています。Both the simple parser and full parser support full text search.

Cognitive Search では、フルテキスト検索は Apache Lucene クエリ エンジン上に構築されています。In Cognitive Search, full text search is built on the Apache Lucene query engine. フルテキスト検索のクエリ文字列は、字句解析を使用してスキャンを効率化します。Query strings in full text search undergo lexical analysis to make scans more efficient. 解析には、すべての用語の小文字化、"the" などのストップ ワードの削除、プリミティブな原形への用語の単純化が含まれます。Analysis includes lower-casing all terms, removing stop words like "the", and reducing terms to primitive root forms. 標準のアナライザーは Standard Lucene です。The default analyzer is Standard Lucene.

一致する用語が見つかった場合、クエリ エンジンは、ドキュメント キーまたは ID を使用してフィールド値をアセンブルする一致を含む検索ドキュメントを再構築し、ドキュメントを関連性の順にランク付けし、応答の上位 50 (既定) を返すか、 top を指定した場合は別の番号を返します。When matching terms are found, the query engine reconstitutes a search document containing the match using the document key or ID to assemble field values, ranks the documents in order of relevance, and returns the top 50 (by default) in the response or a different number if you specified top.

フルテキスト検索を実装している場合は、コンテンツがトークン化される方法を理解すると、クエリの異常のデバッグに役立ちます。If you're implementing full text search, understanding how your content is tokenized will help you debug any query anomalies. ハイフンでつながれた文字列または特殊文字に対するクエリでは、既定の Standard Lucene 以外のアナライザーを使用してインデックスに正しいトークンが含まれていることを確認することが必要になります。Queries over hyphenated strings or special characters could necessitate using an analyzer other than the default standard Lucene to ensure the index contains the right tokens. 既定値をオーバーライドして、言語アナライザーや、字句解析を変更する特別なアナライザーを使用できます。You can override the default with language analyzers or specialized analyzers that modify lexical analysis. たとえば、フィールドの内容全体を 1 つのトークンとして扱う keyword です。One example is keyword that treats the entire contents of a field as a single token. これは、郵便番号、ID、製品名などのデータで役立ちます。This is useful for data like zip codes, IDs, and some product names. 詳細については、「部分的な用語検索と特殊文字を含むパターン」をご覧ください。For more information, see Partial term search and patterns with special characters.

大きなテキスト ブロック (コンテンツ フィールドや長い説明) が含まれているインデックスでブール演算子が頻繁な使用されることが多いですが、これが予想される場合は、 searchMode=Any|All パラメーターを使用してクエリをテストし、その設定がブール検索に与える影響を評価してください。If you anticipate heavy use of Boolean operators, which is more likely in indexes that contain large text blocks (a content field or long descriptions), be sure to test queries with the searchMode=Any|All parameter to evaluate the impact of that setting on boolean search.

オートコンプリートとクエリ候補Autocomplete and suggested queries

オートコンプリートや結果候補は、逐次検索エクスペリエンスでの部分文字列入力に基づいて連続するクエリ要求を実行する search に代わる代替手段です。Autocomplete or suggested results are alternatives to search that fire successive query requests based on partial string inputs (after each character) in a search-as-you-type experience. このチュートリアルで説明しているように、 autocompletesuggestions パラメーターは一緒に使用することも、個別に使用することもできますが、 search と一緒に使用することはできません。You can use autocomplete and suggestions parameter together or separately, as described in this tutorial, but you cannot use them with search. 完成した用語とクエリ候補はどちらもインデックスの内容から派生されます。Both completed terms and suggested queries are derived from index contents. このエンジンは、インデックスに存在しない文字列や候補を返しません。The engine will never return a string or suggestion that is non-existent in your index. 詳細については、「オートコンプリート (REST API)」と「検索候補 (REST API)」をご覧ください。For more information, see Autocomplete (REST API) and Suggestions (REST API).

フィルターは、Cognitive Search を含むアプリで広く使用されています。Filters are widely used in apps that include Cognitive Search. アプリケーション ページでは、フィルターは多くの場合、ユーザー向けのフィルター処理のためにリンク ナビゲーション構造のファセットとして視覚化されます。On application pages, filters are often visualized as facets in link navigation structures for user-directed filtering. フィルターは、インデックス付きコンテンツのスライスを公開するために、内部的にも使用されます。Filters are also used internally to expose slices of indexed content. たとえば、製品カテゴリに対してフィルターを使用して検索ページを初期化したり、インデックスに英語とフランス語の両方のフィールドが含まれている場合は、言語を初期化したりすることができます。For example, you might initialize a search page using a filter on a product category, or a language if an index contains fields in both English and French.

次の表に示すように、特殊なクエリ フォームを呼び出すフィルターが必要な場合もあります。You might also need filters to invoke a specialized query form, as described in the following table. 指定されていない検索 ( search=* ) を含むフィルターを使用することも、用語、語句、演算子、およびパターンを含むクエリ文字列を含むフィルターを使用することもできます。You can use a filter with an unspecified search (search=*) or with a query string that includes terms, phrases, operators, and patterns.

ユーザー シナリオFilter scenario 説明Description
範囲フィルターRange filters Azure Cognitive Search では、範囲クエリは filter パラメーターを使用して作成されます。In Azure Cognitive Search, range queries are built using the filter parameter. 詳細と例については、「範囲フィルターの例」をご覧ください。For more information and examples, see Range filter example.
地理的な位置の検索Geo-location search 検索可能なフィールドが Edm.GeographyPoint 型の場合は、"近くを検索" またはマップに基づいた検索コントロールのフィルター式を作成できます。If a searchable field is of Edm.GeographyPoint type, you can create a filter expression for "find near me" or map-based search controls. 地理空間検索を操作するフィールドには座標が含まれます。Fields that drive geo-search contain coordinates. 詳細および例については、「地理空間検索の例」をご覧ください。For more information and an example, see Geo-search example.
ファセット ナビゲーションFaceted navigation ファセット ナビゲーション構造は、ファセットでの onclick イベントに応答してフィルターを呼び出するときに、ユーザー向けのナビゲーションに役立ちます。A facet navigation structure becomes instrumental in user-directed navigation when you invoke a filter in response to an onclick event on a facet. そのため、ファセットとフィルターは連携しています。As such, facets and filters go hand-in-hand. ファセット ナビゲーションを追加する場合は、エクスペリエンスを完了するためのフィルターが必要です。If you add facet navigation, you will need filters to complete the experience. 詳細については、ファセット フィルターの作成方法に関するページをご覧ください。For more information, see How to build a facet filter.

注意

フィルター式で使用されるテキストは、クエリ処理中には分析されません。Text that's used in a filter expression is not analyzed during query processing. テキスト入力は、照合に成功するか失敗するかのどちらかになる逐語的な文字パターンで、大文字と小文字が区別されます。The text input is presumed to be a verbatim case-sensitive character pattern that either succeeds or fails on the match. フィルター式は OData 構文を使用して構築され、インデックス内のすべての フィルター可能な フィールドの filter パラメーターで渡されます。Filter expressions are constructed using OData syntax and passed in a filter parameter in all filterable fields in your index. 詳細については、「Azure Cognitive Search のフィルター」をご覧ください。For more information, see Filters in Azure Cognitive Search.

ドキュメントの検索Document look-up

前述のクエリ フォームとは対照的に、このフォームでは、対応するインデックス検索またはスキャンを行わずに、ID による検索ドキュメントを 1 つ取得します。In contrast with the previously described query forms, this one retrieves a single search document by ID, with no corresponding index search or scan. 1 つのドキュメントのみが要求され、返されます。Only the one document is requested and returned. ユーザーが検索結果で項目を選択する場合、ドキュメントの取得と詳細ページでのフィールドの設定が典型的な応答になり、ドキュメントの検索はこれをサポートする操作になります。When a user selects an item in search results, retrieving the document and populating a details page with fields is a typical response, and a document look-up is the operation that supports it.

高度な検索: あいまい、ワイルドカード、近接、正規表現Advanced search: fuzzy, wildcard, proximity, regex

高度なクエリ フォームは、特定のクエリ動作をトリガーする完全な Lucene パーサーと演算子に依存します。An advanced query form depends on the Full Lucene parser and operators that trigger a specific query behavior.

クエリの種類Query type 使用法Usage 例と詳細Examples and more information
フィールド検索Fielded search search パラメーター、 queryType=fullsearch parameter, queryType=full 1 つのフィールドを対象とする複合クエリ式を作成します。Build a composite query expression targeting a single field.
フィールド検索の例Fielded search example
あいまい検索fuzzy search search パラメーター、 queryType=fullsearch parameter, queryType=full 構造やスペリングが似ている語句を照合します。Matches on terms having a similar construction or spelling.
あいまい検索の例Fuzzy search example
近接検索proximity search search パラメーター、 queryType=fullsearch parameter, queryType=full ドキュメント内で近くにある語句を検索します。Finds terms that are near each other in a document.
近接検索の例Proximity search example
用語ブーストterm boosting search パラメーター、 queryType=fullsearch parameter, queryType=full ブーストされた語を含むドキュメントの順位を、含まないドキュメントよりも引き上げます。Ranks a document higher if it contains the boosted term, relative to others that don't.
用語ブーストの例Term boosting example
正規表現検索regular expression search search パラメーター、 queryType=fullsearch parameter, queryType=full 正規表現の内容に基づいて照合します。Matches based on the contents of a regular expression.
正規表現の例Regular expression example
ワイルドカードまたはプレフィックス検索wildcard or prefix search *~ または ? を使用した search パラメーター、 queryType=fullsearch parameter with *~ or ?, queryType=full プレフィックスとチルダ (~) または 1 つの文字 (?) に基づいて照合します。Matches based on a prefix and tilde (~) or single character (?).
ワイルドカード検索の例Wildcard search example

次の手順Next steps

クエリの実装について詳しく見るには、構文ごとに例を確認します。For a closer look at query implementation, review the examples for each syntax. フルテキスト検索を初めて使用する場合は、クエリ エンジンの機能をよく理解しておくことをお勧めします。If you are new to full text search, a closer look at what the query engine does might be an equally good choice.