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

Migrate documentation site to Antora.

Browse Source 
Closes #2685
This commit is contained in:
Mark Paluch 2023-09-04 09:39:15 +02:00
parent a82952b124
commit 1a0e147119
No known key found for this signature in database
GPG Key ID: 4406B84C1661DCD1
50 changed files with 386 additions and 265 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
.gitignore vendored
View File

@ -26,3 +26,9 @@ target
/zap.env /zap.env
/localdocker.env /localdocker.env
.localdocker-env .localdocker-env
build/
node_modules
node
package.json
package-lock.json

6
README.adoc
View File

@ -137,7 +137,7 @@ If you want to raise an issue, please follow the recommendations below:
* Before you log a bug, please search the * Before you log a bug, please search the
https://github.com/spring-projects/spring-data-elasticsearch/issues[issue tracker] to see if someone has already reported the problem. https://github.com/spring-projects/spring-data-elasticsearch/issues[issue tracker] to see if someone has already reported the problem.
* If the issue doesn’t already exist, https://github.com/spring-projects/spring-data-elasticsearch/issues/new[create a new issue]. * If the issue doesn't already exist, https://github.com/spring-projects/spring-data-elasticsearch/issues/new[create a new issue].
* Please provide as much information as possible with the issue report, we like to know the version of Spring Data Elasticsearch that you are using and JVM version. * Please provide as much information as possible with the issue report, we like to know the version of Spring Data Elasticsearch that you are using and JVM version.
* If you need to paste code, or include a stack trace use Markdown +++```+++ escapes before and after your text. * If you need to paste code, or include a stack trace use Markdown +++```+++ escapes before and after your text.
* If possible try to create a test-case or project that replicates the issue. * If possible try to create a test-case or project that replicates the issue.
@ -168,10 +168,10 @@ Building the documentation builds also the project without running tests.
[source,bash] [source,bash]
---- ----
$ ./mvnw clean install -Pdistribute $ ./mvnw clean install -Pantora
---- ----
The generated documentation is available from `target/site/reference/html/index.html`. The generated documentation is available from `target/antora/site/index.html`.
== Examples == Examples

28
pom.xml
View File

@ -409,10 +409,6 @@
<groupId>org.apache.maven.plugins</groupId> <groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-assembly-plugin</artifactId> <artifactId>maven-assembly-plugin</artifactId>
</plugin> </plugin>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
</plugin>
</plugins> </plugins>
</build> </build>
@ -463,6 +459,30 @@
</plugins> </plugins>
</build> </build>
</profile> </profile>
<profile>
<id>antora-process-resources</id>
<build>
<resources>
<resource>
<directory>src/main/antora/resources/antora-resources</directory>
<filtering>true</filtering>
</resource>
</resources>
</build>
</profile>
<profile>
<id>antora</id>
<build>
<plugins>
<plugin>
<groupId>io.spring.maven.antora</groupId>
<artifactId>antora-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</profile>
</profiles> </profiles>
<repositories> <repositories>

42
src/main/antora/antora-playbook.yml Normal file
View File

@ -0,0 +1,42 @@
# PACKAGES antora@3.2.0-alpha.2 @antora/atlas-extension:1.0.0-alpha.1 @antora/collector-extension@1.0.0-alpha.3 @springio/antora-extensions@1.1.0-alpha.2 @asciidoctor/tabs@1.0.0-alpha.12 @opendevise/antora-release-line-extension@1.0.0-alpha.2
#
# The purpose of this Antora playbook is to build the docs in the current branch.
antora:
extensions:
- '@antora/collector-extension'
- require: '@springio/antora-extensions/root-component-extension'
root_component_name: 'data-elasticsearch'
site:
title: Spring Data Elasticsearch
url: https://docs.spring.io/spring-data-elasticsearch/reference/
content:
sources:
- url: ./../../..
branches: HEAD
start_path: src/main/antora
worktrees: true
- url: https://github.com/spring-projects/spring-data-commons
# Refname matching:
# https://docs.antora.org/antora/latest/playbook/content-refname-matching/
branches: [ main, 3.2.x ]
start_path: src/main/antora
asciidoc:
attributes:
page-pagination: ''
hide-uri-scheme: '@'
tabs-sync-option: '@'
chomp: 'all'
extensions:
- '@asciidoctor/tabs'
- '@springio/asciidoctor-extensions'
sourcemap: true
urls:
latest_version_segment: ''
runtime:
log:
failure_level: warn
format: pretty
ui:
bundle:
url: https://github.com/spring-io/antora-ui-spring/releases/download/v0.3.5/ui-bundle.zip
snapshot: true

12
src/main/antora/antora.yml Normal file
View File

@ -0,0 +1,12 @@
name: data-elasticsearch
version: true
title: Spring Data Elasticsearch
nav:
- modules/ROOT/nav.adoc
ext:
collector:
- run:
command: ./mvnw validate process-resources -am -Pantora-process-resources
local: true
scan:
dir: target/classes/

42
src/main/antora/modules/ROOT/nav.adoc Normal file
View File

@ -0,0 +1,42 @@
* xref:index.adoc[Overview]
** xref:commons/upgrade.adoc[]
** xref:migration-guides.adoc[]
*** xref:migration-guides/migration-guide-3.2-4.0.adoc[]
*** xref:migration-guides/migration-guide-4.0-4.1.adoc[]
*** xref:migration-guides/migration-guide-4.1-4.2.adoc[]
*** xref:migration-guides/migration-guide-4.2-4.3.adoc[]
*** xref:migration-guides/migration-guide-4.3-4.4.adoc[]
*** xref:migration-guides/migration-guide-4.4-5.0.adoc[]
*** xref:migration-guides/migration-guide-5.0-5.1.adoc[]
*** xref:migration-guides/migration-guide-5.1-5.2.adoc[]
* xref:elasticsearch.adoc[]
** xref:elasticsearch/clients.adoc[]
** xref:elasticsearch/object-mapping.adoc[]
** xref:elasticsearch/template.adoc[]
** xref:elasticsearch/reactive-template.adoc[]
** xref:elasticsearch/entity-callbacks.adoc[]
** xref:elasticsearch/auditing.adoc[]
** xref:elasticsearch/join-types.adoc[]
** xref:elasticsearch/routing.adoc[]
** xref:elasticsearch/misc.adoc[]
** xref:elasticsearch/scripted-and-runtime-fields.adoc[]
* xref:repositories.adoc[]
** xref:repositories/core-concepts.adoc[]
** xref:repositories/definition.adoc[]
** xref:elasticsearch/repositories/elasticsearch-repositories.adoc[]
** xref:elasticsearch/repositories/reactive-elasticsearch-repositories.adoc[]
** xref:repositories/create-instances.adoc[]
** xref:repositories/query-methods-details.adoc[]
** xref:elasticsearch/repositories/elasticsearch-repository-queries.adoc[]
** xref:repositories/projections.adoc[]
** xref:repositories/custom-implementations.adoc[]
** xref:repositories/core-domain-events.adoc[]
** xref:repositories/null-handling.adoc[]
** xref:elasticsearch/repositories/cdi-integration.adoc[]
** xref:repositories/query-keywords-reference.adoc[]
** xref:repositories/query-return-types-reference.adoc[]
* https://github.com/spring-projects/spring-data-commons/wiki[Wiki]

1
src/main/antora/modules/ROOT/pages/commons/upgrade.adoc Normal file
View File

@ -0,0 +1 @@
include::{commons}@data-commons::page$upgrade.adoc[]

16
src/main/antora/modules/ROOT/pages/elasticsearch.adoc Normal file
View File

@ -0,0 +1,16 @@
[[elasticsearch.core]]
= Elasticsearch Support
:page-section-summary-toc: 1
Spring Data support for Elasticsearch contains a wide range of features:
* Spring configuration support for various xref:elasticsearch/clients.adoc[Elasticsearch clients].
* The xref:elasticsearch/template.adoc[`ElasticsearchTemplate` and `ReactiveElasticsearchTemplate`] helper classes that provide object mapping between ES index operations and POJOs.
* xref:elasticsearch/template.adoc#exception-translation[Exception translation] into Spring's portable {springDocsUrl}data-access.html#dao-exceptions[Data Access Exception Hierarchy].
* Feature rich xref:elasticsearch/object-mapping.adoc[object mapping] integrated with _Spring's_ {springDocsUrl}core.html#core-convert[Conversion Service].
* xref:elasticsearch/object-mapping.adoc#elasticsearch.mapping.meta-model.annotations[Annotation-based mapping] metadata that is extensible to support other metadata formats.
* Java-based xref:elasticsearch/template.adoc#cassandra.template.query[query, criteria, and update DSLs].
* Automatic implementation of xref:repositories.adoc[imperative and reactive `Repository` interfaces] including support for xref:repositories/custom-implementations.adoc[custom query methods].
For most data-oriented tasks, you can use the `[Reactive]ElasticsearchTemplate` or the `Repository` support, both of which use the rich object-mapping functionality.
Spring Data Elasticsearch uses consistent naming conventions on objects in various APIs to those found in the DataStax Java Driver so that they are familiar and so that you can map your existing knowledge onto the Spring APIs.

6
src/main/asciidoc/reference/elasticsearch-auditing.adoc → src/main/antora/modules/ROOT/pages/elasticsearch/auditing.adoc
View File

