选择指南版本

Connecting to an Elasticsearch cluster

Elasticsearch is a well known full text search engine and NoSQL datastore.

In this guide, we will see how you can get your REST services to use an Elasticsearch cluster.

Quarkus provides two ways of accessing Elasticsearch: via the lower level RestClient or via the RestHighLevelClient we will call them the low level and the high level clients.

先决条件

要完成这个指南，你需要：

大概15分钟
编辑器
安装JDK 11以上版本并正确配置了 JAVA_HOME
Apache Maven 3.8.6
如果你愿意的话，还可以选择使用Quarkus CLI
如果你想构建原生可执行程序，可以选择安装Mandrel或者GraalVM，并正确配置(或者使用Docker在容器中进行构建)
Elasticsearch installed or Docker installed

应用结构

本指南中构建的应用程序非常简单：用户可以使用一个表单在列表中添加元素并更新列表。

浏览器和服务器之间的所有信息都被格式化为JSON。

The elements are stored in Elasticsearch.

创建Maven项目

首先，我们需要一个新的项目。使用以下命令创建一个新的项目:

CLI

quarkus create app org.acme:elasticsearch-quickstart \
    --stream=2.16 \
    --extension='resteasy-reactive-jackson,elasticsearch-rest-client' \
    --no-code
cd elasticsearch-quickstart

创建Grade项目，请添加 --gradle 或者 --gradle-kotlin-dsl 参数。

关于如何安装并使用Quarkus CLI的更多信息，请参考Quarkus CLI指南。

Maven

mvn io.quarkus.platform:quarkus-maven-plugin:2.16.12.Final:create \
    -DplatformVersion=2.16 \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=elasticsearch-quickstart \
    -Dextensions='resteasy-reactive-jackson,elasticsearch-rest-client' \
    -DnoCode
cd elasticsearch-quickstart

创建Grade项目，请添加 -DbuildTool=gradle 或者 -DbuildTool=gradle-kotlin-dsl 参数。

This command generates a Maven structure importing the RESTEasy Reactive/JAX-RS, Jackson, and the Elasticsearch low level client extensions. After this, the quarkus-elasticsearch-rest-client extension has been added to your build file.

If you want to use the high level client instead, replace the elasticsearch-rest-client extension by the elasticsearch-rest-high-level-client extension.

We use the resteasy-reactive-jackson extension here and not the JSON-B variant because we will use the Vert.x JsonObject helper to serialize/deserialize our objects to/from Elasticsearch and it uses Jackson under the hood.

If you don’t want to generate a new project, add the following dependencies to your build file.

For the Elasticsearch low level client, add:

pom.xml

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-elasticsearch-rest-client</artifactId>
</dependency>

build.gradle

implementation("io.quarkus:quarkus-elasticsearch-rest-client")

For the Elasticsearch high level client, add:

pom.xml

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-elasticsearch-rest-high-level-client</artifactId>
</dependency>

build.gradle

implementation("io.quarkus:quarkus-elasticsearch-rest-high-level-client")

创建你的第一个JSON REST服务

在这个例子中，我们将创建一个应用程序来管理fruit列表。

首先，让我们创建 Fruit 实体类，如下所示：

package org.acme.elasticsearch;

public class Fruit {
    public String id;
    public String name;
    public String color;
}

这非常的简单。需要注意的一件事是， JSON 序列化层需要具有默认构造函数。

Now create a org.acme.elasticsearch.FruitService that will be the business layer of our application and store/load the fruits from the Elasticsearch instance. Here we use the low level client, if you want to use the high level client instead follow the instructions in the Using the High Level REST Client paragraph instead.

package org.acme.elasticsearch;

import java.io.IOException;
import java.util.ArrayList;
import java.util.List;

import javax.enterprise.context.ApplicationScoped;
import javax.inject.Inject;

import org.apache.http.util.EntityUtils;
import org.elasticsearch.client.Request;
import org.elasticsearch.client.Response;
import org.elasticsearch.client.RestClient;

