Azure Cognitive Search でのクエリの種類と構成Query types and composition in Azure Cognitive Search

Azure Cognitive Search では、クエリにラウンドトリップ処理すべてが指定されます。In Azure Cognitive Search, a query is a full specification of a round-trip operation. 要求のパラメーターによって、インデックスでドキュメントを探すための一致条件、含めるまたは除外するフィールド、エンジンに渡される実行指示、応答を形成するための命令を指定します。Parameters on the request provide match criteria for finding documents in an index, which fields to include or exclude, execution instructions passed to the engine, and directives for shaping the response. 明示的に指定しなかった場合 (search=* とした場合) は、フルテキスト検索操作としてすべての検索可能フィールドを対象にクエリが実行され、スコア付けされていない結果セットが任意の順序で返されます。Unspecified (search=*), a query runs against all searchable fields as a full text search operation, returning an unscored result set in arbitrary order.

次の例は、REST API で構成された代表的なクエリです。The following example is a representative query constructed in the REST API. この例では、ホテルのデモ インデックスを対象とし、共通のパラメーターを使用しています。This example targets the hotels demo index and includes common parameters.

{
    "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"
}
  • 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 text but often accompanied by boolean operators. 1 つの用語を単独で指定すると、"用語" クエリです。Single standalone terms are term queries. 複数の部分を引用符で囲むと、"キー フレーズ" クエリです。Quote-enclosed multi-part queries are key phrase queries. search は search=* のように定義しないこともできますが、多くの場合は、この例のように、語、フレーズ、演算子で構成されます。Search can be undefined, as in search=*, but more likely consists of terms, phrases, and operators similar to what appears in the example.

  • searchFields は、クエリの実行を特定のフィールドに制限します。searchFields constrains query execution to specific fields. インデックス スキーマ内で "検索可能" の属性を持つフィールドは、このパラメーターの候補になります。Any field that is attributed as searchable in the index schema is a candidate for this parameter.

応答も、クエリに指定するパラメーターによって形成されます。Responses are also shaped by the parameters you include in the query. この例では、結果セットは select ステートメントに指定されたフィールドで構成されます。In the example, the result set consists of fields listed in the select statement. $select ステートメントでは、"取得可能" とマークされたフィールドのみを使用できます。Only fields marked as retrievable can be used in a $select statement. また、このクエリでは top の 10 件の ヒットのみが返されます。 count では、全体での一致するドキュメント数が示されます。この数は、返される件数よりも大きくなる可能性があります。Additionally, only the top 10 hits are returned in this query, while count tells you how many documents match overall, which can be more than what are returned. このクエリでは、行が評価順に降順で並べ替えられます。In this query, rows are sorted by Rating in descending order.

Azure Cognitive Search では、クエリ実行の対象となるのは常に、要求に含まれている API キーを使用して認証された 1 つのインデックスです。In Azure Cognitive Search, query execution is always against one index, authenticated using an api-key provided in the request. REST では、両方が要求ヘッダーに指定されます。In REST, both are provided in request headers.

このクエリを実行する方法How to run this query

このクエリを実行するには、Search エクスプローラーとホテルのデモ インデックスを使用します。To execute this query, use Search explorer and the hotels demo index.

次のクエリ文字列をエクスプローラーの検索バーに貼り付けます。search=+"New York" +restaurant&searchFields=Description, Address/City, Tags&$select=HotelId, HotelName, Description, Rating, Address/City, Tags&$top=10&$orderby=Rating desc&$count=trueYou can paste this query string into the explorer's search bar: search=+"New York" +restaurant&searchFields=Description, Address/City, Tags&$select=HotelId, HotelName, Description, Rating, Address/City, Tags&$top=10&$orderby=Rating desc&$count=true

インデックスによってクエリ操作が有効になる仕組みHow query operations are enabled by the index

Azure Cognitive Search では、インデックスの設計とクエリの設計は密接に関連しています。Index design and query design are tightly coupled in Azure Cognitive Search. 事前に知っておくべき基本的な事実は、各フィールドに属性が設定されたインデックス スキーマ によって、構築できるクエリの種類が決まるということです。An essential fact to know up front is that the index schema, with attributes on each field, determines the kind of query you can build.

