BM25 scoping statements

Author: HeidiSteen

articles/search/index-ranking-similarity.md

@@ -6,14 +6,19 @@ author: HeidiSteen
 ms.author: heidist
 ms.service: cognitive-search
 ms.topic: how-to
-ms.date: 09/07/2023
+ms.date: 09/25/2023
 ---
 
 # Configure BM25 relevance scoring
 
 In this article, learn how to configure the [BM25 relevance scoring algorithm](https://en.wikipedia.org/wiki/Okapi_BM25) used by Azure Cognitive Search for full text search queries. It also explains how to enable BM25 on older search services.
 
-BM25 applies to strings (text) on fields having a "searchable" attribution. At query time, the search engine uses BM25 to calculate a **@searchScore** for each match in a given query. Matching documents are ranked by their search score, with the top results returned in the query response.
+BM25 applies to:
+
++ Queries that use the `search` parameter for full text search, on text fields having a `searchable` attribution.
++ Scoring is scoped to `searchFields`, or to all `searchable` fields if `searchFields` is null.
+
+The search engine uses BM25 to calculate a **@searchScore** for each match in a given query. Matching documents are ranked by their search score, with the top results returned in the query response. It's possible to get some [score variation](index-similarity-and-scoring.md#score-variation) in results, even from the same query executing over the same search index, but usually these variations are small and don't change the overall ranking of results.
 
 BM25 has defaults for weighting term frequency and document length. You can customize these properties if the defaults aren't suited to your content. Configuration changes are scoped to individual indexes, which means you can adjust relevance scoring based on the characteristics of each index.
 

articles/search/search-query-create.md

@@ -23,9 +23,9 @@ If you're building a query for [full text search](search-lucene-query-architectu
 
 ## Example of a full text query request
 
-In Azure Cognitive Search, a query is a read-only request against the docs collection of a single search index. A full text query is specified in a `search` parameter and consists of terms, quote-enclosed phrases, and operators.
+In Azure Cognitive Search, a query is a read-only request against the docs collection of a single search index. 
 
-Other parameters add more definition. For example, `searchFields` scopes query execution to specific fields, `select` specifies which fields are returned in results, and `count` returns the number of matches found in the index.
+A full text query is specified in a `search` parameter and consists of terms, quote-enclosed phrases, and operators. Other parameters add more definition. For example, `searchFields` scopes query execution to specific fields, `select` specifies which fields are returned in results, and `count` returns the number of matches found in the index.
 
 The following [Search Documents REST API](/rest/api/searchservice/search-documents) call illustrates a query request using the aforementioned parameters.
 
@@ -55,11 +55,11 @@ In the portal, when you open an index, you can work with Search Explorer alongsi
 
 1. Open **Indexes** and select an index.
 
-1. An index opens to the **Search explorer** tab so that you can query right away. A query string can use simple or full syntax, with support for all query parameters (filter, select, searchFields, and so on).
+1. An index opens to the [**Search explorer**](search-explorer.md) tab so that you can query right away. A query string can use simple or full syntax, with support for all query parameters (filter, select, searchFields, and so on). Here's a full text search query expression that works for the Hotels sample index:
 
-   [Search explorer (portal)](search-explorer.md) is a query interface in the Azure portal that runs queries against indexes on the underlying search service. Internally, the portal makes [Search Documents](/rest/api/searchservice/search-documents) requests, but can't invoke Autocomplete, Suggestions, or Document Lookup. 
+   `search=pool spa +airport&$searchFields=Description,Tags&$select=HotelName,Description,Category&$count=true`
 
-1. Change the REST API version if you require search behaviors from a specific version. 
+Notice that you can change the REST API version if you require search behaviors from a specific version, or switch to **JSON view** if you want to paste in the JSON definition of a query. For more information about what a JSON definition looks like, see [Search Documents (REST)](/rest/api/searchservice/search-documents).
 
 ### [**REST API**](#tab/rest-text-query)
 
@@ -80,6 +80,8 @@ The following Azure SDKs provide a **SearchClient** that has methods for formula
 | JavaScript | [SearchClient](/javascript/api/@azure/search-documents/searchclient) | [SDK examples](/javascript/api/overview/azure/search-documents-readme?view=azure-node-latest#examples&preserve-view=true) |
 | Python | [SearchClient](/python/api/azure-search-documents/azure.search.documents.searchclient) | [sample_simple_query.py ](https://github.com/Azure/azure-sdk-for-python/blob/7cd31ac01fed9c790cec71de438af9c45cb45821/sdk/search/azure-search-documents/samples/sample_simple_query.py) |
 
+---
+
 ## Choose a query type: simple | full
 
 If your query is full text search, a query parser is used to process any text that's passed as search terms and phrases. Azure Cognitive Search offers two query parsers.