import io.vertx.core.json.JsonArray;
import io.vertx.core.json.JsonObject;

@ApplicationScoped
public class FruitService {
    @Inject
    RestClient restClient; (1)

    public void index(Fruit fruit) throws IOException {
        Request request = new Request(
                "PUT",
                "/fruits/_doc/" + fruit.id); (2)
        request.setJsonEntity(JsonObject.mapFrom(fruit).toString()); (3)
        restClient.performRequest(request); (4)
    }

    public Fruit get(String id) throws IOException {
        Request request = new Request(
                "GET",
                "/fruits/_doc/" + id);
        Response response = restClient.performRequest(request);
        String responseBody = EntityUtils.toString(response.getEntity());
        JsonObject json = new JsonObject(responseBody); (5)
        return json.getJsonObject("_source").mapTo(Fruit.class);
    }

    public List<Fruit> searchByColor(String color) throws IOException {
        return search("color", color);
    }

    public List<Fruit> searchByName(String name) throws IOException {
        return search("name", name);
    }

    private List<Fruit> search(String term, String match) throws IOException {
        Request request = new Request(
                "GET",
                "/fruits/_search");
        //construct a JSON query like {"query": {"match": {"<term>": "<match"}}
        JsonObject termJson = new JsonObject().put(term, match);
        JsonObject matchJson = new JsonObject().put("match", termJson);
        JsonObject queryJson = new JsonObject().put("query", matchJson);
        request.setJsonEntity(queryJson.encode());
        Response response = restClient.performRequest(request);
        String responseBody = EntityUtils.toString(response.getEntity());

        JsonObject json = new JsonObject(responseBody);
        JsonArray hits = json.getJsonObject("hits").getJsonArray("hits");
        List<Fruit> results = new ArrayList<>(hits.size());
        for (int i = 0; i < hits.size(); i++) {
            JsonObject hit = hits.getJsonObject(i);
            Fruit fruit = hit.getJsonObject("_source").mapTo(Fruit.class);
            results.add(fruit);
        }
        return results;
    }
}

In this example you can note the following:

We inject an Elasticsearch low level RestClient into our service.
We create an Elasticsearch request.
We use Vert.x JsonObject to serialize the object before sending it to Elasticsearch, you can use whatever you want to serialize to JSON.
We send the request (indexing request here) to Elasticsearch.
In order to deserialize the object from Elasticsearch, we again use Vert.x JsonObject.

Now, create the org.acme.elasticsearch.FruitResource class as follows:

package org.acme.elasticsearch;

import javax.inject.Inject;
import javax.ws.rs.GET;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
import java.io.IOException;
import java.net.URI;
import java.util.List;
import java.util.UUID;

import org.jboss.resteasy.reactive.RestQuery;

@Path("/fruits")
public class FruitResource {

    @Inject
    FruitService fruitService;

    @POST
    public Response index(Fruit fruit) throws IOException {
        if (fruit.id == null) {
            fruit.id = UUID.randomUUID().toString();
        }
        fruitService.index(fruit);
        return Response.created(URI.create("/fruits/" + fruit.id)).build();
    }

    @GET
    @Path("/{id}")
    public Fruit get(String id) throws IOException {
        return fruitService.get(id);
    }

    @GET
    @Path("/search")
    public List<Fruit> search(@RestQuery String name, @RestQuery String color) throws IOException {
        if (name != null) {
            return fruitService.searchByName(name);
        } else if (color != null) {
            return fruitService.searchByColor(color);
        } else {
            throw new BadRequestException("Should provide name or color query parameter");
        }
    }
}

实现起来非常简单，你只需要使用JAX-RS注解来定义你的端点，并使用 FruitService 来list/add新的fruits。

Configuring Elasticsearch

The main property to configure is the URL to connect to the Elasticsearch cluster.

示例配置应如下所示：

