From 5a52d6136f3f9b46fbb45934ab65c334ee7cbfef Mon Sep 17 00:00:00 2001 From: Peter-Josef Meisch Date: Wed, 28 Sep 2022 22:21:23 +0200 Subject: [PATCH] Fix documentation index. Original Pull Request #2315 Closes #2299 --- .../asciidoc/reference/elasticsearch-auditing.adoc | 2 ++ .../asciidoc/reference/elasticsearch-clients.adoc | 7 +++++-- .../reference/elasticsearch-join-types.adoc | 3 +++ .../elasticsearch-migration-guide-3.2-4.0.adoc | 2 ++ .../elasticsearch-migration-guide-4.0-4.1.adoc | 4 +++- .../elasticsearch-migration-guide-4.1-4.2.adoc | 8 ++++++++ .../elasticsearch-migration-guide-4.2-4.3.adoc | 8 ++++++++ .../elasticsearch-migration-guide-4.3-4.4.adoc | 10 ++++++++++ .../elasticsearch-migration-guide-4.4-5.0.adoc | 8 ++++++++ src/main/asciidoc/reference/elasticsearch-misc.adoc | 2 ++ .../reference/elasticsearch-object-mapping.adoc | 13 ++++++++++--- .../reference/elasticsearch-repositories.adoc | 2 ++ .../reference/elasticsearch-repository-queries.adoc | 3 ++- .../asciidoc/reference/elasticsearch-routing.adoc | 4 ++-- 14 files changed, 67 insertions(+), 9 deletions(-) diff --git a/src/main/asciidoc/reference/elasticsearch-auditing.adoc b/src/main/asciidoc/reference/elasticsearch-auditing.adoc index 7783db346..107b2b48f 100644 --- a/src/main/asciidoc/reference/elasticsearch-auditing.adoc +++ b/src/main/asciidoc/reference/elasticsearch-auditing.adoc @@ -1,6 +1,7 @@ [[elasticsearch.auditing]] == Elasticsearch Auditing +[[elasticsearch.auditing.preparing]] === 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` interface which is defined as follows: @@ -54,6 +55,7 @@ public class Person implements Persistable { <.> 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. +[[elasticsearch.auditing.activating]] === 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: diff --git a/src/main/asciidoc/reference/elasticsearch-clients.adoc b/src/main/asciidoc/reference/elasticsearch-clients.adoc index 5c8fae707..8abb192e5 100644 --- a/src/main/asciidoc/reference/elasticsearch-clients.adoc +++ b/src/main/asciidoc/reference/elasticsearch-clients.adoc @@ -233,7 +233,8 @@ Default is 5 sec. <.> Optionally set headers. <.> Add basic authentication. <.> A `Supplier
` 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 <>), can be added multiple times. +<.> a function to configure the created client (see <>), 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. @@ -247,6 +248,7 @@ enough, the user can add callback functions by using the `withClientConfigurer(C The following callbacks are provided: +[[elasticsearch.clients.configuration.callbacks.rest]] ==== 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`: ==== @@ -275,7 +278,7 @@ ClientConfiguration.builder() ---- ==== - +[[elasticsearch.clients.configuration.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 diff --git a/src/main/asciidoc/reference/elasticsearch-join-types.adoc b/src/main/asciidoc/reference/elasticsearch-join-types.adoc index 2af07748a..5c6a95348 100644 --- a/src/main/asciidoc/reference/elasticsearch-join-types.adoc +++ b/src/main/asciidoc/reference/elasticsearch-join-types.adoc @@ -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. +[[elasticsearch.jointype.setting-up]] == 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. @@ -160,6 +161,7 @@ Spring Data Elasticsearch will build the following mapping for this class: ---- ==== +[[elasticsearch.jointype.storing]] == Storing data 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.jointype.retrieving]] == Retrieving data Currently native queries must be used to query the data, so there is no support from standard repository methods. <> can be used instead. diff --git a/src/main/asciidoc/reference/elasticsearch-migration-guide-3.2-4.0.adoc b/src/main/asciidoc/reference/elasticsearch-migration-guide-3.2-4.0.adoc index 3e66b0086..258ecc0eb 100644 --- a/src/main/asciidoc/reference/elasticsearch-migration-guide-3.2-4.0.adoc +++ b/src/main/asciidoc/reference/elasticsearch-migration-guide-3.2-4.0.adoc @@ -95,6 +95,7 @@ default boolean createIndex(String indexName) { [[elasticsearch-migration-guide-3.2-4.0.deprecations]] == Deprecations +[[elasticsearch-migration-guide-3.2-4.0.deprecations.methods-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. @@ -115,6 +116,7 @@ Many functions and classes have been deprecated. These functions still work, but T queryForObject(GetQuery query, Class clazz); ---- +[[elasticsearch-migration-guide-3.2-4.0.deprecations.elasticsearch]] === 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. diff --git a/src/main/asciidoc/reference/elasticsearch-migration-guide-4.0-4.1.adoc b/src/main/asciidoc/reference/elasticsearch-migration-guide-4.0-4.1.adoc index 8765ffcce..cbc545be2 100644 --- a/src/main/asciidoc/reference/elasticsearch-migration-guide-4.0-4.1.adoc +++ b/src/main/asciidoc/reference/elasticsearch-migration-guide-4.0-4.1.adoc @@ -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]] == Breaking Changes +[[elasticsearch-migration-guide-4.0-4.1.breaking-changes.returntypes-1]] === Return types of ReactiveElasticsearchClient.Indices methods 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` instead of a `Mono` to signal successful index creation. * the `updateMapping` variants now return a `Mono` instead of a `Mono` 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` containing the ids of the new indexed records. Now they return a `List`; these objects contain the id and information about optimistic locking (seq_no and primary_term) diff --git a/src/main/asciidoc/reference/elasticsearch-migration-guide-4.1-4.2.adoc b/src/main/asciidoc/reference/elasticsearch-migration-guide-4.1-4.2.adoc index 6a1977237..55083e2ef 100644 --- a/src/main/asciidoc/reference/elasticsearch-migration-guide-4.1-4.2.adoc +++ b/src/main/asciidoc/reference/elasticsearch-migration-guide-4.1-4.2.adoc @@ -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]] == Deprecations +[[elasticsearch-migration-guide-4.1-4.2.deprecations.document]] === @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. @@ -28,8 +29,10 @@ The deprecated `find` methods from `ReactiveSearchOperations` and `ReactiveDocum [[elasticsearch-migration-guide-4.1-4.2.breaking-changes]] == Breaking Changes +[[elasticsearch-migration-guide-4.1-4.2.breaking-changes.refresh-policy]] === RefreshPolicy +[[elasticsearch-migration-guide-4.1-4.2.breaking-changes.refresh-policy.enum]] ==== 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. @@ -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`. 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 `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. 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 When configuring Spring Data Elasticsearch like described in <> 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. +[[elasticsearch-migration-guide-4.1-4.2.breaking-changes.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 The reactive methods previously returned a `Mono` with the number of deleted documents, the non reactive versions were void. They now return a `Mono` 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 The implementations of _multiget_ previousl only returned the found entities in a `List` for non-reactive implementations and in a `Flux` 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 diff --git a/src/main/asciidoc/reference/elasticsearch-migration-guide-4.2-4.3.adoc b/src/main/asciidoc/reference/elasticsearch-migration-guide-4.2-4.3.adoc index 8516e8e53..22e64035c 100644 --- a/src/main/asciidoc/reference/elasticsearch-migration-guide-4.2-4.3.adoc +++ b/src/main/asciidoc/reference/elasticsearch-migration-guide-4.2-4.3.adoc @@ -21,6 +21,7 @@ Check the sections on <> and [[elasticsearch-migration-guide-4.2-4.3.deprecations]] == Deprecations +[[elasticsearch-migration-guide-4.2-4.3.deprecations.suggest]] === 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. @@ -32,6 +33,7 @@ Here as well the old methods are deprecated. [[elasticsearch-migration-guide-4.2-4.3.breaking-changes]] == Breaking Changes +[[elasticsearch-migration-guide-4.2-4.3.breaking-changes.1]] === 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. @@ -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. * 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 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. 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 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`. +[[elasticsearch-migration-guide-4.2-4.3.breaking-changes.4]] === BulkOptions changes 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`refreshPolicy` property has been changed to `org.springframework.data.elasticsearch.core.RefreshPolicy`. +[[elasticsearch-migration-guide-4.2-4.3.breaking-changes.5]] === IndicesOptions change 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 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 The `org.springframework.data.elasticsearch.core.mapping.ElasticsearchPersistentPropertyConverter` interface has been renamed to `org.springframework.data.elasticsearch.core.mapping.PropertyValueConverter`. diff --git a/src/main/asciidoc/reference/elasticsearch-migration-guide-4.3-4.4.adoc b/src/main/asciidoc/reference/elasticsearch-migration-guide-4.3-4.4.adoc index 7e5308d1e..9ce87d79b 100644 --- a/src/main/asciidoc/reference/elasticsearch-migration-guide-4.3-4.4.adoc +++ b/src/main/asciidoc/reference/elasticsearch-migration-guide-4.3-4.4.adoc @@ -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]] == Deprecations +[[elasticsearch-migration-guide-4.3-4.4.deprecations.reactive-operations]] === org.springframework.data.elasticsearch.core.ReactiveElasticsearchOperations The method ` Publisher execute(ClientCallback> 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]] == Breaking Changes +[[elasticsearch-migration-guide-4.3-4.4.breaking-changes.1]] === Removal of deprecated classes ==== `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`. 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 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. +[[elasticsearch-migration-guide-4.3-4.4.breaking-changes.3]] === Behaviour change 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 * 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 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: +[[elasticsearch-migration-guide-4.3-4.4.new-clients.how-to.not]] ==== Make sure not to configure the existing default client 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. If Spring Data Elasticsearch was configured using a programmatic configuration (see <>), remove these beans from the Spring application context. +[[elasticsearch-migration-guide-4.3-4.4.new-clients.how-to.dependencies]] ==== Add dependencies 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 +[[elasticsearch-migration-guide-4.3-4.4.new-clients.how-to.configuration.imperative]] ===== 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`: @@ -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 `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 To use the new client in a reactive environment the only difference is the class from which to derive the configuration: diff --git a/src/main/asciidoc/reference/elasticsearch-migration-guide-4.4-5.0.adoc b/src/main/asciidoc/reference/elasticsearch-migration-guide-4.4-5.0.adoc index 322e9f636..899ed7419 100644 --- a/src/main/asciidoc/reference/elasticsearch-migration-guide-4.4-5.0.adoc +++ b/src/main/asciidoc/reference/elasticsearch-migration-guide-4.4-5.0.adoc @@ -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]] == Deprecations +[[elasticsearch-migration-guide-4.4-4.5.deprecations.package]] === `org.springframework.data.elasticsearch.client.erhlc` package See <>, 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-4.5.deprecations.code]] === Removal of deprecated code `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]] == Breaking Changes +[[elasticsearch-migration-guide-4.4-5.0.breaking-changes.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 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. 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 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.SeqNoPrimaryTerm` +[[elasticsearch-migration-guide-4.4-5.0.breaking-changes-http-headers]] === New HttpHeaders class 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`. +[[elasticsearch-migration-guide-4.4-5.0.new-clients.imperative]] === 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`: @@ -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 `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 To use the new client in a reactive environment the only difference is the class from which to derive the configuration: diff --git a/src/main/asciidoc/reference/elasticsearch-misc.adoc b/src/main/asciidoc/reference/elasticsearch-misc.adoc index 412c6be26..b727a09e3 100644 --- a/src/main/asciidoc/reference/elasticsearch-misc.adoc +++ b/src/main/asciidoc/reference/elasticsearch-misc.adoc @@ -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). Spring Data Elasticsearch supports this in two ways: +[[elasticsearch.misc.runtime-fields.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). @@ -238,6 +239,7 @@ public class RuntimeFieldEntity { ---- ==== +[[elasticsearch.misc.runtime-fields.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). diff --git a/src/main/asciidoc/reference/elasticsearch-object-mapping.adoc b/src/main/asciidoc/reference/elasticsearch-object-mapping.adoc index e7b44517d..8c8c60211 100644 --- a/src/main/asciidoc/reference/elasticsearch-object-mapping.adoc +++ b/src/main/asciidoc/reference/elasticsearch-object-mapping.adoc @@ -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]. 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). -** `format`: One or more built-in date formats, see the next section <>. -** `pattern`: One or more custom date formats, see the next section <>. +** `format`: One or more built-in date formats, see the next section <>. +** `pattern`: One or more custom date formats, see the next section <>. ** `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. * `@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. -[[elasticsearch.mapping.meta-model.date-formats]] +[[elasticsearch.mapping.meta-model.annotations.date-formats]] ==== 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. @@ -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_. 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 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 `` are `Integer`, `Long`, `Float`, `Double`, `Date` and classes that implement the `TemporalAccessor` interface. +[[elasticsearch.mapping.meta-model.annotations.mapped-names]] ==== Mapped field names 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]] === Mapping Rules +[[elasticsearch.mapping.meta-model.rules.typehints]] ==== Type Hints 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. 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 like `Point` & `GeoPoint` are converted into _lat/lon_ pairs. @@ -265,6 +269,7 @@ public class Address { ---- ==== +[[elasticsearch.mapping.meta-model.rules.geojson]] ==== GeoJson Types 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` * `GeoJsonGeometryCollection` +[[elasticsearch.mapping.meta-model.rules.collections]] ==== Collections For values inside Collections apply the same mapping rules as for aggregate roots when it comes to _type hints_ and <>. @@ -332,6 +338,7 @@ public class Person { ---- ==== +[[elasticsearch.mapping.meta-model.rules.maps]] ==== Maps For values inside Maps apply the same mapping rules as for aggregate roots when it comes to _type hints_ and <>. diff --git a/src/main/asciidoc/reference/elasticsearch-repositories.adoc b/src/main/asciidoc/reference/elasticsearch-repositories.adoc index 7ac087840..8da6a0e1a 100644 --- a/src/main/asciidoc/reference/elasticsearch-repositories.adoc +++ b/src/main/asciidoc/reference/elasticsearch-repositories.adoc @@ -40,6 +40,7 @@ include::reactive-elasticsearch-repositories.adoc[leveloffset=+1] [[elasticsearch.repositories.annotations]] == Annotations for repository methods +[[elasticsearch.repositories.annotations.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: @@ -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. +[[elasticsearch.repositories.annotations.sourcefilters]] === @SourceFilters Sometimes the user does not need to have all the properties of an entity returned from a search but only a subset. diff --git a/src/main/asciidoc/reference/elasticsearch-repository-queries.adoc b/src/main/asciidoc/reference/elasticsearch-repository-queries.adoc index 50ab16a24..f78b93c9b 100644 --- a/src/main/asciidoc/reference/elasticsearch-repository-queries.adoc +++ b/src/main/asciidoc/reference/elasticsearch-repository-queries.adoc @@ -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. +[[elasticsearch.query-methods.finders.declared]] === Declared queries 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. 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 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 } ---- ==== - diff --git a/src/main/asciidoc/reference/elasticsearch-routing.adoc b/src/main/asciidoc/reference/elasticsearch-routing.adoc index 8407a614d..d1f6940c9 100644 --- a/src/main/asciidoc/reference/elasticsearch-routing.adoc +++ b/src/main/asciidoc/reference/elasticsearch-routing.adoc @@ -1,4 +1,3 @@ - [[elasticsearch.routing]] = 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: +[[elasticsearch.routing.join-types]] == Routing on join-types When using join-types (see <>), 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 <>), Spring Data Elasticsearc 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). +[[elasticsearch.routing.custom]] == Custom routing values 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. ==== -