フィールドのインデックス属性によって、許可される操作が設定されます。フィールドがインデックス内で "検索可能" か、結果に "取得可能" か、"ソート可能" か、"フィルター可能" かなどです。Index attributes on a field set the allowed operations - whether a field is searchable in the index, retrievable in results, sortable, filterable, and so forth. 例のクエリ文字列で "$orderby": "Rating" が処理されるのは、Rating フィールドがインデックス スキーマで "ソート可能" とマークされているためです。In the example query string, "$orderby": "Rating" only works because the Rating field is marked as sortable in the index schema.

ホテル サンプルのインデックス定義Index definition for the hotel sample

上記のスクリーンショットは、ホテル サンプルのインデックス属性の一覧の一部です。The above screenshot is a partial list of index attributes for the hotels sample. ポータルで、インデックススキーマ全体を確認できます。You can view the entire index schema in the portal. インデックス属性について詳しくは、インデックス作成 REST API に関するページをご覧ください。For more information about index attributes, see Create Index REST API.

注意

クエリの一部の機能は、インデックスの各フィールドではなくインデックス全体に基づいて有効化されます。Some query functionality is enabled index-wide rather than on a per-field basis. このような機能には、シノニム マップカスタム アナライザー提案機能による作成 (オートコンプリートおよび提案クエリ)結果を順位付けするためのスコアリング ロジックが含まれます。These capabilities include: synonym maps, custom analyzers, suggester constructs (for autocomplete and suggested queries), scoring logic for ranking results.

クエリ要求の要素Elements of a query request

クエリは常に 1 つのインデックスを対象とします。Queries are always directed at a single index. 複数のインデックスを結合したり、カスタム データ構造や一時的なデータ構造をクエリの対象にしたりすることはできません。You cannot join indexes or create custom or temporary data structures as a query target.

クエリ要求の必須要素には、次のコンポーネントが含まれます。Required elements on a query request include the following components:

  • サービス エンドポイントとインデックス ドキュメントのコレクション。固定コンポーネントとユーザー定義コンポーネントを含む URL として指定されます。 https://<your-service-name>.search.windows.net/indexes/<your-index-name>/docsService endpoint and index documents collection, expressed as a URL containing fixed and user-defined components: https://<your-service-name>.search.windows.net/indexes/<your-index-name>/docs
  • api-version (REST のみ) は必須です。常に複数の API バージョンが使用できるためです。api-version (REST only) is necessary because more than one version of the API is available at all times.
  • api-key (クエリまたは管理者の api-key) が、サービスへの要求を認証します。api-key, either a query or admin api-key, authenticates the request to your service.
  • queryType (simple または full)。組み込まれている既定の単純構文を使用する場合は省略できます。queryType, either simple or full, which can be omitted if you are using the built-in default simple syntax.
  • search または filter には一致条件を指定します。空の検索を実行する場合は、未指定にすることができます。search or filter provides the match criteria, which can be unspecified if you want to perform an empty search. クエリの 2 つの種類については単純なパーサーに関して説明していますが、高度なクエリでも複雑なクエリ式を渡すために search パラメーターが必要です。Both query types are discussed in terms of the simple parser, but even advanced queries require the search parameter for passing complex query expressions.

その他の検索パラメーターはすべて省略可能です。All other search parameters are optional. 属性の完全な一覧は、インデックス作成 (REST) に関するページをご覧ください。For the full list of attributes, see Create Index (REST). 処理中にパラメーターがどのように使用されるかについて詳しくは、Azure Cognitive Search のフルテキスト検索のしくみに関するページをご覧ください。For a closer look at how parameters are used during processing, see How full-text search works in Azure Cognitive Search.

API とツールの選択Choose APIs and tools

次の表は、API とツールを使ってクエリを送信する手法の一覧です。The following table lists the APIs and tool-based approaches for submitting queries.