# configure the Elasticsearch client for a cluster of two nodes
quarkus.elasticsearch.hosts = elasticsearch1:9200,elasticsearch2:9200

在此示例中，我们在 localhost 上运行的单个实例：

# configure the Elasticsearch client for a single instance on localhost
quarkus.elasticsearch.hosts = localhost:9200

If you need a more advanced configuration, you can find the comprehensive list of supported configuration properties at the end of this guide.

开发服务（免配置数据库）。

Quarkus supports a feature called Dev Services that allows you to start various containers without any config. In the case of Elasticsearch this support extends to the default Elasticsearch connection. What that means practically is that, if you have not configured quarkus.elasticsearch.hosts, Quarkus will automatically start an Elasticsearch container when running tests or dev mode, and automatically configure the connection.

When running the production version of the application, the Elasticsearch 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 Elasticsearch settings.

For more information you can read the Dev Services for Elasticsearch guide.

Programmatically Configuring Elasticsearch

On top of the parametric configuration, you can also programmatically apply additional configuration to the client by implementing a RestClientBuilder.HttpClientConfigCallback and annotating it with ElasticsearchClientConfig. You may provide multiple implementations and configuration provided by each implementation will be applied in a randomly ordered cascading manner.

For example, when accessing an Elasticsearch cluster that is set up for TLS on the HTTP layer, the client needs to trust the certificate that Elasticsearch is using. The following is an example of setting up the client to trust the CA that has signed the certificate that Elasticsearch is using, when that CA certificate is available in a PKCS#12 keystore.

import io.quarkus.elasticsearch.restclient.lowlevel.ElasticsearchClientConfig;
import org.apache.http.impl.nio.client.HttpAsyncClientBuilder;
import org.apache.http.ssl.SSLContextBuilder;
import org.apache.http.ssl.SSLContexts;
import org.elasticsearch.client.RestClientBuilder;

import javax.enterprise.context.Dependent;
import javax.net.ssl.SSLContext;
import java.io.InputStream;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.security.KeyStore;

@ElasticsearchClientConfig
public class SSLContextConfigurator implements RestClientBuilder.HttpClientConfigCallback {
    @Override
    public HttpAsyncClientBuilder customizeHttpClient(HttpAsyncClientBuilder httpClientBuilder) {
        try {
            String keyStorePass = "password-for-keystore";
            Path trustStorePath = Paths.get("/path/to/truststore.p12");
            KeyStore truststore = KeyStore.getInstance("pkcs12");
            try (InputStream is = Files.newInputStream(trustStorePath)) {
                truststore.load(is, keyStorePass.toCharArray());
            }
            SSLContextBuilder sslBuilder = SSLContexts.custom()
                    .loadTrustMaterial(truststore, null);
            SSLContext sslContext = sslBuilder.build();
            httpClientBuilder.setSSLContext(sslContext);
        } catch (Exception e) {
            throw new RuntimeException(e);
        }

        return httpClientBuilder;
    }
}

See Elasticsearch documentation for more details on this particular example.

Classes marked with @ElasticsearchClientConfig are made application scoped CDI beans by default. You can override the scope at the class level if you prefer a different scope.

Running an Elasticsearch cluster

As by default, the Elasticsearch client is configured to access a local Elasticsearch cluster on port 9200 (the default Elasticsearch port), if you have a local running instance on this port, there is nothing more to do before being able to test it!

If you want to use Docker to run an Elasticsearch instance, you can use the following command to launch one:

docker run --name elasticsearch  -e "discovery.type=single-node" -e "ES_JAVA_OPTS=-Xms512m -Xmx512m"\
       --rm -p 9200:9200 docker.io/elastic/elasticsearch:7.16.3

运行应用程序

Now let’s run our application via Quarkus dev mode:

CLI

quarkus dev

Maven

./mvnw quarkus:dev

Gradle

./gradlew --console=plain quarkusDev

You can add new fruits to the list via the following curl command:

