mirror of
https://github.com/spring-projects/spring-data-elasticsearch.git
synced 2025-05-31 09:12:11 +00:00
DATAES-676 - Fix documentation to reflect the changes in API restructuring.
Original PR: #362
This commit is contained in:
Peter-Josef Meisch
GitHub
parent
d19e699b32
commit
6dfeee3ba9
71
README.adoc
71
README.adoc
@ -13,8 +13,8 @@ This project is lead and maintained by the community.
|
||||
* Spring configuration support using Java based `@Configuration` classes or an XML namespace for a ES clients instances.
|
||||
* `ElasticsearchRestTemplate` helper class that increases productivity performing common ES operations. Includes integrated object mapping between documents and POJOs.
|
||||
* Feature Rich Object Mapping integrated with Spring’s Conversion Service
|
||||
* Annotation based mapping metadata but extensible to support other metadata formats
|
||||
* Automatic implementation of `Repository` interfaces including support for custom finder methods.
|
||||
* Annotation based mapping metadata
|
||||
* Automatic implementation of `Repository` interfaces including support for custom search methods.
|
||||
* CDI support for repositories
|
||||
|
||||
== Code of Conduct
|
||||
@ -53,57 +53,56 @@ public class MyService {
|
||||
repository.save(person);
|
||||
|
||||
List<Person> lastNameResults = repository.findByLastname("Gierke");
|
||||
List<Person> firstNameResults = repository.findByFirstnameLike("Oli*");
|
||||
List<Person> firstNameResults = repository.findByFirstnameLike("Oli");
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
Using Node Client
|
||||
=== Using Transport Client
|
||||
|
||||
NOTE: Usage of the Node Client is deprecated as of version 4.0, use RestClient instead.
|
||||
NOTE: Usage of the TransportClient is deprecated as of version 4.0, use RestClient instead.
|
||||
|
||||
|
||||
[source,xml]
|
||||
[source,java]
|
||||
----
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<beans xmlns="http://www.springframework.org/schema/beans"
|
||||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xmlns:elasticsearch="http://www.springframework.org/schema/data/elasticsearch"
|
||||
xsi:schemaLocation="http://www.springframework.org/schema/data/elasticsearch https://www.springframework.org/schema/data/elasticsearch/spring-elasticsearch.xsd
|
||||
http://www.springframework.org/schema/beans https://www.springframework.org/schema/beans/spring-beans.xsd">
|
||||
@Configuration
|
||||
public class TransportClientConfig extends ElasticsearchConfigurationSupport {
|
||||
|
||||
<elasticsearch:node-client id="client" local="true"/>
|
||||
@Bean
|
||||
public Client elasticsearchClient() throws UnknownHostException {
|
||||
Settings settings = Settings.builder().put("cluster.name", "elasticsearch").build();
|
||||
TransportClient client = new PreBuiltTransportClient(settings);
|
||||
client.addTransportAddress(new TransportAddress(InetAddress.getByName("127.0.0.1"), 9300));
|
||||
return client;
|
||||
}
|
||||
|
||||
<bean name="elasticsearchTemplate" class="org.springframework.data.elasticsearch.core.ElasticsearchTemplate">
|
||||
<constructor-arg name="client" ref="client"/>
|
||||
</bean>
|
||||
|
||||
</beans>
|
||||
@Bean(name = { "elasticsearchOperations", "elasticsearchTemplate" })
|
||||
public ElasticsearchTemplate elasticsearchTemplate() throws UnknownHostException {
|
||||
return new ElasticsearchTemplate(elasticsearchClient());
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
Using Transport Client
|
||||
=== Using the RestClient
|
||||
|
||||
NOTE: Usage of the Transport Client is deprecated as of version 4.0, use RestClient instead.
|
||||
Provide a configuration like this:
|
||||
|
||||
|
||||
[source,xml]
|
||||
[source,java]
|
||||
----
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<beans xmlns="http://www.springframework.org/schema/beans"
|
||||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xmlns:elasticsearch="http://www.springframework.org/schema/data/elasticsearch"
|
||||
xsi:schemaLocation="http://www.springframework.org/schema/data/elasticsearch https://www.springframework.org/schema/data/elasticsearch/spring-elasticsearch.xsd
|
||||
http://www.springframework.org/schema/beans https://www.springframework.org/schema/beans/spring-beans.xsd">
|
||||
@Configuration
|
||||
public class RestClientConfig extends AbstractElasticsearchConfiguration {
|
||||
|
||||
<elasticsearch:repositories base-package="com.xyz.acme"/>
|
||||
@Override
|
||||
@Bean
|
||||
public RestHighLevelClient elasticsearchClient() {
|
||||
|
||||
<elasticsearch:transport-client id="client" cluster-nodes="ip:9300,ip:9300" cluster-name="elasticsearch" />
|
||||
final ClientConfiguration clientConfiguration = ClientConfiguration.builder()
|
||||
.connectedTo("localhost:9200")
|
||||
.build();
|
||||
|
||||
<bean name="elasticsearchTemplate" class="org.springframework.data.elasticsearch.core.ElasticsearchTemplate">
|
||||
<constructor-arg name="client" ref="client"/>
|
||||
</bean>
|
||||
|
||||
</beans>
|
||||
return RestClients.create(clientConfiguration).rest();
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
=== Maven configuration
|
||||
@ -196,7 +195,7 @@ You also need JDK 1.8.
|
||||
|
||||
If you want to build with the regular `mvn` command, you will need https://maven.apache.org/run-maven/index.html[Maven v3.5.0 or above].
|
||||
|
||||
_Also see link:CONTRIBUTING.adoc[CONTRIBUTING.adoc] if you wish to submit pull requests, and in particular please sign the https://cla.pivotal.io/sign/spring[Contributor’s Agreement] before your first non-trivial change._
|
||||
_Also see link:CONTRIBUTING.adoc[CONTRIBUTING.adoc] if you wish to submit pull requests, and in particular please sign the https://cla.pivotal.io/sign/spring[Contributor’s Agreement] before submitting your first pull request._
|
||||
|
||||
=== Building reference documentation
|
||||
|
||||
|
||||
@ -3,7 +3,7 @@
|
||||
|
||||
The Spring Data Elasticsearch project applies core Spring concepts to the development of solutions using the Elasticsearch Search Engine. It provides:
|
||||
|
||||
* _Templates_ as a high-level abstraction for storing, querying, sorting and faceting documents.
|
||||
* _Templates_ as a high-level abstraction for storing, searching, sorting documents and building aggregations.
|
||||
* _Repositories_ which for example enable the user to express queries by defining interfaces having customized method names (for basic information about repositories see <<repositories>>).
|
||||
|
||||
You will notice similarities to the Spring data solr and mongodb support in the Spring Framework.
|
||||
@ -34,11 +34,12 @@ Requires an installation of https://www.elastic.co/products/elasticsearch[Elasti
|
||||
The following table shows the Elasticsearch versions that are used by Spring Data release trains and version of Spring Data Elasticsearch included in that, as well as the Spring Boot versions refering to that particular Spring Data release train:
|
||||
[cols="^,^,^,^",options="header"]
|
||||
|===
|
||||
|Spring Data Release Train |Spring Data Elasticsearch |Elasticsearch | Spring Boot
|
||||
|Moorefootnote:cdv[Currently in development] |3.2.xfootnote:cdv[]|6.8.1 |2.2.0footnote:cdv[]
|
||||
|Lovelace |3.1.x |6.2.2|2.1.x
|
||||
|Kayfootnote:oom[Out of maintenance]|3.0.xfootnote:oom[] |5.5.0 |2.0.xfootnote:oom[]
|
||||
|Ingallsfootnote:oom[]|2.1.xfootnote:oom[] |2.4.0 |1.5.xfootnote:oom[]
|
||||
| Spring Data Release Train |Spring Data Elasticsearch |Elasticsearch | Spring Boot
|
||||
| Neumannfootnote:cdv[Currently in development] |4.0.xfootnote:cdv[]|7.4.1 |2.3.xfootnote:cdv[]
|
||||
| Moore | 3.2.x |6.8.4 | 2.2.x
|
||||
| Lovelace | 3.1.x | 6.2.2 |2.1.x
|
||||
| Kayfootnote:oom[Out of maintenance] | 3.0.xfootnote:oom[] | 5.5.0 | 2.0.xfootnote:oom[]
|
||||
| Ingallsfootnote:oom[] | 2.1.xfootnote:oom[] | 2.4.0 | 1.5.xfootnote:oom[]
|
||||
|===
|
||||
|
||||
Support for upcoming versions of Elasticsearch is being tracked and general compatibility should be given assuming the usage of the <<elasticsearch.clients.rest,high-level REST client>>.
|
||||
|
||||
@ -3,13 +3,13 @@
|
||||
|
||||
This chapter illustrates configuration and usage of supported Elasticsearch client implementations.
|
||||
|
||||
Spring data Elasticsearch operates upon an Elasticsearch client that is connected to a single Elasticsearch node or a cluster. Although the Elasticsearch Client can be used to work with the cluster, applications using Spring Data Elasticsearch normally use the higher level abstractions of <<elasticsearch.operations>> and <<elasticsearch.repositories>>.
|
||||
Spring Data Elasticsearch operates upon an Elasticsearch client that is connected to a single Elasticsearch node or a cluster. Although the Elasticsearch Client can be used to work with the cluster, applications using Spring Data Elasticsearch normally use the higher level abstractions of <<elasticsearch.operations>> and <<elasticsearch.repositories>>.
|
||||
|
||||
[[elasticsearch.clients.transport]]
|
||||
== Transport Client
|
||||
|
||||
WARNING: The well known `TransportClient` is deprecated as of Elasticsearch 7 and will be removed in Elasticsearch 8. (https://www.elastic.co/guide/en/elasticsearch/client/java-api/current/transport-client.html[see the Elasticsearch documentation]). Spring Data Elasticsearch will support the `TransportClient` as long as it is available in the used
|
||||
Elasticsearch <<elasticsearch.versions,version>>.
|
||||
Elasticsearch <<elasticsearch.versions,version>> but has deprecated the classes using it since version 4.0.
|
||||
|
||||
We strongly recommend to use the <<elasticsearch.clients.rest>> instead of the `TransportClient`.
|
||||
|
||||
@ -17,18 +17,21 @@ We strongly recommend to use the <<elasticsearch.clients.rest>> instead of the `
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
static class Config {
|
||||
@Configuration
|
||||
public class TransportClientConfig extends ElasticsearchConfigurationSupport {
|
||||
|
||||
@Bean
|
||||
Client client() {
|
||||
Settings settings = Settings.builder()
|
||||
.put("cluster.name", "elasticsearch") <1>
|
||||
.build();
|
||||
TransportClient client = new PreBuiltTransportClient(settings);
|
||||
client.addTransportAddress(new TransportAddress(InetAddress.getByName("127.0.0.1")
|
||||
, 9300)); <2>
|
||||
return client;
|
||||
}
|
||||
@Bean
|
||||
public Client elasticsearchClient() throws UnknownHostException {
|
||||
Settings settings = Settings.builder().put("cluster.name", "elasticsearch").build(); <1>
|
||||
TransportClient client = new PreBuiltTransportClient(settings);
|
||||
client.addTransportAddress(new TransportAddress(InetAddress.getByName("127.0.0.1"), 9300)); <2>
|
||||
return client;
|
||||
}
|
||||
|
||||
@Bean(name = { "elasticsearchOperations", "elasticsearchTemplate" })
|
||||
public ElasticsearchTemplate elasticsearchTemplate() throws UnknownHostException {
|
||||
return new ElasticsearchTemplate(elasticsearchClient());
|
||||
}
|
||||
}
|
||||
|
||||
// ...
|
||||
@ -46,7 +49,7 @@ IndexResponse response = client.index(request);
|
||||
[[elasticsearch.clients.rest]]
|
||||
== High Level REST Client
|
||||
|
||||
The Java High Level REST Client now is the default client of Elasticsearch, it provides a straight forward replacement for the `TransportClient` as it accepts and returns
|
||||
The Java High Level REST Client is the default client of Elasticsearch, it provides a straight forward replacement for the `TransportClient` as it accepts and returns
|
||||
the very same request/response objects and therefore depends on the Elasticsearch core project.
|
||||
Asynchronous calls are operated upon a client managed thread pool and require a callback to be notified when the request is done.
|
||||
|
||||
@ -54,18 +57,19 @@ Asynchronous calls are operated upon a client managed thread pool and require a
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
import org.springframework.beans.factory.annotation.Autowired;@Configuration
|
||||
static class Config {
|
||||
@Configuration
|
||||
public class RestClientConfig extends AbstractElasticsearchConfiguration {
|
||||
|
||||
@Bean
|
||||
RestHighLevelClient client() {
|
||||
@Override
|
||||
@Bean
|
||||
public RestHighLevelClient elasticsearchClient() {
|
||||
|
||||
ClientConfiguration clientConfiguration = ClientConfiguration.builder() <1>
|
||||
.connectedTo("localhost:9200", "localhost:9201")
|
||||
.build();
|
||||
final ClientConfiguration clientConfiguration = ClientConfiguration.builder() <1>
|
||||
.connectedTo("localhost:9200")
|
||||
.build();
|
||||
|
||||
return RestClients.create(clientConfiguration).rest(); <2>
|
||||
}
|
||||
return RestClients.create(clientConfiguration).rest(); <2>
|
||||
}
|
||||
}
|
||||
|
||||
// ...
|
||||
@ -73,7 +77,7 @@ static class Config {
|
||||
@Autowired
|
||||
RestHighLevelClient highLevelClient;
|
||||
|
||||
RestClient lowLevelClient = highLevelClient.lowLevelClient(); <3>
|
||||
RestClient lowLevelClient = highLevelClient.lowLevelClient(); <3>
|
||||
|
||||
// ...
|
||||
|
||||
@ -138,27 +142,31 @@ Client behaviour can be changed via the `ClientConfiguration` that allows to set
|
||||
[source,java]
|
||||
----
|
||||
// optional if Basic Auhtentication is needed
|
||||
HttpHeaders defaultHeaders = new HttpHeaders();
|
||||
defaultHeaders.setBasicAuth(USER_NAME, USER_PASS); <1>
|
||||
HttpHeaders httpHeaders = new HttpHeaders();
|
||||
httpHeaders.add("es-security-runas-user", "some-user") <1>
|
||||
|
||||
ClientConfiguration clientConfiguration = ClientConfiguration.builder()
|
||||
.connectedTo("localhost:9200", "localhost:9291") <2>
|
||||
.withConnectTimeout(Duration.ofSeconds(5)) <3>
|
||||
.withSocketTimeout(Duration.ofSeconds(3)) <4>
|
||||
.useSsl() <5>
|
||||
.withDefaultHeaders(defaultHeaders) <6>
|
||||
.withBasicAuth(username, password) <7>
|
||||
.withProxy("localhost:8888") <3>
|
||||
.withPathPrefix("ela") <4>
|
||||
.withConnectTimeout(Duration.ofSeconds(5)) <5>
|
||||
.withSocketTimeout(Duration.ofSeconds(3)) <6>
|
||||
.useSsl() <7>
|
||||
.withDefaultHeaders(defaultHeaders) <8>
|
||||
.withBasicAuth(username, password) <9>
|
||||
. // ... other options
|
||||
.build();
|
||||
|
||||
----
|
||||
<1> Define default headers, if they need to be customized
|
||||
<2> Use the builder to provide cluster addresses, set default `HttpHeaders` or enable SSL.
|
||||
<3> Set the connection timeout. Default is 10 sec.
|
||||
<4> Set the socket timeout. Default is 5 sec.
|
||||
<5> Optionally enable SSL.
|
||||
<6> Optionally set headers.
|
||||
<7> Add basic authentication.
|
||||
<3> Optionally set a proxy footnote:notreactive[not yet implemented for the reactive client].
|
||||
<4> Optionally set a path prefix, mostly used when different clusters a behind some reverse proxy.
|
||||
<5> Set the connection timeout. Default is 10 sec.
|
||||
<6> Set the socket timeout. Default is 5 sec.
|
||||
<7> Optionally enable SSL.
|
||||
<8> Optionally set headers.
|
||||
<9> Add basic authentication.
|
||||
====
|
||||
|
||||
[[elasticsearch.clients.logging]]
|
||||
|
||||
@ -11,27 +11,30 @@ Filter Builder improves query speed.
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
private ElasticsearchTemplate elasticsearchTemplate;
|
||||
private ElasticsearchOperations operations;
|
||||
|
||||
IndexCoordinates index = IndexCoordinates.of("sample-index");
|
||||
|
||||
SearchQuery searchQuery = new NativeSearchQueryBuilder()
|
||||
.withQuery(matchAllQuery())
|
||||
.withFilter(boolFilter().must(termFilter("id", documentId)))
|
||||
.build();
|
||||
|
||||
Page<SampleEntity> sampleEntities =
|
||||
elasticsearchTemplate.queryForPage(searchQuery,SampleEntity.class);
|
||||
Page<SampleEntity> sampleEntities = operations.searchForPage(searchQuery, SampleEntity.class, index);
|
||||
----
|
||||
====
|
||||
|
||||
[[elasticsearch.scroll]]
|
||||
== Using Scroll For Big Result Set
|
||||
|
||||
Elasticsearch has a scroll API for getting big result set in chunks. `ElasticsearchTemplate` has startScroll and continueScroll methods that can be used as below.
|
||||
Elasticsearch has a scroll API for getting big result set in chunks. `ElasticsearchOperations` has startScroll and continueScroll methods that can be used as below.
|
||||
|
||||
.Using startScroll and continueScroll
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
IndexCoordinates index = IndexCoordinates.of("sample-index");
|
||||
|
||||
SearchQuery searchQuery = new NativeSearchQueryBuilder()
|
||||
.withQuery(matchAllQuery())
|
||||
.withIndices(INDEX_NAME)
|
||||
@ -40,25 +43,27 @@ SearchQuery searchQuery = new NativeSearchQueryBuilder()
|
||||
.withPageable(PageRequest.of(0, 10))
|
||||
.build();
|
||||
|
||||
ScrolledPage<SampleEntity> scroll = elasticsearchTemplate.startScroll(1000, searchQuery, SampleEntity.class);
|
||||
ScrolledPage<SampleEntity> scroll = operations.startScroll(1000, searchQuery, SampleEntity.class, index);
|
||||
|
||||
String scrollId = scroll.getScrollId();
|
||||
List<SampleEntity> sampleEntities = new ArrayList<>();
|
||||
while (scroll.hasContent()) {
|
||||
sampleEntities.addAll(scroll.getContent());
|
||||
scrollId = scroll.getScrollId();
|
||||
scroll = elasticsearchTemplate.continueScroll(scrollId, 1000, SampleEntity.class);
|
||||
scroll = operations.continueScroll(scrollId, 1000, SampleEntity.class);
|
||||
}
|
||||
elasticsearchTemplate.clearScroll(scrollId);
|
||||
operations.clearScroll(scrollId);
|
||||
----
|
||||
====
|
||||
|
||||
`ElasticsearchTemplate` additionally has the stream method which wraps the scan and scroll operations into a CloseableIterator.
|
||||
`ElasticsearchOperations` additionally has the stream method which wraps the scan and scroll operations into a CloseableIterator.
|
||||
|
||||
.Using stream
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
IndexCoordinates index = IndexCoordinates.of("sample-index");
|
||||
|
||||
SearchQuery searchQuery = new NativeSearchQueryBuilder()
|
||||
.withQuery(matchAllQuery())
|
||||
.withIndices(INDEX_NAME)
|
||||
@ -67,7 +72,7 @@ SearchQuery searchQuery = new NativeSearchQueryBuilder()
|
||||
.withPageable(PageRequest.of(0, 10))
|
||||
.build();
|
||||
|
||||
CloseableIterator<SampleEntity> stream = elasticsearchTemplate.stream(searchQuery, SampleEntity.class);
|
||||
CloseableIterator<SampleEntity> stream = elasticsearchTemplate.stream(searchQuery, SampleEntity.class, index);
|
||||
|
||||
List<SampleEntity> sampleEntities = new ArrayList<>();
|
||||
while (stream.hasNext()) {
|
||||
|
||||
@ -1,6 +1,18 @@
|
||||
[[new-features]]
|
||||
= What's new
|
||||
|
||||
[[new-features.4-0-0]]
|
||||
== New in Spring Data Elasticsearch 4.0
|
||||
|
||||
* Uses Spring 5.2.
|
||||
* Upgrade to Elasticsearch 7.4.1.
|
||||
* Deprecation of `TransportClient` usage.
|
||||
* Implements most of the mapping-types available for the index mappings.
|
||||
* Removal of the Jackson `ObjectMapper`, now using the <<elasticsearch.mapping.meta-model,MappingElasticsearchConverter>>
|
||||
* Cleanup of the API in the `*Operations` interfaces, grouping and renaming methods so that they match the Elasticsearch API, deprecating the old methods, aligning with other Spring Data modules.
|
||||
* Introduction of `SearchHit<T>` class to represent a found document together with the relevant result metadata for this document (i.e. _sortValues_).
|
||||
* Introduction of the `SearchHits<T>` class to represent a whole search result together with the metadata for the complete search result (i.e. _max_score_).
|
||||
|
||||
[[new-features.3-2-0]]
|
||||
== New in Spring Data Elasticsearch 3.2
|
||||
|
||||
|
||||
@ -1,36 +1,15 @@
|
||||
[[elasticsearch.mapping]]
|
||||
= Elasticsearch Object Mapping
|
||||
|
||||
Spring Data Elasticsearch allows to choose between two mapping implementations abstracted via the `EntityMapper` interface:
|
||||
Spring Data Elasticsearch Object Mapping is the process that maps a Java object - the domain entity - into the JSON representation that is stored in Elasticsearch and back.
|
||||
|
||||
* <<elasticsearch.mapping.jackson2>>
|
||||
* <<elasticsearch.mapping.meta-model>>
|
||||
Earlier versions of Spring Data Elasticsearch used a Jackson based conversion, Spring Data Elasticsearch 3.2.x introduced the <<elasticsearch.mapping.meta-model>>. As of version 4.0 only the Meta Object Mapping is used, the Jackson based mapper is not available anymore.
|
||||
|
||||
[[elasticsearch.mapping.jackson2]]
|
||||
== Jackson Object Mapping
|
||||
The main reasons for the removal of the Jackson based mapper are:
|
||||
|
||||
The Jackson2 based approach (used by default) utilizes a customized `ObjectMapper` instance with spring data specific modules.
|
||||
Extensions to the actual mapping need to be customized via Jackson annotations like `@JsonInclude`.
|
||||
* Custom mappings of fields needed to be done with annotations like `@JsonFormat` or `@JsonInclude`. This often caused problems when the same object was used in different JSON based datastores or sent over a JSON based API.
|
||||
* Custom field types and formats also need to be stored into the Elasticsearch index mappings. The Jackson based annotations did not fully provide all the information that is necessary to represent the types of Elasticsearch.
|
||||
|
||||
.Jackson2 Object Mapping Configuration
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
@Configuration
|
||||
public class Config extends AbstractElasticsearchConfiguration { <1>
|
||||
|
||||
@Override
|
||||
public RestHighLevelClient elasticsearchClient() {
|
||||
return RestClients.create(ClientConfiguration.create("localhost:9200")).rest();
|
||||
}
|
||||
}
|
||||
----
|
||||
<1> `AbstractElasticsearchConfiguration` already defines a Jackson2 based `entityMapper` via `ElasticsearchConfigurationSupport`.
|
||||
====
|
||||
|
||||
[WARNING]
|
||||
`CustomConversions`, `@ReadingConverter` & `@WritingConverter` cannot be applied when using the Jackson based `EntityMapper`. +
|
||||
Setting the name of a mapped field with `@Field(name="custom-name")` also cannot be used with this Mapper.
|
||||
|
||||
[[elasticsearch.mapping.meta-model]]
|
||||
== Meta Model Object Mapping
|
||||
@ -38,43 +17,13 @@ Setting the name of a mapped field with `@Field(name="custom-name")` also cannot
|
||||
The Metamodel based approach uses domain type information for reading/writing from/to Elasticsearch.
|
||||
This allows to register `Converter` instances for specific domain type mapping.
|
||||
|
||||
.Meta Model Object Mapping Configuration
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
@Configuration
|
||||
public class Config extends AbstractElasticsearchConfiguration {
|
||||
|
||||
@Override
|
||||
public RestHighLevelClient elasticsearchClient() {
|
||||
return RestClients.create(ClientConfiguration.create("localhost:9200")).rest()
|
||||
}
|
||||
|
||||
@Bean
|
||||
@Override
|
||||
public EntityMapper entityMapper() { <1>
|
||||
|
||||
ElasticsearchEntityMapper entityMapper = new ElasticsearchEntityMapper(
|
||||
elasticsearchMappingContext(), new DefaultConversionService() <2>
|
||||
);
|
||||
entityMapper.setConversions(elasticsearchCustomConversions()); <3>
|
||||
|
||||
return entityMapper;
|
||||
}
|
||||
}
|
||||
----
|
||||
<1> Overwrite the default `EntityMapper` from `ElasticsearchConfigurationSupport` and expose it as bean.
|
||||
<2> Use the provided `SimpleElasticsearchMappingContext` to avoid inconsistencies and provide a `GenericConversionService`
|
||||
for `Converter` registration.
|
||||
<3> Optionally set `CustomConversions` if applicable.
|
||||
====
|
||||
|
||||
[[elasticsearch.mapping.meta-model.annotations]]
|
||||
=== Mapping Annotation Overview
|
||||
|
||||
The `ElasticsearchEntityMapper` can use metadata to drive the mapping of objects to documents. The following annotations are available:
|
||||
The `ElasticsearchEntityMapper` can use metadata to drive the mapping of objects to documents. The metadata is taken from the entities properties which can be annotated.
|
||||
|
||||
The following annotations are available:
|
||||
|
||||
* `@Id`: Applied at the field level to mark the field used for identity purpose.
|
||||
* `@Document`: Applied at the class level to indicate this class is a candidate for mapping to the database. The most important attributes are:
|
||||
** `indexName`: the name of the index to store this entity in
|
||||
** `type`: the mapping type. If not set, the lowercased simple name of the class is used.
|
||||
@ -84,18 +33,18 @@ The `ElasticsearchEntityMapper` can use metadata to drive the mapping of objects
|
||||
** `indexStoreType`: Index storage type for the index. Used for index creation. Default value is _"fs"_.
|
||||
** `createIndex`: Configuration whether to create an index on repository bootstrapping. Default value is _true_.
|
||||
** `versionType`: Configuration of version management. Default value is _EXTERNAL_.
|
||||
* `@Id`: Applied at the field level to mark the field used for identity purpose.
|
||||
* `@Transient`: By default all private fields are mapped to the document, this annotation excludes the field where it is applied from being stored in the database
|
||||
* `@PersistenceConstructor`: Marks a given constructor - even a package protected one - to use when instantiating the object from the database. Constructor arguments are mapped by name to the key values in the retrieved Document.
|
||||
* `@Field`: Applied at the field level and defines properties of the field, most of the attributes map to the respective https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping.html[Elasticsearch Mapping] definitions:
|
||||
** `name`: The name of the field as it will be represented in the Elasticsearch document, if not set, the Java field name is used.
|
||||
** `type`: the field type, can be one of _Text, Integer, Long, Date, Float, Double, Boolean, Object, Auto, Nested, Ip, Attachment, Keyword_.
|
||||
** `type`: the field type, can be one of _Text, Integer, Long, Date, Float, Double, Boolean, Object, Auto, Nested, Ip, Attachment, Keyword_. See https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-types.html[Elasticsearch Mapping Types]
|
||||
** `format` and `pattern` custom definitions for the _Date_ type.
|
||||
** `store`: Flag wether the original field value should be store in Elasticsearch, default value is _false_.
|
||||
** `analyzer`, `searchAnalyzer`, `normalizer` for specifying custom custom analyzers and normalizer.
|
||||
** `copy_to`: the target field to copy multiple document fields to.
|
||||
* `@GeoPoint`: marks a field as _geo_point_ datatype. Can be omitted if the field is an instance of the `GeoPoint` class.
|
||||
|
||||
|
||||
The mapping metadata infrastructure is defined in a separate spring-data-commons project that is technology agnostic.
|
||||
|
||||
[[elasticsearch.mapping.meta-model.rules]]
|
||||
|
||||
@ -1,10 +1,18 @@
|
||||
[[elasticsearch.operations]]
|
||||
= Elasticsearch Operations
|
||||
|
||||
Spring Data Elasticsearch uses two interfaces to define the operations that can be called against an Elasticsearch index. These are `ElasticsearchOperations` and `ReactiveElasticsearchOperations`. Whereas the first is used with the classic synchronous implementations, the second one uses reactive infrastructure.
|
||||
Spring Data Elasticsearch uses several interfaces to define the operations that can be called against an Elasticsearch index (for a description of the reactive interfaces see <<elasticsearch.reactive.operations>>).
|
||||
|
||||
* `IndexOperations` defines actions on index level like creating or deleting an index.
|
||||
* `DocumentOperations` defines actions to store, update and retrieve entities based on their id.
|
||||
* `SearchOperations` define the actions to search for multiple entities using queries
|
||||
* `ElasticsearchOperations` combines the `DocumentOperations` and `SearchOperations` interfaces.
|
||||
|
||||
These interfaces correspond to the structuring of the https://www.elastic.co/guide/en/elasticsearch/reference/current/rest-apis.html[Elasticsearch API].
|
||||
|
||||
The default implementations of the interfaces offer:
|
||||
|
||||
* index management functionality.
|
||||
* Read/Write mapping support for domain types.
|
||||
* A rich query and criteria api.
|
||||
* Resource management and Exception translation.
|
||||
@ -35,21 +43,10 @@ public class TransportClientConfig extends ElasticsearchConfigurationSupport {
|
||||
public ElasticsearchTemplate elasticsearchTemplate() throws UnknownHostException { <2>
|
||||
return new ElasticsearchTemplate(elasticsearchClient(), entityMapper());
|
||||
}
|
||||
|
||||
// use the ElasticsearchEntityMapper
|
||||
@Bean
|
||||
@Override
|
||||
public EntityMapper entityMapper() { <3>
|
||||
ElasticsearchEntityMapper entityMapper = new ElasticsearchEntityMapper(elasticsearchMappingContext(),
|
||||
new DefaultConversionService());
|
||||
entityMapper.setConversions(elasticsearchCustomConversions());
|
||||
return entityMapper;
|
||||
}
|
||||
}
|
||||
----
|
||||
<1> Setting up the <<elasticsearch.clients.transport>>. Deprecatedas of version 4.0.
|
||||
<1> Setting up the <<elasticsearch.clients.transport>>. Deprecated as of version 4.0.
|
||||
<2> Creating the `ElasticsearchTemplate` bean, offering both names, _elasticsearchOperations_ and _elasticsearchTemplate_.
|
||||
<3> Using the <<elasticsearch.mapping.meta-model>> ElasticsearchMapper.
|
||||
====
|
||||
|
||||
[[elasticsearch.operations.resttemplate]]
|
||||
@ -69,29 +66,16 @@ public class RestClientConfig extends AbstractElasticsearchConfiguration {
|
||||
}
|
||||
|
||||
// no special bean creation needed <2>
|
||||
|
||||
// use the ElasticsearchEntityMapper
|
||||
@Bean
|
||||
@Override
|
||||
public EntityMapper entityMapper() { <3>
|
||||
ElasticsearchEntityMapper entityMapper = new ElasticsearchEntityMapper(elasticsearchMappingContext(),
|
||||
new DefaultConversionService());
|
||||
entityMapper.setConversions(elasticsearchCustomConversions());
|
||||
|
||||
return entityMapper;
|
||||
}
|
||||
}
|
||||
----
|
||||
<1> Setting up the <<elasticsearch.clients.rest>>.
|
||||
<2> The base class `AbstractElasticsearchConfiguration` already provides the `elasticsearchTemplate` bean.
|
||||
<3> Using the <<elasticsearch.mapping.meta-model>> ElasticsearchMapper.
|
||||
====
|
||||
|
||||
[[elasticsearch.operations.usage]]
|
||||
== Usage examples
|
||||
|
||||
As both `ElasticsearchTemplate` and `ElasticsearchRestTemplate` implement the `ElasticsearchOperations` interface, the code to use them is not different. The example shows how to use an injected `ElasticsearchOperations` instance in a Spring REST controller. The decision, if this is using the `TransportClient` or the `RestClient` is made by providing the
|
||||
corresponding Bean with one of the configurations shown above.
|
||||
As both `ElasticsearchTemplate` and `ElasticsearchRestTemplate` implement the `ElasticsearchOperations` interface, the code to use them is not different. The example shows how to use an injected `ElasticsearchOperations` instance in a Spring REST controller. The decision, if this is using the `TransportClient` or the `RestClient` is made by providing the corresponding Bean with one of the configurations shown above.
|
||||
|
||||
.ElasticsearchOperations usage
|
||||
====
|
||||
@ -135,3 +119,26 @@ public class TestController {
|
||||
To see the full possibilities of `ElasticsearchOperations` please refer to the API documentation.
|
||||
|
||||
include::reactive-elasticsearch-operations.adoc[leveloffset=+1]
|
||||
|
||||
[[elasticsearch.operations.searchresulttypes]]
|
||||
== Search Result Types
|
||||
|
||||
When a document is retrieved with the methods of the `DocumentOperations` interface, just the found entity will be returned. When searching with the methods of the `SearchOperations` interface, additional information is available for each entity, for example the _score_ or the _sortValues_ of the found entity.
|
||||
|
||||
In order to return this information, each entity is wrapped in a `SearchHit` object that contains this entity-specific additional information. These `SearchHit` objects themselves are returned within a `SearchHits` object which additionally contains informations about the whole search ike the _maxScore_ or requested aggregations.
|
||||
|
||||
.SearchHit<T>
|
||||
Contains the following information:
|
||||
|
||||
* Id
|
||||
* Score
|
||||
* Sort Values
|
||||
* the retrieved entity of type <T>
|
||||
|
||||
.SearchHits<T>
|
||||
Contains the following information:
|
||||
|
||||
* Number of total hits
|
||||
* Maximum score
|
||||
* A list of `SearchHit<T>` objects
|
||||
|
||||
|
||||
@ -25,8 +25,8 @@ import org.springframework.data.elasticsearch.core.query.AliasQuery;
|
||||
|
||||
/**
|
||||
* ElasticsearchOperations. Since 4.0 this interface only contains common helper functions, the other methods have been
|
||||
* moved to the different interfaces that are extended by ElasticsearchOperations. The interfaces now reflect the <a
|
||||
* href="https://www.elastic.co/guide/en/elasticsearch/reference/current/rest-apis.html>REST API structure</a> of
|
||||
* moved to the different interfaces that are extended by ElasticsearchOperations. The interfaces now reflect the
|
||||
* <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/rest-apis.html">REST API structure</a> of
|
||||
* Elasticsearch.
|
||||
*
|
||||
* @author Rizwan Idrees
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user