@ -1,8 +1,8 @@
[[elasticsearch.auditing]] [[elasticsearch.auditing]]
== Elasticsearch Auditing = Elasticsearch Auditing
[[elasticsearch.auditing.preparing]] [[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:
@ -56,7 +56,7 @@ public class Person implements Persistable<Long> {
<.> 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]] [[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:

26
src/main/asciidoc/reference/elasticsearch-clients.adoc → src/main/antora/modules/ROOT/pages/elasticsearch/clients.adoc
View File

@ -3,10 +3,8 @@
This chapter illustrates configuration and usage of supported Elasticsearch client implementations. This chapter illustrates configuration and usage of supported Elasticsearch client implementations.
Spring Data Elasticsearch operates upon an Elasticsearch client (provided by Elasticsearch client libraries) that is Spring Data Elasticsearch operates upon an Elasticsearch client (provided by Elasticsearch client libraries) that is connected to a single Elasticsearch node or a cluster.
connected to a single Elasticsearch node or a cluster. Although the Elasticsearch Client can be used directly to work with the cluster, applications using Spring Data Elasticsearch normally use the higher level abstractions of xref:elasticsearch/template.adoc[Elasticsearch Operations] and xref:elasticsearch/repositories/elasticsearch-repositories.adoc[Elasticsearch Repositories].
Although the Elasticsearch Client can be used directly to work with the cluster, applications using Spring Data
Elasticsearch normally use the higher level abstractions of <<elasticsearch.operations>> and <<elasticsearch.repositories>>.
[[elasticsearch.clients.restclient]] [[elasticsearch.clients.restclient]]
== Imperative Rest Client == Imperative Rest Client
@ -29,7 +27,8 @@ public class MyClientConfig extends ElasticsearchConfiguration {
} }
} }
---- ----
<.> for a detailed description of the builder methods see <<elasticsearch.clients.configuration>>
<.> for a detailed description of the builder methods see xref:elasticsearch/clients.adoc#elasticsearch.clients.configuration[Client Configuration]
==== ====
The `ElasticsearchConfiguration` class allows further configuration by overriding for example the `jsonpMapper()` or `transportOptions()` methods. The `ElasticsearchConfiguration` class allows further configuration by overriding for example the `jsonpMapper()` or `transportOptions()` methods.
@ -83,7 +82,8 @@ public class MyClientConfig extends ReactiveElasticsearchConfiguration {
} }
} }
---- ----
<.> for a detailed description of the builder methods see <<elasticsearch.clients.configuration>>
<.> for a detailed description of the builder methods see xref:elasticsearch/clients.adoc#elasticsearch.clients.configuration[Client Configuration]
==== ====
The `ReactiveElasticsearchConfiguration` class allows further configuration by overriding for example the `jsonpMapper()` or `transportOptions()` methods. The `ReactiveElasticsearchConfiguration` class allows further configuration by overriding for example the `jsonpMapper()` or `transportOptions()` methods.
@ -161,7 +161,7 @@ ClientConfiguration clientConfiguration = ClientConfiguration.builder()
<.> Define default headers, if they need to be customized <.> Define default headers, if they need to be customized
<.> Use the builder to provide cluster addresses, set default `HttpHeaders` or enable SSL. <.> Use the builder to provide cluster addresses, set default `HttpHeaders` or enable SSL.
<.> Optionally enable SSL. There exist overloads of this function that can take a `SSLContext` or as an alternative the fingerprint of the certificate as it is output by Elasticsearch 8 on startup. <.> Optionally enable SSL.There exist overloads of this function that can take a `SSLContext` or as an alternative the fingerprint of the certificate as it is output by Elasticsearch 8 on startup.
<.> Optionally set a proxy. <.> Optionally set a proxy.
<.> Optionally set a path prefix, mostly used when different clusters a behind some reverse proxy. <.> Optionally set a path prefix, mostly used when different clusters a behind some reverse proxy.
<.> Set the connection timeout. <.> Set the connection timeout.
@ -169,8 +169,7 @@ ClientConfiguration clientConfiguration = ClientConfiguration.builder()
<.> Optionally set headers. <.> Optionally set headers.
<.> Add basic authentication. <.> Add basic authentication.
<.> A `Supplier<HttpHeaders>` 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<HttpHeaders>` 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 <.> a function to configure the created client (see xref:elasticsearch/clients.adoc#elasticsearch.clients.configuration.callbacks[Client configuration callbacks]), can be added multiple times.
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.
@ -179,8 +178,8 @@ If this is used in the reactive setup, the supplier function *must not* block!
[[elasticsearch.clients.configuration.callbacks]] [[elasticsearch.clients.configuration.callbacks]]
=== Client configuration callbacks === Client configuration callbacks
The `ClientConfiguration` class offers the most common parameters to configure the client. In the case this is not The `ClientConfiguration` class offers the most common parameters to configure the client.
enough, the user can add callback functions by using the `withClientConfigurer(ClientConfigurationCallback<?>)` method. In the case this is not enough, the user can add callback functions by using the `withClientConfigurer(ClientConfigurationCallback<?>)` method.
The following callbacks are provided: The following callbacks are provided:
@ -222,9 +221,8 @@ ClientConfiguration.builder()
[[elasticsearch.clients.logging]] [[elasticsearch.clients.logging]]
== Client Logging == Client Logging
To see what is actually sent to and received from the server `Request` / `Response` logging on the transport level To see what is actually sent to and received from the server `Request` / `Response` logging on the transport level needs to be turned on as outlined in the snippet below.
needs to be turned on as outlined in the snippet below. This can be enabled in the Elasticsearch client by setting This can be enabled in the Elasticsearch client by setting the level of the `tracer` package to "trace" (see
the level of the `tracer` package to "trace" (see
https://www.elastic.co/guide/en/elasticsearch/client/java-api-client/current/java-rest-low-usage-logging.html) https://www.elastic.co/guide/en/elasticsearch/client/java-api-client/current/java-rest-low-usage-logging.html)
.Enable transport layer logging .Enable transport layer logging

6
src/main/asciidoc/reference/elasticsearch-new.adoc → src/main/antora/modules/ROOT/pages/elasticsearch/elasticsearch-new.adoc
View File

@ -66,7 +66,7 @@
* Upgrade to Elasticsearch 7.6.2. * Upgrade to Elasticsearch 7.6.2.
* Deprecation of `TransportClient` usage. * Deprecation of `TransportClient` usage.
* Implements most of the mapping-types available for the index mappings. * Implements most of the mapping-types available for the index mappings.
* Removal of the Jackson `ObjectMapper`, now using the <<elasticsearch.mapping.meta-model,MappingElasticsearchConverter>> * Removal of the Jackson `ObjectMapper`, now using the xref:elasticsearch/object-mapping.adoc#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. * 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 `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_). * 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_).
@ -80,7 +80,7 @@
* Secured Elasticsearch cluster support with Basic Authentication and SSL transport. * Secured Elasticsearch cluster support with Basic Authentication and SSL transport.
* Upgrade to Elasticsearch 6.8.1. * Upgrade to Elasticsearch 6.8.1.
* Reactive programming support with <<elasticsearch.reactive.operations>> and <<elasticsearch.reactive.repositories>>. * Reactive programming support with xref:elasticsearch/repositories/reactive-elasticsearch-repositories.adoc[Reactive Elasticsearch Repositories] and xref:.
* Introduction of the <<elasticsearch.mapping.meta-model,ElasticsearchEntityMapper>> as an alternative to the Jackson `ObjectMapper`. * Introduction of the xref:elasticsearch/object-mapping.adoc#elasticsearch.mapping.meta-model[ElasticsearchEntityMapper] as an alternative to the Jackson `ObjectMapper`.
* Field name customization in `@Field`. * Field name customization in `@Field`.
* Support for Delete by Query. * Support for Delete by Query.

4
src/main/asciidoc/reference/elasticsearch-entity-callbacks.adoc → src/main/antora/modules/ROOT/pages/elasticsearch/entity-callbacks.adoc
View File

@ -1,5 +1,7 @@
include::{commons}@data-commons::page$entity-callbacks.adoc[]
[[elasticsearch.entity-callbacks]] [[elasticsearch.entity-callbacks]]
= Elasticsearch EntityCallbacks == Store specific EntityCallbacks
Spring Data Elasticsearch uses the `EntityCallback` API internally for its auditing support and reacts on the following callbacks: Spring Data Elasticsearch uses the `EntityCallback` API internally for its auditing support and reacts on the following callbacks:

6
src/main/asciidoc/reference/elasticsearch-join-types.adoc → src/main/antora/modules/ROOT/pages/elasticsearch/join-types.adoc
View File

