Azure Search のシノニム (プレビュー)Synonyms in Azure Search (preview)

検索エンジンのシノニムは、ユーザーが実際に用語を提供する必要がなく、クエリのスコープを暗黙的に拡張する同等の用語を関連付けます。Synonyms in search engines associate equivalent terms that implicitly expand the scope of a query, without the user having to actually provide the term. たとえば、用語 "dog" と、"canine" と "puppy" のシノニムの関連付けを指定すると、"dog"、"canine"、または "puppy" を含むすべてのドキュメントがクエリのスコープ内に収まります。For example, given the term "dog" and synonym associations of "canine" and "puppy", any documents containing "dog", "canine" or "puppy" will fall within the scope of the query.

Azure Search では、シノニムの拡張は、クエリ時に行われます。In Azure Search, synonym expansion is done at query time. 既存の処理を停止させることなく、シノニム マップをサービスに追加できます。You can add synonym maps to a service with no disruption to existing operations. インデックスを再構築する必要なく、synonymMaps プロパティをフィールド定義に追加できます。You can add a synonymMaps property to a field definition without having to rebuild the index.

使用可能な機能Feature availability

シノニム機能は現在プレビューで、最新のプレビュー api-version (api-version=2016-09-01-Preview) でのみサポートされています。The synonyms feature is currently in preview and only supported in the latest preview api-version (api-version=2016-09-01-Preview). 現時点で Azure Portal のサポートはありません。There is no Azure portal support at this time. API バージョンは要求で指定するため、同じアプリで一般公開 (GA) API とプレビュー API を組み合わせることができます。Because the API version is specified on the request, it's possible to combine generally available (GA) and preview APIs in the same app. ただし、プレビュー API は SLA の対象ではなく、機能が変更される場合があるため、実稼働アプリケーションでの使用はお勧めしません。However, preview APIs are not under SLA and features may change, so we do not recommend using them in production applications.

Azure Search のシノニムのサポートは、シノニム マップに基づき、これを定義して、サービスにアップロードします。In Azure Search, synonym support is based on synonym maps that you define and upload to your service. これらのマップは独立したリソース (インデックスやデータ ソースなど) を構成し、検索サービスで、任意のインデックスの任意の検索可能フィールドで使用できます。These maps constitute an independent resource (like indexes or data sources), and can be used by any searchable field in any index in your search service.

シノニム マップとインデックスは独立して保持されます。Synonym maps and indexes are maintained independently. シノニム マップを定義して、サービスにアップロードしたら、フィールド定義に synonymMaps という新しいプロパティを追加することによって、フィールドでシノニム機能を有効にできます。Once you define a synonym map and upload it to your service, you can enable the synonym feature on a field by adding a new property called synonymMaps in the field definition. シノニム マップの作成、更新、および削除は、常にドキュメント全体の操作になります。つまり、シノニム マップの一部を段階的に作成、更新、または削除することはできません。Creating, updating, and deleting a synonym map is always a whole-document operation, meaning that you cannot create, update or delete parts of the synonym map incrementally. 1 つのエントリの更新でも、再読み込みが必要になります。Updating even a single entry requires a reload.

検索アプリケーションにシノニムを組み込むことは、2 段階のプロセスです。Incorporating synonyms into your search application is a two-step process:

  1. 次の API によって、検索サービスにシノニム マップを追加します。Add a synonym map to your search service through the APIs below.

  2. インデックス定義でシノニム マップを使用するように、検索可能フィールドを構成します。Configure a searchable field to use the synonym map in the index definition.

SynonymMaps リソース APISynonymMaps Resource APIs

POST または PUT を使用して、サービスでシノニム マップを追加または更新します。Add or update a synonym map under your service, using POST or PUT.

シノニム マップは、POST または PUT を使用してサービスにアップロードします。Synonym maps are uploaded to the service via POST or PUT. 各規則は、改行文字 ('\n') で区切る必要があります。Each rule must be delimited by the new line character ('\n'). 無料サービスでシノニム マップあたり最大 5,000 規則、およびその他のすべての SKU で 10,000 規則を定義できます。You can define up to 5,000 rules per synonym map in a free service and 10,000 rules in all other SKUs. 各規則には、最大 20 個の拡張を設定できます。Each rule can have up to 20 expansions.

