components/camel-elasticsearch/src/main/docs/elasticsearch-component.adoc

= Elasticsearch Component
:doctitle: Elasticsearch
:shortname: elasticsearch
:artifactid: camel-elasticsearch
:description: Send requests to ElasticSearch via Java Client API.
:since: 3.19
:supportlevel: Stable
:tabs-sync-option:
:component-header: Only producer is supported
//Manually maintained attributes
:camel-spring-boot-name: elasticsearch

*Since Camel {since}*

*{component-header}*

The ElasticSearch component allows you to interface with an
https://www.elastic.co/products/elasticsearch[ElasticSearch] 8.x API using the Java API Client library.

Maven users will need to add the following dependency to their `pom.xml`
for this component:

[source,xml]
----
<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-elasticsearch</artifactId>
    <version>x.x.x</version>
    <!-- use the same version as your Camel core version -->
</dependency>
----

== URI format

----
elasticsearch://clusterName[?options]
----


// component-configure options: START

// component-configure options: END

// component options: START
include::partial$component-configure-options.adoc[]
include::partial$component-endpoint-options.adoc[]
// component options: END

// endpoint options: START

// endpoint options: END

// component headers: START
include::partial$component-endpoint-headers.adoc[]
// component headers: END

== Message Operations

The following ElasticSearch operations are currently supported. Simply
set an endpoint URI option or exchange header with a key of "operation"
and a value set to one of the following. Some operations also require
other parameters or the message body to be set.

[width="100%",cols="10%,10%,80%",options="header",]
|===
|operation |message body |description

|Index |*Map*, *String*, *byte[]*, *Reader*, *InputStream* or *IndexRequest.Builder* content to index |Adds content to an index and returns the content's indexId in the body.
You can set the name of the target index by setting the message header with the key "indexName".
You can set the indexId by setting the message header with
the key "indexId".

|GetById |*String* or *GetRequest.Builder* index id of content to retrieve |Retrieves the document corresponding to the given index id and returns a GetResponse object in the body.
You can set the name of the target index by setting the message header with the key "indexName".
You can set the type of document by setting the message header with
the key "documentClass".

|Delete |*String* or *DeleteRequest.Builder* index id of content to delete |Deletes the specified indexName and returns a Result object in the body.
You can set the name of the target index by setting the message header with the key "indexName".

|DeleteIndex |*String* or *DeleteIndexRequest.Builder* index name of the index to delete |Deletes the specified indexName and returns a status code in the body.
You can set the name of the target index by setting the message header with the key "indexName".

|Bulk |*Iterable* or *BulkRequest.Builder* of any type that is already accepted (DeleteOperation.Builder for delete operation, UpdateOperation.Builder for update operation, CreateOperation.Builder for create operation, byte[], InputStream, String, Reader, Map or any document type for index operation) | Adds/Updates/Deletes content from/to an index and returns a List<BulkResponseItem> object in the body
You can set the name of the target index by setting the message header with the key "indexName".

|Search |*Map*, *String* or *SearchRequest.Builder* |Search the content with the map of query string.
You can set the name of the target index by setting the message header with the key "indexName".
You can set the number of hits to return by setting the message header with the key "size".
You can set the starting document offset by setting the message header with the key "from".

|MultiSearch |*MsearchRequest.Builder* |Multiple search in one

|MultiGet |*Iterable<String>* or *MgetRequest.Builder* the id of the document to retrieve |Multiple get in one

You can set the name of the target index by setting the message header with the key "indexName".

|Exists |None |Checks whether the index exists or not and returns a Boolean flag in the body.

You must set the name of the target index by setting the message header with the key "indexName".

|Update |*byte[]*, *InputStream*, *String*, *Reader*, *Map* or any document type content to update |Updates content to an index and returns the content's indexId in the body.
You can set the name of the target index by setting the message header with the key "indexName".
You can set the indexId by setting the message header with
the key "indexId". Be aware of the fact that unlike the component _camel-elasticsearch-rest_, by default, the expected content of
an update request must be the same as what the https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-update.html[Update API expects], consequently
if you want to update one part of an existing document, you need to embed the content to update into a "doc" object. To change the default behavior, it is possible
to configure it globally at the component level thanks to the option _enableDocumentOnlyMode_ or by request by setting the header _ElasticsearchConstants.PARAM_DOCUMENT_MODE_ to true.
|Ping |None  |Pings the Elasticsearch cluster and returns true if the ping succeeded, false otherwise

|===

== Configure the component and enable basic authentication
To use the Elasticsearch component it has to be configured with a minimum configuration.

[source,java]
----
ElasticsearchComponent elasticsearchComponent = new ElasticsearchComponent();
elasticsearchComponent.setHostAddresses("myelkhost:9200");
camelContext.addComponent("elasticsearch", elasticsearchComponent);
----

For basic authentication with elasticsearch or using reverse http proxy in front of the elasticsearch cluster, simply setup
basic authentication and SSL on the component like the example below

[source,java]
----
ElasticsearchComponent elasticsearchComponent = new ElasticsearchComponent();
elasticsearchComponent.setHostAddresses("myelkhost:9200");
elasticsearchComponent.setUser("elkuser");
elasticsearchComponent.setPassword("secure!!");
elasticsearchComponent.setEnableSSL(true);
elasticsearchComponent.setCertificatePath(certPath);

camelContext.addComponent("elasticsearch", elasticsearchComponent);
----

== Index Example

Below is a simple INDEX example

