Prepare azure-search-documents for September 2023 Beta Release (#36790)

Prepare azure-search-documents for September 2023 Beta Release
Azure · Sep 15, 2023 · e8d5bc0 · e8d5bc0
1 parent 152a5df
commit e8d5bc0
Show file tree

Hide file tree

Showing 6 changed files with 113 additions and 13 deletions.
diff --git a/sdk/search/azure-search-documents/CHANGELOG.md b/sdk/search/azure-search-documents/CHANGELOG.md
@@ -1,14 +1,14 @@
 # Release History
 
-## 11.6.0-beta.9 (Unreleased)
+## 11.6.0-beta.9 (2023-09-15)
 
-### Features Added
-
-### Breaking Changes
+### Other Changes
 
-### Bugs Fixed
+#### Dependency Updates
 
-### Other Changes
+- Upgraded `azure-core-http-netty` from `1.13.6` to version `1.13.7`.
+- Upgraded `azure-core-serializer-json-jackson` from `1.4.3` to version `1.4.4`.
+- Upgraded `azure-core` from `1.42.0` to version `1.43.0`.
 
 ## 11.5.10 (2023-08-18)
 

diff --git a/sdk/search/azure-search-documents/README.md b/sdk/search/azure-search-documents/README.md
@@ -73,7 +73,7 @@ add the direct dependency to your project as follows.
 <dependency>
     <groupId>com.azure</groupId>
     <artifactId>azure-search-documents</artifactId>
-    <version>11.6.0-beta.8</version>
+    <version>11.6.0-beta.9</version>
 </dependency>
 ```
 [//]: # ({x-version-update-end})

diff --git a/...ch/azure-search-documents/src/main/java/com/azure/search/documents/SearchAsyncClient.java b/...ch/azure-search-documents/src/main/java/com/azure/search/documents/SearchAsyncClient.java
@@ -749,6 +749,14 @@ Mono<Response<Long>> getDocumentCountWithResponse(Context context) {
      * If {@code searchText} is set to null or {@code "*"} all documents will be matched, see
      * <a href="https://docs.microsoft.com/rest/api/searchservice/Simple-query-syntax-in-Azure-Search">simple query
      * syntax in Azure Cognitive Search</a> for more information about search query syntax.
+     * <p>
+     * The {@link SearchPagedFlux} will iterate through search result pages until all search results are returned.
+     * Each page is determined by the {@code $skip} and {@code $top} values and the Search service has a limit on the
+     * number of documents that can be skipped, more information about the {@code $skip} limit can be found at
+     * <a href="https://learn.microsoft.com/rest/api/searchservice/search-documents">Search Documents REST API</a> and
+     * reading the {@code $skip} description. If the total number of results exceeds the {@code $skip} limit the
+     * {@link SearchPagedFlux} won't prevent you from exceeding the {@code $skip} limit. To prevent exceeding the limit
+     * you can track the number of documents returned and stop requesting new pages when the limit is reached.
      *
      * <p><strong>Code Sample</strong></p>
      *
@@ -758,9 +766,18 @@ Mono<Response<Long>> getDocumentCountWithResponse(Context context) {
      * <pre>
      * SearchPagedFlux searchPagedFlux = SEARCH_ASYNC_CLIENT.search&#40;&quot;searchText&quot;&#41;;
      * searchPagedFlux.getTotalCount&#40;&#41;.subscribe&#40;
-     *     count -&gt; System.out.printf&#40;&quot;There are around %d results.&quot;, count&#41;
-     * &#41;;
+     *     count -&gt; System.out.printf&#40;&quot;There are around %d results.&quot;, count&#41;&#41;;
+     *
+     * AtomicLong numberOfDocumentsReturned = new AtomicLong&#40;&#41;;
      * searchPagedFlux.byPage&#40;&#41;
+     *     .takeUntil&#40;page -&gt; &#123;
+     *         if &#40;numberOfDocumentsReturned.addAndGet&#40;page.getValue&#40;&#41;.size&#40;&#41;&#41; &gt;= SEARCH_SKIP_LIMIT&#41; &#123;
+     *             &#47;&#47; Reached the $skip limit, stop requesting more documents.
+     *             return true;
+     *         &#125;
+     *
+     *         return false;
+     *     &#125;&#41;
      *     .subscribe&#40;resultResponse -&gt; &#123;
      *         for &#40;SearchResult result: resultResponse.getValue&#40;&#41;&#41; &#123;
      *             SearchDocument searchDocument = result.getDocument&#40;SearchDocument.class&#41;;
@@ -789,6 +806,14 @@ public SearchPagedFlux search(String searchText) {
      * If {@code searchText} is set to null or {@code "*"} all documents will be matched, see
      * <a href="https://docs.microsoft.com/rest/api/searchservice/Simple-query-syntax-in-Azure-Search">simple query
      * syntax in Azure Cognitive Search</a> for more information about search query syntax.
+     * <p>
+     * The {@link SearchPagedFlux} will iterate through search result pages until all search results are returned.
+     * Each page is determined by the {@code $skip} and {@code $top} values and the Search service has a limit on the
+     * number of documents that can be skipped, more information about the {@code $skip} limit can be found at
+     * <a href="https://learn.microsoft.com/rest/api/searchservice/search-documents">Search Documents REST API</a> and
+     * reading the {@code $skip} description. If the total number of results exceeds the {@code $skip} limit the
+     * {@link SearchPagedFlux} won't prevent you from exceeding the {@code $skip} limit. To prevent exceeding the limit
+     * you can track the number of documents returned and stop requesting new pages when the limit is reached.
      *
      * <p><strong>Code Sample</strong></p>
      *
@@ -801,7 +826,16 @@ public SearchPagedFlux search(String searchText) {
      *
      * pagedFlux.getTotalCount&#40;&#41;.subscribe&#40;count -&gt; System.out.printf&#40;&quot;There are around %d results.&quot;, count&#41;&#41;;
      *
+     * AtomicLong numberOfDocumentsReturned = new AtomicLong&#40;&#41;;
      * pagedFlux.byPage&#40;&#41;
+     *     .takeUntil&#40;page -&gt; &#123;
+     *         if &#40;numberOfDocumentsReturned.addAndGet&#40;page.getValue&#40;&#41;.size&#40;&#41;&#41; &gt;= SEARCH_SKIP_LIMIT&#41; &#123;
+     *             &#47;&#47; Reached the $skip limit, stop requesting more documents.
+     *             return true;
+     *         &#125;
+     *
+     *         return false;
+     *     &#125;&#41;
      *     .subscribe&#40;searchResultResponse -&gt; searchResultResponse.getValue&#40;&#41;.forEach&#40;searchDocument -&gt; &#123;
      *         for &#40;Map.Entry&lt;String, Object&gt; keyValuePair
      *             : searchDocument.getDocument&#40;SearchDocument.class&#41;.entrySet&#40;&#41;&#41; &#123;

diff --git a/sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/SearchClient.java b/sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/SearchClient.java
@@ -682,6 +682,14 @@ public Response<Long> getDocumentCountWithResponse(Context context) {
      * If {@code searchText} is set to null or {@code "*"} all documents will be matched, see
      * <a href="https://docs.microsoft.com/rest/api/searchservice/Simple-query-syntax-in-Azure-Search">simple query
      * syntax in Azure Cognitive Search</a> for more information about search query syntax.
+     * <p>
+     * The {@link SearchPagedIterable} will iterate through search result pages until all search results are returned.
+     * Each page is determined by the {@code $skip} and {@code $top} values and the Search service has a limit on the
+     * number of documents that can be skipped, more information about the {@code $skip} limit can be found at
+     * <a href="https://learn.microsoft.com/rest/api/searchservice/search-documents">Search Documents REST API</a> and
+     * reading the {@code $skip} description. If the total number of results exceeds the {@code $skip} limit the
+     * {@link SearchPagedIterable} won't prevent you from exceeding the {@code $skip} limit. To prevent exceeding the
+     * limit you can track the number of documents returned and stop requesting new pages when the limit is reached.
      *
      * <p><strong>Code Sample</strong></p>
      *
@@ -692,15 +700,22 @@ public Response<Long> getDocumentCountWithResponse(Context context) {
      * SearchPagedIterable searchPagedIterable = SEARCH_CLIENT.search&#40;&quot;searchText&quot;&#41;;
      * System.out.printf&#40;&quot;There are around %d results.&quot;, searchPagedIterable.getTotalCount&#40;&#41;&#41;;
      *
+     * long numberOfDocumentsReturned = 0;
      * for &#40;SearchPagedResponse resultResponse: searchPagedIterable.iterableByPage&#40;&#41;&#41; &#123;
      *     System.out.println&#40;&quot;The status code of the response is &quot; + resultResponse.getStatusCode&#40;&#41;&#41;;
+     *     numberOfDocumentsReturned += resultResponse.getValue&#40;&#41;.size&#40;&#41;;
      *     resultResponse.getValue&#40;&#41;.forEach&#40;searchResult -&gt; &#123;
      *         for &#40;Map.Entry&lt;String, Object&gt; keyValuePair: searchResult
      *             .getDocument&#40;SearchDocument.class&#41;.entrySet&#40;&#41;&#41; &#123;
      *             System.out.printf&#40;&quot;Document key %s, document value %s&quot;, keyValuePair.getKey&#40;&#41;,
      *                 keyValuePair.getValue&#40;&#41;&#41;;
      *         &#125;
      *     &#125;&#41;;
+     *
+     *     if &#40;numberOfDocumentsReturned &gt;= SEARCH_SKIP_LIMIT&#41; &#123;
+     *         &#47;&#47; Reached the $skip limit, stop requesting more documents.
+     *         break;
+     *     &#125;
      * &#125;
      * </pre>
      * <!-- end com.azure.search.documents.SearchClient.search#String -->
@@ -722,6 +737,14 @@ public SearchPagedIterable search(String searchText) {
      * If {@code searchText} is set to null or {@code "*"} all documents will be matched, see
      * <a href="https://docs.microsoft.com/rest/api/searchservice/Simple-query-syntax-in-Azure-Search">simple query
      * syntax in Azure Cognitive Search</a> for more information about search query syntax.
+     * <p>
+     * The {@link SearchPagedIterable} will iterate through search result pages until all search results are returned.
+     * Each page is determined by the {@code $skip} and {@code $top} values and the Search service has a limit on the
+     * number of documents that can be skipped, more information about the {@code $skip} limit can be found at
+     * <a href="https://learn.microsoft.com/rest/api/searchservice/search-documents">Search Documents REST API</a> and
+     * reading the {@code $skip} description. If the total number of results exceeds the {@code $skip} limit the
+     * {@link SearchPagedIterable} won't prevent you from exceeding the {@code $skip} limit. To prevent exceeding the
+     * limit you can track the number of documents returned and stop requesting new pages when the limit is reached.
      *
      * <p><strong>Code Sample</strong></p>
      *
@@ -732,15 +755,23 @@ public SearchPagedIterable search(String searchText) {
      * SearchPagedIterable searchPagedIterable = SEARCH_CLIENT.search&#40;&quot;searchText&quot;,
      *     new SearchOptions&#40;&#41;.setOrderBy&#40;&quot;hotelId desc&quot;&#41;, new Context&#40;KEY_1, VALUE_1&#41;&#41;;
      * System.out.printf&#40;&quot;There are around %d results.&quot;, searchPagedIterable.getTotalCount&#40;&#41;&#41;;
+     *
+     * long numberOfDocumentsReturned = 0;
      * for &#40;SearchPagedResponse resultResponse: searchPagedIterable.iterableByPage&#40;&#41;&#41; &#123;
      *     System.out.println&#40;&quot;The status code of the response is &quot; + resultResponse.getStatusCode&#40;&#41;&#41;;
+     *     numberOfDocumentsReturned += resultResponse.getValue&#40;&#41;.size&#40;&#41;;
      *     resultResponse.getValue&#40;&#41;.forEach&#40;searchResult -&gt; &#123;
      *         for &#40;Map.Entry&lt;String, Object&gt; keyValuePair: searchResult
      *             .getDocument&#40;SearchDocument.class&#41;.entrySet&#40;&#41;&#41; &#123;
      *             System.out.printf&#40;&quot;Document key %s, document value %s&quot;, keyValuePair.getKey&#40;&#41;,
      *                 keyValuePair.getValue&#40;&#41;&#41;;
      *         &#125;
      *     &#125;&#41;;
+     *
+     *     if &#40;numberOfDocumentsReturned &gt;= SEARCH_SKIP_LIMIT&#41; &#123;
+     *         &#47;&#47; Reached the $skip limit, stop requesting more documents.
+     *         break;
+     *     &#125;
      * &#125;
      * </pre>
      * <!-- end com.azure.search.documents.SearchClient.search#String-SearchOptions-Context -->
@@ -779,7 +810,7 @@ private SearchPagedResponse search(SearchRequest request, String continuationTok
             SearchPagedResponse page = new SearchPagedResponse(
                 new SimpleResponse<>(response, getSearchResults(result, serializer)),
                 createContinuationToken(result, serviceVersion), result.getFacets(), result.getCount(),
-                result.getCoverage(), result.getAnswers(), result.getSemanticPartialResponseReason(), 
+                result.getCoverage(), result.getAnswers(), result.getSemanticPartialResponseReason(),
                 result.getSemanticPartialResponseType());
             if (continuationToken == null) {
                 firstPageResponseWrapper.setFirstPageResponse(page);

diff --git a/sdk/search/azure-search-documents/src/samples/README.md b/sdk/search/azure-search-documents/src/samples/README.md
@@ -61,7 +61,7 @@ add the direct dependency to your project as follows.
 <dependency>
     <groupId>com.azure</groupId>
     <artifactId>azure-search-documents</artifactId>
-    <version>11.6.0-beta.8</version>
+    <version>11.6.0-beta.9</version>
 </dependency>
 ```
 [//]: # ({x-version-update-end})

diff --git a/...arch-documents/src/samples/java/com/azure/search/documents/SearchJavaDocCodeSnippets.java b/...arch-documents/src/samples/java/com/azure/search/documents/SearchJavaDocCodeSnippets.java
@@ -58,10 +58,12 @@
 import java.util.Collections;
 import java.util.List;
 import java.util.Map;
+import java.util.concurrent.atomic.AtomicLong;
 
 @SuppressWarnings("unused")
 public class SearchJavaDocCodeSnippets {
     private static final SearchClient SEARCH_CLIENT = new SearchClientBuilder().buildClient();
+    private static final long SEARCH_SKIP_LIMIT = 100_000; // May change over time
 
     /**
      * Code snippet for creating a {@link SearchClient}.
@@ -312,15 +314,22 @@ public void searchDocuments() {
         SearchPagedIterable searchPagedIterable = SEARCH_CLIENT.search("searchText");
         System.out.printf("There are around %d results.", searchPagedIterable.getTotalCount());
 
+        long numberOfDocumentsReturned = 0;
         for (SearchPagedResponse resultResponse: searchPagedIterable.iterableByPage()) {
             System.out.println("The status code of the response is " + resultResponse.getStatusCode());
+            numberOfDocumentsReturned += resultResponse.getValue().size();
             resultResponse.getValue().forEach(searchResult -> {
                 for (Map.Entry<String, Object> keyValuePair: searchResult
                     .getDocument(SearchDocument.class).entrySet()) {
                     System.out.printf("Document key %s, document value %s", keyValuePair.getKey(),
                         keyValuePair.getValue());
                 }
             });
+
+            if (numberOfDocumentsReturned >= SEARCH_SKIP_LIMIT) {
+                // Reached the $skip limit, stop requesting more documents.
+                break;
+            }
         }
         // END: com.azure.search.documents.SearchClient.search#String
     }
@@ -333,15 +342,23 @@ public void searchDocumentsWithOptions() {
         SearchPagedIterable searchPagedIterable = SEARCH_CLIENT.search("searchText",
             new SearchOptions().setOrderBy("hotelId desc"), new Context(KEY_1, VALUE_1));
         System.out.printf("There are around %d results.", searchPagedIterable.getTotalCount());
+
+        long numberOfDocumentsReturned = 0;
         for (SearchPagedResponse resultResponse: searchPagedIterable.iterableByPage()) {
             System.out.println("The status code of the response is " + resultResponse.getStatusCode());
+            numberOfDocumentsReturned += resultResponse.getValue().size();
             resultResponse.getValue().forEach(searchResult -> {
                 for (Map.Entry<String, Object> keyValuePair: searchResult
                     .getDocument(SearchDocument.class).entrySet()) {
                     System.out.printf("Document key %s, document value %s", keyValuePair.getKey(),
                         keyValuePair.getValue());
                 }
             });
+
+            if (numberOfDocumentsReturned >= SEARCH_SKIP_LIMIT) {
+                // Reached the $skip limit, stop requesting more documents.
+                break;
+            }
         }
         // END: com.azure.search.documents.SearchClient.search#String-SearchOptions-Context
     }
@@ -662,9 +679,18 @@ public void searchDocumentsAsync() {
         // BEGIN: com.azure.search.documents.SearchAsyncClient.search#String
         SearchPagedFlux searchPagedFlux = SEARCH_ASYNC_CLIENT.search("searchText");
         searchPagedFlux.getTotalCount().subscribe(
-            count -> System.out.printf("There are around %d results.", count)
-        );
+            count -> System.out.printf("There are around %d results.", count));
+
+        AtomicLong numberOfDocumentsReturned = new AtomicLong();
         searchPagedFlux.byPage()
+            .takeUntil(page -> {
+                if (numberOfDocumentsReturned.addAndGet(page.getValue().size()) >= SEARCH_SKIP_LIMIT) {
+                    // Reached the $skip limit, stop requesting more documents.
+                    return true;
+                }
+
+                return false;
+            })
             .subscribe(resultResponse -> {
                 for (SearchResult result: resultResponse.getValue()) {
                     SearchDocument searchDocument = result.getDocument(SearchDocument.class);
@@ -686,7 +712,16 @@ public void searchDocumentsWithOptionsAsync() {
 
         pagedFlux.getTotalCount().subscribe(count -> System.out.printf("There are around %d results.", count));
 
+        AtomicLong numberOfDocumentsReturned = new AtomicLong();
         pagedFlux.byPage()
+            .takeUntil(page -> {
+                if (numberOfDocumentsReturned.addAndGet(page.getValue().size()) >= SEARCH_SKIP_LIMIT) {
+                    // Reached the $skip limit, stop requesting more documents.
+                    return true;
+                }
+
+                return false;
+            })
             .subscribe(searchResultResponse -> searchResultResponse.getValue().forEach(searchDocument -> {
                 for (Map.Entry<String, Object> keyValuePair
                     : searchDocument.getDocument(SearchDocument.class).entrySet()) {