手法Methodology 説明Description
Search エクスプローラー (ポータル)Search explorer (portal) 検索バーのほか、インデックスと API バージョンの選択に関するオプションが用意されています。Provides a search bar and options for index and api-version selections. 結果は JSON ドキュメントとして返されます。Results are returned as JSON documents. 探索、テスト、検証用に推奨されます。Recommended for exploration, testing, and validation.
詳細情報。Learn more.
Postman またはその他の REST ツールPostman or other REST tools Web テスト ツールは、REST 呼び出しを作成するための優れた選択肢です。Web testing tools are an excellent choice for formulating REST calls. REST API では、Azure Cognitive Search で利用可能なすべての操作をサポートします。The REST API supports every possible operation in Azure Cognitive Search. この記事では、Azure Cognitive Search に要求を送信するために HTTP 要求のヘッダーと本文を設定する方法について学習します。In this article, learn how to set up an HTTP request header and body for sending requests to Azure Cognitive Search.
SearchIndexClient (.NET)SearchIndexClient (.NET) Azure Cognitive Search のインデックスに対してクエリを実行するために使用できるクライアント。Client that can be used to query an Azure Cognitive Search index.
詳細情報。Learn more.
Search Documents (REST API)Search Documents (REST API) インデックスに対する GET メソッドまたは POST メソッド。追加の入力には、クエリ パラメーターを使用します。GET or POST methods on an index, using query parameters for additional input.

パーサーの選択: simple | fullChoose a parser: simple | full

Azure Cognitive Search は、Apache Lucene を基盤としており、一般的なクエリと特殊なクエリの処理用に 2 つのクエリ パーサーが用意されています。Azure Cognitive Search sits on top of Apache Lucene and gives you a choice between two query parsers for handling typical and specialized queries. 単純なパーサーを使用する要求は、単純なクエリ構文を使用して形成されます。これは自由な形式のテキスト クエリにおける処理速度と有効性のために既定として選択されます。Requests using the simple parser are formulated using the simple query syntax, selected as the default for its speed and effectiveness in free form text queries. この構文では、AND、OR、NOT、フレーズ、サフィックス、優先順位の演算子など、一般的な各種検索演算子がサポートされています。This syntax supports a number of common search operators including the AND, OR, NOT, phrase, suffix, and precedence operators.

完全な Lucene クエリ構文は、要求に queryType=full を追加することで有効になります。これは、Apache Lucene の一部として開発されたもので、広く採用されている表現性の高いクエリ言語です。The full Lucene query syntax, enabled when you add queryType=full to the request, exposes the widely adopted and expressive query language developed as part of Apache Lucene. 完全な構文は、単純な構文を拡張したものです。Full syntax extends the simple syntax. 単純な構文で記述するすべてのクエリは、完全な Lucene パーサーで実行できます。Any query you write for the simple syntax runs under the full Lucene parser.

次の例で示すのは、同じクエリでも、queryType 設定が異なると、異なる結果が生成されるということです。The following examples illustrate the point: same query, but with different queryType settings, yield different results. 最初のクエリでは、historic の後の ^3 が検索語句の一部として扱われます。In the first query, the ^3 after historic is treated as part of the search term. このクエリの最上位の結果は "Marquis Plaza & Suites" であり、その説明には ocean が含まれていますThe top-ranked result for this query is "Marquis Plaza & Suites", which has ocean in its description

queryType=simple&search=ocean historic^3&searchFields=Description, Tags&$select=HotelId, HotelName, Tags, Description&$count=true

完全な Lucene パーサーを使用した同じクエリでは、^3 がフィールド内の語句ブースターとして解釈されます。The same query using the full Lucene parser interprets ^3 as an in-field term booster. パーサーを切り替えると順位が変更され、historic という用語が含まれた結果が表示されます。Switching parsers changes the rank, with results containing the term historic moving to the top.

queryType=full&search=ocean historic^3&searchFields=Description, Tags&$select=HotelId, HotelName, Tags, Description&$count=true

クエリの種類Types of queries

Azure Cognitive Search では、幅広いクエリの種類がサポートされます。Azure Cognitive Search supports a broad range of query types.

クエリの種類Query type 使用法Usage 例と詳細Examples and more information
自由形式のテキスト検索Free form text search search パラメーターといずれかのパーサーSearch parameter and either parser フルテキスト検索は、インデックスのすべての "検索可能" フィールドで 1 つ以上の語句をスキャンし、Google や Bing などの検索エンジンに期待するのと同様に機能します。Full text search scans for one or more terms in all searchable fields in your index, and works the way you would expect a search engine like Google or Bing to work. 最初の例はフルテキスト検索です。The example in the introduction is full text search.

