Azure Cognitive Search でのシノニムSynonyms in Azure Cognitive Search

シノニム マップを使用すると、ユーザーが実際に用語を提供する必要がなく、クエリのスコープを拡張する同等の用語を関連付けられます。With synonym maps, you can associate equivalent terms, expanding the scope of a query without the user having to actually provide the term. たとえば、"dog"、"canine"、"puppy" がシノニムであると仮定すると、"canine" に対するクエリは "dog" を含むドキュメントで一致します。For example, assuming "dog", "canine", and "puppy" are synonyms, a query on "canine" will match on a document containing "dog".

シノニムを作成するCreate synonyms

シノニム マップは、一度作成すると多数のインデックスで使用できるアセットです。A synonym map is an asset that can be created once and used by many indexes. サービス レベルによって、作成できるシノニム マップの数が決定されます。これは、Free および Basic レベルでの 3 つのシノニム マップから、Standard レベルでの 20 までの範囲です。The service tier determines how many synonym maps you can create, ranging from three synonym maps for Free and Basic tiers, up to 20 for the Standard tiers.

英語版やフランス語版など、言語によって別々のシノニム マップを複数作成したり、コンテンツに技術用語やあいまいな用語が含まれている場合は、辞書を作成したりすることができます。You might create multiple synonym maps for different languages, such as English and French versions, or lexicons if your content includes technical or obscure terminology. 検索サービスで複数のシノニム マップを作成できますが、フィールドではそのうちの 1 つしか使用できません。Although you can create multiple synonym maps in your search service, a field can only use one of them.

シノニム マップは、シノニム マップ エントリとして機能する名前、形式、および規則で構成されます。A synonym map consists of name, format, and rules that function as synonym map entries. サポートされている形式は solr のみで、solr 形式によってルールの構成が決まります。The only format that is supported is solr, and the solr format determines rule construction.

POST /synonymmaps?api-version=2020-06-30
{
    "name": "geo-synonyms",
    "format": "solr",
    "synonyms": "
        USA, United States, United States of America\n
        Washington, Wash., WA => WA\n"
}

シノニム マップを作成するには、「シノニム マップの作成 (REST API)」または Azure SDK を使用します。To create a synonym map, use the Create Synonym Map (REST API) or an Azure SDK. C# 開発者には、「C# で Azure Cognitive Search にシノニムを追加する」から始めることをお勧めします。For C# developers, we recommend starting with Add Synonyms in Azure Cognitive Searching using C#.

ルールを定義するDefine rules

マッピング規則は、このドキュメントで説明している Apache Solr のオープンソース シノニム フィルター仕様SynonymFilter に従います。solr 形式では、次の 2 種類の規則がサポートされています。Mapping rules adhere to the open-source synonym filter specification of Apache Solr, described in this document: SynonymFilter.The solr format supports two kinds of rules:

  • 同義性 (用語はクエリで同等の代用語になります)equivalency (where terms are equal substitutes in the query)

  • 明示的なマッピング (クエリ実行の前に、用語は 1 つの明示的な用語にマップされます)explicit mappings (where terms are mapped to one explicit term prior to querying)

各規則は、改行文字 (\n) で区切る必要があります。Each rule must be delimited by the new line character (\n). 無料サービスでシノニム マップあたり最大 5,000 個の規則、その他のレベルでマップあたり最大 20,000 個の規則を定義できます。You can define up to 5,000 rules per synonym map in a free service and 20,000 rules per map in other tiers. 各規則には、最大 20 個の拡張 (つまり規則内の項目) を設定できます。Each rule can have up to 20 expansions (or items in a rule). 詳細については、「シノニムの制限」をご覧ください。For more information, see Synonym limits.

クエリ パーサーでは大文字の用語や大文字と小文字が混在した用語は小文字に変換されますが、コンマやダッシュなどの特殊文字を文字列で保持する場合は、シノニム マップの作成時に適切なエスケープ文字を追加します。Query parsers will lower-case any upper or mixed case terms, but if you want to preserve special characters in the string, such as a comma or dash, add the appropriate escape characters when creating the synonym map.