curl localhost:8080/fruits -d '{"name": "bananas", "color": "yellow"}' -H "Content-Type: application/json"

And search for fruits by name or color via the flowing curl command:

curl localhost:8080/fruits/search?color=yellow

Using the High Level REST Client

Quarkus provides support for the Elasticsearch High Level REST Client but keep in mind that it comes with some caveats:

It drags a lot of dependencies - especially Lucene -, which doesn’t fit well with Quarkus philosophy. The Elasticsearch team is aware of this issue, and it might improve sometime in the future.
It is tied to a certain version of the Elasticsearch server: you cannot use a High Level REST Client version 7 to access a server version 6.

Due to the license change made by Elastic for the Elasticsearch High Level REST Client, we are keeping in Quarkus the last Open Source version of this particular client, namely 7.10, and it won’t be upgraded to newer versions.

Given this client was deprecated by Elastic and replaced by a new Open Source Java client, the Elasticsearch High Level REST Client extension is considered deprecated and will be removed from the Quarkus codebase at some point in the future.

Note that contrary to the High Level REST client, we are using the latest version of the Low Level REST client (which is still Open Source), and, while we believe it should work, the situation is less than ideal and might cause some issues. Feel free to override the versions of the clients in your applications depending on your requirements, but be aware of the new licence of the High Level REST Client for versions 7.11+: it is not Open Source and has several usage restrictions.

We will eventually provide an extension for the new Open Source Java client, but it will require changes in your applications as it is an entirely new client.

Here is a version of the FruitService using the high level client instead of the low level one:

import java.io.IOException;
import java.util.ArrayList;
import java.util.List;

import javax.enterprise.context.ApplicationScoped;
import javax.inject.Inject;

import org.elasticsearch.action.get.GetRequest;
import org.elasticsearch.action.get.GetResponse;
import org.elasticsearch.action.index.IndexRequest;
import org.elasticsearch.action.search.SearchRequest;
import org.elasticsearch.action.search.SearchResponse;
import org.elasticsearch.client.RequestOptions;
import org.elasticsearch.client.RestHighLevelClient;
import org.elasticsearch.common.xcontent.XContentType;
import org.elasticsearch.index.query.QueryBuilders;
import org.elasticsearch.search.SearchHit;
import org.elasticsearch.search.SearchHits;
import org.elasticsearch.search.builder.SearchSourceBuilder;

import io.vertx.core.json.JsonObject;

@ApplicationScoped
public class FruitService {
    @Inject
    RestHighLevelClient restHighLevelClient; (1)

    public void index(Fruit fruit) throws IOException {
        IndexRequest request = new IndexRequest("fruits"); (2)
        request.id(fruit.id);
        request.source(JsonObject.mapFrom(fruit).toString(), XContentType.JSON); (3)
        restHighLevelClient.index(request, RequestOptions.DEFAULT); (4)
    }

    public Fruit get(String id) throws IOException {
        GetRequest getRequest = new GetRequest("fruits", id);
        GetResponse getResponse = restHighLevelClient.get(getRequest, RequestOptions.DEFAULT);
        if (getResponse.isExists()) {
            String sourceAsString = getResponse.getSourceAsString();
            JsonObject json = new JsonObject(sourceAsString); (5)
            return json.mapTo(Fruit.class);
        }
        return null;
    }

    public List<Fruit> searchByColor(String color) throws IOException {
        return search("color", color);
    }

    public List<Fruit> searchByName(String name) throws IOException {
        return search("name", name);
    }

    private List<Fruit> search(String term, String match) throws IOException {
        SearchRequest searchRequest = new SearchRequest("fruits");
        SearchSourceBuilder searchSourceBuilder = new SearchSourceBuilder();
        searchSourceBuilder.query(QueryBuilders.matchQuery(term, match));
        searchRequest.source(searchSourceBuilder);

        SearchResponse searchResponse = restHighLevelClient.search(searchRequest, RequestOptions.DEFAULT);
        SearchHits hits = searchResponse.getHits();
        List<Fruit> results = new ArrayList<>(hits.getHits().length);
        for (SearchHit hit : hits.getHits()) {
            String sourceAsString = hit.getSourceAsString();
            JsonObject json = new JsonObject(sourceAsString);
            results.add(json.mapTo(Fruit.class));
        }
        return results;
    }
}