@ -112,7 +112,7 @@ public class Statement {
} }
} }
---- ----
<.> for routing related info see <<elasticsearch.routing>> <.> for routing related info see xref:elasticsearch/routing.adoc[Routing values]
<.> a question can have answers and comments <.> a question can have answers and comments
<.> an answer can have votes <.> an answer can have votes
<.> the `JoinField` property is used to combine the name (_question_, _answer_, _comment_ or _vote_) of the relation with the parent id. <.> the `JoinField` property is used to combine the name (_question_, _answer_, _comment_ or _vote_) of the relation with the parent id.
@ -208,13 +208,13 @@ void init() {
<2> the first answer to the question <2> the first answer to the question
<3> the second answer <3> the second answer
<4> a comment to the question <4> a comment to the question
<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 xref:elasticsearch/routing.adoc[Routing values].
==== ====
[[elasticsearch.jointype.retrieving]] [[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. xref:repositories/custom-implementations.adoc[] can be used instead.
The following code shows as an example how to retrieve all entries that have a _vote_ (which must be _answers_, because only answers can have a vote) using an `ElasticsearchOperations` instance: The following code shows as an example how to retrieve all entries that have a _vote_ (which must be _answers_, because only answers can have a vote) using an `ElasticsearchOperations` instance:

10
src/main/asciidoc/reference/elasticsearch-misc.adoc → src/main/antora/modules/ROOT/pages/elasticsearch/misc.adoc
View File

@ -2,7 +2,7 @@
= Miscellaneous Elasticsearch Operation Support = Miscellaneous Elasticsearch Operation Support
This chapter covers additional support for Elasticsearch operations that cannot be directly accessed via the repository interface. This chapter covers additional support for Elasticsearch operations that cannot be directly accessed via the repository interface.
It is recommended to add those operations as custom implementation as described in <<repositories.custom-implementations>> . It is recommended to add those operations as custom implementation as described in xref:repositories/custom-implementations.adoc[] .
[[elasticsearc.misc.index.settings]] [[elasticsearc.misc.index.settings]]
== Index settings == Index settings
@ -50,7 +50,7 @@ class Entity {
[[elasticsearch.misc.mappings]] [[elasticsearch.misc.mappings]]
== Index Mapping == Index Mapping
When Spring Data Elasticsearch creates the index mapping with the `IndexOperations.createMapping()` methods, it uses the annotations described in <<elasticsearch.mapping.meta-model.annotations>>, especially the `@Field` annotation. When Spring Data Elasticsearch creates the index mapping with the `IndexOperations.createMapping()` methods, it uses the annotations described in xref:elasticsearch/object-mapping.adoc#elasticsearch.mapping.meta-model.annotations[Mapping Annotation Overview], especially the `@Field` annotation.
In addition to that it is possible to add the `@Mapping` annotation to a class. In addition to that it is possible to add the `@Mapping` annotation to a class.
This annotation has the following properties: This annotation has the following properties:
@ -181,7 +181,7 @@ interface SampleEntityRepository extends Repository<SampleEntity, String> {
[[elasticsearch.misc.sorts]] [[elasticsearch.misc.sorts]]
== Sort options == Sort options
In addition to the default sort options described in <<repositories.paging-and-sorting>>, Spring Data Elasticsearch provides the class `org.springframework.data.elasticsearch.core.query.Order` which derives from `org.springframework.data.domain.Sort.Order`. In addition to the default sort options described in xref:repositories/query-methods-details.adoc#repositories.paging-and-sorting[Paging and Sorting], Spring Data Elasticsearch provides the class `org.springframework.data.elasticsearch.core.query.Order` which derives from `org.springframework.data.domain.Sort.Order`.
It offers additional parameters that can be sent to Elasticsearch when specifying the sorting of the result (see https://www.elastic.co/guide/en/elasticsearch/reference/7.15/sort-search-results.html). It offers additional parameters that can be sent to Elasticsearch when specifying the sorting of the result (see https://www.elastic.co/guide/en/elasticsearch/reference/7.15/sort-search-results.html).
There also is the `org.springframework.data.elasticsearch.core.query.GeoDistanceOrder` class which can be used to have the result of a search operation ordered by geographical distance. There also is the `org.springframework.data.elasticsearch.core.query.GeoDistanceOrder` class which can be used to have the result of a search operation ordered by geographical distance.
@ -366,8 +366,7 @@ operations.putScript( <.>
To use a search template in a search query, Spring Data Elasticsearch provides the `SearchTemplateQuery`, an implementation of the `org.springframework.data.elasticsearch.core.query.Query` interface. To use a search template in a search query, Spring Data Elasticsearch provides the `SearchTemplateQuery`, an implementation of the `org.springframework.data.elasticsearch.core.query.Query` interface.
In the following code, we will add a call using a search template query to a custom repository implementation (see In the following code, we will add a call using a search template query to a custom repository implementation (see
<<repositories.custom-implementations>>) as xref:repositories/custom-implementations.adoc[]) as an example how this can be integrated into a repository call.
an example how this can be integrated into a repository call.
We first define the custom repository fragment interface: We first define the custom repository fragment interface:
@ -451,4 +450,3 @@ About the filter query: It is not possible to use a `CriteriaQuery` here, as thi
For the definition of the order path and the nested paths, the Java entity property names should be used. For the definition of the order path and the nested paths, the Java entity property names should be used.
include::elasticsearch-misc-scripted-and-runtime-fields.adoc[leveloffset=+1]

20
src/main/asciidoc/reference/elasticsearch-object-mapping.adoc → src/main/antora/modules/ROOT/pages/elasticsearch/object-mapping.adoc
View File

@ -25,11 +25,11 @@ The most important attributes are (check the API documentation for the complete
This can contain a SpEL template expression like `"log-#{T(java.time.LocalDate).now().toString()}"` This can contain a SpEL template expression like `"log-#{T(java.time.LocalDate).now().toString()}"`
** `createIndex`: flag whether to create an index on repository bootstrapping. ** `createIndex`: flag whether to create an index on repository bootstrapping.
Default value is _true_. Default value is _true_.
See <<elasticsearch.repositories.autocreation>> See xref:elasticsearch/repositories/elasticsearch-repositories.adoc#elasticsearch.repositories.autocreation[Automatic creation of indices with the corresponding mapping]
* `@Id`: Applied at the field level to mark the field used for identity purpose. * `@Id`: Applied at the field level to mark the field used for identity purpose.
* `@Transient`, `@ReadOnlyProperty`, `@WriteOnlyProperty`: see the following section <<elasticsearch.mapping.meta-model.annotations.read-write>> for detailed information. * `@Transient`, `@ReadOnlyProperty`, `@WriteOnlyProperty`: see the following section xref:elasticsearch/object-mapping.adoc#elasticsearch.mapping.meta-model.annotations.read-write[Controlling which properties are written to and read from Elasticsearch] for detailed information.
* `@PersistenceConstructor`: Marks a given constructor - even a package protected one - to use when instantiating the object from 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. 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 (the following list is not complete, check the annotation Javadoc for a complete reference): * `@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 (the following list is not complete, check the annotation Javadoc for a complete reference):
@ -38,8 +38,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.annotations.date-formats>>. ** `format`: One or more built-in date formats, see the next section xref:elasticsearch/object-mapping.adoc#elasticsearch.mapping.meta-model.annotations.date-formats[Date format mapping].
** `pattern`: One or more custom date formats, see the next section <<elasticsearch.mapping.meta-model.annotations.date-formats>>. ** `pattern`: One or more custom date formats, see the next section xref:elasticsearch/object-mapping.adoc#elasticsearch.mapping.meta-model.annotations.date-formats[Date format mapping].
** `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.
@ -158,7 +158,7 @@ Supported classes for the type `<T>` are `Integer`, `Long`, `Float`, `Double`, `
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.
This can be changed for individual field by using the `@Field` annotation on that property. This can be changed for individual field by using the `@Field` annotation on that property.
It is also possible to define a `FieldNamingStrategy` in the configuration of the client (<<elasticsearch.clients>>). It is also possible to define a `FieldNamingStrategy` in the configuration of the client (xref:elasticsearch/clients.adoc[Elasticsearch Clients]).
If for example a `SnakeCaseFieldNamingStrategy` is configured, the property _sampleProperty_ of the object would be mapped to _sample_property_ in Elasticsearch. If for example a `SnakeCaseFieldNamingStrategy` is configured, the property _sampleProperty_ of the object would be mapped to _sample_property_ in Elasticsearch.
A `FieldNamingStrategy` applies to all entities; it can be overwritten by setting a specific name with `@Field` on a property. A `FieldNamingStrategy` applies to all entities; it can be overwritten by setting a specific name with `@Field` on a property.
@ -187,6 +187,7 @@ public String getProperty() {
[[elasticsearch.mapping.meta-model.annotations.misc]] [[elasticsearch.mapping.meta-model.annotations.misc]]
==== Other property annotations ==== Other property annotations
[[indexedindexname]]
===== @IndexedIndexName ===== @IndexedIndexName
This annotation can be set on a String property of an entity. This annotation can be set on a String property of an entity.
@ -260,12 +261,13 @@ public class Person {
NOTE: Type hints will not be written for nested Objects unless the properties type is `Object`, an interface or the actual value type does not match the properties declaration. NOTE: Type hints will not be written for nested Objects unless the properties type is `Object`, an interface or the actual value type does not match the properties declaration.
[[disabling-type-hints]]
===== Disabling Type Hints ===== Disabling Type Hints
It may be necessary to disable writing of type hints when the index that should be used already exists without having the type hints defined in its mapping and with the mapping mode set to strict. It may be necessary to disable writing of type hints when the index that should be used already exists without having the type hints defined in its mapping and with the mapping mode set to strict.
In this case, writing the type hint will produce an error, as the field cannot be added automatically. In this case, writing the type hint will produce an error, as the field cannot be added automatically.
Type hints can be disabled for the whole application by overriding the method `writeTypeHints()` in a configuration class derived from `AbstractElasticsearchConfiguration` (see <<elasticsearch.clients>>). Type hints can be disabled for the whole application by overriding the method `writeTypeHints()` in a configuration class derived from `AbstractElasticsearchConfiguration` (see xref:elasticsearch/clients.adoc[Elasticsearch Clients]).
As an alternative they can be disabled for a single index with the `@Document` annotation: As an alternative they can be disabled for a single index with the `@Document` annotation:
@ -349,7 +351,7 @@ The following GeoJson types are implemented:
[[elasticsearch.mapping.meta-model.rules.collections]] [[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 xref:elasticsearch/object-mapping.adoc#elasticsearch.mapping.meta-model.conversions[Custom Conversions].
.Collections .Collections
==== ====
@ -377,7 +379,7 @@ public class Person {
[[elasticsearch.mapping.meta-model.rules.maps]] [[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 xref:elasticsearch/object-mapping.adoc#elasticsearch.mapping.meta-model.conversions[Custom Conversions].
However the Map key needs to a String to be processed by Elasticsearch. However the Map key needs to a String to be processed by Elasticsearch.
.Collections .Collections
@ -412,7 +414,7 @@ public class Person {
[[elasticsearch.mapping.meta-model.conversions]] [[elasticsearch.mapping.meta-model.conversions]]
=== Custom Conversions === Custom Conversions
Looking at the `Configuration` from the <<elasticsearch.mapping.meta-model, previous section>> `ElasticsearchCustomConversions` allows registering specific rules for mapping domain and simple types. Looking at the `Configuration` from the xref:elasticsearch/object-mapping.adoc#elasticsearch.mapping.meta-model[previous section] `ElasticsearchCustomConversions` allows registering specific rules for mapping domain and simple types.
.Meta Model Object Mapping Configuration .Meta Model Object Mapping Configuration
==== ====

15
src/main/asciidoc/reference/reactive-elasticsearch-operations.adoc → src/main/antora/modules/ROOT/pages/elasticsearch/reactive-template.adoc
View File

@ -5,18 +5,13 @@
The `ReactiveElasticsearchTemplate` is the default implementation of `ReactiveElasticsearchOperations`. The `ReactiveElasticsearchTemplate` is the default implementation of `ReactiveElasticsearchOperations`.
[[elasticsearch.reactive.operations]]
== Reactive Elasticsearch Operations
To get started the `ReactiveElasticsearchOperations` needs to know about the actual client to work with. To get started the `ReactiveElasticsearchOperations` needs to know about the actual client to work with.
Please see <<elasticsearch.clients.reactiverestclient>> for details on the client and how to configure it. Please see xref:elasticsearch/clients.adoc#elasticsearch.clients.reactiverestclient[Reactive Rest Client] for details on the client and how to configure it.
[[elasticsearch.reactive.operations.usage]] [[elasticsearch.reactive.operations.usage]]
=== Reactive Operations Usage == Reactive Operations Usage
`ReactiveElasticsearchOperations` lets you save, find and delete your domain objects and map those objects to documents `ReactiveElasticsearchOperations` lets you save, find and delete your domain objects and map those objects to documents stored in Elasticsearch.
stored
in Elasticsearch.
Consider the following: Consider the following:
@ -61,8 +56,8 @@ The above outputs the following sequence on the console.
> QjWCWWcBXiLAnp77ksfR > QjWCWWcBXiLAnp77ksfR
> 0 > 0
---- ----
<.> Insert a new `Person` document into the _marvel_ index . The `id` is generated on server
side and set into the instance returned. <.> Insert a new `Person` document into the _marvel_ index . The `id` is generated on server side and set into the instance returned.
<.> Lookup the `Person` with matching `id` in the _marvel_ index. <.> Lookup the `Person` with matching `id` in the _marvel_ index.
<.> Delete the `Person` with matching `id`, extracted from the given instance, in the _marvel_ index. <.> Delete the `Person` with matching `id`, extracted from the given instance, in the _marvel_ index.
<.> Count the total number of documents in the _marvel_ index. <.> Count the total number of documents in the _marvel_ index.

35
src/main/antora/modules/ROOT/pages/elasticsearch/repositories/cdi-integration.adoc Normal file
View File

@ -0,0 +1,35 @@
[[elasticsearch.cdi]]
= CDI Integration
The Spring Data Elasticsearch repositories can also be set up using CDI functionality.
.Spring Data Elasticsearch repositories using CDI
====
[source,java]
----
class ElasticsearchTemplateProducer {
@Produces
@ApplicationScoped
public ElasticsearchOperations createElasticsearchTemplate() {
// ... <1>
}
}
class ProductService {
private ProductRepository repository; <2>
public Page<Product> findAvailableBookByName(String name, Pageable pageable) {
return repository.findByAvailableTrueAndNameStartingWith(name, pageable);
}
@Inject
public void setRepository(ProductRepository repository) {
this.repository = repository;
}
}
----
<1> Create a component by using the same calls as are used in the xref:elasticsearch/template.adoc[Elasticsearch Operations] chapter.
<2> Let the CDI framework inject the Repository into your class.
====

48
src/main/asciidoc/reference/elasticsearch-repositories.adoc → src/main/antora/modules/ROOT/pages/elasticsearch/repositories/elasticsearch-repositories.adoc
View File

@ -29,13 +29,13 @@ class Book {
[[elasticsearch.repositories.autocreation]] [[elasticsearch.repositories.autocreation]]
== Automatic creation of indices with the corresponding mapping == Automatic creation of indices with the corresponding mapping
The `@Document` annotation has an argument `createIndex`. If this argument is set to true - which is the default value - Spring Data Elasticsearch will during bootstrapping the repository support on application startup check if the index defined by the `@Document` annotation exists. The `@Document` annotation has an argument `createIndex`.
If this argument is set to true - which is the default value - Spring Data Elasticsearch will during bootstrapping the repository support on application startup check if the index defined by the `@Document` annotation exists.
If it does not exist, the index will be created and the mappings derived from the entity's annotations (see <<elasticsearch.mapping>>) will be written to the newly created index. Details of the index that will be created can be set by using the `@Setting` annotation, refer to <<elasticsearc.misc.index.settings>> for further information. If it does not exist, the index will be created and the mappings derived from the entity's annotations (see xref:elasticsearch/object-mapping.adoc[Elasticsearch Object Mapping]) will be written to the newly created index.
Details of the index that will be created can be set by using the `@Setting` annotation, refer to xref:elasticsearch/misc.adoc#elasticsearc.misc.index.settings[Index settings] for further information.
include::elasticsearch-repository-queries.adoc[leveloffset=+1]
include::reactive-elasticsearch-repositories.adoc[leveloffset=+1]
[[elasticsearch.repositories.annotations]] [[elasticsearch.repositories.annotations]]
== Annotations for repository methods == Annotations for repository methods
@ -43,7 +43,7 @@ include::reactive-elasticsearch-repositories.adoc[leveloffset=+1]
[[elasticsearch.repositories.annotations.highlight]] [[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:
==== ====
[source,java] [source,java]
@ -125,51 +125,17 @@ class ProductService {
<1> The `EnableElasticsearchRepositories` annotation activates the Repository support. <1> The `EnableElasticsearchRepositories` annotation activates the Repository support.
If no base package is configured, it will use the one of the configuration class it is put on. If no base package is configured, it will use the one of the configuration class it is put on.
<2> Provide a Bean named `elasticsearchTemplate` of type `ElasticsearchOperations` by using one of the configurations shown in the <<elasticsearch.operations>> chapter. <2> Provide a Bean named `elasticsearchTemplate` of type `ElasticsearchOperations` by using one of the configurations shown in the xref:elasticsearch/template.adoc[Elasticsearch Operations] chapter.
<3> Let Spring inject the Repository bean into your class. <3> Let Spring inject the Repository bean into your class.
==== ====
[[elasticsearch.cdi]]
== Elasticsearch Repositories using CDI
The Spring Data Elasticsearch repositories can also be set up using CDI functionality.
.Spring Data Elasticsearch repositories using CDI
====
[source,java]
----
class ElasticsearchTemplateProducer {
@Produces
@ApplicationScoped
public ElasticsearchOperations createElasticsearchTemplate() {
// ... <1>
}
}
class ProductService {
private ProductRepository repository; <2>
public Page<Product> findAvailableBookByName(String name, Pageable pageable) {
return repository.findByAvailableTrueAndNameStartingWith(name, pageable);
}
@Inject
public void setRepository(ProductRepository repository) {
this.repository = repository;
}
}
----
<1> Create a component by using the same calls as are used in the <<elasticsearch.operations>> chapter.
<2> Let the CDI framework inject the Repository into your class.
====
[[elasticsearch.namespace]] [[elasticsearch.namespace]]
== Spring Namespace == Spring Namespace
The Spring Data Elasticsearch module contains a custom namespace allowing definition of repository beans as well as elements for instantiating a `ElasticsearchServer` . The Spring Data Elasticsearch module contains a custom namespace allowing definition of repository beans as well as elements for instantiating a `ElasticsearchServer` .
Using the `repositories` element looks up Spring Data repositories as described in <<repositories.create-instances>> . Using the `repositories` element looks up Spring Data repositories as described in xref:repositories/create-instances.adoc[].
.Setting up Elasticsearch repositories using Namespace .Setting up Elasticsearch repositories using Namespace
==== ====

4
src/main/asciidoc/reference/elasticsearch-repository-queries.adoc → src/main/antora/modules/ROOT/pages/elasticsearch/repositories/elasticsearch-repository-queries.adoc
View File

@ -10,12 +10,12 @@ The Elasticsearch module supports all basic query building feature as string que
=== 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.
In this case one might make use of the `@Query` annotation (see <<elasticsearch.query-methods.at-query>> ). In this case one might make use of the `@Query` annotation (see xref:elasticsearch/repositories/elasticsearch-repository-queries.adoc#elasticsearch.query-methods.at-query[Using @Query Annotation] ).
[[elasticsearch.query-methods.criterions]] [[elasticsearch.query-methods.criterions]]
== Query creation == Query creation
Generally the query creation mechanism for Elasticsearch works as described in <<repositories.query-methods>>. Generally the query creation mechanism for Elasticsearch works as described in xref:repositories/query-methods-details.adoc[].
Here's a short example of what a Elasticsearch query method translates into: Here's a short example of what a Elasticsearch query method translates into:
.Query creation from method names .Query creation from method names

6
src/main/asciidoc/reference/reactive-elasticsearch-repositories.adoc → src/main/antora/modules/ROOT/pages/elasticsearch/repositories/reactive-elasticsearch-repositories.adoc
View File

@ -1,11 +1,9 @@
[[elasticsearch.reactive.repositories]] [[elasticsearch.reactive.repositories]]
= Reactive Elasticsearch Repositories = Reactive Elasticsearch Repositories
Reactive Elasticsearch repository support builds on the core repository support explained in <<repositories>> utilizing Reactive Elasticsearch repository support builds on the core repository support explained in xref:repositories.adoc[] utilizing operations provided via xref:elasticsearch/reactive-template.adoc[] executed by a xref:elasticsearch/clients.adoc#elasticsearch.clients.reactiverestclient[Reactive REST Client].
operations provided via <<elasticsearch.reactive.operations>> executed by a <<elasticsearch.clients.reactive>>.
Spring Data Elasticsearch reactive repository support uses https://projectreactor.io/[Project Reactor] as its reactive Spring Data Elasticsearch reactive repository support uses https://projectreactor.io/[Project Reactor] as its reactive composition library of choice.
composition library of choice.
There are 3 main interfaces to be used: There are 3 main interfaces to be used:

2
src/main/asciidoc/reference/elasticsearch-routing.adoc → src/main/antora/modules/ROOT/pages/elasticsearch/routing.adoc
View File

@ -10,7 +10,7 @@ Spring Data Elasticsearch supports routing definitions on storing and retrieving
[[elasticsearch.routing.join-types]] [[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 xref:elasticsearch/join-types.adoc[Join-Type implementation]), Spring Data Elasticsearch will automatically use the `parent` property of the entity's `JoinField` property as the value for the routing.
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).

5
src/main/asciidoc/reference/elasticsearch-misc-scripted-and-runtime-fields.adoc → src/main/antora/modules/ROOT/pages/elasticsearch/scripted-and-runtime-fields.adoc
View File

@ -10,6 +10,7 @@ In the context of Spring Data Elasticsearch you can use
The following code snippets will show what you can do (these show imperative code, but the reactive implementation works similar). The following code snippets will show what you can do (these show imperative code, but the reactive implementation works similar).
[[the-person-entity]]
== The person entity == The person entity
The enity that is used in these examples is a `Person` entity. The enity that is used in these examples is a `Person` entity.
@ -68,6 +69,7 @@ public record Person(
Note that the `age` property is annotated with `@ScriptedField`. Note that the `age` property is annotated with `@ScriptedField`.
This inhibits the writing of a corresponding entry in the index mapping and marks the property as a target to put a calculated field from a search response. This inhibits the writing of a corresponding entry in the index mapping and marks the property as a target to put a calculated field from a search response.
[[the-repository-interface]]
== The repository interface == The repository interface
The repository used in this example: The repository used in this example:
@ -85,6 +87,7 @@ public interface PersonRepository extends ElasticsearchRepository<Person, String
---- ----
==== ====
[[the-service-class]]
== The service class == The service class
The service class has a repository injected and an `ElasticsearchOperations` instance to show several ways of populating and using the `age` property. The service class has a repository injected and an `ElasticsearchOperations` instance to show several ways of populating and using the `age` property.
@ -135,6 +138,7 @@ public class PersonService {
<.> a utility method to store some data in Elasticsearch. <.> a utility method to store some data in Elasticsearch.
==== ====
[[scripted-fields]]
=== Scripted fields === Scripted fields
The next piece shows how to use a scripted field to calculate and return the age of the persons. The next piece shows how to use a scripted field to calculate and return the age of the persons.
@ -177,6 +181,7 @@ Scripted fields can only add something to the returned data, the age cannot be u
<.> when using the repository, all that needs to be done is adding the scripted field as method parameter. <.> when using the repository, all that needs to be done is adding the scripted field as method parameter.
==== ====
[[runtime-fields]]
=== Runtime fields === Runtime fields
When using runtime fields, the calculated value can be used in the query itself. When using runtime fields, the calculated value can be used in the query itself.

11
src/main/asciidoc/reference/elasticsearch-operations.adoc → src/main/antora/modules/ROOT/pages/elasticsearch/template.adoc
View File

@ -1,7 +1,7 @@
[[elasticsearch.operations]] [[elasticsearch.operations]]
= Elasticsearch Operations = Elasticsearch Operations
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>>). 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 xref:elasticsearch/reactive-template.adoc[]).
* `IndexOperations` defines actions on index level like creating or deleting an index. * `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. * `DocumentOperations` defines actions to store, update and retrieve entities based on their id.
@ -21,12 +21,12 @@ The default implementations of the interfaces offer:
==== ====
.Index management and automatic creation of indices and mappings. .Index management and automatic creation of indices and mappings.
The `IndexOperations` interface and the provided implementation which can be obtained from an `ElasticsearchOperations` instance - for example with a call to `operations.indexOps(clazz)`- give the user the ability to create indices, put mappings or store template and alias information in the Elasticsearch cluster. The `IndexOperations` interface and the provided implementation which can be obtained from an `ElasticsearchOperations` instance - for example with a call to `operations.indexOps(clazz)`- give the user the ability to create indices, put mappings or store template and alias information in the Elasticsearch cluster.
Details of the index that will be created can be set by using the `@Setting` annotation, refer to <<elasticsearc.misc.index.settings>> for further information. Details of the index that will be created can be set by using the `@Setting` annotation, refer to xref:elasticsearch/misc.adoc#elasticsearc.misc.index.settings[Index settings] for further information.
**None of these operations are done automatically** by the implementations of `IndexOperations` or `ElasticsearchOperations`. **None of these operations are done automatically** by the implementations of `IndexOperations` or `ElasticsearchOperations`.
It is the user's responsibility to call the methods. It is the user's responsibility to call the methods.
There is support for automatic creation of indices and writing the mappings when using Spring Data Elasticsearch repositories, see <<elasticsearch.repositories.autocreation>> There is support for automatic creation of indices and writing the mappings when using Spring Data Elasticsearch repositories, see xref:elasticsearch/repositories/elasticsearch-repositories.adoc#elasticsearch.repositories.autocreation[Automatic creation of indices with the corresponding mapping]
==== ====
@ -34,7 +34,7 @@ There is support for automatic creation of indices and writing the mappings when
== Usage examples == Usage examples
The example shows how to use an injected `ElasticsearchOperations` instance in a Spring REST controller. The example shows how to use an injected `ElasticsearchOperations` instance in a Spring REST controller.
The example assumes that `Person` is a class that is annotated with `@Document`, `@Id` etc (see <<elasticsearch.mapping.meta-model.annotations>>). The example assumes that `Person` is a class that is annotated with `@Document`, `@Id` etc (see xref:elasticsearch/object-mapping.adoc#elasticsearch.mapping.meta-model.annotations[Mapping Annotation Overview]).
.ElasticsearchOperations usage .ElasticsearchOperations usage
==== ====
@ -73,7 +73,6 @@ The id is read from the returned entity, as it might have been null in the `pers
To see the full possibilities of `ElasticsearchOperations` please refer to the API documentation. To see the full possibilities of `ElasticsearchOperations` please refer to the API documentation.
include::reactive-elasticsearch-operations.adoc[leveloffset=+1]
[[elasticsearch.operations.searchresulttypes]] [[elasticsearch.operations.searchresulttypes]]
== Search Result Types == Search Result Types
@ -239,4 +238,4 @@ SearchHits<Person> searchHits = operations.search(query, Person.class);
=== SearchTemplateQuery === SearchTemplateQuery
This is a special implementation of the `Query` interface to be used in combination with a stored search template. This is a special implementation of the `Query` interface to be used in combination with a stored search template.
See <<elasticsearch.misc.searchtemplates>> for further information. See xref:elasticsearch/misc.adoc#elasticsearch.misc.searchtemplates[Search Template support] for further information.

24
src/main/antora/modules/ROOT/pages/elasticsearch/versions.adoc Normal file
View File

@ -0,0 +1,24 @@
[[preface.versions]]
= Versions
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 referring to that particular Spring Data release train.
The Elasticsearch version given shows with which client libraries Spring Data Elasticsearch was built and tested.
[cols="^,^,^,^,^",options="header"]
|===
| Spring Data Release Train | Spring Data Elasticsearch | Elasticsearch | Spring Framework | Spring Boot
| 2023.1 (Vaughan) | 5.2.x | 8.9.0 | 6.0.x | 3.1.x
| 2023.0 (Ullmann) | 5.1.x | 8.7.1 | 6.0.x | 3.1.x
| 2022.0 (Turing) | 5.0.x | 8.5.3 | 6.0.x | 3.0.x
| 2021.2 (Raj) | 4.4.xfootnote:oom[Out of maintenance] | 7.17.3 | 5.3.x | 2.7.x
| 2021.1 (Q) | 4.3.xfootnote:oom[] | 7.15.2 | 5.3.x | 2.6.x
| 2021.0 (Pascal) | 4.2.xfootnote:oom[] | 7.12.0 | 5.3.x | 2.5.x
| 2020.0 (Ockham) | 4.1.xfootnote:oom[] | 7.9.3 | 5.3.2 | 2.4.x
| Neumann | 4.0.xfootnote:oom[] | 7.6.2 | 5.2.12 |2.3.x
| Moore | 3.2.xfootnote:oom[] |6.8.12 | 5.2.12| 2.2.x
| Lovelace | 3.1.xfootnote:oom[] | 6.2.2 | 5.1.19 |2.1.x
| Kay | 3.0.xfootnote:oom[] | 5.5.0 | 5.0.13 | 2.0.x
| Ingalls | 2.1.xfootnote:oom[] | 2.4.0 | 4.3.25 | 1.5.x
|===
Support for upcoming versions of Elasticsearch is being tracked and general compatibility should be given assuming the usage of the xref:elasticsearch/template.adoc[ElasticsearchOperations interface].

22
src/main/antora/modules/ROOT/pages/index.adoc Normal file
View File

@ -0,0 +1,22 @@
[[spring-data-elasticsearch-reference-documentation]]
= Spring Data Elasticsearch
:revnumber: {version}
:revdate: {localdate}
:feature-scroll: true
_Spring Data Elasticsearch provides repository support for the Elasticsearch database.
It eases development of applications with a consistent programming model that need to access Elasticsearch data sources._
[horizontal]
xref:elasticsearch/versions.adoc[Versions] :: Version Compatibility Matrix
xref:elasticsearch/clients.adoc[Clients] :: Elasticsearch Client Configuration
xref:elasticsearch.adoc[Elasticsearch] :: Elasticsearch support
xref:repositories.adoc[Repositories] :: Elasticsearch Repositories
xref:migration-guides.adoc[Migration] :: Migration Guides
https://github.com/spring-projects/spring-data-commons/wiki[Wiki] :: What's New, Upgrade Notes, Supported Versions, additional cross-version information.
BioMed Central Development Team; Oliver Drotbohm; Greg Turnquist; Christoph Strobl; Peter-Josef Meisch
(C) 2008-2023 VMware, Inc.
Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.

8
src/main/antora/modules/ROOT/pages/migration-guides.adoc Normal file
View File

@ -0,0 +1,8 @@
[[elasticsearch.migration]]
= Migration Guides
:page-section-summary-toc: 1
This section contains version-specific migration guides explaining how to upgrade across versions.

23
src/main/asciidoc/reference/elasticsearch-migration-guide-3.2-4.0.adoc → src/main/antora/modules/ROOT/pages/migration-guides/migration-guide-3.2-4.0.adoc
View File

@ -6,9 +6,12 @@ This section describes breaking changes from version 3.2.x to 4.0.x and how remo
[[elasticsearch-migration-guide-3.2-4.0.jackson-removal]] [[elasticsearch-migration-guide-3.2-4.0.jackson-removal]]
== Removal of the used Jackson Mapper == Removal of the used Jackson Mapper
One of the changes in version 4.0.x is that Spring Data Elasticsearch does not use the Jackson Mapper anymore to map an entity to the JSON representation needed for Elasticsearch (see <<elasticsearch.mapping>>). In version 3.2.x the Jackson Mapper was the default that was used. It was possible to switch to the meta-model based converter (named `ElasticsearchEntityMapper`) by explicitly configuring it (<<elasticsearch.mapping.meta-model>>). One of the changes in version 4.0.x is that Spring Data Elasticsearch does not use the Jackson Mapper anymore to map an entity to the JSON representation needed for Elasticsearch (see xref:elasticsearch/object-mapping.adoc[Elasticsearch Object Mapping]).
In version 3.2.x the Jackson Mapper was the default that was used.
It was possible to switch to the meta-model based converter (named `ElasticsearchEntityMapper`) by explicitly configuring it (xref:elasticsearch/object-mapping.adoc#elasticsearch.mapping.meta-model[Meta Model Object Mapping]).
In version 4.0.x the meta-model based converter is the only one that is available and does not need to be configured explicitly. If you had a custom configuration to enable the meta-model converter by providing a bean like this: In version 4.0.x the meta-model based converter is the only one that is available and does not need to be configured explicitly.
If you had a custom configuration to enable the meta-model converter by providing a bean like this:
[source,java] [source,java]
---- ----
@ -28,13 +31,16 @@ public EntityMapper entityMapper() {
You now have to remove this bean, the `ElasticsearchEntityMapper` interface has been removed. You now have to remove this bean, the `ElasticsearchEntityMapper` interface has been removed.
.Entity configuration .Entity configuration
Some users had custom Jackson annotations on the entity class, for example in order to define a custom name for the mapped document in Elasticsearch or to configure date conversions. These are not taken into account anymore. The needed functionality is now provided with Spring Data Elasticsearch's `@Field` annotation. Please see <<elasticsearch.mapping.meta-model.annotations>> for detailed information. Some users had custom Jackson annotations on the entity class, for example in order to define a custom name for the mapped document in Elasticsearch or to configure date conversions.
These are not taken into account anymore.
The needed functionality is now provided with Spring Data Elasticsearch's `@Field` annotation.
Please see xref:elasticsearch/object-mapping.adoc#elasticsearch.mapping.meta-model.annotations[Mapping Annotation Overview] for detailed information.
[[elasticsearch-migration-guide-3.2-4.0.implicit-index-name]] [[elasticsearch-migration-guide-3.2-4.0.implicit-index-name]]
== Removal of implicit index name from query objects == Removal of implicit index name from query objects
In 3.2.x the different query classes like `IndexQuery` or `SearchQuery` had properties that were taking the index name or index names that they were operating upon. If these were not set, the passed in entity was inspected to retrieve the index name that was set in the `@Document` annotation. + In 3.2.x the different query classes like `IndexQuery` or `SearchQuery` had properties that were taking the index name or index names that they were operating upon.If these were not set, the passed in entity was inspected to retrieve the index name that was set in the `@Document` annotation. +
In 4.0.x the index name(s) must now be provided in an additional parameter of type `IndexCoordinates`. By separating this, it now is possible to use one query object against different indices. In 4.0.x the index name(s) must now be provided in an additional parameter of type `IndexCoordinates`.By separating this, it now is possible to use one query object against different indices.
So for example the following code: So for example the following code:
@ -130,6 +136,9 @@ Mapping types were removed from Elasticsearch 7, they still exist as deprecated
* The `SearchQuery` interface has been merged into it's base interface `Query`, so it's occurrences can just be replaced with `Query`. * The `SearchQuery` interface has been merged into it's base interface `Query`, so it's occurrences can just be replaced with `Query`.
* The method `org.springframework.data.elasticsearch.core.ElasticsearchOperations.query(SearchQuery query, ResultsExtractor<T> resultsExtractor);` and the `org.springframework.data.elasticsearch.core.ResultsExtractor` interface have been removed. These could be used to parse the result from Elasticsearch for cases in which the response mapping done with the Jackson based mapper was not enough. Since version 4.0, there are the new <<elasticsearch.operations.searchresulttypes>> to return the information from an Elasticsearch response, so there is no need to expose this low level functionality. * The method `org.springframework.data.elasticsearch.core.ElasticsearchOperations.query(SearchQuery query, ResultsExtractor<T> resultsExtractor);` and the `org.springframework.data.elasticsearch.core.ResultsExtractor` interface have been removed.
These could be used to parse the result from Elasticsearch for cases in which the response mapping done with the Jackson based mapper was not enough.
Since version 4.0, there are the new xref:elasticsearch/template.adoc#elasticsearch.operations.searchresulttypes[Search Result Types] to return the information from an Elasticsearch response, so there is no need to expose this low level functionality.
* The low level methods `startScroll`, `continueScroll` and `clearScroll` have been removed from the `ElasticsearchOperations` interface. For low level scroll API access, there now are `searchScrollStart`, `searchScrollContinue` and `searchScrollClear` methods on the `ElasticsearchRestTemplate` class. * The low level methods `startScroll`, `continueScroll` and `clearScroll` have been removed from the `ElasticsearchOperations` interface.
For low level scroll API access, there now are `searchScrollStart`, `searchScrollContinue` and `searchScrollClear` methods on the `ElasticsearchRestTemplate` class.

0
src/main/asciidoc/reference/elasticsearch-migration-guide-4.0-4.1.adoc → src/main/antora/modules/ROOT/pages/migration-guides/migration-guide-4.0-4.1.adoc
View File

2
src/main/asciidoc/reference/elasticsearch-migration-guide-4.1-4.2.adoc → src/main/antora/modules/ROOT/pages/migration-guides/migration-guide-4.1-4.2.adoc
View File

@ -54,7 +54,7 @@ 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]] [[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 xref:elasticsearch/clients.adoc[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]] [[elasticsearch-migration-guide-4.1-4.2.breaking-changes.method-return-types]]

2
src/main/asciidoc/reference/elasticsearch-migration-guide-4.2-4.3.adoc → src/main/antora/modules/ROOT/pages/migration-guides/migration-guide-4.2-4.3.adoc
View File

@ -15,7 +15,7 @@ For the user that means, that some enum classes that were used are replaced by e
Places where classes are used that cannot easily be replaced, this usage is marked as deprecated, we are working on replacements. Places where classes are used that cannot easily be replaced, this usage is marked as deprecated, we are working on replacements.
Check the sections on <<elasticsearch-migration-guide-4.2-4.3.deprecations>> and <<elasticsearch-migration-guide-4.2-4.3.breaking-changes>> for further details. Check the sections on xref:migration-guides/migration-guide-4.2-4.3.adoc#elasticsearch-migration-guide-4.2-4.3.deprecations[Deprecations] and xref:migration-guides/migration-guide-4.2-4.3.adoc#elasticsearch-migration-guide-4.2-4.3.breaking-changes[Breaking Changes] for further details.
==== ====
[[elasticsearch-migration-guide-4.2-4.3.deprecations]] [[elasticsearch-migration-guide-4.2-4.3.deprecations]]

5
src/main/asciidoc/reference/elasticsearch-migration-guide-4.3-4.4.adoc → src/main/antora/modules/ROOT/pages/migration-guides/migration-guide-4.3-4.4.adoc
View File

@ -18,6 +18,7 @@ As there now are multiple implementations using different client libraries the `
[[elasticsearch-migration-guide-4.3-4.4.breaking-changes.1]] [[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 ==== `org.springframework.data.elasticsearch.core.ElasticsearchTemplate` has been removed
As of version 4.4 Spring Data Elasticsearch does not use the `TransportClient` from Elasticsearch anymore (which itself is deprecated since Elasticsearch 7.0). As of version 4.4 Spring Data Elasticsearch does not use the `TransportClient` from Elasticsearch anymore (which itself is deprecated since Elasticsearch 7.0).
@ -38,7 +39,7 @@ The `ReactiveElasticsearchTemplate`, when created directly or by Spring Boot con
This could cause performance issues on heavy indexing and was different than the default behaviour of Elasticsearch. This could cause performance issues on heavy indexing and was different than the default behaviour of Elasticsearch.
This has been changed to that now the default refresh policy is NONE. This has been changed to that now the default refresh policy is NONE.
When the When the
`ReactiveElasticsearchTemplate` was provided by using the configuration like described in <<elasticsearch.clients.reactive>> the default refresh policy already was set to NONE. `ReactiveElasticsearchTemplate` was provided by using the configuration like described in xref:elasticsearch/clients.adoc#elasticsearch.clients.reactiverestclient[Reactive REST Client] the default refresh policy already was set to NONE.
[[elasticsearch-migration-guide-4.3-4.4.new-clients]] [[elasticsearch-migration-guide-4.3-4.4.new-clients]]
== New Elasticsearch client == New Elasticsearch client
@ -75,7 +76,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 xref:elasticsearch/clients.adoc[Elasticsearch Clients]), remove these beans from the Spring application context.
[[elasticsearch-migration-guide-4.3-4.4.new-clients.how-to.dependencies]] [[elasticsearch-migration-guide-4.3-4.4.new-clients.how-to.dependencies]]
==== Add dependencies ==== Add dependencies

7
src/main/asciidoc/reference/elasticsearch-migration-guide-4.4-5.0.adoc → src/main/antora/modules/ROOT/pages/migration-guides/migration-guide-4.4-5.0.adoc
View File

@ -6,16 +6,15 @@ 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
[[custom-trace-level-logging]]
=== Custom trace level logging === Custom trace level logging
Logging by setting the property `logging.level.org.springframework.data.elasticsearch.client.WIRE=trace` is Logging by setting the property `logging.level.org.springframework.data.elasticsearch.client.WIRE=trace` is deprecated now, the Elasticsearch `RestClient` provides a better solution that can be activated by setting the logging level of the `tracer` package to "trace".
deprecated now, the Elasticsearch `RestClient` provides a better solution that can be activated by setting the
logging level of the `tracer` package to "trace".
[[elasticsearch-migration-guide-4.4-4.5.deprecations.package]] [[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 xref:migration-guides/migration-guide-4.4-5.0.adoc#elasticsearch-migration-guide-4.4-5.0.breaking-changes-packages[Package changes], 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 xref:migration-guides/migration-guide-4.4-5.0.adoc#elasticsearch-migration-guide-4.4-5.0.new-clients[New Elasticsearch client]
[[elasticsearch-migration-guide-4.4-4.5.deprecations.code]] [[elasticsearch-migration-guide-4.4-4.5.deprecations.code]]
=== Removal of deprecated code === Removal of deprecated code

1
src/main/asciidoc/reference/elasticsearch-migration-guide-5.0-5.1.adoc → src/main/antora/modules/ROOT/pages/migration-guides/migration-guide-5.0-5.1.adoc
View File

@ -18,6 +18,7 @@ Adaptions are necessary when this enum was used at other places than as a proper
[[elasticsearch-migration-guide-5.0-5.1.deprecations]] [[elasticsearch-migration-guide-5.0-5.1.deprecations]]
== Deprecations == Deprecations
[[template-functions]]
=== template functions === template functions
The functions in the `IndexOperations` and `ReactiverIndexOperations` to manage index templates that were introduced in Spring Data Elasticsearch 4.1 The functions in the `IndexOperations` and `ReactiverIndexOperations` to manage index templates that were introduced in Spring Data Elasticsearch 4.1

8
src/main/asciidoc/reference/elasticsearch-migration-guide-5.1-5.2.adoc → src/main/antora/modules/ROOT/pages/migration-guides/migration-guide-5.1-5.2.adoc
View File

@ -6,6 +6,7 @@ This section describes breaking changes from version 5.1.x to 5.2.x and how remo
[[elasticsearch-migration-guide-5.1-5.2.breaking-changes]] [[elasticsearch-migration-guide-5.1-5.2.breaking-changes]]
== Breaking Changes == Breaking Changes
[[bulk-failures]]
=== Bulk failures === Bulk failures
In the `org.springframework.data.elasticsearch.BulkFailureException` class, the return type of the `getFailedDocuments` is changed from `Map<String, String>` In the `org.springframework.data.elasticsearch.BulkFailureException` class, the return type of the `getFailedDocuments` is changed from `Map<String, String>`
to `Map<String, FailureDetails>`, which allows to get additional details about failure reasons. to `Map<String, FailureDetails>`, which allows to get additional details about failure reasons.
@ -15,6 +16,7 @@ The definition of the `FailureDetails` class (inner to `BulkFailureException`):
public record FailureDetails(Integer status, String errorMessage) { public record FailureDetails(Integer status, String errorMessage) {
} }
[[scripted-and-runtime-fields]]
=== scripted and runtime fields === scripted and runtime fields
The classes `org.springframework.data.elasticsearch.core.RuntimeField` and `org.springframework.data.elasticsearch.core.query.ScriptType` have been moved to the subpackage `org.springframework.data.elasticsearch.core.query`. The classes `org.springframework.data.elasticsearch.core.RuntimeField` and `org.springframework.data.elasticsearch.core.query.ScriptType` have been moved to the subpackage `org.springframework.data.elasticsearch.core.query`.
@ -24,13 +26,15 @@ The `type` parameter of the `ScriptData` constructor is not nullable any longer.
[[elasticsearch-migration-guide-5.1-5.2.deprecations]] [[elasticsearch-migration-guide-5.1-5.2.deprecations]]
== Deprecations == Deprecations
[[removal-of-deprecated-code]]
=== Removal of deprecated code === Removal of deprecated code
* All the code using the old deprecated `RestHighLevelClient` has been removed. * All the code using the old deprecated `RestHighLevelClient` has been removed.
The default Elasticsearch client used since version 5.0 is the (not so) new Elasticsearch Java client. The default Elasticsearch client used since version 5.0 is the (not so) new Elasticsearch Java client.
* The `org.springframework.data.elasticsearch.client.ClientLogger` class has been removed. * The `org.springframework.data.elasticsearch.client.ClientLogger` class has been removed.
This logger was configured with the `org.springframework.data.elasticsearch.client.WIRE` setting, but was not working with all clients. This logger was configured with the `org.springframework.data.elasticsearch.client.WIRE` setting, but was not working with all clients.
From version 5 on, use the trace logger available in the Elasticsearch Java client, see <<elasticsearch.clients.logging>>. From version 5 on, use the trace logger available in the Elasticsearch Java client, see xref:elasticsearch/clients.adoc#elasticsearch.clients.logging[Client Logging].
* The method `org.springframework.data.elasticsearch.core.ElasticsearchOperations.stringIdRepresentation(Object)` has been removed, use the `convertId(Object)` method defined in the same interface instead. * The method `org.springframework.data.elasticsearch.core.ElasticsearchOperations.stringIdRepresentation(Object)` has been removed, use the `convertId(Object)` method defined in the same interface instead.
* The class `org.springframework.data.elasticsearch.core.Range` has been removed, use `org.springframework.data.domain.Range` instead. * The class `org.springframework.data.elasticsearch.core.Range` has been removed, use `org.springframework.data.domain.Range` instead.
* The methods `org.springframework.data.elasticsearch.core.query.IndexQuery.getParentId() and `setParentId(String)` have been removed, they werent used anymore and were no-ops. It has been removed from the `org.springframework.data.elasticsearch.core.query.IndexQuery` class as well. * The methods `org.springframework.data.elasticsearch.core.query.IndexQuery.getParentId() and `setParentId(String)` have been removed, they weren't used anymore and were no-ops.
It has been removed from the `org.springframework.data.elasticsearch.core.query.IndexQuery` class as well.

8
src/main/antora/modules/ROOT/pages/repositories.adoc Normal file
View File

@ -0,0 +1,8 @@
[[elasticsearch.repositories]]
= Repositories
:page-section-summary-toc: 1
This chapter explains the basic foundations of Spring Data repositories and Elasticsearch specifics.
Before continuing to the Elasticsearch specifics, make sure you have a sound understanding of the basic concepts.
The goal of the Spring Data repository abstraction is to significantly reduce the amount of boilerplate code required to implement data access layers for various persistence stores.

4
src/main/antora/modules/ROOT/pages/repositories/core-concepts.adoc Normal file
View File

@ -0,0 +1,4 @@
include::{commons}@data-commons::page$repositories/core-concepts.adoc[]
[[elasticsearch.entity-persistence.state-detection-strategies]]
include::{commons}@data-commons::page$is-new-state-detection.adoc[leveloffset=+1]

1
src/main/antora/modules/ROOT/pages/repositories/core-domain-events.adoc Normal file
View File

@ -0,0 +1 @@
include::{commons}@data-commons::page$repositories/core-domain-events.adoc[]

1
src/main/antora/modules/ROOT/pages/repositories/core-extensions.adoc Normal file
View File

@ -0,0 +1 @@
include::{commons}@data-commons::page$repositories/core-extensions.adoc[]

1
src/main/antora/modules/ROOT/pages/repositories/create-instances.adoc Normal file
View File

@ -0,0 +1 @@
include::{commons}@data-commons::page$repositories/create-instances.adoc[]

1
src/main/antora/modules/ROOT/pages/repositories/custom-implementations.adoc Normal file
View File

@ -0,0 +1 @@
include::{commons}@data-commons::page$repositories/custom-implementations.adoc[]

1
src/main/antora/modules/ROOT/pages/repositories/definition.adoc Normal file
View File

@ -0,0 +1 @@
include::{commons}@data-commons::page$repositories/definition.adoc[]

1
src/main/antora/modules/ROOT/pages/repositories/null-handling.adoc Normal file
View File

@ -0,0 +1 @@
include::{commons}@data-commons::page$repositories/null-handling.adoc[]

4
src/main/antora/modules/ROOT/pages/repositories/projections.adoc Normal file
View File

@ -0,0 +1,4 @@
[[elasticsearch.projections]]
= Projections
include::{commons}@data-commons::page$repositories/projections.adoc[leveloffset=+1]

1
src/main/antora/modules/ROOT/pages/repositories/query-keywords-reference.adoc Normal file
View File

@ -0,0 +1 @@
include::{commons}@data-commons::page$repositories/query-keywords-reference.adoc[]

1
src/main/antora/modules/ROOT/pages/repositories/query-methods-details.adoc Normal file
View File

@ -0,0 +1 @@
include::{commons}@data-commons::page$repositories/query-methods-details.adoc[]

1
src/main/antora/modules/ROOT/pages/repositories/query-return-types-reference.adoc Normal file
View File

@ -0,0 +1 @@
include::{commons}@data-commons::page$repositories/query-return-types-reference.adoc[]

20
src/main/antora/resources/antora-resources/antora.yml Normal file
View File

@ -0,0 +1,20 @@
version: ${antora-component.version}
prerelease: ${antora-component.prerelease}
asciidoc:
attributes:
version: ${project.version}
springversionshort: ${spring.short}
springversion: ${spring}
attribute-missing: 'warn'
commons: ${springdata.commons.docs}
include-xml-namespaces: false
spring-data-commons-docs-url: https://docs.spring.io/spring-data-commons/reference
spring-data-commons-javadoc-base: https://docs.spring.io/spring-data/commons/docs/${springdata.commons}/api/
springdocsurl: https://docs.spring.io/spring-framework/reference/{springversionshort}
springjavadocurl: https://docs.spring.io/spring-framework/docs/${spring}/javadoc-api
spring-framework-docs: '{springdocsurl}'
spring-framework-javadoc: '{springjavadocurl}'
springhateoasversion: ${spring-hateoas}
releasetrainversion: ${releasetrain}
store: Elasticsearch

52
src/main/asciidoc/index.adoc
View File

@ -1,52 +0,0 @@
= Spring Data Elasticsearch - Reference Documentation
BioMed Central Development Team; Oliver Drotbohm; Greg Turnquist; Christoph Strobl; Peter-Josef Meisch
:revnumber: {version}
:revdate: {localdate}
ifdef::backend-epub3[:front-cover-image: image:epub-cover.png[Front Cover,1050,1600]]
:spring-data-commons-docs: ../../../../spring-data-commons/src/main/asciidoc
(C) 2013-2022 The original author(s).
NOTE: Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.
toc::[]
include::preface.adoc[]
include::{spring-data-commons-docs}/upgrade.adoc[leveloffset=+1]
:leveloffset: +1
include::{spring-data-commons-docs}/repositories.adoc[]
:leveloffset: -1
[[reference]]
= Reference Documentation
:leveloffset: +1
include::reference/elasticsearch-clients.adoc[]
include::reference/elasticsearch-object-mapping.adoc[]
include::reference/elasticsearch-operations.adoc[]
include::reference/elasticsearch-repositories.adoc[]
include::{spring-data-commons-docs}/auditing.adoc[]
include::reference/elasticsearch-auditing.adoc[]
include::{spring-data-commons-docs}/entity-callbacks.adoc[]
include::reference/elasticsearch-entity-callbacks.adoc[leveloffset=+1]
include::reference/elasticsearch-join-types.adoc[]
include::reference/elasticsearch-routing.adoc[]
include::reference/elasticsearch-misc.adoc[]
:leveloffset: -1
[[appendix]]
= Appendix
:numbered!:
:leveloffset: +1
include::{spring-data-commons-docs}/repository-namespace-reference.adoc[]
include::{spring-data-commons-docs}/repository-populator-namespace-reference.adoc[]
include::{spring-data-commons-docs}/repository-query-keywords-reference.adoc[]
include::{spring-data-commons-docs}/repository-query-return-types-reference.adoc[]
include::reference/migration-guides.adoc[]
:leveloffset: -1

55
src/main/asciidoc/preface.adoc
View File

@ -1,55 +0,0 @@
[[preface]]
= Preface
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, 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.
include::reference/elasticsearch-new.adoc[leveloffset=+1]
[[preface.metadata]]
== Project Metadata
* Version Control - https://github.com/spring-projects/spring-data-elasticsearch
* API Documentation - https://docs.spring.io/spring-data/elasticsearch/docs/current/api/
* Bugtracker - https://github.com/spring-projects/spring-data-elasticsearch/issues
* Release repository - https://repo1.maven.org/maven2/
* Milestone repository - https://repo.spring.io/milestone/
* Snapshot repository - https://repo.spring.io/snapshot/
[[preface.requirements]]
== Requirements
Requires an installation of https://www.elastic.co/products/elasticsearch[Elasticsearch].
[[preface.versions]]
=== Versions
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 referring to that particular Spring
Data release train. The Elasticsearch version given shows with which client libraries Spring Data Elasticsearch was
built and tested.
[cols="^,^,^,^,^",options="header"]
|===
| Spring Data Release Train | Spring Data Elasticsearch | Elasticsearch | Spring Framework | Spring Boot
| 2023.1 (Vaughan) | 5.2.x | 8.9.0 | 6.0.x | 3.1.x
| 2023.0 (Ullmann) | 5.1.x | 8.7.1 | 6.0.x | 3.1.x
| 2022.0 (Turing) | 5.0.x | 8.5.3 | 6.0.x | 3.0.x
| 2021.2 (Raj) | 4.4.xfootnote:oom[Out of maintenance] | 7.17.3 | 5.3.x | 2.7.x
| 2021.1 (Q) | 4.3.xfootnote:oom[] | 7.15.2 | 5.3.x | 2.6.x
| 2021.0 (Pascal) | 4.2.xfootnote:oom[] | 7.12.0 | 5.3.x | 2.5.x
| 2020.0 (Ockham) | 4.1.xfootnote:oom[] | 7.9.3 | 5.3.2 | 2.4.x
| Neumann | 4.0.xfootnote:oom[] | 7.6.2 | 5.2.12 |2.3.x
| Moore | 3.2.xfootnote:oom[] |6.8.12 | 5.2.12| 2.2.x
| Lovelace | 3.1.xfootnote:oom[] | 6.2.2 | 5.1.19 |2.1.x
| Kay | 3.0.xfootnote:oom[] | 5.5.0 | 5.0.13 | 2.0.x
| Ingalls | 2.1.xfootnote:oom[] | 2.4.0 | 4.3.25 | 1.5.x
|===
Support for upcoming versions of Elasticsearch is being tracked and general compatibility should be given assuming
the usage of the <<elasticsearch.operations,ElasticsearchOperations interface>>.

22
src/main/asciidoc/reference/migration-guides.adoc
View File

@ -1,22 +0,0 @@
[[elasticsearch.migration]]
= Appendix E: Migration Guides
// line breaks required otherwise the TOC breaks due to joining of first/last lines.
:leveloffset: +1
include::elasticsearch-migration-guide-3.2-4.0.adoc[]
include::elasticsearch-migration-guide-4.0-4.1.adoc[]
include::elasticsearch-migration-guide-4.1-4.2.adoc[]
include::elasticsearch-migration-guide-4.2-4.3.adoc[]
include::elasticsearch-migration-guide-4.3-4.4.adoc[]
include::elasticsearch-migration-guide-4.4-5.0.adoc[]
include::elasticsearch-migration-guide-5.0-5.1.adoc[]
include::elasticsearch-migration-guide-5.1-5.2.adoc[]
:leveloffset: -1