このプレビューでは、シノニム マップは、次に説明する Apache Solr 形式である必要があります。In this preview, synonym maps must be in the Apache Solr format which is explained below. 別の形式の既存のシノニム辞書があり、それを直接使用する場合は、UserVoice でお知らせください。If you have an existing synonym dictionary in a different format and want to use it directly, please let us know on UserVoice.

次の例のように、HTTP POST を使用して、新しいシノニム マップを作成できます。You can create a new synonym map using HTTP POST, as in the following example:

POST https://[servicename].search.windows.net/synonymmaps?api-version=2016-09-01-Preview
api-key: [admin key]

{  
   "name":"mysynonymmap",
   "format":"solr",
   "synonyms": "
      USA, United States, United States of America\n
      Washington, Wash., WA => WA\n"
}

または、PUT を使用し、URI にシノニム マップ名を指定できます。Alternatively, you can use PUT and specify the synonym map name on the URI. シノニム マップが存在しない場合、作成されます。If the synonym map does not exist, it will be created.

PUT https://[servicename].search.windows.net/synonymmaps/mysynonymmap?api-version=2016-09-01-Preview
api-key: [admin key]

{  
   "format":"solr",
   "synonyms": "
      USA, United States, United States of America\n
      Washington, Wash., WA => WA\n"
}
Apache Solr シノニム形式Apache Solr synonym format

Solr 形式は同等の明示的なシノニム マッピングをサポートします。The Solr format supports equivalent and explicit synonym mappings. マッピング規則は、このドキュメントで説明している Apache Solr のオープン ソース シノニム フィルター仕様 SynonymFilter に準拠しています。Mapping rules adhere to the open source synonym filter specification of Apache Solr, described in this document: SynonymFilter. 同等のシノニムのサンプル規則を以下に示します。Below is a sample rule for equivalent synonyms.

USA, United States, United States of America

上の規則では、検索クエリ "USA" が "USA" または "United States" または "United States of America" に拡張されます。With the rule above, a search query "USA" will expand to "USA" OR "United States" OR "United States of America".

明示的なマッピングは、"=>" 矢印で示します。Explicit mapping is denoted by an arrow "=>". 指定した場合、"=>" の左側に一致する検索クエリの用語のシーケンスが、右側の代替で置き換えられます。When specified, a term sequence of a search query that matches the left hand side of "=>" will be replaced with the alternatives on the right hand side. 次の規則を指定した場合、検索クエリ "Washington"、"Wash."、Given the rule below, search queries "Washington", "Wash." または "WA" はすべて "WA" に書き換えられます。or "WA" will all be rewritten to "WA". 明示的なマッピングは指定した方向でのみ適用され、この例では、クエリ "WA" が "Washington" に書き換えられることはありません。Explicit mapping only applies in the direction specified and does not rewrite the query "WA" to "Washington" in this case.

Washington, Wash., WA => WA

サービスのシノニム マップを一覧表示します。List synonym maps under your service.

GET https://[servicename].search.windows.net/synonymmaps?api-version=2016-09-01-Preview
api-key: [admin key]

サービスのシノニム マップを取得します。Get a synonym map under your service.

GET https://[servicename].search.windows.net/synonymmaps/mysynonymmap?api-version=2016-09-01-Preview
api-key: [admin key]

サービスのシノニム マップを削除します。Delete a synonyms map under your service.

DELETE https://[servicename].search.windows.net/synonymmaps/mysynonymmap?api-version=2016-09-01-Preview
api-key: [admin key]

インデックス定義でシノニム マップを使用するように、検索可能フィールドを構成します。Configure a searchable field to use the synonym map in the index definition.

新しいフィールド プロパティ synonymMaps を使用して、検索可能フィールドに使用するシノニム マップを指定できます。A new field property synonymMaps can be used to specify a synonym map to use for a searchable field. シノニム マップは、サービス レベル リソースであり、そのサービスに属するインデックスの任意のフィールドによって参照できます。Synonym maps are service level resources and can be referenced by any field of an index under the service.

POST https://[servicename].search.windows.net/indexes?api-version=2016-09-01-Preview
api-key: [admin key]

{
   "name":"myindex",
   "fields":[
      {
         "name":"id",
         "type":"Edm.String",
         "key":true
      },
      {
         "name":"name",
         "type":"Edm.String",
         "searchable":true,
         "analyzer":"en.lucene",
         "synonymMaps":[
            "mysynonymmap"
         ]
      },
      {
         "name":"name_jp",
         "type":"Edm.String",
         "searchable":true,
         "analyzer":"ja.microsoft",
         "synonymMaps":[
            "japanesesynonymmap"
         ]
      }
   ]
}

