例:C# で Azure Search にシノニムを追加するExample: Add synonyms for Azure Search in C#

シノニムは、意味的に入力用語と同等と見なされる用語を一致させることにより、クエリを拡張します。Synonyms expand a query by matching on terms considered semantically equivalent to the input term. たとえば、"car" を "automobile" または "vehicle" という用語が含まれているドキュメントと一致させたい場合があります。For example, you might want "car" to match documents containing the terms "automobile" or "vehicle".

Azure Search では、シノニムは同等の用語を関連付ける "マッピング規則" を通じて "シノニム マップ" で定義されています。In Azure Search, synonyms are defined in a synonym map, through mapping rules that associate equivalent terms. この例では、既にインデックスがある状態で同意語を追加して使用する最も重要な手順について取り上げます。This example covers essential steps for adding and using synonyms with an existing index. 学習内容は次のとおりです。You learn how to:

  • SynonymMap クラスを使用して、シノニム マップを作成する。Create a synonym map using the SynonymMap class.
  • シノニムを介してクエリ拡張をサポートする必要があるフィールドに対して SynonymMaps プロパティを設定する。Set the SynonymMaps property on fields that should support query expansion via synonyms.

シノニム対応フィールドに対するクエリは、通常と同じ方法で実行できます。You can query a synonym-enabled field as you would normally. クエリ構文を追加しなくてもシノニムにアクセスできます。There is no additional query syntax required to access synonyms.

複数のシノニム マップを作成し、サービス全体の任意のインデックスで使用できるリソースとしてポストして、フィールド レベルでどのマップを使用するかを参照することができます。You can create multiple synonym maps, post them as a service-wide resource available to any index, and then reference which one to use at the field level. クエリの際に、Azure Search はインデックスを検索するだけでなく、クエリで使用されているフィールドにシノニム マップが指定されていれば、そのマップも参照します。At query time, in addition to searching an index, Azure Search does a lookup in a synonym map, if one is specified on fields used in the query.

注意

シノニムは、プログラムで作成できますが、ポータルでは作成できません。Synonyms can be created programmatically, but not in the portal. Azure portal でのシノニムのサポートが役に立つ場合は、UserVoice でフィードバックをお送りくださいIf Azure portal support for synonyms would be useful to you, please provide your feedback on the UserVoice

前提条件Prerequisites

チュートリアルには、次のような要件があります。Tutorial requirements include the following:

概要Overview

前と後のクエリで、シノニムの値を示します。Before-and-after queries demonstrate the value of synonyms. この例では、サンプル インデックスに対してクエリを実行して結果を返すサンプル アプリケーションを使用します。In this example, use a sample application that executes queries and returns results on a sample index. サンプル アプリケーションは "hotels" という名前の小さいインデックスを作成し、2 つのドキュメントを設定します。The sample application creates a small index named "hotels" populated with two documents. アプリケーションはインデックス内に出現しない語句を使用して検索クエリを実行し、シノニム機能を有効にしてから同じ検索を再度発行します。The application executes search queries using terms and phrases that do not appear in the index, enables the synonyms feature, then issues the same searches again. 次のコードは、全体的な流れを示しています。The code below demonstrates the overall flow.

  static void Main(string[] args)
  {
      SearchServiceClient serviceClient = CreateSearchServiceClient();

      Console.WriteLine("{0}", "Cleaning up resources...\n");
      CleanupResources(serviceClient);

      Console.WriteLine("{0}", "Creating index...\n");
      CreateHotelsIndex(serviceClient);

      ISearchIndexClient indexClient = serviceClient.Indexes.GetClient("hotels");

      Console.WriteLine("{0}", "Uploading documents...\n");
      UploadDocuments(indexClient);

      ISearchIndexClient indexClientForQueries = CreateSearchIndexClient();

      RunQueriesWithNonExistentTermsInIndex(indexClientForQueries);

      Console.WriteLine("{0}", "Adding synonyms...\n");
      UploadSynonyms(serviceClient);
      EnableSynonymsInHotelsIndex(serviceClient);
      Thread.Sleep(10000); // Wait for the changes to propagate

      RunQueriesWithNonExistentTermsInIndex(indexClientForQueries);

      Console.WriteLine("{0}", "Complete.  Press any key to end application...\n");

      Console.ReadKey();
  }