In this example you can note the following:

We inject an Elasticsearch RestHighLevelClient inside the service.
We create an Elasticsearch index request.
We use Vert.x JsonObject to serialize the object before sending it to Elasticsearch, you can use whatever you want to serialize to JSON.
We send the request to Elasticsearch.
In order to deserialize the object from Elasticsearch, we again use Vert.x JsonObject.

Hibernate Search Elasticsearch

Quarkus supports Hibernate Search with Elasticsearch via the hibernate-search-orm-elasticsearch extension.

Hibernate Search Elasticsearch allows to synchronize your JPA entities to an Elasticsearch cluster and offers a way to query your Elasticsearch cluster using the Hibernate Search API.

If you’re interested in it, you can read the Hibernate Search with Elasticsearch guide.

Cluster Health Check

If you are using the quarkus-smallrye-health extension, both the extension will automatically add a readiness health check to validate the health of the cluster.

So when you access the /q/health/ready endpoint of your application you will have information about the cluster status. It uses the cluster health endpoint, the check will be down if the status of the cluster is red, or the cluster is not available.

This behavior can be disabled by setting the quarkus.elasticsearch.health.enabled property to false in your application.properties.

构建一个本地可执行文件

You can use both clients in a native executable.

你可以使用常用命令构建本机可执行文件：

CLI

quarkus build --native

Maven

./mvnw install -Dnative

Gradle

./gradlew build -Dquarkus.package.type=native

Running it is as simple as executing ./target/elasticsearch-low-level-client-quickstart-1.0.0-SNAPSHOT-runner.

然后你可以使用的浏览器访问 <a href="http://localhost:8080/fruits.html" class="bare">http://localhost:8080/fruits.html</a>; 来使用你的应用程序。

解决方案

Accessing an Elasticsearch cluster from a low level or a high level client is easy with Quarkus as it provides easy configuration, CDI integration and native support for it.

配置参考

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property	类型	默认
`quarkus.elasticsearch.health.enabled` Whether a health check is published in case the smallrye-health extension is present. Environment variable: `QUARKUS_ELASTICSEARCH_HEALTH_ENABLED` Show more	boolean	`true`
`quarkus.elasticsearch.hosts` The list of hosts of the Elasticsearch servers. Environment variable: `QUARKUS_ELASTICSEARCH_HOSTS` Show more	list of host:port	`localhost:9200`
`quarkus.elasticsearch.protocol` The protocol to use when contacting Elasticsearch servers. Set to "https" to enable SSL/TLS. Environment variable: `QUARKUS_ELASTICSEARCH_PROTOCOL` Show more	string	`http`
`quarkus.elasticsearch.username` The username for basic HTTP authentication. Environment variable: `QUARKUS_ELASTICSEARCH_USERNAME` Show more	string
`quarkus.elasticsearch.password` The password for basic HTTP authentication. Environment variable: `QUARKUS_ELASTICSEARCH_PASSWORD` Show more	string
`quarkus.elasticsearch.connection-timeout` The connection timeout. Environment variable: `QUARKUS_ELASTICSEARCH_CONNECTION_TIMEOUT` Show more	Duration	`1S`
`quarkus.elasticsearch.socket-timeout` The socket timeout. Environment variable: `QUARKUS_ELASTICSEARCH_SOCKET_TIMEOUT` Show more	Duration	`30S`
`quarkus.elasticsearch.max-connections` The maximum number of connections to all the Elasticsearch servers. Environment variable: `QUARKUS_ELASTICSEARCH_MAX_CONNECTIONS` Show more	int	`20`
`quarkus.elasticsearch.max-connections-per-route` The maximum number of connections per Elasticsearch server. Environment variable: `QUARKUS_ELASTICSEARCH_MAX_CONNECTIONS_PER_ROUTE` Show more	int	`10`
`quarkus.elasticsearch.io-thread-counts` 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: `QUARKUS_ELASTICSEARCH_IO_THREAD_COUNTS` Show more	int
`quarkus.elasticsearch.discovery.enabled` Defines if automatic discovery is enabled. Environment variable: `QUARKUS_ELASTICSEARCH_DISCOVERY_ENABLED` Show more	boolean	`false`
`quarkus.elasticsearch.discovery.refresh-interval` Refresh interval of the node list. Environment variable: `QUARKUS_ELASTICSEARCH_DISCOVERY_REFRESH_INTERVAL` Show more	Duration	`5M`

