Azure Cognitive Search でのクエリの作成

クエリを初めて作成する場合、この記事では要求を設定するためのアプローチとメソッドについて説明します。 また、クエリ構造の概要を示し、フィールド属性と言語アナライザーによってクエリ結果がどのような影響を受けるかについても説明します。

クエリ要求とは

クエリとは、単一の検索インデックスのドキュメント コレクションに対する読み取り専用の要求です。 ここでは、'Search' パラメーターを指定します。また、語句、引用符で囲まれたフレーズ、および演算子で構成されたクエリ式が含まれます。

要求で追加のパラメーターを使用すると、クエリと応答をより詳細に定義することができます。 たとえば、'searchFields' では特定のフィールドに対してクエリを実行します。'select' では結果で返されるフィールドを指定し、'count' ではインデックス内で見つかった一致の数を返します。

次の例では、使用可能ないくつかのパラメーターを示すことにより、クエリ要求の一般的な概念を示します。 クエリの構成の詳細については、クエリの種類と構成およびドキュメントの検索 (REST) に関する記事を参照してください。

POST https://[service name].search.windows.net/indexes/hotels-sample-index/docs/search?api-version=2020-06-30
{
    "search": "NY +view",
    "queryType": "simple",
    "searchMode": "all",
    "searchFields": "HotelName, Description, Address/City, Address/StateProvince, Tags",
    "select": "HotelName, Description, Address/City, Address/StateProvince, Tags",
    "count": "true"
}

クライアントを選択する

Azure portal や Postman などのツール、または API を使用してクエリ クライアントをインスタンス化するコードが必要です。 早期の開発と概念実証のテストには、Azure portal または REST API をお勧めします。

アクセス許可

クエリ要求には、ヘッダーで渡された API キーを使用して許可される読み取りアクセス許可が必要です。 クエリ要求を含むすべての操作は管理 API キーで動作しますが、クエリ要求は必要に応じてクエリ API キーを使用できます。 クエリ API キーを強くお勧めします。 サービスあたり最大 50 個作成でき、アプリケーションごとに異なるキーを割り当てることができます。

Azure portal では、ツール、ウィザード、およびオブジェクトへのアクセスには、サービスに対する共同作成者ロール以上のメンバーシップが必要です。

Azure portal を使用してインデックスに対してクエリを実行する

検索エクスプローラー (ポータル) は、Azure portal のクエリ インターフェイスで、基になる検索サービスでインデックスに対してクエリを実行します。 内部的には、ポータルはドキュメントの検索要求を行いますが、オートコンプリート、提案、またはドキュメント検索を呼び出すことはできません。

プレビューを含む、任意のインデックスと REST API バージョンを選択できます。 クエリ文字列では、すべてのクエリ パラメーター (filter、select、searchFields など) をサポートする単純な構文または完全な構文を使用できます。 ポータルでは、インデックスを開くと、フィールド属性に簡単にアクセスできるように、横に並んだタブでインデックス JSON 定義と共に検索エクスプローラーを操作できます。 クエリのテスト中に、検索可能、並べ替え可能、フィルター可能、およびファセット可能の各フィールドを確認します。

REST クライアントを使用する

Postman と Visual Studio Code (Azure Cognitive Search 用の拡張機能を備えているもの) はどちらも、クエリ クライアントとして機能できます。 どちらのツールを使用しても、検索サービスに接続し、ドキュメントの検索 (REST) 要求を送信できます。 インデックスに対するクエリの実行のための REST クライアントを示すチュートリアルと例が多数提供されています。

各クライアントの詳細については、最初にこれらのいずれかの記事を参照してください (どちらにもクエリの説明が含まれています)。

各要求はスタンドアロンであるため、要求ごとにエンドポイント、インデックス名、および API バージョンを指定する必要があります。 その他のプロパティ、Content-Type、API キーは、要求ヘッダーで渡されます。 詳細については、ドキュメントの検索 (REST) に関する記事で、クエリ要求の作成について参照してください。

SDK を使用する

Cognitive Search の場合、一般公開される機能は Azure SDK によって実装されています。 そのため、いずれかの SDK を使用してインデックスに対するクエリを実行できます。 これらのすべてには、ドキュメントの検索を使用したインデックスの読み込みから、クエリ要求の作成に至るまでの、インデックスと対話するためのメソッドを持つ SearchClient が用意されています。

Azure SDK Client
.NET SearchClient DotNetHowTo
Java SearchClient SearchForDynamicDocumentsExample.java
JavaScript SearchClient 保留中
Python SearchClient sample_simple_query.py

クエリの種類を選択する: simple | full