フルテキスト検索では、標準の Lucene アナライザーを使用したテキスト分析が行われ (既定)、すべての語句を小文字に変換し、"the" のようなストップワードを除去します。Full text search undergoes text analysis using the standard Lucene analyzer (by default) to lower-case all terms, remove stop words like "the". テキスト分析を変更する英語以外のアナライザー言語に関係なく使える特別なアナライザーを使用して、既定値をオーバーライドできます。You can override the default with non-English analyzers or specialized language-agnostic analyzers that modify text analysis. たとえば、フィールドの内容全体を 1 つのトークンとして扱う keyword です。An 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.
フィルター検索Filtered search OData フィルター式といずれかのパーサーOData filter expression and either parser フィルター クエリは、インデックスのすべての "フィルター処理可能" フィールドでブール式を評価します。Filter queries evaluate a boolean expression over all filterable fields in an index. 検索クエリと異なり、フィルター クエリはフィールドの内容を厳密に照合します。たとえば、文字列フィールドでは大文字と小文字が区別されます。Unlike search, a filter query matches the exact contents of a field, including case-sensitivity on string fields. もう 1 つの違いは、フィルター クエリは OData 構文で表されることです。Another difference is that filter queries are expressed in OData syntax.
フィルター式の例Filter expression example
地理空間検索Geo-search フィールドの Edm.GeographyPoint 型、フィルター式、いずれかのパーサーEdm.GeographyPoint type on the field, filter expression, and either parser Edm.GeographyPoint 型のフィールドに格納された座標が、"近くを探す" つまりマップに基づいた検索コントロールで使用されます。Coordinates stored in a field having an Edm.GeographyPoint are used for "find near me" or map-based search controls.
地理空間検索の例Geo-search example
範囲検索Range search フィルター式と単純なパーサーfilter expression and simple parser Azure Cognitive Search では、範囲クエリは filter パラメーターを使用して作成されます。In Azure Cognitive Search, range queries are built using the filter parameter.
範囲フィルターの例Range filter example
フィールド検索Fielded search search パラメーターと完全なパーサーSearch parameter and Full parser 1 つのフィールドを対象とする複合クエリ式を作成します。Build a composite query expression targeting a single field.
フィールド検索の例Fielded search example
あいまい検索fuzzy search search パラメーターと完全なパーサーSearch parameter and Full parser 構造やスペリングが似ている語句を照合します。Matches on terms having a similar construction or spelling.
あいまい検索の例Fuzzy search example
近接検索proximity search search パラメーターと完全なパーサーSearch parameter and Full parser ドキュメント内で近くにある語句を検索します。Finds terms that are near each other in a document.
近接検索の例Proximity search example
用語ブーストterm boosting search パラメーターと完全なパーサーSearch parameter and Full parser ブーストされた語を含むドキュメントの順位を、含まないドキュメントよりも引き上げます。Ranks a document higher if it contains the boosted term, relative to others that don't.
用語ブーストの例Term boosting example
正規表現検索regular expression search search パラメーターと完全なパーサーSearch parameter and Full parser 正規表現の内容に基づいて照合します。Matches based on the contents of a regular expression.
正規表現の例Regular expression example
ワイルドカードまたはプレフィックス検索wildcard or prefix search search パラメーターと完全なパーサーSearch parameter and Full parser プレフィックスとチルダ (~) または 1 つの文字 (?) に基づいて照合します。Matches based on a prefix and tilde (~) or single character (?).
ワイルドカード検索の例Wildcard search example

検索結果の管理Manage search results

クエリの結果は、REST API では JSON ドキュメントとしてストリーム配信されますが、.NET の API を使用する場合は、ビルトインのシリアル化が適用されます。Query results are streamed as JSON documents in the REST API, although if you use .NET APIs, serialization is built in. 検索結果は、クエリでパラメーターを設定し、応答に使用するフィールドを明示的に選択することで加工することができます。You can shape results by setting parameters on the query, selecting specific fields for the response.

クエリにパラメーターを使うことで、次のような方法で結果セットの構造を指定できます。Parameters on the query can be used to structure the result set in the following ways:

  • 結果に含めるドキュメント数を制限またはグループ化する (既定では 50 件)Limiting or batching the number of documents in the results (50 by default)
  • 結果に含めるフィールドを選択するSelecting fields to include in the results
  • 並べ替え順を設定するSetting a sort order
  • 検索語句強調表示を追加して、検索結果の本文中で一致した語句を目立たせるAdding hit highlights to draw attention to matching terms in the body of the search results

予期しない結果が生じた場合のヒントTips for unexpected results

