Azure cognitive search client library for Java
This is the Java client library for Azure Cognitive Search. Azure Cognitive Search is a fully managed cloud search service that provides a rich search experience to custom applications. This library provides an easy (native) way for a Java developer to interact with the service to accomplish tasks like: create and manage indexes, load data, implement search features, execute queries, and handle results.
Source code | Package (Maven) | API reference documentation| Product documentation | Samples
Getting started
Prerequisites
- Java Development Kit (JDK) with version 8 or above
- Azure subscription
- Cognitive search service
Adding the package to your product
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-search</artifactId>
<version>11.0.0-beta.1</version>
</dependency>
Key concepts
Azure Cognitive Search has the concepts of search services and indexes and documents, where a search service contains one or more indexes that provides persistent storage of searchable data, and data is loaded in the form of JSON documents. Data can be pushed to an index from an external data source, but if you use an indexer, it's possible to crawl a data source to extract and load data into an index.
There are several types of operations that can be executed against the service:
- Index management operations. Create, delete, update, or configure a search index.
- Document operations. Add, update, or delete documents in the index, query the index, or look up specific documents by ID.
- Indexer operations. Automate aspects of an indexing operation by configuring a data source and an indexer that you can schedule or run on demand. This feature is supported for a limited number of data source types.
- Skillset operations. Part of a cognitive search workload, a skillset defines a series of a series of enrichment processing steps. A skillset is consumed by an indexer.
- Synonym map operations. A synonym map is a service-level resource that contains user-defined synonyms. This resource is maintained independently from search indexes. Once uploaded, you can point any searchable field to the synonym map (one per field).
Authenticate the client
In order to interact with the Cognitive Search service you'll need to create an instance of the Search Client class. To make this possible you will need an api-key of the Cognitive Search service.
The SDK provides two clients.
- SearchIndexClient for all document operations.
- SearchServiceClient for all CRUD operations on service resources.
Create a SearchServiceClient
Once you have the values of the Cognitive Search Service URL endpoint and admin key you can create the Search Service client:
SearchServiceClient client = new SearchServiceClientBuilder()
.endpoint(endpoint)
.credential(new SearchApiKeyCredential(adminKey))
.buildClient();
or
SearchServiceAsyncClient client = new SearchServiceClientBuilder()
.endpoint(endpoint)
.credential(new SearchApiKeyCredential(adminKey))
.buildAsyncClient();
Create a SearchIndexClient
To create a SearchIndexClient, you will need an existing index name as well as the values of the Cognitive Search Service URL endpoint and query key. Note that you will need an admin key to index documents (query keys only work for queries).
SearchIndexClient client = new SearchIndexClientBuilder()
.endpoint(endpoint)
.credential(new SearchApiKeyCredential(apiKey))
.indexName(indexName)
.buildClient();
or
SearchIndexAsyncClient client = new SearchIndexClientBuilder()
.endpoint(endpoint)
.credential(new SearchApiKeyCredential(apiKey))
.indexName(indexName)
.buildAsyncClient();
Asynchronous and Synchronous Pagination and Iteration
The SDK uses an azure-core concept for paging and async streaming implemented as PagedFlux<T>.
Many APIs in Azure Cognitive Search can return multiple items from a single request. For example, the search API returns all the documents that match a given query. To handle the case where not all items can be returned in a single response, the Java SDK supports paging. The SDK handles this by returning PagedIterableBase for sync APIs and PagedFluxBase for async APIs (More reading can be found in the Java SDK wiki).
Both PagedIterable and PagedFlux enable the common case to be quickly and easily achieved: iterating over a paginated response deserialized into a given type T. In the case of PagedIterable, it implements the Iterable interface, and offers API to receive a Stream. In the case of PagedFlux, it is a Flux.
Pages
For the Cognitive Search service SDK, each page in the response will contain page-specific additional information, based on the executed API:
SearchPagedResponse Represents an HTTP response from the search API request that contains a list of items deserialized into a page. Additional information includes the count of total documents returned, and other metadata.
SuggestPagedResponse Represents an HTTP response from the suggest API request that contains a list of items deserialized into a page. The additional information is:
- coverage - coverage value
AutocompletePagedResponse Represents an HTTP response from the autocomplete API request that contains a list of items deserialized into a page.
Synchronous Pagination and Iteration
Search query options with sync client
Asynchronous Pagination and Iteration
Search queries options with async client
Examples
Samples are explained in detail here.
Troubleshooting
General
When you interact with Azure Cognitive Search using this Java client library, errors returned by the service correspond
to the same HTTP status codes returned for REST API requests. For example, if you try to retrieve a document
that doesn't exist in your index, a 404 error is returned, indicating Not Found.
Enabling Logging
Azure SDKs for Java offer a consistent logging story to help aid in troubleshooting application errors and expedite their resolution. The logs produced will capture the flow of an application before reaching the terminal state to help locate the root issue. View the logging wiki for guidance about enabling logging.
Default HTTP Client
By default a Netty based HTTP client will be used, for more information on configuring or changing the HTTP client is detailed in the HTTP clients wiki.
Next steps
- Samples are explained in detail here.
Contributing
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution.
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
