Merge pull request #6565 from HeidiSteen/heidist-freshness

freshness pass, August 2025

Author: Stacyrch140

articles/search/includes/quickstarts/search-get-started-rbac-rest.md

@@ -4,7 +4,7 @@ author: haileytap
 ms.author: haileytapia
 ms.service: azure-ai-search
 ms.topic: include
-ms.date: 07/09/2025
+ms.date: 08/13/2025
 ---
 
 In this quickstart, you use role-based access control (RBAC) and Microsoft Entra ID to establish a keyless connection to your Azure AI Search service. You then use REST in Visual Studio Code to interact with your service.
@@ -33,10 +33,18 @@ To get your token:
 
 1. On your local system, open a command-line tool.
 
-1. Sign in to Azure. If you have multiple subscriptions, select the one whose ID you obtained in [Get service information](#get-service-information).
+1. Check for the active tenant and subscription in your local environment.
 
    ```azurecli
-   az login
+   az account show
+   ```
+
+1. If the active subscription and tenant aren't valid for your search service, change the variables. You can check for the subscription ID on the search service overview page in the Azure portal. You can check for the tenant ID by clicking through to the subscription. Make a note of the values that are valid for your search service and run the following commands to update your local environment.
+
+   ```azurecli
+    az account set --subscription <your-subscription-id>
+
+    az login --tenant <your-tenant-id>
    ```
 
 1. Generate an access token.

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

@@ -8,12 +8,12 @@ ms.service: azure-ai-search
 ms.custom:
   - ignite-2023
 ms.topic: conceptual
-ms.date: 01/17/2025
+ms.date: 08/13/2025
 ---
 
 # Relevance in keyword search (BM25 scoring)
 
-This article explains the BM25 relevance scoring algorithm used to compute search scores for [full text search](search-lucene-query-architecture.md). BM25 relevance is exclusive to full text search. Filter queries, autocomplete and suggested queries, wildcard search, and fuzzy search queries aren't scored or ranked for relevance.
+This article explains the BM25 relevance scoring algorithm used to compute search scores for [full text search](search-lucene-query-architecture.md). BM25 relevance applies to full text search only. Filter queries, autocomplete and suggested queries, wildcard search, and fuzzy search queries aren't scored or ranked for relevance.
 
 ## Scoring algorithms used in full text search
 
@@ -133,40 +133,88 @@ In Azure AI Search, for keyword search and the text portion of a hybrid query, y
 
 ## featuresMode parameter (preview)
 
-[Search Documents](/rest/api/searchservice/documents/search-post) requests support a featuresMode parameter that provides more detail about a BM25 relevance score at the field level. Whereas the `@searchScore` is calculated for the document all-up (how relevant is this document in the context of this query), featuresMode reveals information about individual fields, as expressed in a `@search.features` structure. The structure contains all fields used in the query (either specific fields through **searchFields** in a query, or all fields attributed as **searchable** in an index). 
+> [!NOTE]
+> The `featuresMode` parameter isn't documented in the REST APIs, but you can use it on a preview REST API call to Search Documents for text (Keyword) search that's BM25-ranked.
+
+[Search Documents (preview)](/rest/api/searchservice/documents/search-post?view=rest-searchservice-2025-05-01-preview&preserve-view=true) requests support a `featuresMode` parameter that provides more detail about a BM25 relevance score at the field level. Whereas the `@searchScore` is calculated for the document all-up (how relevant is this document in the context of this query), featuresMode reveals information about individual fields, as expressed in a `@search.features` structure. The structure contains all fields used in the query (either specific fields through **searchFields** in a query, or all fields attributed as **searchable** in an index).
+
+Valid values for featuresMode:
+
++ "none" (default). No feature-level scoring details are returned.
++ "enabled". Returns detailed scoring breakdowns per field
 
 For each field, `@search.features` give you the following values:
 
 + Number of unique tokens found in the field
 + Similarity score, or a measure of how similar the content of the field is, relative to the query term
 + Term frequency, or the number of times the query term was found in the field
 
-For a query that targets the "description" and "title" fields, a response that includes `@search.features` might look like this:
+This parameter is especially useful when you're trying to understand why certain documents rank higher or lower in search results. It helps explain how different fields contribute to the overall score.
+
+For a query that targets a "description" field, a request might look like this:
+
+```http
+POST {{baseUrl}}/indexes/hotels-sample-index/docs/search?api-version=2025-05-01-preview  HTTP/1.1
+  Content-Type: application/json
+  Authorization: Bearer {{accessToken}}
+
+    {
+        "search": "lake view",
+        "select": "HotelId, HotelName, Tags, Description",
+        "featuresMode": "enabled",
+        "searchFields": "Description, Tags",
+        "count": true
+    }
+```
+
+A response that includes `@search.features` might look like the following example.
 
 ```json
-"value": [
- {
-    "@search.score": 5.1958685,
-    "@search.features": {
-        "description": {
-            "uniqueTokenMatches": 1.0,
-            "similarityScore": 0.29541412,
-            "termFrequency" : 2
+  "value": [
+    {
+      "@search.score": 3.0860271,
+      "@search.features": {
+        "Description": {
+          "uniqueTokenMatches": 2.0,
+          "similarityScore": 3.0860272,
+          "termFrequency": 2.0
+        }
+      },
+      "HotelName": "Downtown Mix Hotel",
+      "Description": "Mix and mingle in the heart of the city. Shop and dine, mix and mingle in the heart of downtown, where fab lake views unite with a cheeky design.",
+      "Tags": [
+        "air conditioning",
+        "laundry service",
+        "free wifi"
+      ]
+    },
+    {
+      "@search.score": 2.7294855,
+      "@search.features": {
+        "Description": {
+          "uniqueTokenMatches": 1.0,
+          "similarityScore": 1.6023184,
+          "termFrequency": 1.0
         },
-        "title": {
-            "uniqueTokenMatches": 3.0,
-            "similarityScore": 1.75451557,
-            "termFrequency" : 6
+        "Tags": {
+          "uniqueTokenMatches": 1.0,
+          "similarityScore": 1.1271671,
+          "termFrequency": 1.0
         }
+      },
+      "HotelName": "Ocean Water Resort & Spa",
+      "Description": "New Luxury Hotel for the vacation of a lifetime. Bay views from every room, location near the pier, rooftop pool, waterfront dining & more.",
+      "Tags": [
+        "view",
+        "pool",
+        "restaurant"
+      ]
     }
- }
-]
+  ]
 ```
 
 You can consume these data points in [custom scoring solutions](https://github.com/Azure-Samples/search-ranking-tutorial) or use the information to debug search relevance problems.
 
-The featuresMode parameter isn't documented in the REST APIs, but you can use it on a preview REST API call to Search Documents for text (Keyword) search that's BM25-ranked.
-
 ## Number of ranked results in a full text query response
 
 By default, if you aren't using pagination, the search engine returns the top 50 highest ranking matches for full text search. You can use the `top` parameter to return a smaller or larger number of items (up to 1,000 in a single response). You can use `skip` and `next` to page results. Paging determines the number of results on each logical page and supports content navigation. For more information, see [Shape search results](search-pagination-page-layout.md).