Package com.azure.search.documents

Class SearchAsyncClient

  • public final class SearchAsyncClient
extends Object
    This class provides a client that contains the operations for querying an index and uploading, merging, or deleting documents in an Azure Cognitive Search service.
    See Also:
    SearchClientBuilder

    • Method Detail

      • getIndexName

        public String getIndexName()
        Gets the name of the Azure Cognitive Search index.
        Returns:
        the indexName value.

      • getEndpoint

        public String getEndpoint()
        Gets the endpoint for the Azure Cognitive Search service.
        Returns:
        the endpoint value.

      • uploadDocuments

        public Mono<IndexDocumentsResult> uploadDocuments​(Iterable<?> documents)
        Uploads a collection of documents to the target index.

        Code Sample

        Upload dynamic SearchDocument. 

         SearchDocument searchDocument = new SearchDocument();
 searchDocument.put("hotelId", "1");
 searchDocument.put("hotelName", "test");
 searchAsyncClient.uploadDocuments(Collections.singletonList(searchDocument))
     .subscribe(result -> {
         for (IndexingResult indexingResult : result.getResults()) {
             System.out.printf("Does document with key %s upload successfully? %b%n",
                 indexingResult.getKey(), indexingResult.isSucceeded());
         }
     });
        Parameters:
        documents - collection of documents to upload to the target Index.
        Returns:
        The result of the document indexing actions.
        Throws:
        IndexBatchException - If some of the indexing actions fail but other actions succeed and modify the state of the index. This can happen when the Search Service is under heavy indexing load. It is important to explicitly catch this exception and check the return value IndexBatchException.getIndexingResults(). The indexing result reports the status of each indexing action in the batch, making it possible to determine the state of the index after a partial failure.
        See Also:
        Add, update, or delete documents

      • uploadDocumentsWithResponse

        public Mono<com.azure.core.http.rest.Response<IndexDocumentsResult>> uploadDocumentsWithResponse​(Iterable<?> documents,
                                                                                                 IndexDocumentsOptions options)
        Uploads a collection of documents to the target index.

        Code Sample

        Upload dynamic SearchDocument. 

         SearchDocument searchDocument = new SearchDocument();
 searchDocument.put("hotelId", "1");
 searchDocument.put("hotelName", "test");
 searchAsyncClient.uploadDocumentsWithResponse(Collections.singletonList(searchDocument), null)
     .subscribe(resultResponse -> {
         System.out.println("The status code of the response is " + resultResponse.getStatusCode());
         for (IndexingResult indexingResult : resultResponse.getValue().getResults()) {
             System.out.printf("Does document with key %s upload successfully? %b%n", indexingResult.getKey(),
                 indexingResult.isSucceeded());
         }
     });
        Parameters:
        documents - collection of documents to upload to the target Index.
        options - Options that allow specifying document indexing behavior.
        Returns:
        A response containing the result of the document indexing actions.
        Throws:
        IndexBatchException - If some of the indexing actions fail but other actions succeed and modify the state of the index. This can happen when the Search Service is under heavy indexing load. It is important to explicitly catch this exception and check the return value IndexBatchException.getIndexingResults(). The indexing result reports the status of each indexing action in the batch, making it possible to determine the state of the index after a partial failure.
        See Also:
        Add, update, or delete documents

      • mergeDocuments

        public Mono<IndexDocumentsResult> mergeDocuments​(Iterable<?> documents)
        Merges a collection of documents with existing documents in the target index.

        If the type of the document contains non-nullable primitive-typed properties, these properties may not merge correctly. If you do not set such a property, it will automatically take its default value (for example, 0 for int or false for boolean), which will override the value of the property currently stored in the index, even if this was not your intent. For this reason, it is strongly recommended that you always declare primitive-typed properties with their class equivalents (for example, an integer property should be of type Integer instead of int).

        Code Sample

        Merge dynamic SearchDocument. 

         SearchDocument searchDocument = new SearchDocument();
 searchDocument.put("hotelName", "merge");
 searchAsyncClient.mergeDocuments(Collections.singletonList(searchDocument))
     .subscribe(result -> {
         for (IndexingResult indexingResult : result.getResults()) {
             System.out.printf("Does document with key %s merge successfully? %b%n", indexingResult.getKey(),
                 indexingResult.isSucceeded());
         }
     });
        Parameters:
        documents - collection of documents to be merged
        Returns:
        document index result
        Throws:
        IndexBatchException - If some of the indexing actions fail but other actions succeed and modify the state of the index. This can happen when the Search Service is under heavy indexing load. It is important to explicitly catch this exception and check the return value IndexBatchException.getIndexingResults(). The indexing result reports the status of each indexing action in the batch, making it possible to determine the state of the index after a partial failure.
        See Also:
        Add, update, or delete documents

      • mergeDocumentsWithResponse

        public Mono<com.azure.core.http.rest.Response<IndexDocumentsResult>> mergeDocumentsWithResponse​(Iterable<?> documents,
                                                                                                IndexDocumentsOptions options)
        Merges a collection of documents with existing documents in the target index.

        If the type of the document contains non-nullable primitive-typed properties, these properties may not merge correctly. If you do not set such a property, it will automatically take its default value (for example, 0 for int or false for boolean), which will override the value of the property currently stored in the index, even if this was not your intent. For this reason, it is strongly recommended that you always declare primitive-typed properties with their class equivalents (for example, an integer property should be of type Integer instead of int).

        Code Sample

        Merge dynamic SearchDocument. 

         SearchDocument searchDocument = new SearchDocument();
 searchDocument.put("hotelName", "test");
 searchAsyncClient.mergeDocumentsWithResponse(Collections.singletonList(searchDocument), null)
     .subscribe(resultResponse -> {
         System.out.println("The status code of the response is " + resultResponse.getStatusCode());
         for (IndexingResult indexingResult : resultResponse.getValue().getResults()) {
             System.out.printf("Does document with key %s merge successfully? %b%n", indexingResult.getKey(),
                 indexingResult.isSucceeded());
         }
     });
        Parameters:
        documents - collection of documents to be merged
        options - Options that allow specifying document indexing behavior.
        Returns:
        response containing the document index result.
        Throws:
        IndexBatchException - If some of the indexing actions fail but other actions succeed and modify the state of the index. This can happen when the Search Service is under heavy indexing load. It is important to explicitly catch this exception and check the return value IndexBatchException.getIndexingResults(). The indexing result reports the status of each indexing action in the batch, making it possible to determine the state of the index after a partial failure.
        See Also:
        Add, update, or delete documents

      • mergeOrUploadDocuments

        public Mono<IndexDocumentsResult> mergeOrUploadDocuments​(Iterable<?> documents)
        This action behaves like merge if a document with the given key already exists in the index. If the document does not exist, it behaves like upload with a new document.

        If the type of the document contains non-nullable primitive-typed properties, these properties may not merge correctly. If you do not set such a property, it will automatically take its default value (for example, 0 for int or false for boolean), which will override the value of the property currently stored in the index, even if this was not your intent. For this reason, it is strongly recommended that you always declare primitive-typed properties with their class equivalents (for example, an integer property should be of type Integer instead of int).

        Code Sample

        Merge or upload dynamic SearchDocument. 

         SearchDocument searchDocument = new SearchDocument();
 searchDocument.put("hotelId", "1");
 searchDocument.put("hotelName", "test");
 searchAsyncClient.mergeOrUploadDocuments(Collections.singletonList(searchDocument))
     .subscribe(result -> {
         for (IndexingResult indexingResult : result.getResults()) {
             System.out.printf("Does document with key %s mergeOrUpload successfully? %b%n",
                 indexingResult.getKey(), indexingResult.isSucceeded());
         }
     });
        Parameters:
        documents - collection of documents to be merged, if exists, otherwise uploaded
        Returns:
        document index result
        Throws:
        IndexBatchException - If some of the indexing actions fail but other actions succeed and modify the state of the index. This can happen when the Search Service is under heavy indexing load. It is important to explicitly catch this exception and check the return value IndexBatchException.getIndexingResults(). The indexing result reports the status of each indexing action in the batch, making it possible to determine the state of the index after a partial failure.
        See Also:
        Add, update, or delete documents

      • mergeOrUploadDocumentsWithResponse

        public Mono<com.azure.core.http.rest.Response<IndexDocumentsResult>> mergeOrUploadDocumentsWithResponse​(Iterable<?> documents,
                                                                                                        IndexDocumentsOptions options)
        This action behaves like merge if a document with the given key already exists in the index. If the document does not exist, it behaves like upload with a new document.

        If the type of the document contains non-nullable primitive-typed properties, these properties may not merge correctly. If you do not set such a property, it will automatically take its default value (for example, 0 for int or false for boolean), which will override the value of the property currently stored in the index, even if this was not your intent. For this reason, it is strongly recommended that you always declare primitive-typed properties with their class equivalents (for example, an integer property should be of type Integer instead of int).

        Code Sample

        Merge or upload dynamic SearchDocument. 

         SearchDocument searchDocument = new SearchDocument();
 searchDocument.put("hotelId", "1");
 searchDocument.put("hotelName", "test");
 searchAsyncClient.mergeOrUploadDocumentsWithResponse(Collections.singletonList(searchDocument), null)
     .subscribe(resultResponse -> {
         System.out.println("The status code of the response is " + resultResponse.getStatusCode());
         for (IndexingResult indexingResult : resultResponse.getValue().getResults()) {
             System.out.printf("Does document with key %s mergeOrUpload successfully? %b%n",
                 indexingResult.getKey(), indexingResult.isSucceeded());
         }
     });
        Parameters:
        documents - collection of documents to be merged, if exists, otherwise uploaded
        options - Options that allow specifying document indexing behavior.
        Returns:
        document index result
        Throws:
        IndexBatchException - If some of the indexing actions fail but other actions succeed and modify the state of the index. This can happen when the Search Service is under heavy indexing load. It is important to explicitly catch this exception and check the return value IndexBatchException.getIndexingResults(). The indexing result reports the status of each indexing action in the batch, making it possible to determine the state of the index after a partial failure.
        See Also:
        Add, update, or delete documents

      • deleteDocuments

        public Mono<IndexDocumentsResult> deleteDocuments​(Iterable<?> documents)
        Deletes a collection of documents from the target index.

        Code Sample

        Delete dynamic SearchDocument. 

         SearchDocument searchDocument = new SearchDocument();
 searchDocument.put("hotelId", "1");
 searchDocument.put("hotelName", "test");
 searchAsyncClient.deleteDocuments(Collections.singletonList(searchDocument))
     .subscribe(result -> {
         for (IndexingResult indexingResult : result.getResults()) {
             System.out.printf("Does document with key %s delete successfully? %b%n", indexingResult.getKey(),
                 indexingResult.isSucceeded());
         }
     });
        Parameters:
        documents - collection of documents to delete from the target Index. Fields other than the key are ignored.
        Returns:
        document index result.
        Throws:
        IndexBatchException - If some of the indexing actions fail but other actions succeed and modify the state of the index. This can happen when the Search Service is under heavy indexing load. It is important to explicitly catch this exception and check the return value IndexBatchException.getIndexingResults(). The indexing result reports the status of each indexing action in the batch, making it possible to determine the state of the index after a partial failure.
        See Also:
        Add, update, or delete documents

      • deleteDocumentsWithResponse

        public Mono<com.azure.core.http.rest.Response<IndexDocumentsResult>> deleteDocumentsWithResponse​(Iterable<?> documents,
                                                                                                 IndexDocumentsOptions options)
        Deletes a collection of documents from the target index.

        Code Sample

        Delete dynamic SearchDocument. 

         SearchDocument searchDocument = new SearchDocument();
 searchDocument.put("hotelId", "1");
 searchDocument.put("hotelName", "test");
 searchAsyncClient.deleteDocumentsWithResponse(Collections.singletonList(searchDocument), null)
     .subscribe(resultResponse -> {
         System.out.println("The status code of the response is " + resultResponse.getStatusCode());
         for (IndexingResult indexingResult : resultResponse.getValue().getResults()) {
             System.out.printf("Does document with key %s delete successfully? %b%n", indexingResult.getKey(),
                 indexingResult.isSucceeded());
         }
     });
        Parameters:
        documents - collection of documents to delete from the target Index. Fields other than the key are ignored.
        options - Options that allow specifying document indexing behavior.
        Returns:
        response containing the document index result.
        Throws:
        IndexBatchException - If some of the indexing actions fail but other actions succeed and modify the state of the index. This can happen when the Search Service is under heavy indexing load. It is important to explicitly catch this exception and check the return value IndexBatchException.getIndexingResults(). The indexing result reports the status of each indexing action in the batch, making it possible to determine the state of the index after a partial failure.
        See Also:
        Add, update, or delete documents

      • indexDocuments

        public Mono<IndexDocumentsResult> indexDocuments​(IndexDocumentsBatch<?> batch)
        Sends a batch of upload, merge, and/or delete actions to the search index.

        Code Sample

        Index batch operation on dynamic SearchDocument. 

         SearchDocument searchDocument1 = new SearchDocument();
 searchDocument1.put("hotelId", "1");
 searchDocument1.put("hotelName", "test1");
 SearchDocument searchDocument2 = new SearchDocument();
 searchDocument2.put("hotelId", "2");
 searchDocument2.put("hotelName", "test2");
 IndexDocumentsBatch<SearchDocument> indexDocumentsBatch = new IndexDocumentsBatch<>();
 indexDocumentsBatch.addUploadActions(Collections.singletonList(searchDocument1));
 indexDocumentsBatch.addDeleteActions(Collections.singletonList(searchDocument2));
 searchAsyncClient.indexDocuments(indexDocumentsBatch)
     .subscribe(result -> {
         for (IndexingResult indexingResult : result.getResults()) {
             System.out.printf("Does document with key %s finish successfully? %b%n", indexingResult.getKey(),
                 indexingResult.isSucceeded());
         }
     });
        Parameters:
        batch - The batch of index actions
        Returns:
        Response containing the status of operations for all actions in the batch.
        Throws:
        IndexBatchException - If some of the indexing actions fail but other actions succeed and modify the state of the index. This can happen when the Search Service is under heavy indexing load. It is important to explicitly catch this exception and check the return value IndexBatchException.getIndexingResults(). The indexing result reports the status of each indexing action in the batch, making it possible to determine the state of the index after a partial failure.
        See Also:
        Add, update, or delete documents

      • indexDocumentsWithResponse

        public Mono<com.azure.core.http.rest.Response<IndexDocumentsResult>> indexDocumentsWithResponse​(IndexDocumentsBatch<?> batch,
                                                                                                IndexDocumentsOptions options)
        Sends a batch of upload, merge, and/or delete actions to the search index.

        Code Sample

        Index batch operation on dynamic SearchDocument. 

         SearchDocument searchDocument1 = new SearchDocument();
 searchDocument1.put("hotelId", "1");
 searchDocument1.put("hotelName", "test1");
 SearchDocument searchDocument2 = new SearchDocument();
 searchDocument2.put("hotelId", "2");
 searchDocument2.put("hotelName", "test2");
 IndexDocumentsBatch<SearchDocument> indexDocumentsBatch = new IndexDocumentsBatch<>();
 indexDocumentsBatch.addUploadActions(Collections.singletonList(searchDocument1));
 indexDocumentsBatch.addDeleteActions(Collections.singletonList(searchDocument2));
 searchAsyncClient.indexDocumentsWithResponse(indexDocumentsBatch, null)
     .subscribe(resultResponse -> {
         System.out.println("The status code of the response is " + resultResponse.getStatusCode());
         for (IndexingResult indexingResult : resultResponse.getValue().getResults()) {
             System.out.printf("Does document with key %s finish successfully? %b%n", indexingResult.getKey(),
                 indexingResult.isSucceeded());
         }
     });
        Parameters:
        batch - The batch of index actions
        options - Options that allow specifying document indexing behavior.
        Returns:
        Response containing the status of operations for all actions in the batch
        Throws:
        IndexBatchException - If some of the indexing actions fail but other actions succeed and modify the state of the index. This can happen when the Search Service is under heavy indexing load. It is important to explicitly catch this exception and check the return value IndexBatchException.getIndexingResults(). The indexing result reports the status of each indexing action in the batch, making it possible to determine the state of the index after a partial failure.
        See Also:
        Add, update, or delete documents

      • getDocument

        public <T> Mono<T> getDocument​(String key,
                               Class<T> modelClass)
        Retrieves a document from the Azure Cognitive Search index.

        View naming rules for guidelines on constructing valid document keys.

        Code Sample

        Get dynamic SearchDocument. 

         searchAsyncClient.getDocument("hotelId", SearchDocument.class)
     .subscribe(result -> {
         for (Map.Entry<String, Object> keyValuePair : result.entrySet()) {
             System.out.printf("Document key %s, Document value %s", keyValuePair.getKey(),
                 keyValuePair.getValue());
         }
     });
        Type Parameters:
        T - Convert document to the generic type.
        Parameters:
        key - The key of the document to retrieve.
        modelClass - The model class converts to.
        Returns:
        the document object
        See Also:
        Lookup document

      • getDocumentWithResponse

        public <T> Mono<com.azure.core.http.rest.Response<T>> getDocumentWithResponse​(String key,
                                                                              Class<T> modelClass,
                                                                              List<String> selectedFields)
        Retrieves a document from the Azure Cognitive Search index.

        View naming rules for guidelines on constructing valid document keys.

        Code Sample

        Get dynamic SearchDocument. 

         searchAsyncClient.getDocumentWithResponse("hotelId", SearchDocument.class, null)
     .subscribe(resultResponse -> {
         System.out.println("The status code of the response is " + resultResponse.getStatusCode());
         for (Map.Entry<String, Object> keyValuePair : resultResponse.getValue().entrySet()) {
             System.out.printf("Document key %s, Document value %s", keyValuePair.getKey(),
                 keyValuePair.getValue());
         }
     });
        Type Parameters:
        T - Convert document to the generic type.
        Parameters:
        key - The key of the document to retrieve.
        modelClass - The model class converts to.
        selectedFields - List of field names to retrieve for the document; Any field not retrieved will have null or default as its corresponding property value in the returned object.
        Returns:
        a response containing the document object
        See Also:
        Lookup document

      • getDocumentCount

        public Mono<Long> getDocumentCount()
        Queries the number of documents in the search index.

        Code Sample

        Get document count. 

         searchAsyncClient.getDocumentCount()
     .subscribe(count -> System.out.printf("There are %d documents in service.", count));
        Returns:
        the number of documents.

      • getDocumentCountWithResponse

        public Mono<com.azure.core.http.rest.Response<Long>> getDocumentCountWithResponse()
        Queries the number of documents in the search index.

        Code Sample

        Get document count. 

         searchAsyncClient.getDocumentCountWithResponse()
     .subscribe(countResponse -> {
         System.out.println("The status code of the response is " + countResponse.getStatusCode());
         System.out.printf("There are %d documents in service.", countResponse.getValue());
     });
        Returns:
        response containing the number of documents.

      • search

        public SearchPagedFlux search​(String searchText)
        Searches for documents in the Azure Cognitive Search index.

        If searchText is set to null or "*" all documents will be matched, see simple query syntax in Azure Cognitive Search for more information about search query syntax.

        Code Sample

        Search text from documents in service. 

         SearchPagedFlux searchPagedFlux = searchAsyncClient.search("searchText");
 searchPagedFlux.getTotalCount().subscribe(
     count -> System.out.printf("There are around %d results.", count)
 );
 searchPagedFlux.byPage()
     .subscribe(resultResponse -> {
         for (SearchResult result: resultResponse.getValue()) {
             SearchDocument searchDocument = result.getDocument(SearchDocument.class);
             for (Map.Entry<String, Object> keyValuePair: searchDocument.entrySet()) {
                 System.out.printf("Document key %s, document value %s", keyValuePair.getKey(), keyValuePair.getValue());
             }
         }
     });
        Parameters:
        searchText - A full-text search query expression.
        Returns:
        A SearchPagedFlux that iterates over SearchResult objects and provides access to the SearchPagedResponse object for each page containing HTTP response and count, facet, and coverage information.
        See Also:
        Search documents

      • search

        public SearchPagedFlux search​(String searchText,
                              SearchOptions searchOptions)
        Searches for documents in the Azure Cognitive Search index.

        If searchText is set to null or "*" all documents will be matched, see simple query syntax in Azure Cognitive Search for more information about search query syntax.

        Code Sample

        Search text from documents in service with option. 

         SearchPagedFlux pagedFlux = searchAsyncClient.search("searchText",
     new SearchOptions().setOrderBy("hotelId desc"));

 pagedFlux.getTotalCount().subscribe(count -> System.out.printf("There are around %d results.", count));

 pagedFlux.byPage()
     .subscribe(searchResultResponse -> searchResultResponse.getValue().forEach(searchDocument -> {
         for (Map.Entry<String, Object> keyValuePair
             : searchDocument.getDocument(SearchDocument.class).entrySet()) {
             System.out.printf("Document key %s, document value %s", keyValuePair.getKey(),
                 keyValuePair.getValue());
         }
     }));
        Parameters:
        searchText - A full-text search query expression.
        searchOptions - Parameters to further refine the search query
        Returns:
        A SearchPagedFlux that iterates over SearchResult objects and provides access to the SearchPagedResponse object for each page containing HTTP response and count, facet, and coverage information.
        See Also:
        Search documents

      • suggest

        public SuggestPagedFlux suggest​(String searchText,
                                String suggesterName)
        Suggests documents in the index that match the given partial query.

        Code Sample

        Suggest text from documents in service. 

         searchAsyncClient.suggest("searchText", "sg")
     .subscribe(results -> {
         for (Map.Entry<String, Object> keyValuePair: results.getDocument(SearchDocument.class).entrySet()) {
             System.out.printf("Document key %s, document value %s", keyValuePair.getKey(),
                 keyValuePair.getValue());
         }
     });
        Parameters:
        searchText - The search text on which to base suggestions
        suggesterName - The name of the suggester as specified in the suggesters collection that's part of the index definition
        Returns:
        A SuggestPagedFlux that iterates over SuggestResult objects and provides access to the SuggestPagedResponse object for each page containing HTTP response and coverage information.
        See Also:
        Suggestions

      • suggest

        public SuggestPagedFlux suggest​(String searchText,
                                String suggesterName,
                                SuggestOptions suggestOptions)
        Suggests documents in the index that match the given partial query.

        Code Sample

        Suggest text from documents in service with option. 

         searchAsyncClient.suggest("searchText", "sg",
     new SuggestOptions().setOrderBy("hotelId desc"))
     .subscribe(results -> {
         for (Map.Entry<String, Object> keyValuePair: results.getDocument(SearchDocument.class).entrySet()) {
             System.out.printf("Document key %s, document value %s", keyValuePair.getKey(),
                 keyValuePair.getValue());
         }
     });
        Parameters:
        searchText - The search text on which to base suggestions
        suggesterName - The name of the suggester as specified in the suggesters collection that's part of the index definition
        suggestOptions - Parameters to further refine the suggestion query.
        Returns:
        A SuggestPagedFlux that iterates over SuggestResult objects and provides access to the SuggestPagedResponse object for each page containing HTTP response and coverage information.
        See Also:
        Suggestions

      • autocomplete

        public AutocompletePagedFlux autocomplete​(String searchText,
                                          String suggesterName)
        Autocompletes incomplete query terms based on input text and matching terms in the index.

        Code Sample

        Autocomplete text from documents in service. 

         searchAsyncClient.autocomplete("searchText", "sg")
     .subscribe(result -> System.out.printf("The complete term is %s", result.getText()));
        Parameters:
        searchText - search text
        suggesterName - suggester name
        Returns:
        auto complete result.

      • autocomplete

        public AutocompletePagedFlux autocomplete​(String searchText,
                                          String suggesterName,
                                          AutocompleteOptions autocompleteOptions)
        Autocompletes incomplete query terms based on input text and matching terms in the index.

        Code Sample

        Autocomplete text from documents in service with option. 

         searchAsyncClient.autocomplete("searchText", "sg",
     new AutocompleteOptions().setAutocompleteMode(AutocompleteMode.ONE_TERM_WITH_CONTEXT))
     .subscribe(result ->
         System.out.printf("The complete term is %s", result.getText())
     );
        Parameters:
        searchText - search text
        suggesterName - suggester name
        autocompleteOptions - autocomplete options
        Returns:
        auto complete result.