[source,java]
----
from("direct:index")
  .to("elasticsearch://elasticsearch?operation=Index&indexName=twitter");
----

[source,xml]
----
<route>
    <from uri="direct:index"/>
    <to uri="elasticsearch://elasticsearch?operation=Index&amp;indexName=twitter"/>
</route>
----

*For this operation you'll need to specify a indexId header.*

A client would simply need to pass a body message containing a Map to
the route. The result body contains the indexId created.

[source,java]
----
Map<String, String> map = new HashMap<String, String>();
map.put("content", "test");
String indexId = template.requestBody("direct:index", map, String.class);
----

== Search Example

Searching on specific field(s) and value use the Operation ´Search´.
Pass in the query JSON String or the Map

[source,java]
----
from("direct:search")
  .to("elasticsearch://elasticsearch?operation=Search&indexName=twitter");
----

[source,xml]
----
<route>
    <from uri="direct:search"/>
    <to uri="elasticsearch://elasticsearch?operation=Search&amp;indexName=twitter"/>
</route>
----

[source,java]
----
String query = "{\"query\":{\"match\":{\"content\":\"new release of ApacheCamel\"}}}";
HitsMetadata<?> response = template.requestBody("direct:search", query, HitsMetadata.class);

----

Search on specific field(s) using Map.

[source,java]
----
Map<String, Object> actualQuery = new HashMap<>();
actualQuery.put("content", "new release of ApacheCamel");

Map<String, Object> match = new HashMap<>();
match.put("match", actualQuery);

Map<String, Object> query = new HashMap<>();
query.put("query", match);
HitsMetadata<?> response = template.requestBody("direct:search", query, HitsMetadata.class);

----

Search using Elasticsearch scroll api in order to fetch all results.

[source,java]
----
from("direct:search")
  .to("elasticsearch://elasticsearch?operation=Search&indexName=twitter&useScroll=true&scrollKeepAliveMs=30000");
----

[source,xml]
----
<route>
    <from uri="direct:search"/>
    <to uri="elasticsearch://elasticsearch?operation=Search&amp;indexName=twitter&amp;useScroll=true&amp;scrollKeepAliveMs=30000"/>
</route>
----

[source,java]
----
String query = "{\"query\":{\"match\":{\"content\":\"new release of ApacheCamel\"}}}";
try (ElasticsearchScrollRequestIterator response = template.requestBody("direct:search", query, ElasticsearchScrollRequestIterator.class)) {
    // do something smart with results
}
----

xref:eips:split-eip.adoc[Split EIP] can also be used.

[source,java]
----
from("direct:search")
  .to("elasticsearch://elasticsearch?operation=Search&indexName=twitter&useScroll=true&scrollKeepAliveMs=30000")
  .split()
  .body()
  .streaming()
  .to("mock:output")
  .end();
----

== MultiSearch Example

MultiSearching on specific field(s) and value use the Operation ´MultiSearch´.
Pass in the MultiSearchRequest instance

[source,java]
----
from("direct:multiSearch")
  .to("elasticsearch://elasticsearch?operation=MultiSearch");
----

[source,xml]
----
<route>
    <from uri="direct:multiSearch"/>
    <to uri="elasticsearch://elasticsearch?operation=MultiSearch"/>
</route>
----

MultiSearch on specific field(s) 

[source,java]
----
MsearchRequest.Builder builder = new MsearchRequest.Builder().index("twitter").searches(
        new RequestItem.Builder().header(new MultisearchHeader.Builder().build())
                .body(new MultisearchBody.Builder().query(b -> b.matchAll(x -> x)).build()).build(),
        new RequestItem.Builder().header(new MultisearchHeader.Builder().build())
                .body(new MultisearchBody.Builder().query(b -> b.matchAll(x -> x)).build()).build());
List<MultiSearchResponseItem<?>> response = template.requestBody("direct:multiSearch", builder, List.class);
----

== Document type

For all the search operations, it is possible to indicate the type of document to retrieve in order to get the result already unmarshalled with the expected type.

The document type can be set using the header "documentClass" or via the uri parameter of the same name.

== Using Camel Elasticsearch with Spring Boot

When you use `camel-elasticsearch-starter` with Spring Boot v2, then you must declare the following
dependency in your own `pom.xml`.

[source,xml]
----
<dependency>
  <groupId>jakarta.json</groupId>
  <artifactId>jakarta.json-api</artifactId>
  <version>2.0.2</version>
</dependency>
----

This is needed because Spring Boot v2 provides jakarta.json-api:1.1.6, and Elasticsearch requires to use json-api v2.

=== Use RestClient provided by Spring Boot

By default Spring Boot will auto configure an Elasticsearch RestClient that will be used by camel, it is possible to customize the client with the following basic properties:

[source,properties]
----
spring.elasticsearch.uris=myelkhost:9200
spring.elasticsearch.username=elkuser
spring.elasticsearch.password=secure!!
----

More information can be found in https://docs.spring.io/spring-boot/docs/current/reference/html/application-properties.html#application-properties.data.spring.elasticsearch.connection-timeout

=== Disable Sniffer when using Spring Boot

When Spring Boot is on the classpath the Sniffer client for Elasticsearch is enabled by default. This option can be disabled in the Spring Boot Configuration:

[source,yaml]
----
spring:
  autoconfigure:
    exclude: org.springframework.boot.autoconfigure.elasticsearch.ElasticsearchRestClientAutoConfiguration
----

include::spring-boot:partial$starter.adoc[]