サンプル インデックスの作成と設定の手順は、「.NET アプリケーションから Azure Search を使用する方法」で説明されています。The steps to create and populate the sample index are explained in How to use Azure Search from a .NET Application.

"前" のクエリ"Before" queries

RunQueriesWithNonExistentTermsInIndex では、"five star"、"internet"、および "economy AND hotel" で検索クエリを発行します。In RunQueriesWithNonExistentTermsInIndex, issue search queries with "five star", "internet", and "economy AND hotel".

Console.WriteLine("Search the entire index for the phrase \"five star\":\n");
results = indexClient.Documents.Search<Hotel>("\"five star\"", parameters);
WriteDocuments(results);

Console.WriteLine("Search the entire index for the term 'internet':\n");
results = indexClient.Documents.Search<Hotel>("internet", parameters);
WriteDocuments(results);

Console.WriteLine("Search the entire index for the terms 'economy' AND 'hotel':\n");
results = indexClient.Documents.Search<Hotel>("economy AND hotel", parameters);
WriteDocuments(results);

これらの用語は 2 つのインデックス付きドキュメントのどちらにも含まれていないため、最初の RunQueriesWithNonExistentTermsInIndex からは次の出力が返されます。Neither of the two indexed documents contain the terms, so we get the following output from the first RunQueriesWithNonExistentTermsInIndex.

Search the entire index for the phrase "five star":

no document matched

Search the entire index for the term 'internet':

no document matched

Search the entire index for the terms 'economy' AND 'hotel':

no document matched

シノニムの有効化Enable synonyms

シノニムの有効化は、2 段階のプロセスです。Enabling synonyms is a two-step process. まず、シノニム規則を定義してアップロードします。次に、それらを使用するフィールドを構成します。We first define and upload synonym rules and then configure fields to use them. プロセスの概要は、UploadSynonyms および EnableSynonymsInHotelsIndex で示されています。The process is outlined in UploadSynonyms and EnableSynonymsInHotelsIndex.

  1. シノニム マップを検索サービスに追加します。Add a synonym map to your search service. UploadSynonyms で、シノニム マップ 'desc-synonymmap' に 4 つの規則を定義し、サービスにアップロードします。In UploadSynonyms, we define four rules in our synonym map 'desc-synonymmap' and upload to the service.

     var synonymMap = new SynonymMap()
     {
         Name = "desc-synonymmap",
         Format = "solr",
         Synonyms = "hotel, motel\n
                     internet,wifi\n
                     five star=>luxury\n
                     economy,inexpensive=>budget"
     };
    
     serviceClient.SynonymMaps.CreateOrUpdate(synonymMap);
    

    シノニム マップは、オープン ソース標準の solr の形式に準拠する必要があります。A synonym map must conform to the open source standard solr format. この形式については、「Synonyms in Azure Search (Azure Search でのシノニム)」の「Apache Solr synonym format (Apache Solr のシノニムの形式)」のセクションで説明されています。The format is explained in Synonyms in Azure Search under the section Apache Solr synonym format.

  2. インデックス定義でシノニム マップを使用するように、検索可能フィールドを構成します。Configure searchable fields to use the synonym map in the index definition. EnableSynonymsInHotelsIndex の 2 つのフィールド category および tags で、synonymMaps プロパティを新たにアップロードしたシノニム マップの名前に設定して、シノニムを有効にします。In EnableSynonymsInHotelsIndex, we enable synonyms on two fields category and tags by setting the synonymMaps property to the name of the newly uploaded synonym map.

    Index index = serviceClient.Indexes.Get("hotels");
    index.Fields.First(f => f.Name == "category").SynonymMaps = new[] { "desc-synonymmap" };
    index.Fields.First(f => f.Name == "tags").SynonymMaps = new[] { "desc-synonymmap" };
    
    serviceClient.Indexes.CreateOrUpdate(index);
    

    シノニム マップを追加するときに、インデックスの再作成は必要ありません。When you add a synonym map, index rebuilds are not required. シノニム マップをサービスに追加し、任意のインデックス内の既存のフィールド定義を、新しいシノニム マップを使用するように修正できます。You can add a synonym map to your service, and then amend existing field definitions in any index to use the new synonym map. 新しい属性を追加しても、インデックスの可用性に影響はありません。The addition of new attributes has no impact on index availability. フィールドでシノニムを無効にする場合も同様です。The same applies in disabling synonyms for a field. 単に synonymMaps プロパティに空のリストを設定するだけです。You can simply set the synonymMaps property to an empty list.

    index.Fields.First(f => f.Name == "category").SynonymMaps = new List<string>();
    