同義性規則Equivalency rules

同義語の規則は、同じ規則内でコンマで区切られます。Rules for equivalent terms are comma-delimited within the same rule. 最初の例では、USA に対するクエリが USA"United States"、または "United States of America" に拡張されます。In the first example, a query on USA will expand to USA OR "United States" OR "United States of America". 句で一致させる場合は、クエリ自体を引用符で囲まれた句のクエリにする必要があることに注意してください。Notice that if you want to match on a phrase, the query itself must be a quote-enclosed phrase query.

同義性の場合、dog のクエリは、puppycanine も含めるようにクエリを拡張します。In the equivalence case, a query for dog will expand the query to also include puppy and canine.

{
"format": "solr",
"synonyms": "
    USA, United States, United States of America\n
    dog, puppy, canine\n
    coffee, latte, cup of joe, java\n"
}

明示的なマッピングExplicit mapping

明示的なマッピングの規則は、矢印 => によって示されます。Rules for an explicit mapping are 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 at query time.

明示的な場合、WashingtonWash.、または WA に対するクエリは WA に書き換えられ、クエリ エンジンは WA の用語でのみ一致を検索します。In the explicit case, a query for Washington, Wash. or WA will be rewritten as WA, and the query engine will only look for matches on the term WA. 明示的なマッピングは指定した方向でのみ適用され、この例では、クエリ WAWashington に書き換えられることはありません。Explicit mapping only applies in the direction specified, and does not rewrite the query WA to Washington in this case.

{
"format": "solr",
"synonyms": "
    Washington, Wash., WA => WA\n
    California, Calif., CA => CA\n"
}

特殊文字のエスケープEscaping special characters

シノニムは、クエリ処理中に分析されます。Synonyms are analyzed during query processing. コンマや他の特殊文字を含むシノニムを定義する必要がある場合は、次の例のように円記号でエスケープできます。If you need to define synonyms that contain commas or other special characters, you can escape them with a backslash, like in this example:

{
"format": "solr",
"synonyms": "WA\, USA, WA, Washington\n"
}

JSON や C# などの他の言語では、円記号自体が特殊文字であるため、通常、二重にエスケープする必要があります。Since the backslash is itself a special character in other languages like JSON and C#, you will probably need to double-escape it. たとえば、上記のシノニム マップに対して REST API に送信される JSON は、次のようになります。For example, the JSON sent to the REST API for the above synonym map would look like this:

{
"format":"solr",
"synonyms": "WA\\, USA, WA, Washington"
}

シノニム マップをアップロードして管理するUpload and manage synonym maps

前述のように、クエリおよびインデックス作成ワークロードを中断せずにシノニム マップを作成または更新することができます。As mentioned previously, you can create or update a synonym map without disrupting query and indexing workloads. シノニム マップはスタンドアロン オブジェクト (インデックスやデータ ソースなど) であり、これを使用しているフィールドがない限り、更新によってインデックス作成やクエリが失敗することはありません。A synonym map is a standalone object (like indexes or data sources), and as long as no field is using it, updates won't cause indexing or queries to fail. ただし、シノニム マップをフィールド定義に追加した後でシノニム マップを削除すると、該当するフィールドを含むクエリが 404 エラーで失敗します。However, once you add a synonym map to a field definition, if you then delete a synonym map, any query that includes the fields in question will fail with a 404 error.

シノニム マップの作成、更新、および削除は、常にドキュメント全体の操作になります。つまり、シノニム マップの一部を段階的に更新または削除することはできません。Creating, updating, and deleting a synonym map is always a whole-document operation, meaning that you cannot update or delete parts of the synonym map incrementally. 1 つの規則の更新でも、再読み込みが必要になります。Updating even a single rule requires a reload.

フィールドにシノニムを割り当てるAssign synonyms to fields

