Quarkus Opensearch Extension
The quarkus-opensearch extension allows you to connect to an OpenSearch cluster using the clients provided by the OpenSearch project.
OpenSearch Clients
OpenSearch provides three different flavours of clients for connecting to the cluster. This extension has support for all three of them.
OpenSearch Java Client
This is the latest implementation of the OpenSearch clients, when starting a new project you should use this client and not bother about the others.
This will be the only OpenSearch Client supported in the future.
Just like the OpenSearch REST high-level level, the OpenSearch Java client lets you interact with OpenSearch through Java methods and data structures. In comparison to the REST high-level, it has no dependency to org.opensearch:opensearch and also provides an async client implementation.
|
Deprecation
The OpenSearch REST clients are deprecated. Support will be removed in OpenSearch version 3.0.0. It is recommended to switch to the Java client. We will try to support the REST clients as long as possible, but if you start a new project this is not the client you should use anymore. |
OpenSearch REST High-Level Client
The OpenSearch Java high-level REST client lets you interact with your OpenSearch clusters and indices through Java methods and data structures rather than HTTP methods and JSON.
Installation
OpenSearch Java client
The java client does not have any dependencies on the REST client. All clients are sharing most of the configuration properties.
The AWS related configuration properties quarkus.opensearch.aws.* are only applicable to this java client.
If you want to use this client all you need to do is add the io.quarkiverse.opensearch:quarkus-opensearch-java-client extension first to your build file.
with Maven, add the following dependency to your POM file:
<dependency>
<groupId>io.quarkiverse.opensearch</groupId>
<artifactId>quarkus-opensearch-java-client</artifactId>
<version>1.18.0</version>
</dependency>OpenSearch REST High-Level Client
The REST High-Level Client depends on the REST client and does not require any additional configuration.
If you want to use this client all you need to do is add the io.quarkiverse.opensearch:quarkus-opensearch-rest-high-level-client extension first to your build file.
with Maven, add the following dependency to your POM file:
<dependency>
<groupId>io.quarkiverse.opensearch</groupId>
<artifactId>quarkus-opensearch-rest-high-level-client</artifactId>
<version>1.18.0</version>
</dependency>OpenSearch REST Low-Level Client
If you want to use this extension, you need to add the io.quarkiverse.opensearch:quarkus-opensearch-rest-client extension first to your build file.
For instance, with Maven, add the following dependency to your POM file:
<dependency>
<groupId>io.quarkiverse.opensearch</groupId>
<artifactId>quarkus-opensearch-rest-client</artifactId>
<version>1.18.0</version>
</dependency>Configuring Opensearch
The main property to configure is the URL to connect to the Opensearch cluster.
For a typical clustered Opensearch service, a sample configuration would look like the following:
# configure the Elasticsearch client for a cluster of two nodes
quarkus.opensearch.hosts = opensearch-01:9200,opensearch-02:9200In this case, we are using a single instance running on localhost:
# configure the Opensearch client for a single instance on localhost
quarkus.opensearch.hosts = localhost:9200If you need a more advanced configuration, you can find the comprehensive list of supported configuration properties at the end of this guide.
Dev Services
Quarkus supports a feature called Dev Services that allows you to start various containers without any config.
In the case of Opensearch, this support extends to the default Opensearch connection.
What that means practically is that, if you have not configured quarkus.opensearch.hosts, Quarkus will automatically
start an Opensearch container when running tests or dev mode, and automatically configure the connection.
When running the production version of the application, the Opensearch connection needs to be configured as usual,
so if you want to include a production database config in your application.properties and continue to use Dev Services
we recommend that you use the %prod. profile to define your Opensearch settings.
Extension Configuration Reference
Configuration property fixed at build time - All other configuration properties are overridable at runtime
Configuration property |
Type |
Default |
|---|---|---|
If Dev Services for OpenSearch has been explicitly enabled or disabled. Dev Services are generally enabled by default, unless there is an existing configuration present. For OpenSearch, Dev Services starts a server unless Environment variable: |
boolean |
|
Optional fixed port the dev service will listen to. If not defined, the port will be chosen randomly. Environment variable: |
int |
|
The OpenSearch container image to use. Defaults to the opensearch image provided by OpenSearch. Environment variable: |
string |
|
The value for the OPENSEARCH_JAVA_OPTS env variable. Defaults to setting the heap to 512MB min - 1GB max. Environment variable: |
string |
|
Indicates if the OpenSearch server managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for OpenSearch starts a new container. The discovery uses the Container sharing is only used in dev mode. Environment variable: |
boolean |
|
The value of the This property is used when you need multiple shared OpenSearch servers. Environment variable: |
string |
|
Whether a health check is published in case the smallrye-health extension is present. Environment variable: |
boolean |
|
The list of hosts of the OpenSearch servers, when accessing AWS OpenSearch set to AWS endpoint name. Host Example: opensearch-01:9200,opensearch-02:9200 AWS Endpoint Example: search-domain-name-identifier.region.es.amazonaws.com Environment variable: |
list of string |
|
The protocol to use when contacting OpenSearch servers. Set to "https" to enable SSL/TLS. Environment variable: |
string |
|
The username for basic HTTP authentication. Environment variable: |
string |
|
The password for basic HTTP authentication. Environment variable: |
string |
|
The connection timeout. Environment variable: |
|
|
The connection timeout. Environment variable: |
|
|
The socket timeout. Environment variable: |
|
|
The maximum number of connections to all the OpenSearch servers. Environment variable: |
int |
|
The maximum number of connections per OpenSearch server. Environment variable: |
int |
|
The number of IO thread. By default, this is the number of locally detected processors. Thread counts higher than the number of processors should not be necessary because the I/O threads rely on non-blocking operations, but you may want to use a thread count lower than the number of processors. Environment variable: |
int |
|
AWS Region Environment variable: |
string |
|
Set to "es" or "aoss" to use AWS OpenSearch Service. es : Amazon OpenSearch Service aoss : Amazon OpenSearch Serverless Environment variable: |
string |
|
AWS Secret Access Key for setting up StaticCredentialsProvider Environment variable: |
string |
|
AWS Secret Access Key Secret for setting up StaticCredentialsProvider Environment variable: |
string |
|
Optional keyStoreFile to be used when connecting to cluster nodes Environment variable: |
string |
|
Optional password for accessing keyStoreFile Environment variable: |
string |
|
SSL Verify Hostname Environment variable: |
boolean |
|
Verify SSL Certificates Environment variable: |
boolean |
|
Defines if automatic discovery is enabled. Environment variable: |
boolean |
|
Refresh interval of the node list. Environment variable: |
|
|
About the Duration format
To write duration values, use the standard You can also use a simplified format, starting with a number:
In other cases, the simplified format is translated to the
|