similarity property table

Author: HeidiSteen

articles/search/index-ranking-similarity.md

@@ -14,13 +14,13 @@ ms.date: 03/13/2020
 # Ranking algorithm in Azure Cognitive Search
 
 > [!IMPORTANT]
-> Starting July 15, 2020, newly created search services will use the BM25 ranking function, which has proven in most cases to provide search rankings that align better with user expectations than the current default ranking. Beyond superior ranking, BM25 also enables configuration options for tuning results based on factors such as document size.  
+> Starting July 15, 2020, newly created search services will use the BM25 ranking function automatically, which has proven in most cases to provide search rankings that align better with user expectations than the current default ranking. Beyond superior ranking, BM25 also enables configuration options for tuning results based on factors such as document size.  
 >
 > With this change, you will most likely see slight changes in the ordering of your search results. For those who want to test the impact of this change, the BM25 algorithm is available in the api-version 2019-05-06-Preview.  
 
 This article describes how you can use the new BM25 ranking algorithm on existing search services for new indexes created and queried using the preview API.
 
-Azure Cognitive Search is in the process of adopting the official Lucene implementation of the Okapi BM25 algorithm, *BM25Similarity*, which will replace the previously used *ClassicSimilarity* implementation. Like the older ClassicSimilarity algorithm, BM25Similarity is a TF-IDF-like retrieval function which uses the term frequency (TF) and the inverse document frequency (IDF) as variables to calculate relevance scores for each document-query pair, which is then used for ranking. 
+Azure Cognitive Search is in the process of adopting the official Lucene implementation of the Okapi BM25 algorithm, *BM25Similarity*, which will replace the previously used *ClassicSimilarity* implementation. Like the older ClassicSimilarity algorithm, BM25Similarity is a TF-IDF-like retrieval function that uses the term frequency (TF) and the inverse document frequency (IDF) as variables to calculate relevance scores for each document-query pair, which is then used for ranking. 
 
 While conceptually similar to the older Classic Similarity algorithm, BM25 takes its root in probabilistic information retrieval to improve upon it. BM25 also offers advanced customization options, such as allowing the user to decide how the relevance score scales with the term frequency of matched terms.
 
@@ -55,11 +55,15 @@ PUT https://[search service name].search.windows.net/indexes/[index name]?api-ve
 }
 ```
 
-For services created before July 15, 2020: If the similarity property is omitted or set to null, the index will use the old classic similarity algorithm.
+The **similarity** property is useful during this interim period when both algorithms are available, on existing services only. 
 
-For services created after July 15, 2020: If the similarity is omitted or set to null, the index will use the new BM25 similarity algorithm.
+| Property | Description |
+|----------|-------------|
+| similarity | Optional. Valid values include *"#Microsoft.Azure.Search.ClassicSimilarity"* or *"#Microsoft.Azure.Search.BM25Similarity"*. <br/> Requires `api-version=2019-05-06-Preview` or later on a search service created prior to July 15, 2020. |
 
-You can also explicitly set the similarity value to be one of the following two values: *"#Microsoft.Azure.Search.ClassicSimilarity"* or *"#Microsoft.Azure.Search.BM25Similarity"*.
+For new services created after July 15, 2020, BM25 is used automatically and is the sole similarity algorithm. If you try to set **similarity** to `ClassicSimilarity` on a new service, a 400 error will be returned because that algorithm is not supported on a new service.
+
+For existing services created before July 15, 2020, the Classic similarity remains the default algorithm. If the **similarity** property is omitted or set to null, the index uses the Classic algorithm. If you want to use the new algorithm, you will need to set **similarity** as described above.
 
 ## BM25 similarity parameters
 

articles/search/index-similarity-and-scoring.md

@@ -50,7 +50,7 @@ GET https://[service name].search.windows.net/indexes/[index name]/docs?scoringS
 
 ## Similarity ranking algorithms
 
-Azure Cognitive Search supports two different similarity ranking algorithms: A *classic similarity* algorithm and the official implementation of the *Okapi BM25* algorithm (currently in preview). The classical similarity algorithm is the default algorithm, but starting July 15, any new services created after that date use the new BM25 algorithm. It will be the only algorithm available.
+Azure Cognitive Search supports two different similarity ranking algorithms: A *classic similarity* algorithm and the official implementation of the *Okapi BM25* algorithm (currently in preview). The classical similarity algorithm is the default algorithm, but starting July 15, any new services created after that date use the new BM25 algorithm. It will be the only algorithm available on new services.
 
 For now, you can specify which similarity ranking algorithm you would like to use. For more information, see [Ranking algorithm](index-ranking-similarity.md).