Azure Search のシノニム (プレビュー) C# チュートリアルSynonym (preview) C# tutorial for Azure Search

シノニムは、意味的に入力用語と同等と見なされる用語を一致させることにより、クエリを拡張します。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. 複数のシノニム マップを作成し、サービス全体の任意のインデックスで使用できるリソースとしてポストして、フィールド レベルでどのマップを使用するかを参照することができます。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.

注意

シノニム機能は現時点でプレビュー段階であり、最新のプレビュー API および SDK バージョン (api-version=2016-09-01-Preview、SDK version 4.x-preview) だけでサポートされています。The synonyms feature is currently in preview and only supported in the latest preview API and SDK versions (api-version=2016-09-01-Preview, SDK version 4.x-preview). 現在、Azure Portal でのサポートはありません。There is no Azure portal support at this time. プレビュー API は SLA の対象ではなく、プレビュー機能は変更される場合があるため、実稼働アプリケーションでの使用はお勧めしません。Preview APIs are not under SLA and preview features may change, so we do not recommend using them in production applications.

前提条件Prerequisites

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

概要Overview

前と後のクエリで、シノニムの値を示します。Before-and-after queries demonstrate the value of synonyms. このチュートリアルでは、サンプル インデックスに対してクエリを実行して結果を返すサンプル アプリケーションを使用します。In this tutorial, we 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, we 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 tutorial, 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.

次のステップNext steps