結果の実質 (構造ではなく実質的な中身) が、予期しない内容になっている場合も少なくありません。Occasionally, the substance and not the structure of results are unexpected. クエリの結果が想定と異なる場合は、次のような変更をクエリに加えて、結果が改善されるかどうかを試してみてください。When query outcomes are not what you expect to see, you can try these query modifications to see if results improve:

  • searchMode=any (既定) を searchMode=all に変更し、いずれかの条件への一致ではなく、すべての条件への一致を強制します。Change searchMode=any (default) to searchMode=all to require matches on all criteria instead of any of the criteria. これは特に、ブール演算子がクエリに含まれているときに当てはまります。This is especially true when boolean operators are included the query.

  • テキスト解析または字句解析が必要であるものの、クエリの種類が言語処理の妨げになっている場合は、クエリ手法を変更します。Change the query technique if text or lexical analysis is necessary, but the query type precludes linguistic processing. フルテキスト検索では、スペル ミスや単語の単数形と複数形、不規則動詞、不規則名詞までもが、テキスト解析または字句解析によって自動的に修正されます。In full text search, text or lexical analysis autocorrects for spelling errors, singular-plural word forms, and even irregular verbs or nouns. ファジー検索やワイルドカード検索など、一部のクエリでは、クエリ解析パイプラインの過程でテキスト解析が行われません。For some queries such as fuzzy or wildcard search, text analysis is not part of the query parsing pipeline. シナリオによっては、従来より正規表現が回避策として使用されています。For some scenarios, regular expressions have been used as a workaround.

ページングの結果Paging results

Azure Cognitive Search では、検索結果のページングを簡単に実装できます。Azure Cognitive Search makes it easy to implement paging of search results. top および skip パラメーターを使用すると、管理しやすい並べ替えられたサブセットとして検索結果一式を取得できるようにする検索要求をスムーズに発行できます。また、このような検索結果により、検索 UI の利便性を簡単に高めることができます。By using the top and skip parameters, you can smoothly issue search requests that allow you to receive the total set of search results in manageable, ordered subsets that easily enable good search UI practices. こうした結果の少数のサブセットを取得する際には、検索結果一式に含まれるドキュメントの数を取得することもできます。When receiving these smaller subsets of results, you can also receive the count of documents in the total set of search results.

検索結果のページングの詳細については、Azure Cognitive Search での検索結果のページング方法に関する記事をご覧ください。You can learn more about paging search results in the article How to page search results in Azure Cognitive Search.

結果の並べ替えOrdering results

検索クエリに対する結果を受け取るときに、Azure Cognitive Search から指定のフィールドの値に基づいて並べ替えられた結果が返されるように要求することができます。When receiving results for a search query, you can request that Azure Cognitive Search serves the results ordered by values in a specific field. 既定では、Azure Cognitive Search では、TF-IDF から派生する各ドキュメントの検索スコアのランクに基づいて検索結果を並べ替えます。By default, Azure Cognitive Search orders the search results based on the rank of each document's search score, which is derived from TF-IDF.

検索スコア以外の値に基づいて並べ替えられた結果が Azure Cognitive Search から返されるようにするには、 orderby 検索パラメーターを使います。If you want Azure Cognitive Search to return your results ordered by a value other than the search score, you can use the orderby search parameter. フィールド名を含める orderby パラメーターの値と、地理空間値の geo.distance() 関数の呼び出しを指定できます。You can specify the value of the orderby parameter to include field names and calls to the geo.distance() function for geospatial values. 結果を昇順で要求する場合は各式の後に asc を指定し、降順で要求する場合は desc を指定します。Each expression can be followed by asc to indicate that results are requested in ascending order, and desc to indicate that results are requested in descending order. 既定のランクは昇順です。The default ranking ascending order.

検索結果の強調表示Hit highlighting

Azure Cognitive Search では、検索クエリに一致する検索結果の特定の部分を正確に強調表示できます。これは、 highlighthighlightPreTaghighlightPostTag の各パラメーターを使用して簡単に行えます。In Azure Cognitive Search, emphasizing the exact portion of search results that match the search query is made easy by using the highlight, highlightPreTag, and highlightPostTag parameters. 一致するテキストを強調表示する検索可能フィールドを指定できるほか、Azure Cognitive Search から返される一致テキストの先頭と末尾に追加する文字列タグを正確に指定することもできます。You can specify which searchable fields should have their matched text emphasized as well as specifying the exact string tags to append to the start and end of the matched text that Azure Cognitive Search returns.

関連項目See also