クエリがフルテキスト検索の場合、検索語句やフレーズとして渡されたテキストを処理するためにクエリ パーサーが使用されます。 Azure Cognitive Search には、2 つのクエリ パーサーが用意されています。

  • 単純なパーサーは、単純なクエリ構文を認識します。 このパーサーは、自由形式のテキスト クエリの速度と有効性により既定で選択されています。 この構文では、用語検索と語句検索に共通の検索演算子 (AND、OR、NOT) とプレフィックス (*) 検索をサポートしています (Seattle や Seaside に対する "sea*" など)。 一般的には、最初に単純なパーサーを試してから、アプリケーションの要件でより強力なクエリが必要になる場合に完全なパーサーに移行することをお勧めします。

  • 完全な Lucene クエリ構文は、 を要求に追加したときに有効になり、Apache Lucene パーサーに基づいています。

完全な構文と単純な構文は、両方が同じプレフィックスとブール演算をサポートしているという点で重複しますが、完全な構文のほうがより多くの演算子を用意しています。 完全では、ブール式の演算子や、あいまい検索、ワイルドカード検索、近接検索、正規表現などの高度なクエリ用の演算子が多数用意されています。

クエリ メソッドを選択する

検索は基本的にユーザー主導の動作であり、検索ボックスから、またはページでのクリック イベントから、用語や語句が収集されます。 次の表は、予想される検索エクスペリエンスと共にユーザー入力を収集するためのメカニズムをまとめたものです。

入力 エクスペリエンス
検索メソッド ユーザーは、演算子の有無にかかわらず検索ボックスに用語または語句を入力し、[検索] をクリックして要求を送信します。 検索は同じ要求でフィルターと共に使用できますが、オートコンプリートや提案と共には使用できません。
オートコンプリート メソッド ユーザーがいくつかの文字を入力すると、新しい文字が入力されるたびにクエリが開始されます。 応答は、インデックスからの完成した文字列になります。 指定された文字列が有効な場合、ユーザーは [検索] をクリックしてそのクエリをサービスに送信します。
提案メソッド オートコンプリートと同様に、ユーザーがいくつかの文字を入力すると、増分クエリが生成されます。 応答は一致したドキュメントのドロップダウン リストであり、通常はいくつかの一意または説明のフィールドで表されます。 いずれかの選択が有効な場合、ユーザーが 1 つをクリックすると、一致したドキュメントが返されます。
ファセット ナビゲーション ページには、クリック可能なナビゲーション リンクまたは階層リンクが表示され、検索範囲を絞り込むことができます。 ファセット ナビゲーション構造は、初期クエリに基づいて動的に構成されます。 たとえば、search=* は、可能なすべてのカテゴリから構成されるファセット ナビゲーション ツリーを設定します。 ファセット ナビゲーション構造はクエリ応答から作成されますが、次のクエリを表現するためのメカニズムでもあります。 REST API リファレンスでは、facets は、ドキュメントの検索操作のクエリ パラメーターとして記述されていますが、search パラメーターを指定せずに使用できます。
フィルター メソッド フィルターは、結果を絞り込むためにファセットと共に使用されます。 また、ページの背後にフィルターを実装することもでき、たとえば、言語固有のフィールドでページを初期化することができます。 REST API リファレンスでは、$filter はドキュメントの検索操作のクエリ パラメーターとして記述されていますが、search パラメーターを指定せずに使用できます。

クエリでのフィールド属性の影響

クエリの種類と構成に詳しい場合、クエリ要求のパラメーターはインデックスのフィールド属性に依存することをご存じかもしれません。 たとえば、"検索可能""取得可能" のマークが付いているフィールドのみクエリと検索結果で使用できます。 要求で searchfilterorderby パラメーターを設定するとき、予想外の結果を避けるため、属性を確認してください。

ホテルのサンプル インデックスの下にあるポータルのスクリーンショットでは、 だけの句で使用できるのは、"LastRenovationDate" と "Rating" の最後の 2 つのフィールドだけです。

Index definition for the hotel sample

フィールド属性の定義については、「Create Index (REST API)」を参照してください。

クエリに対するトークンの影響

インデックス作成中、検索エンジンでは、文字列にテキスト アナライザーを使用し、クエリ時に一致を見つける可能性を最大化します。 少なくとも文字列は小文字に変換されますが、アナライザーによっては、レンマ化とストップ ワードの削除も行われる可能性があります。 通常、長い文字列や複合語は、空白、ハイフン、またはダッシュによって分割され、個別のトークンとしてインデックスが付けられます。

ここでの要点は、インデックスに含まれていると思われることと、実際に含まれていることは異なる場合があるということです。 クエリで予想された結果が返されない場合は、分析テキスト (REST API) を通じてアナライザーによって作成されたトークンを検査できます。 トークン化とクエリへの影響の詳細については、「部分的な用語検索と特殊文字を含むパターン」をご覧ください。

次のステップ

これで、クエリ要求のしくみについての理解が深まったので、次のクイックスタートで実際に体験してみてください。