"後" のクエリ"After" queries

シノニム マップがアップロードされ、インデックスがシノニム マップを使用するように更新された後、2 回目の RunQueriesWithNonExistentTermsInIndex 呼び出しは次の出力を返します。After the synonym map is uploaded and the index is updated to use the synonym map, the second RunQueriesWithNonExistentTermsInIndex call outputs the following:

Search the entire index for the phrase "five star":

Name: Fancy Stay        Category: Luxury        Tags: [pool, view, wifi, concierge]

Search the entire index for the term 'internet':

Name: Fancy Stay        Category: Luxury        Tags: [pool, view, wifi, concierge]

Search the entire index for the terms 'economy' AND 'hotel':

Name: Roach Motel       Category: Budget        Tags: [motel, budget]

最初のクエリは、規則 five star=>luxury からドキュメントを見つけます。The first query finds the document from the rule five star=>luxury. 2 番目のクエリは internet,wifi を使用して検索を拡張し、3 番目のクエリは hotel, moteleconomy,inexpensive=>budget の両方を使用してそれらと一致するドキュメントを見つけます。The second query expands the search using internet,wifi and the third using both hotel, motel and economy,inexpensive=>budget in finding the documents they matched.

シノニムを追加することで、検索エクスペリエンスがまったく違うものになります。Adding synonyms completely changes the search experience. この例で元のクエリは、インデックス内のドキュメントが関連性を持っているにもかかわらず、意味のある結果を返すことができませんでした。In this example, the original queries failed to return meaningful results even though the documents in our index were relevant. シノニムを有効にすると、インデックス内の基になるデータは変更せずに、よく使用される用語が含まれるようにインデックスを拡張できます。By enabling synonyms, we can expand an index to include terms in common use, with no changes to underlying data in the index.

サンプル アプリケーションのソース コードSample application source code

このチュートリアルで使用したサンプル アプリケーションの完全なソース コードが GitHub にあります。You can find the full source code of the sample application used in this walk through on GitHub.

リソースのクリーンアップClean up resources

例の後で最も速くクリーンアップする方法は、Azure Search サービスが含まれているリソース グループを削除することです。The fastest way to clean up after an example is by deleting the resource group containing the Azure Search service. リソース グループを削除することで、そのすべての内容を完全に削除することができます。You can delete the resource group now to permanently delete everything in it. ポータルでは、リソース グループ名は Azure Search サービスの [概要] ページに表示されます。In the portal, the resource group name is on the Overview page of Azure Search service.

次の手順Next steps

この例では、マッピング規則を作成、ポストしてからクエリでシノニム マップを呼び出す C# コードのシノニム機能を示します。This example demonstrated the synonyms feature in C# code to create and post mapping rules and then call the synonym map on a query. さらに詳しい情報については、.NET SDKREST API のリファレンス ドキュメントをご覧ください。Additional information can be found in the .NET SDK and REST API reference documentation.