シノニム マップをアップロードした後、"searchable":true を含むフィールドで Edm.String または Collection(Edm.String) 型のフィールドに対してシノニムを有効にすることができます。After uploading a synonym map, you can enable the synonyms on fields of the type Edm.String or Collection(Edm.String), on fields having "searchable":true. 前述のように、フィールド定義で使用できるシノニム マップは 1 つだけです。As noted, a field definition can use only one synonym map.

POST /indexes?api-version=2020-06-30
{
    "name":"hotels-sample-index",
    "fields":[
        {
            "name":"description",
            "type":"Edm.String",
            "searchable":true,
            "synonymMaps":[
            "en-synonyms"
            ]
        },
        {
            "name":"description_fr",
            "type":"Edm.String",
            "searchable":true,
            "analyzer":"fr.microsoft",
            "synonymMaps":[
            "fr-synonyms"
            ]
        }
    ]
}

同義またはマップされたフィールドに対するクエリQuery on equivalent or mapped fields

シノニムを追加しても、新しい要件はクエリ構造に適用されません。Adding synonyms does not impose new requirements on query construction. シノニムの追加前と同じようにして、用語と語句のクエリを発行できます。You can issue term and phrase queries just as you did before the addition of synonyms. 唯一の違いは、シノニム マップにクエリ用語が存在する場合、クエリ エンジンは規則に応じて、用語または句を拡張したり、書き換えたりするという点です。The only difference is that if a query term exists in the synonym map, the query engine will either expand or rewrite the term or phrase, depending on the rule.

クエリの実行中にシノニムが使用される方法How synonyms are used during query execution

シノニムは、インデックスの内容を同等の用語で補完するクエリ拡張の手法ですが、シノニムの割り当てがあるフィールドでのみ機能します。Synonyms are a query expansion technique that supplements the contents of an index with equivalent terms, but only for fields that have a synonym assignment. フィールド スコープ クエリでシノニム対応フィールドが 除外 されている場合、シノニム マップからの一致は表示されません。If a field-scoped query excludes a synonym-enabled field, you won't see matches from the synonym map.

シノニム対応フィールドの場合、シノニムは、関連付けられているフィールドと同じテキスト分析に従います。For synonym-enabled fields, synonyms are subject to the same text analysis as the associated field. たとえば、フィールドが標準の Lucene アナライザーを使用して分析される場合は、シノニム用語もクエリ時に標準の Lucene アナライザーに従います。For example, if a field is analyzed using the standard Lucene analyzer, synonym terms will also be subject to the standard Lucene analyzer at query time. シノニム用語に句読点 (ピリオドやダッシュなど) を保持したい場合は、フィールドでコンテンツ保持アナライザーを適用します。If you want to preserve punctuation, such as periods or dashes, in the synonym term, apply a content-preserving analyzer on the field.

内部的には、シノニム機能により、シノニムを含む元のクエリが OR 演算子で書き換えられます。Internally, 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.

シノニムは自由形式のテキスト クエリにのみ適用され、フィルター、ファセット、オートコンプリート、または提案ではサポートされません。Synonyms apply to free form text queries only and are not supported for filters, facets, autocomplete, or suggestions. オートコンプリートと提案は、元の用語にのみ基づき、シノニムの一致は応答に示されません。Autocomplete and 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.

シノニムの拡張とワイルドカード検索、正規表現検索、またはあいまい検索を 1 つのクエリで適用する必要がある場合は、OR 構文を使用してクエリを組み合わせることができます。If you need to do a single query that applies synonym expansion and wildcard, regex, or fuzzy searches, you can combine the queries using the OR syntax. たとえば、クエリ構文が単純になるようにシノニムとワイルドカードを組み合わせる場合は、用語は <query> | <query>* のようになります。For example, to combine synonyms with wildcards for simple query syntax, the term would be <query> | <query>*.

開発 (非運用) 環境に既存のインデックスがある場合は、小さな辞書で実験して、シノニムの追加によって、スコアリング プロファイル、検索結果の強調表示、検索候補への影響など、検索操作がどのように変わるかを確認します。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.

次のステップNext steps