synonymMaps は型 'Edm.String' または 'Collection(Edm.String)' の検索可能フィールドに指定できます。synonymMaps can be specified for searchable fields of the type 'Edm.String' or 'Collection(Edm.String)'.

注意

このプレビューでは、フィールドあたり 1 つのシノニム マップのみを指定できます。In this preview, you can only have one synonym map per field. 複数のシノニム マップを使用する必要がある場合は、UserVoice でお知らせください。If you want to use multiple synonym maps, please let us know on UserVoice.

他の検索機能へのシノニムの影響Impact of synonyms on other search features

シノニム機能は、OR 演算子によって元のクエリをシノニムに書き換えます。The synonyms feature rewrites the original query with synonyms with the OR operator. このため、検索結果の強調表示とスコアリング プロファイルは元の用語とシノニムを同等として処理します。For this reason, hit highlighting and scoring profiles treat the original term and synonyms as equivalent.

シノニム機能は、検索クエリに適用され、フィルターやファセットには適用されません。Synonym feature applies to search queries and does not apply to filters or facets. 同様に、検索候補は元の用語にのみ基づき、シノニムの一致は応答に示されません。Similarly, suggestions are based only on the original term; synonym matches do not appear in the response.

シノニムの拡張は、ワイルドカード検索語句には適用されません。プレフィックス、あいまい検索、および正規表現語句は拡張されません。Synonym expansions do not apply to wildcard search terms; prefix, fuzzy, and regex terms aren't expanded.

シノニム マップの構築のヒントTips for building a synonym map

  • 簡潔で適切に設計されたシノニム マップは、網羅的な一致候補の一覧よりも効率的です。A concise, well-designed synonym map is more efficient than an exhaustive list of possible matches. 過度に大規模または複雑な辞書は、解析に時間がかかり、クエリが多数のシノニムに拡張された場合に、クエリの待ち時間に影響を与えます。Excessively large or complex dictionaries take longer to parse and affect the query latency if the query expands to many synonyms. 使用される可能性のある用語を推測するのではなく、検索トラフィック分析レポートによって実際の用語を取得できます。Rather than guess at which terms might be used, you can get the actual terms via a search traffic analysis report.

  • 準備と検証の両方の練習として、このレポートを有効にして使用し、シノニムの一致から利点が得られる用語を正確に判断して、シノニム マップで優れた結果を生成する検証としてそれを使い続けます。As both a preliminary and validation exercise, enable and then use this report to precisely determine which terms will benefit from a synonym match, and then continue to use it as validation that your synonym map is producing a better outcome. 事前定義済みのレポートで、タイル "よくある検索クエリ" や "結果なしの検索クエリ" によって必要な情報が得られます。In the predefined report, the tiles "Most common search queries" and "Zero-result search queries" will give you the necessary information.

  • 検索アプリケーションでは、複数のシノニム マップを作成できます (アプリケーションで多言語の顧客ベースをサポートしている場合に言語別など)。You can create multiple synonym maps for your search application (for example, by language if your application supports a multi-lingual customer base). 現在、フィールドではそれらのうちの 1 つしか使用できません。Currently, a field can only use one of them. フィールドの synonymMaps プロパティは、いつでも更新できます。You can update a field's synonymMaps property at any time.

次のステップNext steps

  • 開発 (非運用) 環境に既存のインデックスがある場合は、小さな辞書で実験して、シノニムの追加によって、スコアリング プロファイル、検索結果の強調表示、検索候補への影響など、検索操作がどのように変わるかを確認します。If you have an existing index in a development (non-production) environment, experiment with a small dictionary to see how the addition of synonyms changes the search experience, including impact on scoring profiles, hit highlighting, and suggestions.

  • 検索トラフィック分析を有効にし、事前定義済みの Power BI レポートを使用して、最も使われた用語と、ドキュメントを返さない用語を調べます。Enable search traffic analytics and use the predefined Power BI report to learn which terms are used the most, and which ones return zero documents. これらの洞察を使用して、インデックスでドキュメントに解決する必要がある非生産的クエリのシノニムを含めるように辞書を変更します。Armed with these insights, revise the dictionary to include synonyms for unproductive queries that should be resolving to documents in your index.