Cwikius-Spring/spring-data-elasticsearch
1
0
Fork 0
mirror of https://github.com/spring-projects/spring-data-elasticsearch.git synced 2025-06-21 11:32:12 +00:00
Code Issues Packages Projects Releases Wiki Activity

Fix documentation index.

Browse Source 
Original Pull Request #2315
Closes #2299
This commit is contained in:
Peter-Josef Meisch 2022-09-28 22:21:23 +02:00 committed by GitHub
parent fb210e338f
commit 5a52d6136f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
14 changed files with 67 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
src/main/asciidoc/reference/elasticsearch-auditing.adoc
View File

@ -1,6 +1,7 @@
[[elasticsearch.auditing]] [[elasticsearch.auditing]]
== Elasticsearch Auditing == Elasticsearch Auditing
[[elasticsearch.auditing.preparing]]
=== Preparing entities === Preparing entities
In order for the auditing code to be able to decide whether an entity instance is new, the entity must implement the `Persistable<ID>` interface which is defined as follows: In order for the auditing code to be able to decide whether an entity instance is new, the entity must implement the `Persistable<ID>` interface which is defined as follows:
@ -54,6 +55,7 @@ public class Person implements Persistable<Long> {
<.> the getter is the required implementation from the interface <.> the getter is the required implementation from the interface
<.> an object is new if it either has no `id` or none of fields containing creation attributes are set. <.> an object is new if it either has no `id` or none of fields containing creation attributes are set.
[[elasticsearch.auditing.activating]]
=== Activating auditing === Activating auditing
After the entities have been set up and providing the `AuditorAware` - or `ReactiveAuditorAware` - the Auditing must be activated by setting the `@EnableElasticsearchAuditing` on a configuration class: After the entities have been set up and providing the `AuditorAware` - or `ReactiveAuditorAware` - the Auditing must be activated by setting the `@EnableElasticsearchAuditing` on a configuration class:

7
src/main/asciidoc/reference/elasticsearch-clients.adoc
View File

@ -233,7 +233,8 @@ Default is 5 sec.
<.> Optionally set headers. <.> Optionally set headers.
<.> Add basic authentication. <.> Add basic authentication.
<.> A `Supplier<Header>` function can be specified which is called every time before a request is sent to Elasticsearch - here, as an example, the current time is written in a header. <.> A `Supplier<Header>` function can be specified which is called every time before a request is sent to Elasticsearch - here, as an example, the current time is written in a header.
<.> a function to configure the created client (see <<elasticsearch.clients.configuration.callbacks>>), can be added multiple times. <.> a function to configure the created client (see <<elasticsearch.clients.configuration.callbacks>>), can be added
multiple times.
==== ====
IMPORTANT: Adding a Header supplier as shown in above example allows to inject headers that may change over the time, like authentication JWT tokens. IMPORTANT: Adding a Header supplier as shown in above example allows to inject headers that may change over the time, like authentication JWT tokens.
@ -247,6 +248,7 @@ enough, the user can add callback functions by using the `withClientConfigurer(C
The following callbacks are provided: The following callbacks are provided:
[[elasticsearch.clients.configuration.callbacks.rest]]
==== Configuration of the low level Elasticsearch `RestClient`: ==== Configuration of the low level Elasticsearch `RestClient`:
==== ====
@ -261,6 +263,7 @@ ClientConfiguration.builder()
---- ----
==== ====
[[elasticsearch.clients.configurationcallbacks.httpasync]]
==== Configuration of the HttpAsyncClient used by the low level Elasticsearch `RestClient`: ==== Configuration of the HttpAsyncClient used by the low level Elasticsearch `RestClient`:
==== ====
@ -275,7 +278,7 @@ ClientConfiguration.builder()
---- ----
==== ====
[[elasticsearch.clients.configuration.headers]]
=== Elasticsearch 7 compatibility headers === Elasticsearch 7 compatibility headers
When using the deprecated `RestHighLevelClient` and accessing an Elasticsearch cluster that is running on version 8, it is necessary to set the compatibility headers When using the deprecated `RestHighLevelClient` and accessing an Elasticsearch cluster that is running on version 8, it is necessary to set the compatibility headers

3
src/main/asciidoc/reference/elasticsearch-join-types.adoc
View File

@ -3,6 +3,7 @@
Spring Data Elasticsearch supports the https://www.elastic.co/guide/en/elasticsearch/reference/current/parent-join.html[Join data type] for creating the corresponding index mappings and for storing the relevant information. Spring Data Elasticsearch supports the https://www.elastic.co/guide/en/elasticsearch/reference/current/parent-join.html[Join data type] for creating the corresponding index mappings and for storing the relevant information.
[[elasticsearch.jointype.setting-up]]
== Setting up the data == Setting up the data
For an entity to be used in a parent child join relationship, it must have a property of type `JoinField` which must be annotated. For an entity to be used in a parent child join relationship, it must have a property of type `JoinField` which must be annotated.
@ -160,6 +161,7 @@ Spring Data Elasticsearch will build the following mapping for this class:
---- ----
==== ====
[[elasticsearch.jointype.storing]]
== Storing data == Storing data
Given a repository for this class the following code inserts a question, two answers, a comment and a vote: Given a repository for this class the following code inserts a question, two answers, a comment and a vote:
@ -209,6 +211,7 @@ void init() {
<5> a vote for the first answer, this needs to have the routing set to the weather document, see <<elasticsearch.routing>>. <5> a vote for the first answer, this needs to have the routing set to the weather document, see <<elasticsearch.routing>>.
==== ====
[[elasticsearch.jointype.retrieving]]
== Retrieving data == Retrieving data
Currently native queries must be used to query the data, so there is no support from standard repository methods. <<repositories.custom-implementations>> can be used instead. Currently native queries must be used to query the data, so there is no support from standard repository methods. <<repositories.custom-implementations>> can be used instead.

2
src/main/asciidoc/reference/elasticsearch-migration-guide-3.2-4.0.adoc
View File

@ -95,6 +95,7 @@ default boolean createIndex(String indexName) {
[[elasticsearch-migration-guide-3.2-4.0.deprecations]] [[elasticsearch-migration-guide-3.2-4.0.deprecations]]
== Deprecations == Deprecations
[[elasticsearch-migration-guide-3.2-4.0.deprecations.methods-classes]]
=== Methods and classes === Methods and classes
Many functions and classes have been deprecated. These functions still work, but the Javadocs show with what they should be replaced. Many functions and classes have been deprecated. These functions still work, but the Javadocs show with what they should be replaced.
@ -115,6 +116,7 @@ Many functions and classes have been deprecated. These functions still work, but
<T> T queryForObject(GetQuery query, Class<T> clazz); <T> T queryForObject(GetQuery query, Class<T> clazz);
---- ----
[[elasticsearch-migration-guide-3.2-4.0.deprecations.elasticsearch]]
=== Elasticsearch deprecations === Elasticsearch deprecations
Since version 7 the Elasticsearch `TransportClient` is deprecated, it will be removed with Elasticsearch version 8. Spring Data Elasticsearch deprecates the `ElasticsearchTemplate` class which uses the `TransportClient` in version 4.0. Since version 7 the Elasticsearch `TransportClient` is deprecated, it will be removed with Elasticsearch version 8. Spring Data Elasticsearch deprecates the `ElasticsearchTemplate` class which uses the `TransportClient` in version 4.0.

4
src/main/asciidoc/reference/elasticsearch-migration-guide-4.0-4.1.adoc
View File

@ -32,6 +32,7 @@ They had been deprecated in Spring Data Elasticsearch 4.0 and their values weren
[[elasticsearch-migration-guide-4.0-4.1.breaking-changes]] [[elasticsearch-migration-guide-4.0-4.1.breaking-changes]]
== Breaking Changes == Breaking Changes
[[elasticsearch-migration-guide-4.0-4.1.breaking-changes.returntypes-1]]
=== Return types of ReactiveElasticsearchClient.Indices methods === Return types of ReactiveElasticsearchClient.Indices methods
The methods in the `ReactiveElasticsearchClient.Indices` were not used up to now. The methods in the `ReactiveElasticsearchClient.Indices` were not used up to now.
@ -40,7 +41,8 @@ With the introduction of the `ReactiveIndexOperations` it became necessary to ch
* the `createIndex` variants now return a `Mono<Boolean>` instead of a `Mono<Void>` to signal successful index creation. * the `createIndex` variants now return a `Mono<Boolean>` instead of a `Mono<Void>` to signal successful index creation.
* the `updateMapping` variants now return a `Mono<Boolean>` instead of a `Mono<Void>` to signal successful mappings storage. * the `updateMapping` variants now return a `Mono<Boolean>` instead of a `Mono<Void>` to signal successful mappings storage.
=== Return types of DocumentOperartions.bulkIndex methods [[elasticsearch-migration-guide-4.0-4.1.breaking-changes.returntypes-2]]
=== Return types of DocumentOperations.bulkIndex methods
These methods were returing a `List<String>` containing the ids of the new indexed records. These methods were returing a `List<String>` containing the ids of the new indexed records.
Now they return a `List<IndexedObjectInformation>`; these objects contain the id and information about optimistic locking (seq_no and primary_term) Now they return a `List<IndexedObjectInformation>`; these objects contain the id and information about optimistic locking (seq_no and primary_term)

8
src/main/asciidoc/reference/elasticsearch-migration-guide-4.1-4.2.adoc
View File

@ -6,6 +6,7 @@ This section describes breaking changes from version 4.1.x to 4.2.x and how remo
[[elasticsearch-migration-guide-4.1-4.2.deprecations]] [[elasticsearch-migration-guide-4.1-4.2.deprecations]]
== Deprecations == Deprecations
[[elasticsearch-migration-guide-4.1-4.2.deprecations.document]]
=== @Document parameters === @Document parameters
The parameters of the `@Document` annotation that are relevant for the index settings (`useServerConfiguration`, `shards`. `replicas`, `refreshIntervall` and `indexStoretype`) have been moved to the `@Setting` annotation. Use in `@Document` is still possible but deprecated. The parameters of the `@Document` annotation that are relevant for the index settings (`useServerConfiguration`, `shards`. `replicas`, `refreshIntervall` and `indexStoretype`) have been moved to the `@Setting` annotation. Use in `@Document` is still possible but deprecated.
@ -28,8 +29,10 @@ The deprecated `find` methods from `ReactiveSearchOperations` and `ReactiveDocum
[[elasticsearch-migration-guide-4.1-4.2.breaking-changes]] [[elasticsearch-migration-guide-4.1-4.2.breaking-changes]]
== Breaking Changes == Breaking Changes
[[elasticsearch-migration-guide-4.1-4.2.breaking-changes.refresh-policy]]
=== RefreshPolicy === RefreshPolicy
[[elasticsearch-migration-guide-4.1-4.2.breaking-changes.refresh-policy.enum]]
==== Enum package changed ==== Enum package changed
It was possible in 4.1 to configure the refresh policy for the `ReactiveElasticsearchTemplate` by overriding the method `AbstractReactiveElasticsearchConfiguration.refreshPolicy()` in a custom configuration class. It was possible in 4.1 to configure the refresh policy for the `ReactiveElasticsearchTemplate` by overriding the method `AbstractReactiveElasticsearchConfiguration.refreshPolicy()` in a custom configuration class.
@ -38,6 +41,7 @@ The return value of this method was an instance of the class `org.elasticsearch.
Now the configuration must return `org.springframework.data.elasticsearch.core.RefreshPolicy`. Now the configuration must return `org.springframework.data.elasticsearch.core.RefreshPolicy`.
This enum has the same values and triggers the same behaviour as before, so only the `import` statement has to be adjusted. This enum has the same values and triggers the same behaviour as before, so only the `import` statement has to be adjusted.
[[elasticsearch-migration-guide-4.1-4.2.breaking-changes.refresh-policy.behaviour]]
==== Refresh behaviour ==== Refresh behaviour
`ElasticsearchOperations` and `ReactiveElasticsearchOperations` now explicitly use the `RefreshPolicy` set on the template for write requests if not null. `ElasticsearchOperations` and `ReactiveElasticsearchOperations` now explicitly use the `RefreshPolicy` set on the template for write requests if not null.
@ -47,17 +51,21 @@ The provided implementations for `ElasticsearchRepository` and `ReactiveElastics
This is the same behaviour as in previous versions. This is the same behaviour as in previous versions.
If a refresh policy is set, then it will be used by the repositories as well. If a refresh policy is set, then it will be used by the repositories as well.
[[elasticsearch-migration-guide-4.1-4.2.breaking-changes.refresh-policy.configuration]]
==== Refresh configuration ==== Refresh configuration
When configuring Spring Data Elasticsearch like described in <<elasticsearch.clients>> by using `ElasticsearchConfigurationSupport`, `AbstractElasticsearchConfiguration` or `AbstractReactiveElasticsearchConfiguration` the refresh policy will be initialized to `null`. When configuring Spring Data Elasticsearch like described in <<elasticsearch.clients>> by using `ElasticsearchConfigurationSupport`, `AbstractElasticsearchConfiguration` or `AbstractReactiveElasticsearchConfiguration` the refresh policy will be initialized to `null`.
Previously the reactive code initialized this to `IMMEDIATE`, now reactive and non-reactive code show the same behaviour. Previously the reactive code initialized this to `IMMEDIATE`, now reactive and non-reactive code show the same behaviour.
[[elasticsearch-migration-guide-4.1-4.2.breaking-changes.method-return-types]]
=== Method return types === Method return types
[[elasticsearch-migration-guide-4.1-4.2.breaking-changes.method-return-types.delete]]
==== delete methods that take a Query ==== delete methods that take a Query
The reactive methods previously returned a `Mono<Long>` with the number of deleted documents, the non reactive versions were void. They now return a `Mono<ByQueryResponse>` which contains much more detailed information about the deleted documents and errors that might have occurred. The reactive methods previously returned a `Mono<Long>` with the number of deleted documents, the non reactive versions were void. They now return a `Mono<ByQueryResponse>` which contains much more detailed information about the deleted documents and errors that might have occurred.
[[elasticsearch-migration-guide-4.1-4.2.breaking-changes.method-return-types.multiget]]
==== multiget methods ==== multiget methods
The implementations of _multiget_ previousl only returned the found entities in a `List<T>` for non-reactive implementations and in a `Flux<T>` for reactive implementations. If the request contained ids that were not found, the information that these are missing was not available. The user needed to compare the returned ids to the requested ones to find The implementations of _multiget_ previousl only returned the found entities in a `List<T>` for non-reactive implementations and in a `Flux<T>` for reactive implementations. If the request contained ids that were not found, the information that these are missing was not available. The user needed to compare the returned ids to the requested ones to find

8
src/main/asciidoc/reference/elasticsearch-migration-guide-4.2-4.3.adoc
View File

@ -21,6 +21,7 @@ Check the sections on <<elasticsearch-migration-guide-4.2-4.3.deprecations>> and
[[elasticsearch-migration-guide-4.2-4.3.deprecations]] [[elasticsearch-migration-guide-4.2-4.3.deprecations]]
== Deprecations == Deprecations
[[elasticsearch-migration-guide-4.2-4.3.deprecations.suggest]]
=== suggest methods === suggest methods
In `SearchOperations`, and so in `ElasticsearchOperations` as well, the `suggest` methods taking a `org.elasticsearch.search.suggest.SuggestBuilder` as argument and returning a `org.elasticsearch.action.search.SearchResponse` have been deprecated. In `SearchOperations`, and so in `ElasticsearchOperations` as well, the `suggest` methods taking a `org.elasticsearch.search.suggest.SuggestBuilder` as argument and returning a `org.elasticsearch.action.search.SearchResponse` have been deprecated.
@ -32,6 +33,7 @@ Here as well the old methods are deprecated.
[[elasticsearch-migration-guide-4.2-4.3.breaking-changes]] [[elasticsearch-migration-guide-4.2-4.3.breaking-changes]]
== Breaking Changes == Breaking Changes
[[elasticsearch-migration-guide-4.2-4.3.breaking-changes.1]]
=== Removal of `org.elasticsearch` classes from the API. === Removal of `org.elasticsearch` classes from the API.
* In the `org.springframework.data.elasticsearch.annotations.CompletionContext` annotation the property `type()` has changed from `org.elasticsearch.search.suggest.completion.context.ContextMapping.Type` to `org.springframework.data.elasticsearch.annotations.CompletionContext.ContextMappingType`, the available enum values are the same. * In the `org.springframework.data.elasticsearch.annotations.CompletionContext` annotation the property `type()` has changed from `org.elasticsearch.search.suggest.completion.context.ContextMapping.Type` to `org.springframework.data.elasticsearch.annotations.CompletionContext.ContextMappingType`, the available enum values are the same.
@ -46,6 +48,7 @@ The same change has been done to the `ReactiveSearchOperations.aggregate()` func
Programs using the aggregations need to be changed to cast the returned value to the appropriate class to further proces it. Programs using the aggregations need to be changed to cast the returned value to the appropriate class to further proces it.
* methods that might have thrown a `org.elasticsearch.ElasticsearchStatusException` now will throw `org.springframework.data.elasticsearch.RestStatusException` instead. * methods that might have thrown a `org.elasticsearch.ElasticsearchStatusException` now will throw `org.springframework.data.elasticsearch.RestStatusException` instead.
[[elasticsearch-migration-guide-4.2-4.3.breaking-changes.2]]
=== Handling of field and sourceFilter properties of Query === Handling of field and sourceFilter properties of Query
Up to version 4.2 the `fields` property of a `Query` was interpreted and added to the include list of the `sourceFilter`. Up to version 4.2 the `fields` property of a `Query` was interpreted and added to the include list of the `sourceFilter`.
@ -53,11 +56,13 @@ This was not correct, as these are different things for Elasticsearch.
This has been corrected. This has been corrected.
As a consequence code might not work anymore that relies on using `fields` to specify which fields should be returned from the document's `_source' and should be changed to use the `sourceFilter`. As a consequence code might not work anymore that relies on using `fields` to specify which fields should be returned from the document's `_source' and should be changed to use the `sourceFilter`.
[[elasticsearch-migration-guide-4.2-4.3.breaking-changes.3]]
=== search_type default value === search_type default value
The default value for the `search_type` in Elasticsearch is `query_then_fetch`. The default value for the `search_type` in Elasticsearch is `query_then_fetch`.
This now is also set as default value in the `Query` implementations, it was previously set to `dfs_query_then_fetch`. This now is also set as default value in the `Query` implementations, it was previously set to `dfs_query_then_fetch`.
[[elasticsearch-migration-guide-4.2-4.3.breaking-changes.4]]
=== BulkOptions changes === BulkOptions changes
Some properties of the `org.springframework.data.elasticsearch.core.query.BulkOptions` class have changed their type: Some properties of the `org.springframework.data.elasticsearch.core.query.BulkOptions` class have changed their type:
@ -65,14 +70,17 @@ Some properties of the `org.springframework.data.elasticsearch.core.query.BulkOp
* the type of the `timeout` property has been changed to `java.time.Duration`. * the type of the `timeout` property has been changed to `java.time.Duration`.
* the type of the`refreshPolicy` property has been changed to `org.springframework.data.elasticsearch.core.RefreshPolicy`. * the type of the`refreshPolicy` property has been changed to `org.springframework.data.elasticsearch.core.RefreshPolicy`.
[[elasticsearch-migration-guide-4.2-4.3.breaking-changes.5]]
=== IndicesOptions change === IndicesOptions change
Spring Data Elasticsearch now uses `org.springframework.data.elasticsearch.core.query.IndicesOptions` instead of `org.elasticsearch.action.support.IndicesOptions`. Spring Data Elasticsearch now uses `org.springframework.data.elasticsearch.core.query.IndicesOptions` instead of `org.elasticsearch.action.support.IndicesOptions`.
[[elasticsearch-migration-guide-4.2-4.3.breaking-changes.6]]
=== Completion classes === Completion classes
The classes from the package `org.springframework.data.elasticsearch.core.completion` have been moved to `org.springframework.data.elasticsearch.core.suggest`. The classes from the package `org.springframework.data.elasticsearch.core.completion` have been moved to `org.springframework.data.elasticsearch.core.suggest`.
[[elasticsearch-migration-guide-4.2-4.3.breaking-changes.7]]
=== Other renamings === Other renamings
The `org.springframework.data.elasticsearch.core.mapping.ElasticsearchPersistentPropertyConverter` interface has been renamed to `org.springframework.data.elasticsearch.core.mapping.PropertyValueConverter`. The `org.springframework.data.elasticsearch.core.mapping.ElasticsearchPersistentPropertyConverter` interface has been renamed to `org.springframework.data.elasticsearch.core.mapping.PropertyValueConverter`.

10
src/main/asciidoc/reference/elasticsearch-migration-guide-4.3-4.4.adoc
View File

@ -6,6 +6,7 @@ This section describes breaking changes from version 4.3.x to 4.4.x and how remo
[[elasticsearch-migration-guide-4.3-4.4.deprecations]] [[elasticsearch-migration-guide-4.3-4.4.deprecations]]
== Deprecations == Deprecations
[[elasticsearch-migration-guide-4.3-4.4.deprecations.reactive-operations]]
=== org.springframework.data.elasticsearch.core.ReactiveElasticsearchOperations === org.springframework.data.elasticsearch.core.ReactiveElasticsearchOperations
The method `<T> Publisher<T> execute(ClientCallback<Publisher<T>> callback)` has been deprecated. The method `<T> Publisher<T> execute(ClientCallback<Publisher<T>> callback)` has been deprecated.
@ -14,6 +15,7 @@ As there now are multiple implementations using different client libraries the `
[[elasticsearch-migration-guide-4.3-4.4.breaking-changes]] [[elasticsearch-migration-guide-4.3-4.4.breaking-changes]]
== Breaking Changes == Breaking Changes
[[elasticsearch-migration-guide-4.3-4.4.breaking-changes.1]]
=== Removal of deprecated classes === Removal of deprecated classes
==== `org.springframework.data.elasticsearch.core.ElasticsearchTemplate` has been removed ==== `org.springframework.data.elasticsearch.core.ElasticsearchTemplate` has been removed
@ -23,11 +25,13 @@ This means that the `org.springframework.data.elasticsearch.core.ElasticsearchTe
This was the implementation of the `ElasticsearchOperations` interface that was using the `TransportClient`. This was the implementation of the `ElasticsearchOperations` interface that was using the `TransportClient`.
Connections to Elasticsearch must be made using either the imperative `ElasticsearchRestTemplate` or the reactive `ReactiveElasticsearchTemplate`. Connections to Elasticsearch must be made using either the imperative `ElasticsearchRestTemplate` or the reactive `ReactiveElasticsearchTemplate`.
[[elasticsearch-migration-guide-4.3-4.4.breaking-changes.2]]
=== Package changes === Package changes
In 4.3 two classes (`ElasticsearchAggregations` and `ElasticsearchAggregation`) had been moved to the `org.springframework.data.elasticsearch.core.clients.elasticsearch7` package in preparation for the integration of the new Elasticsearch client. In 4.3 two classes (`ElasticsearchAggregations` and `ElasticsearchAggregation`) had been moved to the `org.springframework.data.elasticsearch.core.clients.elasticsearch7` package in preparation for the integration of the new Elasticsearch client.
The were moved back to the `org.springframework.data.elasticsearch.core` package as we keep the classes use the old Elasticsearch client where they were. The were moved back to the `org.springframework.data.elasticsearch.core` package as we keep the classes use the old Elasticsearch client where they were.
[[elasticsearch-migration-guide-4.3-4.4.breaking-changes.3]]
=== Behaviour change === Behaviour change
The `ReactiveElasticsearchTemplate`, when created directly or by Spring Boot configuration had a default refresh policy of IMMEDIATE. The `ReactiveElasticsearchTemplate`, when created directly or by Spring Boot configuration had a default refresh policy of IMMEDIATE.
@ -46,6 +50,7 @@ Spring Data Elasticsearch 4.4 still uses the old client as the default client fo
* There are still some bugs in the Elasticsearch client which need to be resolved * There are still some bugs in the Elasticsearch client which need to be resolved
* The implementation using the new client in Spring Data Elasticsearch is not yet complete, due to limited resources working on that - remember Spring Data Elasticsearch is a community driven project that lives from public contributions. * The implementation using the new client in Spring Data Elasticsearch is not yet complete, due to limited resources working on that - remember Spring Data Elasticsearch is a community driven project that lives from public contributions.
[[elasticsearch-migration-guide-4.3-4.4.new-clients.how-to]]
=== How to use the new client === How to use the new client
CAUTION: The implementation using the new client is not complete, some operations will throw a `java.lang.UnsupportedOperationException` or might throw NPE (for example when the Elasticsearch cannot parse a response from the server, this still happens sometimes) + CAUTION: The implementation using the new client is not complete, some operations will throw a `java.lang.UnsupportedOperationException` or might throw NPE (for example when the Elasticsearch cannot parse a response from the server, this still happens sometimes) +
@ -53,6 +58,7 @@ Use the new client to test the implementations but do not use it in productive c
In order to try and use the new client the following steps are necessary: In order to try and use the new client the following steps are necessary:
[[elasticsearch-migration-guide-4.3-4.4.new-clients.how-to.not]]
==== Make sure not to configure the existing default client ==== Make sure not to configure the existing default client
If using Spring Boot, exclude Spring Data Elasticsearch from the autoconfiguration If using Spring Boot, exclude Spring Data Elasticsearch from the autoconfiguration
@ -71,6 +77,7 @@ public class SpringdataElasticTestApplication {
Remove Spring Data Elasticsearch related properties from your application configuration. Remove Spring Data Elasticsearch related properties from your application configuration.
If Spring Data Elasticsearch was configured using a programmatic configuration (see <<elasticsearch.clients>>), remove these beans from the Spring application context. If Spring Data Elasticsearch was configured using a programmatic configuration (see <<elasticsearch.clients>>), remove these beans from the Spring application context.
[[elasticsearch-migration-guide-4.3-4.4.new-clients.how-to.dependencies]]
==== Add dependencies ==== Add dependencies
The dependencies for the new Elasticsearch client are still optional in Spring Data Elasticsearch so they need to be added explicitly: The dependencies for the new Elasticsearch client are still optional in Spring Data Elasticsearch so they need to be added explicitly:
@ -116,8 +123,10 @@ When using Spring Boot, it is necessary to set the following property in the _po
---- ----
==== ====
[[elasticsearch-migration-guide-4.3-4.4.new-clients.how-to.configuration]]
==== New configuration classes ==== New configuration classes
[[elasticsearch-migration-guide-4.3-4.4.new-clients.how-to.configuration.imperative]]
===== Imperative style ===== Imperative style
In order configure Spring Data Elasticsearch to use the new client, it is necessary to create a configuration bean that derives from `org.springframework.data.elasticsearch.client.elc.ElasticsearchConfiguration`: In order configure Spring Data Elasticsearch to use the new client, it is necessary to create a configuration bean that derives from `org.springframework.data.elasticsearch.client.elc.ElasticsearchConfiguration`:
@ -145,6 +154,7 @@ With this configuration, the following beans will be available in the Spring app
* an `ElasticsearchClient` bean, this is the new client that uses the `RestClient` * an `ElasticsearchClient` bean, this is the new client that uses the `RestClient`
* an `ElasticsearchOperations` bean, available with the bean names _elasticsearchOperations_ and _elasticsearchTemplate_, this uses the `ElasticsearchClient` * an `ElasticsearchOperations` bean, available with the bean names _elasticsearchOperations_ and _elasticsearchTemplate_, this uses the `ElasticsearchClient`
[[elasticsearch-migration-guide-4.3-4.4.new-clients.how-to.configuration.reactive]]
===== Reactive style ===== Reactive style
To use the new client in a reactive environment the only difference is the class from which to derive the configuration: To use the new client in a reactive environment the only difference is the class from which to derive the configuration:

8
src/main/asciidoc/reference/elasticsearch-migration-guide-4.4-5.0.adoc
View File

@ -6,10 +6,12 @@ This section describes breaking changes from version 4.4.x to 5.0.x and how remo
[[elasticsearch-migration-guide-4.4-4.5.deprecations]] [[elasticsearch-migration-guide-4.4-4.5.deprecations]]
== Deprecations == Deprecations
[[elasticsearch-migration-guide-4.4-4.5.deprecations.package]]
=== `org.springframework.data.elasticsearch.client.erhlc` package === `org.springframework.data.elasticsearch.client.erhlc` package
See <<elasticsearch-migration-guide-4.4-5.0.breaking-changes-packages>>, all classes in this package have been deprecated, as the default client implementations to use are the ones based on the new Java Client from Elasticsearch, see <<elasticsearch-migration-guide-4.4-5.0.new-clients>> See <<elasticsearch-migration-guide-4.4-5.0.breaking-changes-packages>>, all classes in this package have been deprecated, as the default client implementations to use are the ones based on the new Java Client from Elasticsearch, see <<elasticsearch-migration-guide-4.4-5.0.new-clients>>
[[elasticsearch-migration-guide-4.4-4.5.deprecations.code]]
=== Removal of deprecated code === Removal of deprecated code
`DateFormat.none` and `DateFormat.custom` had been deprecated since version 4.2 and have been removed. `DateFormat.none` and `DateFormat.custom` had been deprecated since version 4.2 and have been removed.
@ -23,8 +25,10 @@ Use `@Document.dynamic` or `@Field.dynamic` instead.
[[elasticsearch-migration-guide-4.4-5.0.breaking-changes]] [[elasticsearch-migration-guide-4.4-5.0.breaking-changes]]
== Breaking Changes == Breaking Changes
[[elasticsearch-migration-guide-4.4-5.0.breaking-changes.deprecated-calls]]
=== Removal of deprecated calls === Removal of deprecated calls
[[elasticsearch-migration-guide-4.4-5.0.breaking-changes.deprecated-calls.1]]
==== suggest calls in operations interfaces have been removed ==== suggest calls in operations interfaces have been removed
Both `SearchOperations` and `ReactiveSearchOperations` had deprecated calls that were using Elasticsearch classes as parameters. Both `SearchOperations` and `ReactiveSearchOperations` had deprecated calls that were using Elasticsearch classes as parameters.
@ -43,6 +47,7 @@ When working with the `NativeSearchQuery` class, you'll need to switch to the `N
`Query` instance comign from the new Elasticsearch client libraries. `Query` instance comign from the new Elasticsearch client libraries.
You'll find plenty of examples in the test code. You'll find plenty of examples in the test code.
[[elasticsearch-migration-guide-4.4-5.0.breaking-changes-records]]
=== Conversion to Java 17 records === Conversion to Java 17 records
The following classes have been converted to `Record`, you might need to adjust the use of getter methods from The following classes have been converted to `Record`, you might need to adjust the use of getter methods from
@ -55,6 +60,7 @@ The following classes have been converted to `Record`, you might need to adjust
* `org.springframework.data.elasticsearch.core.query.ScriptData` * `org.springframework.data.elasticsearch.core.query.ScriptData`
* `org.springframework.data.elasticsearch.core.query.SeqNoPrimaryTerm` * `org.springframework.data.elasticsearch.core.query.SeqNoPrimaryTerm`
[[elasticsearch-migration-guide-4.4-5.0.breaking-changes-http-headers]]
=== New HttpHeaders class === New HttpHeaders class
Until version 4.4 the client configuration used the `HttpHeaders` class from the `org.springframework:spring-web` Until version 4.4 the client configuration used the `HttpHeaders` class from the `org.springframework:spring-web`
@ -75,6 +81,7 @@ Hint: You can pass a `org.springframework.http
Spring Data Elasticsearch now uses the new `ElasticsearchClient` and has deprecated the use of the previous `RestHighLevelClient`. Spring Data Elasticsearch now uses the new `ElasticsearchClient` and has deprecated the use of the previous `RestHighLevelClient`.
[[elasticsearch-migration-guide-4.4-5.0.new-clients.imperative]]
=== Imperative style configuration === Imperative style configuration
To configure Spring Data Elasticsearch to use the new client, it is necessary to create a configuration bean that derives from `org.springframework.data.elasticsearch.client.elc.ElasticsearchConfiguration`: To configure Spring Data Elasticsearch to use the new client, it is necessary to create a configuration bean that derives from `org.springframework.data.elasticsearch.client.elc.ElasticsearchConfiguration`:
@ -102,6 +109,7 @@ With this configuration, the following beans will be available in the Spring app
* an `ElasticsearchClient` bean, this is the new client that uses the `RestClient` * an `ElasticsearchClient` bean, this is the new client that uses the `RestClient`
* an `ElasticsearchOperations` bean, available with the bean names _elasticsearchOperations_ and _elasticsearchTemplate_, this uses the `ElasticsearchClient` * an `ElasticsearchOperations` bean, available with the bean names _elasticsearchOperations_ and _elasticsearchTemplate_, this uses the `ElasticsearchClient`
[[elasticsearch-migration-guide-4.4-5.0.new-clients.reactive]]
=== Reactive style configuration === Reactive style configuration
To use the new client in a reactive environment the only difference is the class from which to derive the configuration: To use the new client in a reactive environment the only difference is the class from which to derive the configuration:

2
src/main/asciidoc/reference/elasticsearch-misc.adoc
View File

@ -204,6 +204,7 @@ Sort.by(new GeoDistanceOrder("location", new GeoPoint(48.137154, 11.5761247)))
From version 7.12 on Elasticsearch has added the feature of runtime fields (https://www.elastic.co/guide/en/elasticsearch/reference/7.12/runtime.html). From version 7.12 on Elasticsearch has added the feature of runtime fields (https://www.elastic.co/guide/en/elasticsearch/reference/7.12/runtime.html).
Spring Data Elasticsearch supports this in two ways: Spring Data Elasticsearch supports this in two ways:
[[elasticsearch.misc.runtime-fields.index-mappings]]
=== Runtime field definitions in the index mappings === Runtime field definitions in the index mappings
The first way to define runtime fields is by adding the definitions to the index mappings (see https://www.elastic.co/guide/en/elasticsearch/reference/7.12/runtime-mapping-fields.html). The first way to define runtime fields is by adding the definitions to the index mappings (see https://www.elastic.co/guide/en/elasticsearch/reference/7.12/runtime-mapping-fields.html).
@ -238,6 +239,7 @@ public class RuntimeFieldEntity {
---- ----
==== ====
[[elasticsearch.misc.runtime-fields.query]]
=== Runtime fields definitions set on a Query === Runtime fields definitions set on a Query
The second way to define runtime fields is by adding the definitions to a search query (see https://www.elastic.co/guide/en/elasticsearch/reference/7.12/runtime-search-request.html). The second way to define runtime fields is by adding the definitions to a search query (see https://www.elastic.co/guide/en/elasticsearch/reference/7.12/runtime-search-request.html).

13
src/main/asciidoc/reference/elasticsearch-object-mapping.adoc
View File

@ -50,8 +50,8 @@ Constructor arguments are mapped by name to the key values in the retrieved Docu
See https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-types.html[Elasticsearch Mapping Types]. See https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-types.html[Elasticsearch Mapping Types].
If the field type is not specified, it defaults to `FieldType.Auto`. If the field type is not specified, it defaults to `FieldType.Auto`.
This means, that no mapping entry is written for the property and that Elasticsearch will add a mapping entry dynamically when the first data for this property is stored (check the Elasticsearch documentation for dynamic mapping rules). This means, that no mapping entry is written for the property and that Elasticsearch will add a mapping entry dynamically when the first data for this property is stored (check the Elasticsearch documentation for dynamic mapping rules).
** `format`: One or more built-in date formats, see the next section <<elasticsearch.mapping.meta-model.date-formats>>. ** `format`: One or more built-in date formats, see the next section <<elasticsearch.mapping.meta-model.annotations.date-formats>>.
** `pattern`: One or more custom date formats, see the next section <<elasticsearch.mapping.meta-model.date-formats>>. ** `pattern`: One or more custom date formats, see the next section <<elasticsearch.mapping.meta-model.annotations.date-formats>>.
** `store`: Flag whether the original field value should be store in Elasticsearch, default value is _false_. ** `store`: Flag whether the original field value should be store in Elasticsearch, default value is _false_.
** `analyzer`, `searchAnalyzer`, `normalizer` for specifying custom analyzers and normalizer. ** `analyzer`, `searchAnalyzer`, `normalizer` for specifying custom analyzers and normalizer.
* `@GeoPoint`: Marks a field as _geo_point_ datatype. * `@GeoPoint`: Marks a field as _geo_point_ datatype.
@ -61,7 +61,7 @@ In difference to a registered Spring `Converter` this only converts the annotate
The mapping metadata infrastructure is defined in a separate spring-data-commons project that is technology agnostic. The mapping metadata infrastructure is defined in a separate spring-data-commons project that is technology agnostic.
[[elasticsearch.mapping.meta-model.date-formats]] [[elasticsearch.mapping.meta-model.annotations.date-formats]]
==== Date format mapping ==== Date format mapping
Properties that derive from `TemporalAccessor` or are of type `java.util.Date` must either have a `@Field` annotation of type `FieldType.Date` or a custom converter must be registered for this type. Properties that derive from `TemporalAccessor` or are of type `java.util.Date` must either have a `@Field` annotation of type `FieldType.Date` or a custom converter must be registered for this type.
@ -103,6 +103,7 @@ The following table shows the different attributes and the mapping created from
NOTE: If you are using a custom date format, you need to use _uuuu_ for the year instead of _yyyy_. NOTE: If you are using a custom date format, you need to use _uuuu_ for the year instead of _yyyy_.
This is due to a https://www.elastic.co/guide/en/elasticsearch/reference/current/migrate-to-java-time.html#java-time-migration-incompatible-date-formats[change in Elasticsearch 7]. This is due to a https://www.elastic.co/guide/en/elasticsearch/reference/current/migrate-to-java-time.html#java-time-migration-incompatible-date-formats[change in Elasticsearch 7].
[[elasticsearch.mapping.meta-model.annotations.range]]
==== Range types ==== Range types
When a field is annotated with a type of one of _Integer_Range, Float_Range, Long_Range, Double_Range, Date_Range,_ or _Ip_Range_ the field must be an instance of a class that will be mapped to an Elasticsearch range, for example: When a field is annotated with a type of one of _Integer_Range, Float_Range, Long_Range, Double_Range, Date_Range,_ or _Ip_Range_ the field must be an instance of a class that will be mapped to an Elasticsearch range, for example:
@ -148,6 +149,7 @@ class SomePersonData {
Supported classes for the type `<T>` are `Integer`, `Long`, `Float`, `Double`, `Date` and classes that implement the Supported classes for the type `<T>` are `Integer`, `Long`, `Float`, `Double`, `Date` and classes that implement the
`TemporalAccessor` interface. `TemporalAccessor` interface.
[[elasticsearch.mapping.meta-model.annotations.mapped-names]]
==== Mapped field names ==== Mapped field names
Without further configuration, Spring Data Elasticsearch will use the property name of an object as field name in Elasticsearch. Without further configuration, Spring Data Elasticsearch will use the property name of an object as field name in Elasticsearch.
@ -160,6 +162,7 @@ A `FieldNamingStrategy` applies to all entities; it can be overwritten by settin
[[elasticsearch.mapping.meta-model.rules]] [[elasticsearch.mapping.meta-model.rules]]
=== Mapping Rules === Mapping Rules
[[elasticsearch.mapping.meta-model.rules.typehints]]
==== Type Hints ==== Type Hints
Mapping uses _type hints_ embedded in the document sent to the server to allow generic type mapping. Mapping uses _type hints_ embedded in the document sent to the server to allow generic type mapping.
@ -240,6 +243,7 @@ WARNING: We strongly advise against disabling Type Hints.
Only do this if you are forced to. Only do this if you are forced to.
Disabling type hints can lead to documents not being retrieved correctly from Elasticsearch in case of polymorphic data or document retrieval may fail completely. Disabling type hints can lead to documents not being retrieved correctly from Elasticsearch in case of polymorphic data or document retrieval may fail completely.
[[elasticsearch.mapping.meta-model.rules.geospatial]]
==== Geospatial Types ==== Geospatial Types
Geospatial types like `Point` & `GeoPoint` are converted into _lat/lon_ pairs. Geospatial types like `Point` & `GeoPoint` are converted into _lat/lon_ pairs.
@ -265,6 +269,7 @@ public class Address {
---- ----
==== ====
[[elasticsearch.mapping.meta-model.rules.geojson]]
==== GeoJson Types ==== GeoJson Types
Spring Data Elasticsearch supports the GeoJson types by providing an interface `GeoJson` and implementations for the different geometries. Spring Data Elasticsearch supports the GeoJson types by providing an interface `GeoJson` and implementations for the different geometries.
@ -305,6 +310,7 @@ The following GeoJson types are implemented:
* `GeoJsonMultiPolygon` * `GeoJsonMultiPolygon`
* `GeoJsonGeometryCollection` * `GeoJsonGeometryCollection`
[[elasticsearch.mapping.meta-model.rules.collections]]
==== Collections ==== Collections
For values inside Collections apply the same mapping rules as for aggregate roots when it comes to _type hints_ and <<elasticsearch.mapping.meta-model.conversions>>. For values inside Collections apply the same mapping rules as for aggregate roots when it comes to _type hints_ and <<elasticsearch.mapping.meta-model.conversions>>.
@ -332,6 +338,7 @@ public class Person {
---- ----
==== ====
[[elasticsearch.mapping.meta-model.rules.maps]]
==== Maps ==== Maps
For values inside Maps apply the same mapping rules as for aggregate roots when it comes to _type hints_ and <<elasticsearch.mapping.meta-model.conversions>>. For values inside Maps apply the same mapping rules as for aggregate roots when it comes to _type hints_ and <<elasticsearch.mapping.meta-model.conversions>>.

2
src/main/asciidoc/reference/elasticsearch-repositories.adoc
View File

@ -40,6 +40,7 @@ include::reactive-elasticsearch-repositories.adoc[leveloffset=+1]
[[elasticsearch.repositories.annotations]] [[elasticsearch.repositories.annotations]]
== Annotations for repository methods == Annotations for repository methods
[[elasticsearch.repositories.annotations.highlight]]
=== @Highlight === @Highlight
The `@Highlight` annotation on a repository method defines for which fields of the returned entity highlighting should be included. To search for some text in a `Book` 's name or summary and have the found data highlighted, the following repository method can be used: The `@Highlight` annotation on a repository method defines for which fields of the returned entity highlighting should be included. To search for some text in a `Book` 's name or summary and have the found data highlighted, the following repository method can be used:
@ -62,6 +63,7 @@ It is possible to define multiple fields to be highlighted like above, and both
In the search results the highlight data can be retrieved from the `SearchHit` class. In the search results the highlight data can be retrieved from the `SearchHit` class.
[[elasticsearch.repositories.annotations.sourcefilters]]
=== @SourceFilters === @SourceFilters
Sometimes the user does not need to have all the properties of an entity returned from a search but only a subset. Sometimes the user does not need to have all the properties of an entity returned from a search but only a subset.

3
src/main/asciidoc/reference/elasticsearch-repository-queries.adoc
View File

@ -6,6 +6,7 @@
The Elasticsearch module supports all basic query building feature as string queries, native search queries, criteria based queries or have it being derived from the method name. The Elasticsearch module supports all basic query building feature as string queries, native search queries, criteria based queries or have it being derived from the method name.
[[elasticsearch.query-methods.finders.declared]]
=== Declared queries === Declared queries
Deriving the query from the method name is not always sufficient and/or may result in unreadable method names. Deriving the query from the method name is not always sufficient and/or may result in unreadable method names.
@ -298,6 +299,7 @@ A list of supported keywords for Elasticsearch is shown below.
NOTE: Methods names to build Geo-shape queries taking `GeoJson` parameters are not supported. NOTE: Methods names to build Geo-shape queries taking `GeoJson` parameters are not supported.
Use `ElasticsearchOperations` with `CriteriaQuery` in a custom repository implementation if you need to have such a function in a repository. Use `ElasticsearchOperations` with `CriteriaQuery` in a custom repository implementation if you need to have such a function in a repository.
[[elasticsearch.query-methods.return-types]]
== Method return types == Method return types
Repository methods can be defined to have the following return types for returning multiple Elements: Repository methods can be defined to have the following return types for returning multiple Elements:
@ -359,4 +361,3 @@ would make an https://www.elastic.co/guide/en/elasticsearch/reference/current/qu
} }
---- ----
==== ====

4
src/main/asciidoc/reference/elasticsearch-routing.adoc
View File

@ -1,4 +1,3 @@
[[elasticsearch.routing]] [[elasticsearch.routing]]
= Routing values = Routing values
@ -8,6 +7,7 @@ For this Elasticsearch offers the possibility to define a routing, which is the
Spring Data Elasticsearch supports routing definitions on storing and retrieving data in the following ways: Spring Data Elasticsearch supports routing definitions on storing and retrieving data in the following ways:
[[elasticsearch.routing.join-types]]
== Routing on join-types == Routing on join-types
When using join-types (see <<elasticsearch.jointype>>), Spring Data Elasticsearch will automatically use the `parent` property of the entity's `JoinField` property as the value for the routing. When using join-types (see <<elasticsearch.jointype>>), Spring Data Elasticsearch will automatically use the `parent` property of the entity's `JoinField` property as the value for the routing.
@ -15,6 +15,7 @@ When using join-types (see <<elasticsearch.jointype>>), Spring Data Elasticsearc
This is correct for all the use-cases where the parent-child relationship has just one level. This is correct for all the use-cases where the parent-child relationship has just one level.
If it is deeper, like a child-parent-grandparent relationship - like in the above example from _vote_ -> _answer_ -> _question_ - then the routing needs to explicitly specified by using the techniques described in the next section (the _vote_ needs the _question.id_ as routing value). If it is deeper, like a child-parent-grandparent relationship - like in the above example from _vote_ -> _answer_ -> _question_ - then the routing needs to explicitly specified by using the techniques described in the next section (the _vote_ needs the _question.id_ as routing value).
[[elasticsearch.routing.custom]]
== Custom routing values == Custom routing values
To define a custom routing for an entity, Spring Data Elasticsearch provides a `@Routing` annotation (reusing the `Statement` class from above): To define a custom routing for an entity, Spring Data Elasticsearch provides a `@Routing` annotation (reusing the `Statement` class from above):
@ -103,4 +104,3 @@ operations.withRouting(RoutingResolver.just(routing)).delete(id);
---- ----
<.> `RoutingResolver.just(s)` returns a resolver that will just return the given String. <.> `RoutingResolver.just(s)` returns a resolver that will just return the given String.
==== ====