You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/search/search-synonyms.md
+23-21Lines changed: 23 additions & 21 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,5 @@
1
1
---
2
-
title: Synonyms for query expansion
2
+
title: Add synonyms to expand queries for equivalent terms
3
3
titleSuffix: Azure AI Search
4
4
description: Create a synonym map to expand the scope of a search query over an Azure AI Search index. The query can search on equivalent terms provided in the synonym map, even if the query doesn't explicitly include the term.
5
5
@@ -10,12 +10,12 @@ ms.service: azure-ai-search
10
10
ms.custom:
11
11
- ignite-2023
12
12
ms.topic: how-to
13
-
ms.date: 07/22/2024
13
+
ms.date: 10/28/2024
14
14
---
15
15
16
-
# Synonyms in Azure AI Search
16
+
# Add synonyms in Azure AI Search
17
17
18
-
On a search service, a synonym map associates equivalent terms, expanding the scope of a query without the user having to actually provide the term. For example, assuming "dog", "canine", and "puppy" are mapped synonyms, a query on "canine" matches on a document containing "dog". You might create multiple synonym maps for different languages, such as English and French versions, or lexicons if your content includes technical jargon, slang, or obscure terminology.
18
+
On a search service, a synonym map associates equivalent terms, expanding the scope of a query without the user having to actually provide the term. For example, assuming *dog*, *canine*, and *puppy* are mapped synonyms, a query on *canine* matches on a document containing *dog*. You might create multiple synonym maps for different languages, such as English and French versions, or lexicons if your content includes technical jargon, slang, or obscure terminology.
19
19
20
20
Some key points about synonym maps:
21
21
@@ -27,7 +27,7 @@ Some key points about synonym maps:
27
27
28
28
## Create a synonym map
29
29
30
-
A synonym map consists of name, format, and rules that function as synonym map entries. The only format that is supported is `solr`, and the `solr` format determines rule construction.
30
+
A synonym map consists of name, format, and rules that function as synonym map entries. The only format that's supported is `solr`, and the `solr` format determines rule construction.
31
31
32
32
To create a synonym map, do so programmatically. The portal doesn't support synonym map definitions.
33
33
@@ -48,7 +48,7 @@ POST /synonymmaps?api-version=2024-07-01
48
48
49
49
### [.NET](#tab/dotnet)
50
50
51
-
Use the [SynonymMap class (.NET)](/dotnet/api/azure.search.documents.indexes.models.synonymmap) and [Create a synonym map(Azure SDK sample)](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/search/Azure.Search.Documents/samples/Sample02_Service.md#create-a-synonym-map) to create the map.
51
+
Use the [SynonymMap class (.NET)](/dotnet/api/azure.search.documents.indexes.models.synonymmap) and [Create a synonym map(Azure SDK sample)](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/search/Azure.Search.Documents/samples/Sample02_Service.md#create-a-synonym-map) to create the map.
52
52
53
53
### [Python](#tab/python)
54
54
@@ -66,21 +66,21 @@ Use the [SynonymMap interface (JavaScript)](/javascript/api/@azure/search-docume
66
66
67
67
### Define rules
68
68
69
-
Mapping rules adhere to the open-source synonym filter specification of Apache Solr, described in this document: [SynonymFilter](https://cwiki.apache.org/confluence/display/solr/Filter+Descriptions#FilterDescriptions-SynonymFilter). The `solr` format supports two kinds of rules:
69
+
Mapping rules adhere to the open-source synonym filter specification of Apache Solr, described in this document: [SynonymGraphFilter](https://cwiki.apache.org/confluence/display/solr/Filter+Descriptions#FilterDescriptions-SynonymGraphFilter). The `solr` format supports two kinds of rules:
70
70
71
71
- equivalency (where terms are equal substitutes in the query)
72
72
73
73
- explicit mappings (where terms are mapped to one explicit term)
74
74
75
-
Each rule is delimited by the new line character (`\n`). You can define up to 5,000 rules per synonym map in a free service and 20,000 rules per map in other tiers. Each rule can have up to 20 expansions (or items in a rule). For more information, see [Synonym limits](search-limits-quotas-capacity.md#synonym-limits).
75
+
Each rule is delimited by the new line character (`\n`). You can define up to 5,000 rules per synonym map in a free service and 20,000 rules per map in other tiers. Each rule can have up to 20 expansions, or items in a rule. For more information, see [Synonym limits](search-limits-quotas-capacity.md#synonym-limits).
76
76
77
77
Query parsers automatically lower-case any upper or mixed case terms. To preserve special characters in the string, such as a comma or dash, add the appropriate escape characters when creating the synonym map.
78
78
79
79
### Equivalency rules
80
80
81
-
Rules for equivalent terms are comma-delimited within the same rule. In the first example, a query on `USA` expands 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.
81
+
Rules for equivalent terms are comma-delimited within the same rule. In the first example, a query on *USA* expands 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.
82
82
83
-
In the equivalence case, a query for `dog` expands the query to also include `puppy` and `canine`.
83
+
In the equivalence case, a query for *dog* expands the query to also include *puppy* and *canine*.
84
84
85
85
```json
86
86
{
@@ -96,7 +96,7 @@ In the equivalence case, a query for `dog` expands the query to also include `pu
96
96
97
97
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 `=>` is replaced with the alternatives on the right-hand side at query time.
98
98
99
-
In the explicit case, a query for `Washington`, `Wash.` or `WA` is rewritten as `WA`, and the query engine only looks for matches on the term `WA`. Explicit mapping only applies in the direction specified, and doesn't rewrite the query `WA` to `Washington` in this case.
99
+
In the explicit case, a query for *Washington*, *Wash.* or *WA* is rewritten as *WA*, and the query engine only looks for matches on the term *WA*. Explicit mapping only applies in the direction specified, and doesn't rewrite the query *WA* to *Washington* in this case.
100
100
101
101
```json
102
102
{
@@ -109,7 +109,7 @@ In the explicit case, a query for `Washington`, `Wash.` or `WA` is rewritten as
109
109
110
110
### Escaping special characters
111
111
112
-
Synonyms are analyzed during query processing just like any other query term, which means that rules for reserved and special characters apply to the terms in your synonym map. The list of characters that requires escaping varies between the simple syntax and full syntax:
112
+
Synonyms are analyzed during query processing just like any other query term, which means that rules for reserved and special characters apply to the terms in your synonym map. The list of characters that require escaping varies between the simple syntax and full syntax:
@@ -136,7 +136,7 @@ Since the backslash is itself a special character in other languages like JSON a
136
136
137
137
## Manage synonym maps
138
138
139
-
You can update a synonym map without disrupting query and indexing workloads. However, once you add a synonym map to a field, if you then delete a synonym map, any query that includes the fields in question fail with a 404 error.
139
+
You can update a synonym map without disrupting query and indexing workloads. However, once you add a synonym map to a field, if you then delete a synonym map, any query that includes the fields in question fails with a 404 error.
140
140
141
141
Creating, updating, and deleting a synonym map is always a whole-document operation. You can't update or delete parts of the synonym map incrementally. Updating even a single rule requires a reload.
142
142
@@ -184,10 +184,10 @@ POST /indexes?api-version=2024-07-01
184
184
185
185
Use the [**SearchIndexClient**](/dotnet/api/azure.search.documents.indexes.searchindexclient) to update an index. Provide the whole index definition and include the new parameters for synonym map assignments.
186
186
187
-
In this example, the "country" field has a synonymMapName property.
187
+
In this example, the `country` field has a `synonymMapName` property.
188
188
189
189
```csharp
190
-
// Update anindex
190
+
// Update an index
191
191
stringindexName="hotels";
192
192
SearchIndexindex=newSearchIndex(indexName)
193
193
{
@@ -214,7 +214,7 @@ SearchIndex index = new SearchIndex(indexName)
214
214
awaitindexClient.CreateIndexAsync(index);
215
215
```
216
216
217
-
For more examples, see[azure-search-dotnet-samples/quickstart/v11/](https://github.com/Azure-Samples/azure-search-dotnet-samples/tree/main/quickstart/v11).
217
+
For more examples, see the [quickstart/v11 on GitHub](https://github.com/Azure-Samples/azure-search-dotnet-samples/tree/main/quickstart/v11).
218
218
219
219
### [**Other SDKs**](#tab/other-sdks-assign)
220
220
@@ -223,7 +223,7 @@ You can use any supported SDK to update a search index. All of them provide a **
@@ -238,17 +238,19 @@ Synonyms are a query expansion technique that supplements the contents of an ind
238
238
239
239
For synonym-enabled fields, synonyms are subject to the same text analysis as the associated field. For example, if a field is analyzed using the standard Lucene analyzer, synonym terms are also 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.
240
240
241
-
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.
241
+
Internally, the synonyms feature rewrites the original query with synonyms by using the OR operator. For this reason, hit highlighting and scoring profiles treat the original term and synonyms as equivalent.
242
242
243
243
Synonyms apply to free-form text queries only and aren't supported for filters, facets, autocomplete, or suggestions. Autocomplete and suggestions are based only on the original term; synonym matches don't appear in the response.
244
244
245
+
If you have an existing index in a development (nonproduction) 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.
246
+
247
+
### Wildcard searches
248
+
245
249
Synonym expansions don't apply to wildcard search terms; prefix, fuzzy, and regex terms aren't expanded.
246
250
247
251
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. For example, to combine synonyms with wildcards for simple query syntax, the term would be `<query> | <query>*`.
248
252
249
-
If you have an existing index in a development (nonproduction) 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.
250
-
251
-
## Next steps
253
+
## Next step
252
254
253
255
> [!div class="nextstepaction"]
254
256
> [Create a synonym map (REST API)](/rest/api/searchservice/synonym-maps/create)
Copy file name to clipboardExpand all lines: articles/search/semantic-how-to-enable-disable.md
+14-13Lines changed: 14 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
---
2
2
title: Enable or disable semantic ranker
3
3
titleSuffix: Azure AI Search
4
-
description: Steps for turning semantic ranker on or off in Azure AI Search.
4
+
description: Learn how to turn semantic ranker on or off in Azure AI Search, and how to prevent others from enabling it.
5
5
6
6
manager: nitinme
7
7
author: HeidiSteen
@@ -10,16 +10,16 @@ ms.service: azure-ai-search
10
10
ms.custom:
11
11
- ignite-2023
12
12
ms.topic: how-to
13
-
ms.date: 09/24/2024
13
+
ms.date: 10/28/2024
14
14
---
15
15
16
16
# Enable or disable semantic ranker
17
17
18
-
Semantic ranker is a premium feature billed by usage. By default, semantic ranker is turned off on a new search service, but it can be enabled by anyone with **Contributor** permissions. If you don't want anyone enabling it inadvertently, you can [disable it using the REST API](#disable-semantic-ranker-using-the-rest-api).
18
+
Semantic ranker is a premium feature billed by usage. By default, semantic ranker is turned off when you create a new search service, but anyone with *Contributor* permissions can enable it. If you don't want anyone enabling it inadvertently, you can [disable it using the REST API](#disable-semantic-ranker-using-the-rest-api).
19
19
20
20
## Check availability
21
21
22
-
Check the [regions list](search-region-support.md) to see if your region is listed.
22
+
To check if semantic ranker is available in your region, see the [Azure AI Search regions list](search-region-support.md).
23
23
24
24
## Enable semantic ranker
25
25
@@ -29,7 +29,7 @@ Follow these steps to enable [semantic ranker](semantic-search-overview.md) at t
29
29
30
30
1. Open the [Azure portal](https://portal.azure.com).
31
31
32
-
1. Navigate to your search service. On the **Overview** page, make sure the service is a billable tier, Basic or higher.
32
+
1. Navigate to your search service. On the **Overview** page, make sure the pricing tier is set to **Basic** or higher.
33
33
34
34
1. On the left-navigation pane, select **Settings** > **Semantic ranker**.
35
35
@@ -43,14 +43,14 @@ The free plan is capped at 1,000 queries per month. After the first 1,000 querie
43
43
44
44
To enable semantic ranker using the REST API, you can use the [Create or Update Service API](/rest/api/searchmanagement/services/create-or-update?view=rest-searchmanagement-2023-11-01&tabs=HTTP#searchsemanticsearch&preserve-view=true).
45
45
46
-
Management REST API calls are authenticated through Microsoft Entra ID. See [Manage your Azure AI Search service with REST APIs](search-manage-rest.md) for instructions on how to authenticate.
46
+
Management REST API calls are authenticated through Microsoft Entra ID. For instructions on how to authenticate, see [Manage your Azure AI Search service with REST APIs](search-manage-rest.md).
47
47
48
48
* Management REST API version 2023-11-01 provides the configuration property.
49
49
50
-
* Owner or Contributor permissions are required to enable or disable features.
50
+
**Owner* or *Contributor* permissions are required to enable or disable features.
51
51
52
52
> [!NOTE]
53
-
> Create or Update supports two HTTP methods: PUT and PATCH. Both PUT and PATCH can be used to update existing services, but only PUT can be used to create a new service. If PUT is used to update an existing service, it replaces all properties in the service with their defaults if they are not specified in the request. When PATCH is used to update an existing service, it only replaces properties that are specified in the request. When using PUT to update an existing service, it's possible to accidentally introduce an unexpected scaling or configuration change. When enabling semantic ranking on an existing service, it's recommended to use PATCH instead of PUT.
53
+
> Create or Update supports two HTTP methods: *PUT* and *PATCH*. Both PUT and PATCH can be used to update existing services, but only PUT can be used to create a new service. If PUT is used to update an existing service, it replaces all properties in the service with their defaults if they aren't specified in the request. When PATCH is used to update an existing service, it only replaces properties that are specified in the request. When using PUT to update an existing service, it's possible to accidentally introduce an unexpected scaling or configuration change. When enabling semantic ranking on an existing service, it's recommended to use PATCH instead of PUT.
To reverse feature enablement, or for full protection against accidental usage and charges, you can disable semantic ranker using the [Create or Update Service API](/rest/api/searchmanagement/services/create-or-update#searchsemanticsearch) on your search service. After the feature is disabled, any requests that include the semantic query type will be rejected.
68
+
To turn off feature enablement, or for full protection against accidental usage and charges, you can disable semantic ranker by using the [Create or Update Service API](/rest/api/searchmanagement/services/create-or-update#searchsemanticsearch) on your search service. After the feature is disabled, any requests that include the semantic query type are rejected.
69
69
70
-
Management REST API calls are authenticated through Microsoft Entra ID. See [Manage your Azure AI Search service with REST APIs](search-manage-rest.md) for instructions on how to authenticate.
70
+
Management REST API calls are authenticated through Microsoft Entra ID. For instructions on how to authenticate, see [Manage your Azure AI Search service with REST APIs](search-manage-rest.md).
0 commit comments