Configuration property

类型

默认

quarkus.elasticsearch.health.enabled

Whether a health check is published in case the smallrye-health extension is present.

Environment variable: QUARKUS_ELASTICSEARCH_HEALTH_ENABLED

boolean

true

quarkus.elasticsearch.hosts

The list of hosts of the Elasticsearch servers.

Environment variable: QUARKUS_ELASTICSEARCH_HOSTS

list of host:port

localhost:9200

quarkus.elasticsearch.protocol

The protocol to use when contacting Elasticsearch servers. Set to "https" to enable SSL/TLS.

Environment variable: QUARKUS_ELASTICSEARCH_PROTOCOL

string

http

quarkus.elasticsearch.username

The username for basic HTTP authentication.

Environment variable: QUARKUS_ELASTICSEARCH_USERNAME

string

quarkus.elasticsearch.password

The password for basic HTTP authentication.

Environment variable: QUARKUS_ELASTICSEARCH_PASSWORD

string

quarkus.elasticsearch.connection-timeout

The connection timeout.

Environment variable: QUARKUS_ELASTICSEARCH_CONNECTION_TIMEOUT

Duration

1S

quarkus.elasticsearch.socket-timeout

The socket timeout.

Environment variable: QUARKUS_ELASTICSEARCH_SOCKET_TIMEOUT

Duration

30S

quarkus.elasticsearch.max-connections

The maximum number of connections to all the Elasticsearch servers.

Environment variable: QUARKUS_ELASTICSEARCH_MAX_CONNECTIONS

int

20

quarkus.elasticsearch.max-connections-per-route

The maximum number of connections per Elasticsearch server.

Environment variable: QUARKUS_ELASTICSEARCH_MAX_CONNECTIONS_PER_ROUTE

int

10

quarkus.elasticsearch.io-thread-counts

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: QUARKUS_ELASTICSEARCH_IO_THREAD_COUNTS

int

quarkus.elasticsearch.discovery.enabled

Defines if automatic discovery is enabled.

Environment variable: QUARKUS_ELASTICSEARCH_DISCOVERY_ENABLED

boolean

false

quarkus.elasticsearch.discovery.refresh-interval

Refresh interval of the node list.

Environment variable: QUARKUS_ELASTICSEARCH_DISCOVERY_REFRESH_INTERVAL

Duration

5M

About the Duration format

持续时间的格式使用标准的 java.time.Duration 格式您可以在 Duration#parse() javadoc 中了解更多信息。

您还可以提供以数字开头的持续时间值。在这种情况下，如果该值仅包含一个数字，则转换器将该值视为秒。否则，PT 会隐式添加到值的前面，以获得标准的`java.time.Duration` 格式。

先决条件
应用结构
创建Maven项目
创建你的第一个JSON REST服务
Configuring Elasticsearch
- 开发服务（免配置数据库）。
- Programmatically Configuring Elasticsearch
Running an Elasticsearch cluster
运行应用程序
Using the High Level REST Client
Hibernate Search Elasticsearch
Cluster Health Check
构建一个本地可执行文件
解决方案
配置参考