more examples and edits

Author: HeidiSteen

articles/search/hybrid-search-how-to-query.md

@@ -235,9 +235,17 @@ api-key: {{admin-api-key}}
 
 ## Relevance tuning through maxTextRecallSize and countAndFacetMode (preview)
 
-In a `hybridSearch` query parameter object, specify the maximum number of documents recalled through the text portion of a hybrid (text and vector) query. The default is `1000` documents. With this parameter, you can increase or decrease the number of results returned in hybrid queries. Reducing the number of text documents retrieved can significantly improve performance. 
+In a `hybridSearch` query parameter object, specify the maximum number of documents recalled through the text portion of a hybrid (text and vector) query. You can also set `countAndFacetMode` property to report the counts for the text query (and for facets if you're using them) to the document limits set by `maxTextRecallSize`.
+
+The default maximum is `1000` documents. 
+
+With `maxTextRecallSize`, you can increase or decrease the number of BM25-ranked results returned in hybrid queries. 
+
++ Reducing the number of text documents retrieved can significantly improve performance, assuming vector similarity search is generally performing better. You can also consider [vector weighting](vector-search-how-to-query.md#vector-weighting-preview) as an alternate approach for increasing the importance of vector queries.
+
++ Increasing the number of text documents is useful if you have a large index, and the `1000` document default is not capturing a sufficient number of results. With a larger BM25-ranked result set, you can also set `top`, `skip`, and `next` to retrieve portions of those results.
+
 
-You can set `countAndFacetMode` property to report the counts for the text query (and for facets if you're using them) to the document limits set by `maxTextRecallSize`.
 
 Use [Search - POST](/rest/api/searchservice/documents/search-post?view=rest-searchservice-2024-05-01-preview&preserve-view=true) or [Search - GET](/rest/api/searchservice/documents/search-get?view=rest-searchservice-2024-05-01-preview&preserve-view=true) in `2024-05-01-Preview` to specify these parameters.
 
@@ -263,6 +271,30 @@ POST https://[service-name].search.windows.net/indexes/[index-name]/docs/search?
     } 
 ```
 
+The next example sets `maxTextRecallSize` to 2,000. It also sets `countAndFacetMode` to scope acounts to just those results from `maxTextRecallSize`. It also uses top to return 200 in the initial results.
+
+```http
+POST https://[service-name].search.windows.net/indexes/[index-name]/docs/search?api-version=2024-05-01-Preview 
+
+    { 
+      "vectorQueries": [ 
+        { 
+          "kind": "vector", 
+          "vector": [1.0, 2.0, 3.0], 
+          "fields": "my_vector_field", 
+          "k": 10 
+        } 
+      ], 
+      "search": "hello world",
+      "top": 200,
+      "skip": 0,
+      "hybridSearch": { 
+        "maxTextRecallSize": 2000, 
+        "countAndFacetMode": "countRetrievableResults" 
+      } 
+    } 
+```
+
 ## Configure a query response
 
 When you're setting up the hybrid query, think about the response structure. The response is a flattened rowset. Parameters on the query determine which fields are in each row and how many rows are in the response. The search engine ranks the matching documents and returns the most relevant results.

articles/search/hybrid-search-ranking.md

@@ -57,13 +57,27 @@ The following chart identifies the scoring property returned on each match, algo
 
 Semantic ranking doesn't participate in RRF. Its score (`@search.rerankerScore`) is always reported separately in the query response. Semantic ranking can rerank full text and hybrid search results, assuming those results include fields having semantically rich content.
 
+## Weighted scores
+
+Starting in 2024-05-01-preview, you can [weight vector queries](vector-search-how-to-query.md#vector-weighting-preview) to increase or decrease their importance in a hybrid query.
+
+Recall that when computing RRF for a certain document, the search engine looks at the rank of that document for each result set where it shows up. Assume a document shows up three search result, where the results are from two vector queries and one text BM25-ranked query. The position of the document varies in each result:
+
++ vector results one, match is in position 1
++ vector results two, match is in position 5
++ BM25 results, match is in position 10
+
+The document's position in each result set corresponds to an initial score, which are added up to create the final RRF score for that document. 
+
+If you add vector weighting, the initial scores are subect to a weighting multipilier that increases or decreases the score. The default is 1.0, which means no weighting and the initial score is used as-is in RRF scoring. However, if you add a weight of 0.5, the score is reduced and that result becomes less important in the combined ranking. Conversely, if you add a weight of 2.0, the score becomes a larger factor in the overall RRF score.
+
 ## Number of ranked results in a hybrid query response
 
 By default, if you aren't using pagination, the search engine returns the top 50 highest ranking matches for full text search, and the most similar `k` matches for vector search. In a hybrid query, `top` determines the number of results in the response. Based on defaults, the top 50 highest ranked matches of the unified result set are returned. 
 
-Often, the search engine finds more results than `top` and `k`. To return more results, use the paging parameters `top`, `skip`, and `next`. Paging is how you determine the number of results on each logical page and navigate through the full payload. 
+Often, the search engine finds more results than `top` and `k`. To return more results, use the paging parameters `top`, `skip`, and `next`. Paging is how you determine the number of results on each logical page and navigate through the full payload. You can set `maxTextRecallSize` to larger values (the default is 1,000) to return more results from the text side of hybrid query.
 
-Full text search is subject to a maximum limit of 1,000 matches (see [API response limits](search-limits-quotas-capacity.md#api-response-limits)). Once 1,000 matches are found, the search engine no longer looks for more.
+By default, full text search is subject to a maximum limit of 1,000 matches (see [API response limits](search-limits-quotas-capacity.md#api-response-limits)). Once 1,000 matches are found, the search engine no longer looks for more.
 
 For more information, see [How to work with search results](search-pagination-page-layout.md).
 

articles/search/vector-search-how-to-query.md

@@ -634,9 +634,11 @@ Add a `weight` query parameter to specify the relative weight of each vector inc
 
 The default is 1.0 and the value must be a positive number larger than zero.
 
-Weights are used when calculating the [reciprocal rank fusion](hybrid-search-ranking.md) scores of each document. The calculation is multiplier of the `weight` value against the rank score of the document within its respective result set.
+Weights are used when calculating the [reciprocal rank fusion](hybrid-search-ranking.md#weighted-scores) scores of each document. The calculation is multiplier of the `weight` value against the rank score of the document within its respective result set.
 
-The following example is a hybrid query with two vector query strings and one text string. Weights are assigned to the vector queries. The first query is 0.5 or half the weight, reducing its importance in the request. The second vectory query is twice as important. Text queries have no weight parameters, but you can increase or decrease their importance by setting [maxTextRecallSize](hybrid-search-how-to-query.md#ranking).
+The following example is a hybrid query with two vector query strings and one text string. Weights are assigned to the vector queries. The first query is 0.5 or half the weight, reducing its importance in the request. The second vectory query is twice as important. 
+
+Text queries have no weight parameters, but you can increase or decrease their importance by setting [maxTextRecallSize](hybrid-search-how-to-query.md#ranking).
 
 ```http
 POST https://[service-name].search.windows.net/indexes/[index-name]/docs/search?api-version=2024-05-01-Preview