Adjust Rest5Client building by using and exposing the callbacks provided by the Elasticsearch Java client library.

Original Pull Request #3143
Closes #3129

Signed-off-by: Peter-Josef Meisch <pj.meisch@sothawo.com>

.github/PULL_REQUEST_TEMPLATE.md

@@ -9,8 +9,7 @@ Make sure that:
 -->
 
 - [ ] You have read the [Spring Data contribution guidelines](https://github.com/spring-projects/spring-data-build/blob/master/CONTRIBUTING.adoc).
-- [ ] **There is a ticket in the bug tracker for the project in our [issue tracker](https://github.
-  com/spring-projects/spring-data-elasticsearch/issues)**. Add the issue number to the _Closes #issue-number_ line below
+- [ ] **There is a ticket in the bug tracker for the project in our [issue tracker](https://github.com/spring-projects/spring-data-elasticsearch/issues)**. Add the issue number to the _Closes #issue-number_ line below
 - [ ] You use the code formatters provided [here](https://github.com/spring-projects/spring-data-build/tree/master/etc/ide) and have them applied to your changes. Don’t submit any formatting related changes.
 - [ ] You submit test cases (unit or integration tests) that back your changes.
 - [ ] You added yourself as author in the headers of the classes you touched. Amend the date range in the Apache license header if needed. For new types, add the license header (copy from another file and set the current year only).

.gitignore

@@ -24,3 +24,13 @@ target
 
 
 /zap.env
+/localdocker.env
+.localdocker-env
+
+build/
+node_modules
+node
+package-lock.json
+
+.mvn/.develocity
+/src/test/resources/testcontainers-local.properties

.mvn/extensions.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<extensions>
+	<extension>
+		<groupId>io.spring.develocity.conventions</groupId>
+		<artifactId>develocity-conventions-maven-extension</artifactId>
+		<version>0.0.22</version>
+	</extension>
+</extensions>

.mvn/jvm.config

@@ -0,0 +1,14 @@
+--add-exports jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED
+--add-exports jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED
+--add-exports jdk.compiler/com.sun.tools.javac.main=ALL-UNNAMED
+--add-exports jdk.compiler/com.sun.tools.javac.model=ALL-UNNAMED
+--add-exports jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED
+--add-exports jdk.compiler/com.sun.tools.javac.processing=ALL-UNNAMED
+--add-exports jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED
+--add-exports jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED
+--add-opens jdk.compiler/com.sun.tools.javac.code=ALL-UNNAMED
+--add-opens jdk.compiler/com.sun.tools.javac.comp=ALL-UNNAMED
+--add-opens=java.base/java.util=ALL-UNNAMED
+--add-opens=java.base/java.lang.reflect=ALL-UNNAMED
+--add-opens=java.base/java.text=ALL-UNNAMED
+--add-opens=java.desktop/java.awt.font=ALL-UNNAMED

.mvn/wrapper/maven-wrapper.properties

@@ -1,3 +1,3 @@
-#Tue Feb 22 13:59:12 CET 2022
+#Thu Jul 17 13:59:56 CEST 2025
 wrapperUrl=https\://repo.maven.apache.org/maven2/io/takari/maven-wrapper/0.5.6/maven-wrapper-0.5.6.jar
-distributionUrl=https\://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.8.4/apache-maven-3.8.4-bin.zip
+distributionUrl=https\://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.11/apache-maven-3.9.11-bin.zip

CONTRIBUTING.adoc

@@ -1,11 +1,10 @@
 = Spring Data contribution guidelines
 
 You find the contribution guidelines for Spring Data projects https://github.com/spring-projects/spring-data-build/blob/main/CONTRIBUTING.adoc[here].
+**Please read these carefully!**
+
+Do not submit a Pull Request before having created an issue and having discussed it. This prevents you from doing work that might be rejected.
 
 == Running the test locally
 
 In order to run the tests locally with `./mvnw test` you need to have docker running because Spring Data Elasticsearch uses https://www.testcontainers.org/[Testcontainers] to start a local running Elasticsearch instance.
-
-== Class names of the test classes
-
-Tset classes that do depend on the client have either `ERHLC` (when using the deprecated Elasticsearch  `RestHighLevelClient`) or `ELC` (the new `ElasticsearchClient`) in their name.

Jenkinsfile

@@ -1,7 +1,7 @@
 def p = [:]
 node {
-    checkout scm
-    p = readProperties interpolate: true, file: 'ci/pipeline.properties'
+		checkout scm
+		p = readProperties interpolate: true, file: 'ci/pipeline.properties'
 }
 
 pipeline {
@@ -20,8 +20,9 @@ pipeline {
 	stages {
 		stage("test: baseline (main)") {
 			when {
+				beforeAgent(true)
 				anyOf {
-					branch 'main'
+					branch(pattern: "main|(\\d\\.\\d\\.x)", comparator: "REGEXP")
 					not { triggeredBy 'UpstreamCause' }
 				}
 			}
@@ -31,17 +32,16 @@ pipeline {
 			options { timeout(time: 30, unit: 'MINUTES') }
 
 			environment {
-				DOCKER_HUB = credentials("${p['docker.credentials']}")
 				ARTIFACTORY = credentials("${p['artifactory.credentials']}")
+				DEVELOCITY_ACCESS_KEY = credentials("${p['develocity.access-key']}")
 			}
 
 			steps {
 				script {
-					docker.withRegistry(p['docker.registry'], p['docker.credentials']) {
+					docker.withRegistry(p['docker.proxy.registry'], p['docker.proxy.credentials']) {
 						docker.image(p['docker.java.main.image']).inside(p['docker.java.inside.docker']) {
-							sh "docker login --username ${DOCKER_HUB_USR} --password ${DOCKER_HUB_PSW}"
-							sh 'PROFILE=none ci/verify.sh'
-							sh "ci/clean.sh"
+							sh "PROFILE=none JENKINS_USER_NAME=${p['jenkins.user.name']} ci/verify.sh"
+							sh "JENKINS_USER_NAME=${p['jenkins.user.name']} ci/clean.sh"
 						}
 					}
 				}
@@ -50,8 +50,9 @@ pipeline {
 
 		stage("Test other configurations") {
 			when {
+				beforeAgent(true)
 				allOf {
-					branch 'main'
+					branch(pattern: "main|(\\d\\.\\d\\.x)", comparator: "REGEXP")
 					not { triggeredBy 'UpstreamCause' }
 				}
 			}
@@ -61,43 +62,16 @@ pipeline {
 						label 'data'
 					}
 					options { timeout(time: 30, unit: 'MINUTES') }
-
 					environment {
-						DOCKER_HUB = credentials("${p['docker.credentials']}")
 						ARTIFACTORY = credentials("${p['artifactory.credentials']}")
+						DEVELOCITY_ACCESS_KEY = credentials("${p['develocity.access-key']}")
 					}
-
 					steps {
 						script {
-							docker.withRegistry(p['docker.registry'], p['docker.credentials']) {
+							docker.withRegistry(p['docker.proxy.registry'], p['docker.proxy.credentials']) {
 								docker.image(p['docker.java.next.image']).inside(p['docker.java.inside.docker']) {
-									sh "docker login --username ${DOCKER_HUB_USR} --password ${DOCKER_HUB_PSW}"
-									sh 'PROFILE=none ci/verify.sh'
-									sh "ci/clean.sh"
-								}
-							}
-						}
-					}
-				}
-
-				stage("test: baseline (LTS)") {
-					agent {
-						label 'data'
-					}
-					options { timeout(time: 30, unit: 'MINUTES') }
-
-					environment {
-						DOCKER_HUB = credentials("${p['docker.credentials']}")
-						ARTIFACTORY = credentials("${p['artifactory.credentials']}")
-					}
-
-					steps {
-						script {
-							docker.withRegistry(p['docker.registry'], p['docker.credentials']) {
-								docker.image(p['docker.java.lts.image']).inside(p['docker.java.inside.docker']) {
-									sh "docker login --username ${DOCKER_HUB_USR} --password ${DOCKER_HUB_PSW}"
-									sh 'PROFILE=none ci/verify.sh'
-									sh "ci/clean.sh"
+									sh "PROFILE=none JENKINS_USER_NAME=${p['jenkins.user.name']} ci/verify.sh"
+									sh "JENKINS_USER_NAME=${p['jenkins.user.name']} ci/clean.sh"
 								}
 							}
 						}
@@ -108,8 +82,9 @@ pipeline {
 
 		stage('Release to artifactory') {
 			when {
+				beforeAgent(true)
 				anyOf {
-					branch 'main'
+					branch(pattern: "main|(\\d\\.\\d\\.x)", comparator: "REGEXP")
 					not { triggeredBy 'UpstreamCause' }
 				}
 			}
@@ -117,23 +92,25 @@ pipeline {
 				label 'data'
 			}
 			options { timeout(time: 20, unit: 'MINUTES') }
-
 			environment {
 				ARTIFACTORY = credentials("${p['artifactory.credentials']}")
+				DEVELOCITY_ACCESS_KEY = credentials("${p['develocity.access-key']}")
 			}
-
 			steps {
 				script {
-					docker.withRegistry(p['docker.registry'], p['docker.credentials']) {
-						docker.image(p['docker.java.main.image']).inside(p['docker.java.inside.basic']) {
-							sh 'MAVEN_OPTS="-Duser.name=jenkins -Duser.home=/tmp/jenkins-home" ./mvnw -s settings.xml -Pci,artifactory -Dmaven.repo.local=/tmp/jenkins-home/.m2/spring-data-elasticsearch-non-root ' +
-									'-Dartifactory.server=https://repo.spring.io ' +
+					docker.withRegistry(p['docker.proxy.registry'], p['docker.proxy.credentials']) {
+						docker.image(p['docker.java.main.image']).inside(p['docker.java.inside.docker']) {
+								sh 'MAVEN_OPTS="-Duser.name=' + "${p['jenkins.user.name']}" + ' -Duser.home=/tmp/jenkins-home" ' +
+									"./mvnw -s settings.xml -Pci,artifactory " +
+									"-Ddevelocity.storage.directory=/tmp/jenkins-home/.develocity-root " +
+									"-Dartifactory.server=${p['artifactory.url']} " +
 									"-Dartifactory.username=${ARTIFACTORY_USR} " +
 									"-Dartifactory.password=${ARTIFACTORY_PSW} " +
-									"-Dartifactory.staging-repository=libs-snapshot-local " +
+									"-Dartifactory.staging-repository=${p['artifactory.repository.snapshot']} " +
 									"-Dartifactory.build-name=spring-data-elasticsearch " +
-									"-Dartifactory.build-number=${BUILD_NUMBER} " +
-									'-Dmaven.test.skip=true clean deploy -U -B'
+									"-Dartifactory.build-number=spring-data-elasticsearch-${BRANCH_NAME}-build-${BUILD_NUMBER} " +
+									"-Dmaven.repo.local=/tmp/jenkins-home/.m2/spring-data-elasticsearch " +
+									"-Dmaven.test.skip=true clean deploy -U -B"
 						}
 					}
 				}
@@ -144,10 +121,6 @@ pipeline {
 	post {
 		changed {
 			script {
-				slackSend(
-						color: (currentBuild.currentResult == 'SUCCESS') ? 'good' : 'danger',
-						channel: '#spring-data-dev',
-						message: "${currentBuild.fullDisplayName} - `${currentBuild.currentResult}`\n${env.BUILD_URL}")
 				emailext(
 						subject: "[${currentBuild.fullDisplayName}] ${currentBuild.currentResult}",
 						mimeType: 'text/html',

README.adoc

@@ -1,18 +1,16 @@
-image:https://spring.io/badges/spring-data-elasticsearch/ga.svg[Spring Data Elasticsearch,link=https://projects.spring.io/spring-data-elasticsearch#quick-start] image:https://spring.io/badges/spring-data-elasticsearch/snapshot.svg[Spring Data Elasticsearch,link=https://projects.spring.io/spring-data-elasticsearch#quick-start]
-
-= Spring Data for Elasticsearch image:https://jenkins.spring.io/buildStatus/icon?job=spring-data-elasticsearch%2Fmain&subject=Build[link=https://jenkins.spring.io/view/SpringData/job/spring-data-elasticsearch/] https://gitter.im/spring-projects/spring-data[image:https://badges.gitter.im/spring-projects/spring-data.svg[Gitter]]
+= Spring Data for Elasticsearch image:https://jenkins.spring.io/buildStatus/icon?job=spring-data-elasticsearch%2Fmain&subject=Build[link=https://jenkins.spring.io/view/SpringData/job/spring-data-elasticsearch/] https://gitter.im/spring-projects/spring-data[image:https://badges.gitter.im/spring-projects/spring-data.svg[Gitter]] image:https://img.shields.io/badge/Revved%20up%20by-Develocity-06A0CE?logo=Gradle&labelColor=02303A["Revved up by Develocity", link="https://ge.spring.io/scans?search.rootProjectNames=Spring Data Elasticsearch"]
 
 The primary goal of the https://projects.spring.io/spring-data[Spring Data] project is to make it easier to build Spring-powered applications that use new data access technologies such as non-relational databases, map-reduce frameworks, and cloud based data services.
 
 The Spring Data Elasticsearch project provides integration with the https://www.elastic.co/[Elasticsearch] search engine.
-Key functional areas of Spring Data Elasticsearch are a POJO centric model for interacting with a Elasticsearch Documents and easily writing a Repository style data access layer.
+Key functional areas of Spring Data Elasticsearch are a POJO centric model for interacting with Elasticsearch Documents and easily writing a Repository style data access layer.
 
 This project is lead and maintained by the community.
 
 == Features
 
-* Spring configuration support using Java based `@Configuration` classes or an XML namespace for a ES clients instances.
-* `ElasticsearchRestTemplate` helper class that increases productivity performing common ES operations.
+* Spring configuration support using Java based `@Configuration` classes or an XML namespace for an ES client instances.
+* `ElasticsearchOperations` class and implementations that increases productivity performing common ES operations.
 Includes integrated object mapping between documents and POJOs.
 * Feature Rich Object Mapping integrated with Spring’s Conversion Service
 * Annotation based mapping metadata
@@ -64,25 +62,7 @@ public class MyService {
 
 === Using the RestClient
 
-Provide a configuration like this:
-
-[source,java]
-----
-@Configuration
-public class RestClientConfig extends AbstractElasticsearchConfiguration {
-
-    @Override
-    @Bean
-    public RestHighLevelClient elasticsearchClient() {
-
-        final ClientConfiguration clientConfiguration = ClientConfiguration.builder()
-            .connectedTo("localhost:9200")
-            .build();
-
-        return RestClients.create(clientConfiguration).rest();
-    }
-}
-----
+Please check the https://docs.spring.io/spring-data/elasticsearch/docs/current/reference/html/#elasticsearch.clients.configuration[official documentation].
 
 === Maven configuration
 
@@ -97,9 +77,6 @@ Add the Maven dependency:
 </dependency>
 ----
 
-// NOTE: since Github does not support include directives, the content of
-// the src/main/asciidoc/reference/preface.adoc file is duplicated here
-// Always change both files!
 **Compatibility Matrix**
 
 The compatibility between Spring Data Elasticsearch, Elasticsearch client drivers and Spring Boot versions can be found in the https://docs.spring.io/spring-data/elasticsearch/docs/current/reference/html/#preface.versions[reference documentation].
@@ -115,9 +92,9 @@ To use the Release candidate versions of the upcoming major version, use our Mav
 </dependency>
 
 <repository>
-  <id>spring-libs-snapshot</id>
+  <id>spring-snapshot</id>
   <name>Spring Snapshot Repository</name>
-  <url>https://repo.spring.io/libs-milestone</url>
+  <url>https://repo.spring.io/milestone</url>
 </repository>
 ----
 
@@ -132,9 +109,9 @@ If you'd rather like the latest snapshots of the upcoming major version, use our
 </dependency>
 
 <repository>
-  <id>spring-libs-snapshot</id>
+  <id>spring-snapshot</id>
   <name>Spring Snapshot Repository</name>
-  <url>https://repo.spring.io/libs-snapshot</url>
+  <url>https://repo.spring.io/snapshot</url>
 </repository>
 ----
 
@@ -147,9 +124,7 @@ We’d love to help!
 https://docs.spring.io/spring-data/elasticsearch/docs/current/reference/html/[reference documentation], and https://docs.spring.io/spring-data/elasticsearch/docs/current/api/[Javadocs].
 * Learn the Spring basics – Spring Data builds on Spring Framework, check the https://spring.io[spring.io] web-site for a wealth of reference documentation.
 If you are just starting out with Spring, try one of the https://spring.io/guides[guides].
-* If you are upgrading, check out the https://docs.spring.io/spring-data/elasticsearch/docs/current/changelog.txt[changelog] for "`new and noteworthy`" features.
-* Ask a question - we monitor https://stackoverflow.com[stackoverflow.com] for questions tagged with https://stackoverflow.com/tags/spring-data[`spring-data-elasticsearch`].
-You can also chat with the community on https://gitter.im/spring-projects/spring-data[Gitter].
+* Ask a question or chat with the community on https://app.gitter.im/#/room/#spring-projects_spring-data:gitter.im[Gitter].
 * Report bugs with Spring Data for Elasticsearch at https://github.com/spring-projects/spring-data-elasticsearch/issues[https://github.com/spring-projects/spring-data-elasticsearch/issues].
 
 == Reporting Issues
@@ -159,7 +134,7 @@ If you want to raise an issue, please follow the recommendations below:
 
 * 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.
-* 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.
 * 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.
@@ -168,7 +143,9 @@ Attach a link to your code or a compressed file containing your code.
 == Building from Source
 
 You don’t need to build from source to use Spring Data (binaries in https://repo.spring.io[repo.spring.io]), but if you want to try out the latest and greatest, Spring Data can be easily built with the https://github.com/takari/maven-wrapper[maven wrapper].
-You also need JDK 1.8.
+
+You need JDK 17 or above to build the _main_ branch.
+For the branches up to and including release 4.4, JDK 8 is required.
 
 [source,bash]
 ----
@@ -182,17 +159,16 @@ _Also see link:CONTRIBUTING.adoc[CONTRIBUTING.adoc] if you wish to submit pull r
 IMPORTANT: When contributing, please make sure an issue exists in https://github.com/spring-projects/spring-data-elasticsearch/issues[issue tracker] and comment on this issue with how you want to address it.
 By this we not only know that someone is working on an issue, we can also align architectural questions and possible solutions before work is invested . We so can prevent that much work is put into Pull Requests that have little or no chances of being merged.
 
-
 === Building reference documentation
 
 Building the documentation builds also the project without running tests.
 
 [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/site/index.html`.
 
 == Examples
 

TESTING.adoc

@@ -18,24 +18,3 @@ is run. There must be _docker_ running, as the integration tests use docker to s
 
 Integration tests are tests that have the Junit5 Tag `@Tag("integration-test")` on the test class. Normally this should not be set explicitly, but the annotation `@SpringIntegrationTest` should be used. This not only marks the test as integration test, but integrates an automatic setup of an Elasticsearch Testcontainer and integrate this with Spring, so
 that the required Beans can be automatically injected. Check _src/test/java/org/springframework/data/elasticsearch/JUnit5SampleRestClientBasedTests.java_ as a reference setup
-
-== Mutation testing
-
-The pom includes a plugin dependency to run mutation tests using [pitest](https://pitest.org/). These tests must be explicitly configured and run, they are not included in the normal build steps. Before pitest can run, a normal `./mvnw test` must be executed. The configuration excludes integration tests, only unit tests are considered.
-
-
-pitest can be run directly from the commandline
-----
-./mvnw org.pitest:pitest-maven:mutationCoverage
-----
-This will output an html report to _target/pit-reports/YYYYMMDDHHMI_.
-
-To speed-up repeated analysis of the same codebase set the withHistory parameter to true.
-----
-./mvnw -DwithHistory org.pitest:pitest-maven:mutationCoverage
-----
-
-The classes to test are defined either in the pom.xml or can be set on the commandline:
-----
-./mvnw -DwithHistory org.pitest:pitest-maven:mutationCoverage -DtargetClasses="org.springframework.data.elasticsearch.support.*"
-----

ci/clean.sh

@@ -2,5 +2,7 @@
 
 set -euo pipefail
 
-MAVEN_OPTS="-Duser.name=jenkins -Duser.home=/tmp/jenkins-home" \
-  ./mvnw -s settings.xml clean -Dmaven.repo.local=/tmp/jenkins-home/.m2/spring-data-elasticsearch
+export JENKINS_USER=${JENKINS_USER_NAME}
+
+MAVEN_OPTS="-Duser.name=${JENKINS_USER} -Duser.home=/tmp/jenkins-home" \
+  ./mvnw -s settings.xml clean -Dscan=false -Dmaven.repo.local=/tmp/jenkins-home/.m2/spring-data-elasticsearch -Ddevelocity.storage.directory=/tmp/jenkins-home/.develocity-root

ci/pipeline.properties

@@ -1,23 +1,19 @@
 # Java versions
-java.main.tag=8u322-b06-jdk
-java.next.tag=11.0.14.1_1-jdk
-java.lts.tag=17.0.2_8-jdk
+java.main.tag=24.0.1_9-jdk-noble
+java.next.tag=24.0.1_9-jdk-noble
 
 # Docker container images - standard
-docker.java.main.image=harbor-repo.vmware.com/dockerhub-proxy-cache/library/eclipse-temurin:${java.main.tag}
-docker.java.next.image=harbor-repo.vmware.com/dockerhub-proxy-cache/library/eclipse-temurin:${java.next.tag}
-docker.java.lts.image=harbor-repo.vmware.com/dockerhub-proxy-cache/library/eclipse-temurin:${java.lts.tag}
+docker.java.main.image=library/eclipse-temurin:${java.main.tag}
+docker.java.next.image=library/eclipse-temurin:${java.next.tag}
 
 # Supported versions of MongoDB
-docker.mongodb.4.0.version=4.0.28
-docker.mongodb.4.4.version=4.4.12
-docker.mongodb.5.0.version=5.0.6
+docker.mongodb.6.0.version=6.0.23
+docker.mongodb.7.0.version=7.0.20
+docker.mongodb.8.0.version=8.0.9
 
 # Supported versions of Redis
-docker.redis.6.version=6.2.6
-
-# Supported versions of Cassandra
-docker.cassandra.3.version=3.11.12
+docker.redis.6.version=6.2.13
+docker.redis.7.version=7.2.4
 
 # Docker environment settings
 docker.java.inside.basic=-v $HOME:/tmp/jenkins-home
@@ -26,4 +22,10 @@ docker.java.inside.docker=-u root -v /var/run/docker.sock:/var/run/docker.sock -
 # Credentials
 docker.registry=
 docker.credentials=hub.docker.com-springbuildmaster
+docker.proxy.registry=https://docker-hub.usw1.packages.broadcom.com
+docker.proxy.credentials=usw1_packages_broadcom_com-jenkins-token
 artifactory.credentials=02bd1690-b54f-4c9f-819d-a77cb7a9822c
+artifactory.url=https://repo.spring.io
+artifactory.repository.snapshot=libs-snapshot-local
+develocity.access-key=gradle_enterprise_secret_access_key
+jenkins.user.name=spring-builds+jenkins

ci/verify.sh

@@ -3,8 +3,8 @@
 set -euo pipefail
 
 mkdir -p /tmp/jenkins-home/.m2/spring-data-elasticsearch
-chown -R 1001:1001 .
+export JENKINS_USER=${JENKINS_USER_NAME}
 
-MAVEN_OPTS="-Duser.name=jenkins -Duser.home=/tmp/jenkins-home" \
+MAVEN_OPTS="-Duser.name=${JENKINS_USER} -Duser.home=/tmp/jenkins-home" \
   ./mvnw -s settings.xml \
-  -P${PROFILE} clean dependency:list verify -Dsort -U -B -Dmaven.repo.local=/tmp/jenkins-home/.m2/spring-data-elasticsearch
+  -P${PROFILE} clean dependency:list verify -Dsort -U -B -Dmaven.repo.local=/tmp/jenkins-home/.m2/spring-data-elasticsearch -Ddevelocity.storage.directory=/tmp/jenkins-home/.develocity-root

package.json

@@ -0,0 +1,10 @@
+{
+    "dependencies": {
+        "antora": "3.2.0-alpha.6",
+        "@antora/atlas-extension": "1.0.0-alpha.2",
+        "@antora/collector-extension": "1.0.0-alpha.7",
+        "@asciidoctor/tabs": "1.0.0-beta.6",
+        "@springio/antora-extensions": "1.13.0",
+        "@springio/asciidoctor-extensions": "1.0.0-alpha.11"
+    }
+}

pom.xml

@@ -1,16 +1,16 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<?xml version="1.0" encoding="UTF-8"?>
 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
 
 	<modelVersion>4.0.0</modelVersion>
 
 	<groupId>org.springframework.data</groupId>
 	<artifactId>spring-data-elasticsearch</artifactId>
-	<version>4.4.0-SNAPSHOT</version>
+	<version>6.0.0-SNAPSHOT</version>
 
 	<parent>
 		<groupId>org.springframework.data.build</groupId>
 		<artifactId>spring-data-parent</artifactId>
-		<version>2.7.0-SNAPSHOT</version>
+		<version>4.0.0-SNAPSHOT</version>
 	</parent>
 
 	<name>Spring Data Elasticsearch</name>
@@ -18,13 +18,17 @@
 	<url>https://github.com/spring-projects/spring-data-elasticsearch</url>
 
 	<properties>
-		<elasticsearch>7.17.1</elasticsearch>
-		<elasticsearch-java>7.17.1</elasticsearch-java>
-		<log4j>2.17.1</log4j>
-		<netty>4.1.65.Final</netty>
-		<springdata.commons>2.7.0-SNAPSHOT</springdata.commons>
-		<testcontainers>1.16.2</testcontainers>
-		<blockhound-junit>1.0.6.RELEASE</blockhound-junit>
+		<springdata.commons>4.0.0-SNAPSHOT</springdata.commons>
+
+		<!-- version of the ElasticsearchClient	-->
+		<elasticsearch-java>9.0.4</elasticsearch-java>
+
+		<hoverfly>0.19.0</hoverfly>
+		<log4j>2.23.1</log4j>
+		<jsonassert>1.5.3</jsonassert>
+		<testcontainers>1.20.0</testcontainers>
+		<wiremock>3.9.1</wiremock>
+
 		<java-module-name>spring.data.elasticsearch</java-module-name>
 
 		<!--
@@ -34,7 +38,6 @@
 		-->
 		<mvn.unit-test.goal>test</mvn.unit-test.goal>
 		<mvn.integration-test-elasticsearch.goal>integration-test</mvn.integration-test-elasticsearch.goal>
-		<mvn.integration-test-opensearch.goal>none</mvn.integration-test-opensearch.goal>
 	</properties>
 
 	<developers>
@@ -84,18 +87,6 @@
 		<url>https://github.com/spring-projects/spring-data-elasticsearch/issues</url>
 	</issueManagement>
 
-	<dependencyManagement>
-		<dependencies>
-			<dependency>
-				<groupId>io.netty</groupId>
-				<artifactId>netty-bom</artifactId>
-				<version>${netty}</version>
-				<type>pom</type>
-				<scope>import</scope>
-			</dependency>
-		</dependencies>
-	</dependencyManagement>
-
 	<dependencies>
 
 		<!-- Spring -->
@@ -123,32 +114,12 @@
 			<optional>true</optional>
 		</dependency>
 
-		<dependency>
-			<groupId>io.projectreactor.netty</groupId>
-			<artifactId>reactor-netty-http</artifactId>
-			<optional>true</optional>
-		</dependency>
-
 		<dependency>
 			<groupId>io.projectreactor</groupId>
 			<artifactId>reactor-test</artifactId>
 			<scope>test</scope>
 		</dependency>
 
-		<!-- Elasticsearch  RestHighLevelClient, will be removed probably in SDE 5 -->
-		<dependency>
-			<groupId>org.elasticsearch.client</groupId>
-			<artifactId>elasticsearch-rest-high-level-client</artifactId>
-			<version>${elasticsearch}</version>
-			<exclusions>
-				<exclusion>
-					<groupId>commons-logging</groupId>
-					<artifactId>commons-logging</artifactId>
-				</exclusion>
-			</exclusions>
-		</dependency>
-
-		<!-- new Elasticsearch client, needs the low-level rest client and json api -->
 		<dependency>
 			<groupId>co.elastic.clients</groupId>
 			<artifactId>elasticsearch-java</artifactId>
@@ -160,16 +131,26 @@
 				</exclusion>
 			</exclusions>
 		</dependency>
+
+		<!-- the old RestCLient is an optional dependency for user that still want to use it-->
 		<dependency>
 			<groupId>org.elasticsearch.client</groupId>
-			<artifactId>elasticsearch-rest-client</artifactId> <!-- is Apache 2-->
-			<version>${elasticsearch}</version>
+			<artifactId>elasticsearch-rest-client</artifactId>
+			<version>${elasticsearch-java}</version>
 			<exclusions>
 				<exclusion>
 					<groupId>commons-logging</groupId>
 					<artifactId>commons-logging</artifactId>
 				</exclusion>
 			</exclusions>
+			<optional>true</optional>
+		</dependency>
+
+		<dependency>
+			<groupId>com.querydsl</groupId>
+			<artifactId>querydsl-core</artifactId>
+			<version>${querydsl}</version>
+			<optional>true</optional>
 		</dependency>
 
 		<!-- Jackson JSON Mapper -->
@@ -183,33 +164,25 @@
 		</dependency>
 
 		<!-- CDI -->
-		<!-- Dependency order required to build against CDI 1.0 and test with CDI 2.0 -->
-		<dependency>
-			<groupId>org.apache.geronimo.specs</groupId>
-			<artifactId>geronimo-jcdi_2.0_spec</artifactId>
-			<version>1.3</version>
-			<scope>test</scope>
-		</dependency>
 
 		<dependency>
 			<groupId>javax.interceptor</groupId>
 			<artifactId>javax.interceptor-api</artifactId>
-			<version>1.2.1</version>
+			<version>1.2.2</version>
 			<scope>test</scope>
 		</dependency>
 
 		<dependency>
-			<groupId>javax.enterprise</groupId>
-			<artifactId>cdi-api</artifactId>
-			<version>${cdi}</version>
+			<groupId>jakarta.enterprise</groupId>
+			<artifactId>jakarta.enterprise.cdi-api</artifactId>
 			<scope>provided</scope>
 			<optional>true</optional>
 		</dependency>
 
 		<dependency>
-			<groupId>javax.annotation</groupId>
-			<artifactId>javax.annotation-api</artifactId>
-			<version>${javax-annotation-api}</version>
+			<groupId>jakarta.annotation</groupId>
+			<artifactId>jakarta.annotation-api</artifactId>
+			<version>${jakarta-annotation-api}</version>
 			<scope>test</scope>
 		</dependency>
 
@@ -220,6 +193,31 @@
 			<scope>test</scope>
 		</dependency>
 
+		<!-- Kotlin extension -->
+		<dependency>
+			<groupId>org.jetbrains.kotlin</groupId>
+			<artifactId>kotlin-stdlib</artifactId>
+			<optional>true</optional>
+		</dependency>
+
+		<dependency>
+			<groupId>org.jetbrains.kotlin</groupId>
+			<artifactId>kotlin-reflect</artifactId>
+			<optional>true</optional>
+		</dependency>
+
+		<dependency>
+			<groupId>org.jetbrains.kotlinx</groupId>
+			<artifactId>kotlinx-coroutines-core</artifactId>
+			<optional>true</optional>
+		</dependency>
+
+		<dependency>
+			<groupId>org.jetbrains.kotlinx</groupId>
+			<artifactId>kotlinx-coroutines-reactor</artifactId>
+			<optional>true</optional>
+		</dependency>
+
 		<!-- Test -->
 		<dependency>
 			<groupId>org.springframework</groupId>
@@ -233,6 +231,13 @@
 			</exclusions>
 		</dependency>
 
+		<dependency>
+			<groupId>org.jetbrains.kotlinx</groupId>
+			<artifactId>kotlinx-coroutines-test</artifactId>
+			<scope>test</scope>
+			<optional>true</optional>
+		</dependency>
+
 		<dependency>
 			<groupId>org.slf4j</groupId>
 			<artifactId>log4j-over-slf4j</artifactId>
@@ -252,42 +257,17 @@
 			<scope>test</scope>
 		</dependency>
 
-		<dependency>
-			<groupId>io.projectreactor.tools</groupId>
-			<artifactId>blockhound-junit-platform</artifactId>
-			<version>${blockhound-junit}</version>
-			<scope>test</scope>
-		</dependency>
-
-
-		<!--
-		  we don't use lombok in Spring Data Elasticsearch anymore. But the dependency is set in the parent project, and so the
-		  lombok compiler stuff is executed regardless of the fact that we don't need it.
-		  On AdoptOpenJdk 16.0.0 this leads to an error, so the project does not build.
-		  Therefore we replace lombok with a jar - that just contains an empty file - that lives in a local maven repository in
-		  src/test/resources/local-maven-repo/
-		  It was installed with
-		   mvn deploy:deploy-file -DgroupId=org.projectlombok -DartifactId=lombok -Dversion=999999 -Durl=file:./src/test/resources/local-maven-repo/ -DrepositoryId=local-maven-repo -DupdateReleaseInfo=true -Dfile=path/to/empty.jar
-		-->
-		<dependency>
-			<groupId>org.projectlombok</groupId>
-			<artifactId>lombok</artifactId>
-			<!--suppress MavenPackageUpdate -->
-			<version>999999</version>
-			<scope>test</scope>
-		</dependency>
-
 		<dependency>
 			<groupId>org.skyscreamer</groupId>
 			<artifactId>jsonassert</artifactId>
-			<version>1.5.0</version>
+			<version>${jsonassert}</version>
 			<scope>test</scope>
 		</dependency>
 
 		<dependency>
-			<groupId>com.github.tomakehurst</groupId>
-			<artifactId>wiremock-jre8</artifactId>
-			<version>2.32.0</version>
+			<groupId>org.wiremock</groupId>
+			<artifactId>wiremock</artifactId>
+			<version>${wiremock}</version>
 			<scope>test</scope>
 			<exclusions>
 				<!-- these exclusions are needed because of Elasticsearch JarHell-->
@@ -305,7 +285,7 @@
 		<dependency>
 			<groupId>io.specto</groupId>
 			<artifactId>hoverfly-java-junit5</artifactId>
-			<version>0.14.1</version>
+			<version>${hoverfly}</version>
 			<scope>test</scope>
 		</dependency>
 
@@ -338,6 +318,21 @@
 			<scope>test</scope>
 		</dependency>
 
+		<!--we need Murmur3Hash in a test, before 5.2 we had it from the old Elasticsearch dependency	-->
+		<dependency>
+			<groupId>commons-codec</groupId>
+			<artifactId>commons-codec</artifactId>
+			<version>1.15</version>
+			<scope>test</scope>
+		</dependency>
+
+		<dependency>
+			<groupId>com.tngtech.archunit</groupId>
+			<artifactId>archunit-junit5</artifactId>
+			<version>${archunit}</version>
+			<scope>test</scope>
+		</dependency>
+
 	</dependencies>
 
 	<build>
@@ -399,49 +394,24 @@
 							</systemPropertyVariables>
 						</configuration>
 					</execution>
-					<!-- execution to run the integration tests against Opensearch -->
-					<execution>
-						<id>integration-test-opensearch</id>
-						<phase>${mvn.integration-test-opensearch.goal}</phase>
-						<goals>
-							<goal>test</goal>
-						</goals>
-						<configuration>
-							<groups>integration-test</groups>
-							<systemPropertyVariables>
-								<sde.integration-test.environment>opensearch</sde.integration-test.environment>
-							</systemPropertyVariables>
-						</configuration>
-					</execution>
 				</executions>
 			</plugin>
-			<plugin>
-				<groupId>org.pitest</groupId>
-				<artifactId>pitest-maven</artifactId>
-				<version>1.5.2</version>
-				<dependencies>
-					<dependency>
-						<groupId>org.pitest</groupId>
-						<artifactId>pitest-junit5-plugin</artifactId>
-						<version>0.12</version>
-					</dependency>
-				</dependencies>
-				<configuration>
-					<excludedGroups>integration-test</excludedGroups>
-					<targetClasses>
-						<param>org.springframework.data.elasticsearch.core.geo.*</param>
-					</targetClasses>
-					<excludedMethods>toString</excludedMethods>
-				</configuration>
-			</plugin>
-
 			<plugin>
 				<groupId>org.apache.maven.plugins</groupId>
 				<artifactId>maven-assembly-plugin</artifactId>
 			</plugin>
 			<plugin>
-				<groupId>org.asciidoctor</groupId>
-				<artifactId>asciidoctor-maven-plugin</artifactId>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-compiler-plugin</artifactId>
+				<configuration>
+					<annotationProcessorPaths>
+						<path>
+							<groupId>org.apache.logging.log4j</groupId>
+							<artifactId>log4j-core</artifactId>
+							<version>${log4j}</version>
+						</path>
+					</annotationProcessorPaths>
+				</configuration>
 			</plugin>
 		</plugins>
 	</build>
@@ -476,19 +446,24 @@
 		</profile>
 
 		<profile>
-			<id>jdk13+</id>
-			<!-- on jDK13+, Blockhound needs this JVM flag set -->
-			<activation>
-				<jdk>[13,)</jdk>
-			</activation>
+			<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>org.apache.maven.plugins</groupId>
-						<artifactId>maven-surefire-plugin</artifactId>
-						<configuration>
-							<argLine>-XX:+AllowRedefinitionToAddDeleteMethods</argLine>
-						</configuration>
+						<groupId>org.antora</groupId>
+						<artifactId>antora-maven-plugin</artifactId>
 					</plugin>
 				</plugins>
 			</build>
@@ -497,22 +472,19 @@
 
 	<repositories>
 		<repository>
-			<id>spring-libs-snapshot</id>
-			<url>https://repo.spring.io/libs-snapshot</url>
+			<id>spring-snapshot</id>
+			<url>https://repo.spring.io/snapshot</url>
+			<snapshots>
+				<enabled>true</enabled>
+			</snapshots>
+			<releases>
+				<enabled>false</enabled>
+			</releases>
 		</repository>
-
 		<repository>
-			<id>local-maven-repo</id>
-			<url>file:///${project.basedir}/src/test/resources/local-maven-repo</url>
+			<id>spring-milestone</id>
+			<url>https://repo.spring.io/milestone</url>
 		</repository>
-		
 	</repositories>
 
-	<pluginRepositories>
-		<pluginRepository>
-			<id>spring-plugins-release</id>
-			<url>https://repo.spring.io/plugins-release</url>
-		</pluginRepository>
-	</pluginRepositories>
-
 </project>

src/main/antora/antora-playbook.yml

@@ -0,0 +1,40 @@
+# 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:
+    - require: '@springio/antora-extensions'
+      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.4.x, 3.3.x ]
+      start_path: src/main/antora
+asciidoc:
+  attributes:
+    hide-uri-scheme: '@'
+    tabs-sync-option: '@'
+  extensions:
+    - '@asciidoctor/tabs'
+    - '@springio/asciidoctor-extensions'
+    - '@springio/asciidoctor-extensions/javadoc-extension'
+  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.4.16/ui-bundle.zip
+    snapshot: true

src/main/antora/antora.yml

@@ -0,0 +1,17 @@
+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/
+    - run:
+        command: ./mvnw package -Pdistribute
+        local: true
+      scan:
+        dir: target/antora

src/main/antora/modules/ROOT/nav.adoc

@@ -0,0 +1,47 @@
+* 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:migration-guides/migration-guide-5.2-5.3.adoc[]
+*** xref:migration-guides/migration-guide-5.3-5.4.adoc[]
+*** xref:migration-guides/migration-guide-5.4-5.5.adoc[]
+*** xref:migration-guides/migration-guide-5.5-6.0.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[]
+
+* xref:attachment$api/java/index.html[Javadoc,role=link-external,window=_blank]
+* https://github.com/spring-projects/spring-data-commons/wiki[Wiki,role=link-external,window=_blank]

src/main/antora/modules/ROOT/pages/commons/upgrade.adoc

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

src/main/antora/modules/ROOT/pages/elasticsearch.adoc

@@ -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.

src/main/antora/modules/ROOT/pages/elasticsearch/auditing.adoc

@@ -1,7 +1,8 @@
 [[elasticsearch.auditing]]
-== Elasticsearch Auditing
+= Elasticsearch Auditing
 
-=== Preparing entities
+[[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<ID>` interface which is defined as follows:
 
@@ -9,7 +10,7 @@ In order for the auditing code to be able to decide whether an entity instance i
 ----
 package org.springframework.data.domain;
 
-import org.springframework.lang.Nullable;
+import org.jspecify.annotations.Nullable;
 
 public interface Persistable<ID> {
     @Nullable
@@ -54,7 +55,8 @@ public class Person implements Persistable<Long> {
 <.> 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.
 
-=== Activating auditing
+[[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:
 
@@ -79,5 +81,5 @@ class MyConfiguration {
 }
 ----
 
-If your code contains more than one `AuditorAware` bean for different types, you must provide the name of the bean to use as an argument to the `auditorAwareRef` parameter of the 
- `@EnableElasticsearchAuditing` annotation. 
+If your code contains more than one `AuditorAware` bean for different types, you must provide the name of the bean to use as an argument to the `auditorAwareRef` parameter of the
+ `@EnableElasticsearchAuditing` annotation.

src/main/antora/modules/ROOT/pages/elasticsearch/clients.adoc

@@ -0,0 +1,460 @@
+[[elasticsearch.clients]]
+= Elasticsearch Clients
+
+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 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].
+
+[[elasticsearch.clients.rest5client]]
+== Imperative Rest5Client
+
+To use the imperative (non-reactive) Rest5Client, a configuration bean must be configured like this:
+
+====
+[source,java]
+----
+import org.springframework.data.elasticsearch.client.elc.ElasticsearchConfiguration;
+
+@Configuration
+public class MyClientConfig extends ElasticsearchConfiguration {
+
+	@Override
+	public ClientConfiguration clientConfiguration() {
+		return ClientConfiguration.builder()           <.>
+			.connectedTo("localhost:9200")
+			.build();
+	}
+}
+----
+
+<.> for a detailed description of the builder methods see xref:elasticsearch/clients.adoc#elasticsearch.clients.configuration[Client Configuration]
+====
+
+The javadoc:org.springframework.data.elasticsearch.client.elc.ElasticsearchConfiguration[] class allows further configuration by overriding for example the `jsonpMapper()` or `transportOptions()` methods.
+
+
+The following beans can then be injected in other Spring components:
+
+====
+[source,java]
+----
+import org.springframework.beans.factory.annotation.Autowired;@Autowired
+ElasticsearchOperations operations;      <.>
+
+@Autowired
+ElasticsearchClient elasticsearchClient; <.>
+
+@Autowired
+Rest5Client rest5Client;                 <.>
+
+@Autowired
+JsonpMapper jsonpMapper;                 <.>
+----
+
+<.> an implementation of javadoc:org.springframework.data.elasticsearch.core.ElasticsearchOperations[]
+<.> the `co.elastic.clients.elasticsearch.ElasticsearchClient` that is used.
+<.> the low level `Rest5Client` from the Elasticsearch libraries
+<.> the `JsonpMapper` user by the Elasticsearch `Transport`
+====
+
+Basically one should just use the javadoc:org.springframework.data.elasticsearch.core.ElasticsearchOperations[] to interact with the Elasticsearch cluster.
+When using repositories, this instance is used under the hood as well.
+
+[[elasticsearch.clients.restclient]]
+== Deprecated Imperative RestClient
+
+To use the imperative (non-reactive) RestClient - deprecated since version 6 - , the following dependency needs to be added, adapt the correct version. The exclusion is needed in a Spring Boot application:
+====
+[source,xml]
+----
+        <dependency>
+            <groupId>org.elasticsearch.client</groupId>
+            <artifactId>elasticsearch-rest-client</artifactId>
+            <version>${elasticsearch-client.version}</version>
+            <exclusions>
+                <exclusion>
+                    <groupId>commons-logging</groupId>
+                    <artifactId>commons-logging</artifactId>
+                </exclusion>
+            </exclusions>
+        </dependency>
+
+----
+====
+
+The configuration bean must be configured like this:
+
+====
+[source,java]
+----
+import org.springframework.data.elasticsearch.client.elc.ElasticsearchLegacyRestClientConfiguration;
+
+@Configuration
+public class MyClientConfig extends ElasticsearchLegacyRestClientConfiguration {
+
+	@Override
+	public ClientConfiguration clientConfiguration() {
+		return ClientConfiguration.builder()           <.>
+			.connectedTo("localhost:9200")
+			.build();
+	}
+}
+----
+
+<.> for a detailed description of the builder methods see xref:elasticsearch/clients.adoc#elasticsearch.clients.configuration[Client Configuration]
+====
+
+The javadoc:org.springframework.data.elasticsearch.client.elc.ElasticsearchConfiguration[] class allows further configuration by overriding for example the `jsonpMapper()` or `transportOptions()` methods.
+
+
+The following beans can then be injected in other Spring components:
+
+====
+[source,java]
+----
+import org.springframework.beans.factory.annotation.Autowired;@Autowired
+ElasticsearchOperations operations;      <.>
+
+@Autowired
+ElasticsearchClient elasticsearchClient; <.>
+
+@Autowired
+RestClient restClient;                 <.>
+
+@Autowired
+JsonpMapper jsonpMapper;                 <.>
+----
+
+<.> an implementation of javadoc:org.springframework.data.elasticsearch.core.ElasticsearchOperations[]
+<.> the `co.elastic.clients.elasticsearch.ElasticsearchClient` that is used.
+<.> the low level `RestClient` from the Elasticsearch libraries
+<.> the `JsonpMapper` user by the Elasticsearch `Transport`
+====
+
+Basically one should just use the javadoc:org.springframework.data.elasticsearch.core.ElasticsearchOperations[] to interact with the Elasticsearch cluster.
+When using repositories, this instance is used under the hood as well.
+
+[[elasticsearch.clients.reactiverest5client]]
+== Reactive Rest5Client
+
+When working with the reactive stack, the configuration must be derived from a different class:
+
+====
+[source,java]
+----
+import org.springframework.data.elasticsearch.client.elc.ReactiveElasticsearchConfiguration;
+
+@Configuration
+public class MyClientConfig extends ReactiveElasticsearchConfiguration {
+
+	@Override
+	public ClientConfiguration clientConfiguration() {
+		return ClientConfiguration.builder()           <.>
+			.connectedTo("localhost:9200")
+			.build();
+	}
+}
+----
+
+<.> for a detailed description of the builder methods see xref:elasticsearch/clients.adoc#elasticsearch.clients.configuration[Client Configuration]
+====
+
+The javadoc:org.springframework.data.elasticsearch.client.elc.ReactiveElasticsearchConfiguration[] class allows further configuration by overriding for example the `jsonpMapper()` or `transportOptions()` methods.
+
+The following beans can then be injected in other Spring components:
+
+====
+[source,java]
+----
+@Autowired
+ReactiveElasticsearchOperations operations;      <.>
+
+@Autowired
+ReactiveElasticsearchClient elasticsearchClient; <.>
+
+@Autowired
+Rest5Client rest5Client;                           <.>
+
+@Autowired
+JsonpMapper jsonpMapper;                         <.>
+----
+
+the following can be injected:
+
+<.> an implementation of javadoc:org.springframework.data.elasticsearch.core.ReactiveElasticsearchOperations[]
+<.> the `org.springframework.data.elasticsearch.client.elc.ReactiveElasticsearchClient` that is used.
+This is a reactive implementation based on the Elasticsearch client implementation.
+<.> the low level `RestClient` from the Elasticsearch libraries
+<.> the `JsonpMapper` user by the Elasticsearch `Transport`
+====
+
+Basically one should just use the javadoc:org.springframework.data.elasticsearch.core.ReactiveElasticsearchOperations[] to interact with the Elasticsearch cluster.
+When using repositories, this instance is used under the hood as well.
+
+[[elasticsearch.clients.reactiverestclient]]
+== Deprecated Reactive RestClient
+
+See the section above for the imperative code to use the deprecated RestClient for the necessary dependencies to include.
+
+When working with the reactive stack, the configuration must be derived from a different class:
+
+====
+[source,java]
+----
+import org.springframework.data.elasticsearch.client.elc.ReactiveElasticsearchLegacyRestClientConfiguration;
+
+@Configuration
+public class MyClientConfig extends ReactiveElasticsearchLegacyRestClientConfiguration {
+
+	@Override
+	public ClientConfiguration clientConfiguration() {
+		return ClientConfiguration.builder()           <.>
+			.connectedTo("localhost:9200")
+			.build();
+	}
+}
+----
+
+<.> for a detailed description of the builder methods see xref:elasticsearch/clients.adoc#elasticsearch.clients.configuration[Client Configuration]
+====
+
+The javadoc:org.springframework.data.elasticsearch.client.elc.ReactiveElasticsearchConfiguration[] class allows further configuration by overriding for example the `jsonpMapper()` or `transportOptions()` methods.
+
+The following beans can then be injected in other Spring components:
+
+====
+[source,java]
+----
+@Autowired
+ReactiveElasticsearchOperations operations;      <.>
+
+@Autowired
+ReactiveElasticsearchClient elasticsearchClient; <.>
+
+@Autowired
+RestClient restClient;                           <.>
+
+@Autowired
+JsonpMapper jsonpMapper;                         <.>
+----
+
+the following can be injected:
+
+<.> an implementation of javadoc:org.springframework.data.elasticsearch.core.ReactiveElasticsearchOperations[]
+<.> the `org.springframework.data.elasticsearch.client.elc.ReactiveElasticsearchClient` that is used.
+This is a reactive implementation based on the Elasticsearch client implementation.
+<.> the low level `RestClient` from the Elasticsearch libraries
+<.> the `JsonpMapper` user by the Elasticsearch `Transport`
+====
+
+Basically one should just use the javadoc:org.springframework.data.elasticsearch.core.ReactiveElasticsearchOperations[] to interact with the Elasticsearch cluster.
+When using repositories, this instance is used under the hood as well.
+
+[[elasticsearch.clients.configuration]]
+== Client Configuration
+
+Client behaviour can be changed via the javadoc:org.springframework.data.elasticsearch.client.ClientConfiguration[] that allows to set options for SSL, connect and socket timeouts, headers and other parameters.
+
+.Client Configuration
+====
+[source,java]
+----
+import org.springframework.data.elasticsearch.client.ClientConfiguration;
+import org.springframework.data.elasticsearch.support.HttpHeaders;
+
+import static org.springframework.data.elasticsearch.client.elc.ElasticsearchClients.*;
+
+HttpHeaders httpHeaders = new HttpHeaders();
+httpHeaders.add("some-header", "on every request")                      <.>
+
+ClientConfiguration clientConfiguration = ClientConfiguration.builder()
+  .connectedTo("localhost:9200", "localhost:9291")                      <.>
+  .usingSsl()                                                           <.>
+  .withProxy("localhost:8888")                                          <.>
+  .withPathPrefix("ela")                                                <.>
+  .withConnectTimeout(Duration.ofSeconds(5))                            <.>
+  .withSocketTimeout(Duration.ofSeconds(3))                             <.>
+  .withDefaultHeaders(defaultHeaders)                                   <.>
+  .withBasicAuth(username, password)                                    <.>
+  .withHeaders(() -> {                                                  <.>
+    HttpHeaders headers = new HttpHeaders();
+    headers.add("currentTime", LocalDateTime.now().format(DateTimeFormatter.ISO_LOCAL_DATE_TIME));
+    return headers;
+  })
+  .withClientConfigurer(                                                <.>
+    ElasticsearchHttpClientConfigurationCallback.from(clientBuilder -> {
+  	  // ...
+      return clientBuilder;
+  	}))
+  . // ... other options
+  .build();
+
+----
+
+<.> Define default headers, if they need to be customized
+<.> 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 set a proxy.
+<.> Optionally set a path prefix, mostly used when different clusters a behind some reverse proxy.
+<.> Set the connection timeout.
+<.> Set the socket timeout.
+<.> Optionally set headers.
+<.> 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 function to configure the created client (see xref:elasticsearch/clients.adoc#elasticsearch.clients.configuration.callbacks[Client configuration callbacks]), can be added multiple times.
+====
+
+IMPORTANT: Adding a Header supplier as shown in above example allows to inject headers that may change over the time, like authentication JWT tokens.
+If this is used in the reactive setup, the supplier function *must not* block!
+
+[[elasticsearch.clients.configuration.callbacks]]
+=== Client configuration callbacks
+
+The javadoc:org.springframework.data.elasticsearch.client.ClientConfiguration[] class offers the most common parameters to configure the client.
+In the case this is not enough, the user can add callback functions by using the `withClientConfigurer(ClientConfigurationCallback<?>)` method.
+
+The following callbacks are provided:
+
+[[elasticsearch.clients.configuration.callbacks.rest5]]
+==== Configuration of the low level Elasticsearch `Rest5Client`:
+
+This callback provides a `org.elasticsearch.client.RestClientBuilder` that can be used to configure the Elasticsearch
+`RestClient`:
+====
+[source,java]
+----
+ClientConfiguration.builder()
+    .connectedTo("localhost:9200", "localhost:9291")
+    .withClientConfigurer(Rest5Clients.ElasticsearchRest5ClientConfigurationCallback.from(restClientBuilder -> {
+        // configure the Elasticsearch Rest5Client
+        return restClientBuilder;
+    }))
+    .build();
+----
+====
+[[elasticsearch.clients.configuration.callbacks.rest]]
+==== Configuration of the deprecated low level Elasticsearch `RestClient`:
+
+This callback provides a `org.elasticsearch.client.RestClientBuilder` that can be used to configure the Elasticsearch
+`RestClient`:
+====
+[source,java]
+----
+ClientConfiguration.builder()
+    .connectedTo("localhost:9200", "localhost:9291")
+    .withClientConfigurer(RestClients.ElasticsearchRestClientConfigurationCallback.from(restClientBuilder -> {
+        // configure the Elasticsearch RestClient
+        return restClientBuilder;
+    }))
+    .build();
+----
+====
+
+[[elasticsearch.clients.configurationcallbacks.httpasync5]]
+==== Configuration of the HttpAsyncClient used by the low level Elasticsearch `Rest5Client`:
+
+This callback provides a `org.apache.hc.client5.http.impl.async.HttpAsyncClientBuilder` to configure the HttpClient that is
+used by the `Rest5Client`.
+
+====
+[source,java]
+----
+ClientConfiguration.builder()
+    .connectedTo("localhost:9200", "localhost:9291")
+    .withClientConfigurer(Rest5Clients.ElasticsearchHttpClientConfigurationCallback.from(httpAsyncClientBuilder -> {
+        // configure the HttpAsyncClient
+        return httpAsyncClientBuilder;
+    }))
+    .build();
+----
+====
+
+[[elasticsearch.clients.configurationcallbacks.httpasync]]
+==== Configuration of the HttpAsyncClient used by the deprecated low level Elasticsearch `RestClient`:
+
+This callback provides a `org.apache.http.impl.nio.client.HttpAsyncClientBuilder` to configure the HttpClient that is
+used by the `RestClient`.
+
+====
+[source,java]
+----
+ClientConfiguration.builder()
+    .connectedTo("localhost:9200", "localhost:9291")
+    .withClientConfigurer(RestClients.ElasticsearchHttpClientConfigurationCallback.from(httpAsyncClientBuilder -> {
+        // configure the HttpAsyncClient
+        return httpAsyncClientBuilder;
+    }))
+    .build();
+----
+====
+
+[[elasticsearch.clients.configurationcallbacks.connectionconfig]]
+==== Configuration of the ConnectionConfig used by the low level Elasticsearch `Rest5Client`:
+
+This callback provides a `org.apache.hc.client5.http.config.ConnectionConfig` to configure the connection that is
+used by the `Rest5Client`.
+
+====
+[source,java]
+----
+ClientConfiguration.builder()
+    .connectedTo("localhost:9200", "localhost:9291")
+    .withClientConfigurer(Rest5Clients.ElasticsearchConnectionConfigurationCallback.from(connectionConfigBuilder -> {
+        // configure the connection
+        return connectionConfigBuilder;
+    }))
+    .build();
+----
+====
+
+[[elasticsearch.clients.configurationcallbacks.connectioncmanager]]
+==== Configuration of the ConnectionManager used by the low level Elasticsearch `Rest5Client`:
+
+This callback provides a `org.apache.hc.client5.http.impl.nio.PoolingAsyncClientConnectionManagerBuilder` to configure the connection manager that is
+used by the `Rest5Client`.
+
+====
+[source,java]
+----
+ClientConfiguration.builder()
+    .connectedTo("localhost:9200", "localhost:9291")
+    .withClientConfigurer(Rest5Clients.ElasticsearchConnectionManagerCallback.from(connectionManagerBuilder -> {
+        // configure the connection manager
+        return connectionManagerBuilder;
+    }))
+    .build();
+----
+====
+
+[[elasticsearch.clients.configurationcallbacks.requestconfig]]
+==== Configuration of the RequestConfig used by the low level Elasticsearch `Rest5Client`:
+
+This callback provides a `org.apache.hc.client5.http.config.RequestConfig` to configure the RequestConfig that is
+used by the `Rest5Client`.
+
+====
+[source,java]
+----
+ClientConfiguration.builder()
+    .connectedTo("localhost:9200", "localhost:9291")
+    .withClientConfigurer(Rest5Clients.ElasticsearchRequestConfigCallback.from(requestConfigBuilder -> {
+        // configure the request config
+        return requestConfigBuilder;
+    }))
+    .build();
+----
+====
+
+[[elasticsearch.clients.logging]]
+== Client Logging
+
+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.
+This can be enabled in the Elasticsearch client by setting 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)
+
+.Enable transport layer logging
+[source,xml]
+----
+<logger name="tracer" level="trace"/>
+----

src/main/antora/modules/ROOT/pages/elasticsearch/elasticsearch-new.adoc

@@ -0,0 +1,122 @@
+[[new-features]]
+= What's new
+
+[[new-features.6-0-0]]
+== New in Spring Data Elasticsearch 6.0
+
+* Upgarde to Spring 7
+* Switch to jspecify nullability annotations
+* Upgrade to Elasticsearch 9.0.4
+* Use the new Elasticsearch Rest5Client as default
+
+
+[[new-features.5-5-0]]
+== New in Spring Data Elasticsearch 5.5
+
+* Upgrade to Elasticsearch 8.18.1.
+* Add support for the `@SearchTemplateQuery` annotation on repository methods.
+* Scripted field properties of type collection can be populated from scripts returning arrays.
+
+[[new-features.5-4-0]]
+== New in Spring Data Elasticsearch 5.4
+
+* Upgrade to Elasticsearch 8.15.3.
+* Allow to customize the mapped type name for `@InnerField` and `@Field` annotations.
+* Support for Elasticsearch SQL.
+* Add support for retrieving request executionDuration.
+
+[[new-features.5-3-0]]
+== New in Spring Data Elasticsearch 5.3
+
+* Upgrade to Elasticsearch 8.13.2.
+* Add support for highlight queries in highlighting.
+* Add shard statistics to the `SearchHit` class.
+* Add support for multi search template API.
+* Add support for SpEL in @Query.
+* Add support for field aliases in the index mapping.
+* Add support for has_child and has_parent queries.
+
+[[new-features.5-2-0]]
+== New in Spring Data Elasticsearch 5.2
+
+* Upgrade to Elasticsearch 8.11.1
+* The `JsonpMapper` for Elasticsearch is now configurable and provided as bean.
+* Improved AOT runtime hints for Elasticsearch client library classes.
+* Add Kotlin extensions and repository coroutine support.
+* Introducing `VersionConflictException` class thrown in case thatElasticsearch reports an 409 error with a version conflict.
+* Enable MultiField annotation on property getter
+* Support nested sort option
+* Improved scripted und runtime field support
+* Improved refresh policy support
+
+[[new-features.5-1-0]]
+== New in Spring Data Elasticsearch 5.1
+
+* Upgrade to Elasticsearch 8.7.1
+* Allow specification of the TLS certificate when connecting to an Elasticsearch 8 cluster
+
+[[new-features.5-0-0]]
+== New in Spring Data Elasticsearch 5.0
+
+* Upgrade to Java 17 baseline
+* Upgrade to Spring Framework 6
+* Upgrade to Elasticsearch 8.5.0
+* Use the new Elasticsearch client library
+
+[[new-features.4-4-0]]
+== New in Spring Data Elasticsearch 4.4
+
+* Introduction of new imperative and reactive clients using the classes from the new Elasticsearch Java client
+* Upgrade to Elasticsearch 7.17.3.
+
+[[new-features.4-3-0]]
+== New in Spring Data Elasticsearch 4.3
+
+* Upgrade to Elasticsearch 7.15.2.
+* Allow runtime_fields to be defined in the index mapping.
+* Add native support for range field types by using a range object.
+* Add repository search for nullable or empty properties.
+* Enable custom converters for single fields.
+* Supply a custom `Sort.Order` providing Elasticsearch specific parameters.
+
+[[new-features.4-2-0]]
+== New in Spring Data Elasticsearch 4.2
+
+* Upgrade to Elasticsearch 7.10.0.
+* Support for custom routing values
+
+[[new-features.4-1-0]]
+== New in Spring Data Elasticsearch 4.1
+
+* Uses Spring 5.3.
+* Upgrade to Elasticsearch 7.9.3.
+* Improved API for alias management.
+* Introduction of `ReactiveIndexOperations` for index management.
+* Index templates support.
+* Support for Geo-shape data with GeoJson.
+
+[[new-features.4-0-0]]
+== New in Spring Data Elasticsearch 4.0
+
+* Uses Spring 5.2.
+* Upgrade to Elasticsearch 7.6.2.
+* Deprecation of `TransportClient` usage.
+* Implements most of the mapping-types available for the index mappings.
+* 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.
+* 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 `SearchPage<T>` class to represent a paged result containing a `SearchHits<T>` instance.
+* Introduction of the `GeoDistanceOrder` class to be able to create sorting by geographical distance
+* Implementation of Auditing Support
+* Implementation of lifecycle entity callbacks
+
+[[new-features.3-2-0]]
+== New in Spring Data Elasticsearch 3.2
+
+* Secured Elasticsearch cluster support with Basic Authentication and SSL transport.
+* Upgrade to Elasticsearch 6.8.1.
+* Reactive programming support with xref:elasticsearch/repositories/reactive-elasticsearch-repositories.adoc[Reactive Elasticsearch Repositories] and xref:.
+* 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`.
+* Support for Delete by Query.

src/main/antora/modules/ROOT/pages/elasticsearch/entity-callbacks.adoc

@@ -1,5 +1,7 @@
+include::{commons}@data-commons::page$entity-callbacks.adoc[]
+
 [[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:
 

src/main/antora/modules/ROOT/pages/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.
@@ -51,7 +52,7 @@ public class Statement {
         return routing;
     }
 
-    public void setRouting(Routing routing) {
+    public void setRouting(String routing) {
         this.routing = routing;
     }
 
@@ -111,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
 <.> 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.
@@ -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:
@@ -197,7 +199,7 @@ void init() {
     repository.save(
         Statement.builder()
             .withText("+1 for the sun")
-            ,withRouting(savedWeather.getId())
+            .withRouting(savedWeather.getId())
             .withRelation(new JoinField<>("vote", sunnyAnswer.getId()))         <5>
             .build());
 }
@@ -206,12 +208,13 @@ void init() {
 <2> the first answer to the question
 <3> the second answer
 <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]]
 ==  Retrieving data
 
-Currently native search 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:
 
@@ -219,11 +222,18 @@ The following code shows as an example how to retrieve all entries that have a _
 [source,java]
 ----
 SearchHits<Statement> hasVotes() {
-    NativeSearchQuery query = new NativeSearchQueryBuilder()
-        .withQuery(hasChildQuery("vote", matchAllQuery(), ScoreMode.None))
-        .build();
 
-    return operations.search(query, Statement.class);
+	Query query = NativeQuery.builder()
+		.withQuery(co.elastic.clients.elasticsearch._types.query_dsl.Query.of(qb -> qb
+			.hasChild(hc -> hc
+				.type("answer")
+				.queryName("vote")
+				.query(matchAllQueryAsQuery())
+				.scoreMode(ChildScoreMode.None)
+			)))
+		.build();
+
+	return operations.search(query, Statement.class);
 }
 ----
 ====

src/main/antora/modules/ROOT/pages/elasticsearch/misc.adoc

@@ -0,0 +1,453 @@
+[[elasticsearch.misc]]
+= Miscellaneous Elasticsearch Operation Support
+
+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 xref:repositories/custom-implementations.adoc[] .
+
+[[elasticsearc.misc.index.settings]]
+== Index settings
+
+When creating Elasticsearch indices with Spring Data Elasticsearch different index settings can be defined by using the `@Setting` annotation.
+The following arguments are available:
+
+* `useServerConfiguration` does not send any settings parameters, so the Elasticsearch server configuration determines them.
+* `settingPath` refers to a JSON file defining the settings that must be resolvable in the classpath
+* `shards` the number of shards to use, defaults to _1_
+* `replicas` the number of replicas, defaults to _1_
+* `refreshIntervall`, defaults to _"1s"_
+* `indexStoreType`, defaults to _"fs"_
+
+It is as well possible to define https://www.elastic.co/guide/en/elasticsearch/reference/7.11/index-modules-index-sorting.html[index sorting] (check the linked Elasticsearch documentation for the possible field types and values):
+
+====
+[source,java]
+----
+@Document(indexName = "entities")
+@Setting(
+  sortFields = { "secondField", "firstField" },                                  <.>
+  sortModes = { Setting.SortMode.max, Setting.SortMode.min },                    <.>
+  sortOrders = { Setting.SortOrder.desc, Setting.SortOrder.asc },
+  sortMissingValues = { Setting.SortMissing._last, Setting.SortMissing._first })
+class Entity {
+    @Nullable
+    @Id private String id;
+
+    @Nullable
+    @Field(name = "first_field", type = FieldType.Keyword)
+    private String firstField;
+
+    @Nullable @Field(name = "second_field", type = FieldType.Keyword)
+    private String secondField;
+
+    // getter and setter...
+}
+----
+
+<.> when defining sort fields, use the name of the Java property (_firstField_), not the name that might be defined for Elasticsearch (_first_field_)
+<.> `sortModes`, `sortOrders` and `sortMissingValues` are optional, but if they are set, the number of entries must match the number of `sortFields` elements
+====
+
+[[elasticsearch.misc.mappings]]
+== Index Mapping
+
+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.
+This annotation has the following properties:
+
+* `mappingPath` a classpath resource in JSON format; if this is not empty it is used as the mapping, no other mapping processing is done.
+* `enabled`  when set to false, this flag is written to the mapping and no further processing is done.
+* `dateDetection` and `numericDetection` set the corresponding properties in the mapping when not set to `DEFAULT`.
+* `dynamicDateFormats` when this String array is not empty, it defines the date formats used for automatic date detection.
+* `runtimeFieldsPath` a classpath resource in JSON format containing the definition of runtime fields which is written to the index mappings, for example:
+
+====
+[source,json]
+----
+{
+  "day_of_week": {
+    "type": "keyword",
+    "script": {
+      "source": "emit(doc['@timestamp'].value.dayOfWeekEnum.getDisplayName(TextStyle.FULL, Locale.ROOT))"
+    }
+  }
+}
+----
+====
+
+[[elasticsearch.misc.filter]]
+== Filter Builder
+
+Filter Builder improves query speed.
+
+====
+[source,java]
+----
+private ElasticsearchOperations operations;
+
+IndexCoordinates index = IndexCoordinates.of("sample-index");
+
+Query query = NativeQuery.builder()
+	.withQuery(q -> q
+		.matchAll(ma -> ma))
+	.withFilter( q -> q
+		.bool(b -> b
+			.must(m -> m
+				.term(t -> t
+					.field("id")
+					.value(documentId))
+			)))
+	.build();
+
+SearchHits<SampleEntity> sampleEntities = operations.search(query, SampleEntity.class, index);
+----
+====
+
+[[elasticsearch.scroll]]
+== Using Scroll For Big Result Set
+
+Elasticsearch has a scroll API for getting big result set in chunks.
+This is internally used by Spring Data Elasticsearch to provide the implementations of the `<T> SearchHitsIterator<T> SearchOperations.searchForStream(Query query, Class<T> clazz, IndexCoordinates index)` method.
+
+====
+[source,java]
+----
+IndexCoordinates index = IndexCoordinates.of("sample-index");
+
+Query searchQuery = NativeQuery.builder()
+    .withQuery(q -> q
+        .matchAll(ma -> ma))
+    .withFields("message")
+    .withPageable(PageRequest.of(0, 10))
+    .build();
+
+SearchHitsIterator<SampleEntity> stream = elasticsearchOperations.searchForStream(searchQuery, SampleEntity.class,
+index);
+
+List<SampleEntity> sampleEntities = new ArrayList<>();
+while (stream.hasNext()) {
+  sampleEntities.add(stream.next());
+}
+
+stream.close();
+----
+====
+
+There are no methods in the `SearchOperations` API to access the scroll id, if it should be necessary to access this, the following methods of the `AbstractElasticsearchTemplate` can be used (this is the base implementation for the different `ElasticsearchOperations` implementations):
+
+====
+[source,java]
+----
+
+@Autowired ElasticsearchOperations operations;
+
+AbstractElasticsearchTemplate template = (AbstractElasticsearchTemplate)operations;
+
+IndexCoordinates index = IndexCoordinates.of("sample-index");
+
+Query query = NativeQuery.builder()
+    .withQuery(q -> q
+        .matchAll(ma -> ma))
+    .withFields("message")
+    .withPageable(PageRequest.of(0, 10))
+    .build();
+
+SearchScrollHits<SampleEntity> scroll = template.searchScrollStart(1000, query, SampleEntity.class, index);
+
+String scrollId = scroll.getScrollId();
+List<SampleEntity> sampleEntities = new ArrayList<>();
+while (scroll.hasSearchHits()) {
+  sampleEntities.addAll(scroll.getSearchHits());
+  scrollId = scroll.getScrollId();
+  scroll = template.searchScrollContinue(scrollId, 1000, SampleEntity.class);
+}
+template.searchScrollClear(scrollId);
+----
+====
+
+To use the Scroll API with repository methods, the return type must defined as `Stream` in the Elasticsearch Repository.
+The implementation of the method will then use the scroll methods from the ElasticsearchTemplate.
+
+====
+[source,java]
+----
+interface SampleEntityRepository extends Repository<SampleEntity, String> {
+
+    Stream<SampleEntity> findBy();
+
+}
+----
+====
+
+[[elasticsearch.misc.sorts]]
+== Sort options
+
+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).
+
+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.
+
+If the class to be retrieved has a `GeoPoint` property named _location_, the following `Sort` would sort the results by distance to the given point:
+
+====
+[source,java]
+----
+Sort.by(new GeoDistanceOrder("location", new GeoPoint(48.137154, 11.5761247)))
+----
+====
+
+[[elasticsearch.misc.runtime-fields]]
+== Runtime Fields
+
+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).
+To use this approach in Spring Data Elasticsearch the user must provide a JSON file that contains the corresponding definition, for example:
+
+.runtime-fields.json
+====
+[source,json]
+----
+{
+  "day_of_week": {
+    "type": "keyword",
+    "script": {
+      "source": "emit(doc['@timestamp'].value.dayOfWeekEnum.getDisplayName(TextStyle.FULL, Locale.ROOT))"
+    }
+  }
+}
+----
+====
+
+The path to this JSON file, which must be present on the classpath, must then be set in the `@Mapping` annotation of the entity:
+
+====
+[source,java]
+----
+@Document(indexName = "runtime-fields")
+@Mapping(runtimeFieldsPath = "/runtime-fields.json")
+public class RuntimeFieldEntity {
+	// properties, getter, setter,...
+}
+
+----
+====
+
+[[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).
+The following code example shows how to do this with Spring Data Elasticsearch :
+
+The entity used is a simple object that has a `price` property:
+
+====
+[source,java]
+----
+@Document(indexName = "some_index_name")
+public class SomethingToBuy {
+
+	private @Id @Nullable String id;
+	@Nullable @Field(type = FieldType.Text) private String description;
+	@Nullable @Field(type = FieldType.Double) private Double price;
+
+	// getter and setter
+}
+
+----
+====
+
+The following query uses a runtime field that calculates a `priceWithTax` value by adding 19% to the price and uses this value in the search query to find all entities where `priceWithTax` is higher or equal than a given value:
+
+====
+[source,java]
+----
+RuntimeField runtimeField = new RuntimeField("priceWithTax", "double", "emit(doc['price'].value * 1.19)");
+Query query = new CriteriaQuery(new Criteria("priceWithTax").greaterThanEqual(16.5));
+query.addRuntimeField(runtimeField);
+
+SearchHits<SomethingToBuy> searchHits = operations.search(query, SomethingToBuy.class);
+----
+====
+
+This works with every implementation of the `Query` interface.
+
+[[elasticsearch.misc.point-in-time]]
+== Point In Time (PIT) API
+
+`ElasticsearchOperations` supports the point in time API of Elasticsearch (see https://www.elastic.co/guide/en/elasticsearch/reference/8.3/point-in-time-api.html).
+The following code snippet shows how to use this feature with a fictional `Person` class:
+
+====
+[source,java]
+----
+ElasticsearchOperations operations; // autowired
+Duration tenSeconds = Duration.ofSeconds(10);
+
+String pit = operations.openPointInTime(IndexCoordinates.of("person"), tenSeconds); <.>
+
+// create query for the pit
+Query query1 = new CriteriaQueryBuilder(Criteria.where("lastName").is("Smith"))
+    .withPointInTime(new Query.PointInTime(pit, tenSeconds))                        <.>
+    .build();
+SearchHits<Person> searchHits1 = operations.search(query1, Person.class);
+// do something with the data
+
+// create 2nd query for the pit, use the id returned in the previous result
+Query query2 = new CriteriaQueryBuilder(Criteria.where("lastName").is("Miller"))
+    .withPointInTime(
+        new Query.PointInTime(searchHits1.getPointInTimeId(), tenSeconds))          <.>
+    .build();
+SearchHits<Person> searchHits2 = operations.search(query2, Person.class);
+// do something with the data
+
+operations.closePointInTime(searchHits2.getPointInTimeId());                        <.>
+
+----
+
+<.> create a point in time for an index (can be multiple names) and a keep-alive duration and retrieve its id
+<.> pass that id into the query to search together with the next keep-alive value
+<.> for the next query, use the id returned from the previous search
+<.> when done, close the point in time using the last returned id
+====
+
+[[elasticsearch.misc.searchtemplates]]
+== Search Template support
+
+Use of the search template API is supported.
+To use this, it first is necessary to create a stored script.
+The `ElasticsearchOperations` interface extends `ScriptOperations` which provides the necessary functions.
+The example used here assumes that we have `Person` entity with a property named `firstName`.
+A search template script can be saved like this:
+
+====
+[source,java]
+----
+import org.springframework.data.elasticsearch.core.ElasticsearchOperations;
+import org.springframework.data.elasticsearch.core.script.Script;
+
+operations.putScript(                            <.>
+  Script.builder()
+    .withId("person-firstname")                  <.>
+    .withLanguage("mustache")                    <.>
+    .withSource("""                              <.>
+      {
+        "query": {
+          "bool": {
+            "must": [
+              {
+                "match": {
+                  "firstName": "{{firstName}}"   <.>
+                }
+              }
+            ]
+          }
+        },
+        "from": "{{from}}",                      <.>
+        "size": "{{size}}"                       <.>
+      }
+      """)
+    .build()
+);
+----
+
+<.> Use the `putScript()` method to store a search template script
+<.> The name / id of the script
+<.> Scripts that are used in search templates must be in the _mustache_ language.
+<.> The script source
+<.> The search parameter in the script
+<.> Paging request offset
+<.> Paging request size
+====
+
+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.
+
+NOTE: Although `SearchTemplateQuery` is an implementation of the `Query` interface, not all of the functionality provided by the base class is available for a `SearchTemplateQuery` like setting a `Pageable` or a `Sort`. Values for this functionality must be added to the stored script like shown in the following example for paging parameters. If these values are set on the `Query` object, they will be ignored.
+
+In the following code, we will add a call using a search template query to a custom repository implementation (see
+xref:repositories/custom-implementations.adoc[]) as an example how this can be integrated into a repository call.
+
+We first define the custom repository fragment interface:
+
+====
+[source,java]
+----
+interface PersonCustomRepository {
+	SearchPage<Person> findByFirstNameWithSearchTemplate(String firstName, Pageable pageable);
+}
+----
+====
+
+The implementation of this repository fragment looks like this:
+
+====
+[source,java]
+----
+public class PersonCustomRepositoryImpl implements PersonCustomRepository {
+
+  private final ElasticsearchOperations operations;
+
+  public PersonCustomRepositoryImpl(ElasticsearchOperations operations) {
+    this.operations = operations;
+  }
+
+  @Override
+  public SearchPage<Person> findByFirstNameWithSearchTemplate(String firstName, Pageable pageable) {
+
+    var query = SearchTemplateQuery.builder()                               <.>
+      .withId("person-firstname")                                           <.>
+      .withParams(
+        Map.of(                                                             <.>
+          "firstName", firstName,
+          "from", pageable.getOffset(),
+          "size", pageable.getPageSize()
+          )
+      )
+      .build();
+
+    SearchHits<Person> searchHits = operations.search(query, Person.class); <.>
+
+    return SearchHitSupport.searchPageFor(searchHits, pageable);
+  }
+}
+----
+
+<.> Create a `SearchTemplateQuery`
+<.> Provide the id of the search template
+<.> The parameters are passed in a `Map<String,Object>`
+<.> Do the search in the same way as with the other query types.
+====
+
+[[elasticsearch.misc.nested-sort]]
+== Nested sort
+Spring Data Elasticsearch supports sorting within nested objects (https://www.elastic.co/guide/en/elasticsearch/reference/8.9/sort-search-results.html#nested-sorting)
+
+The following example, taken from the `org.springframework.data.elasticsearch.core.query.sort.NestedSortIntegrationTests` class, shows how to define the nested sort.
+
+====
+[source,java]
+----
+var filter = StringQuery.builder("""
+	{ "term": {"movies.actors.sex": "m"} }
+	""").build();
+var order = new org.springframework.data.elasticsearch.core.query.Order(Sort.Direction.DESC,
+	"movies.actors.yearOfBirth")
+	.withNested(
+		Nested.builder("movies")
+			.withNested(
+				Nested.builder("movies.actors")
+					.withFilter(filter)
+					.build())
+			.build());
+
+var query = Query.findAll().addSort(Sort.by(order));
+
+----
+====
+
+About the filter query: It is not possible to use a `CriteriaQuery` here, as this query would be converted into a Elasticsearch nested query which does not work in the filter context. So only `StringQuery` or `NativeQuery` can be used here. When using one of these, like the term query above, the Elasticsearch field names must be used, so take care, when these are redefined with the `@Field(name="...")` definition.
+
+For the definition of the order path and the nested paths, the Java entity property names should be used.

src/main/antora/modules/ROOT/pages/elasticsearch/object-mapping.adoc

@@ -2,19 +2,8 @@
 = Elasticsearch Object Mapping
 
 Spring Data Elasticsearch Object Mapping is the process that maps a Java object - the domain entity - into the JSON representation that is stored in Elasticsearch and back.
-
-Earlier versions of Spring Data Elasticsearch used a Jackson based conversion, Spring Data Elasticsearch 3.2.x introduced the <<elasticsearch.mapping.meta-model>>.
-As of version 4.0 only the Meta Object Mapping is used, the Jackson based mapper is not available anymore and the `MappingElasticsearchConverter` is used.
-
-The main reasons for the removal of the Jackson based mapper are:
-
-* Custom mappings of fields needed to be done with annotations like `@JsonFormat` or `@JsonInclude`.
-This often caused problems when the same object was used in different JSON based datastores or sent over a JSON based API.
-* Custom field types and formats also need to be stored into the Elasticsearch index mappings.
-The Jackson based annotations did not fully provide all the information that is necessary to represent the types of Elasticsearch.
-* Fields must be mapped not only when converting from and to entities, but also in query argument, returned data and on other places.
-
-Using the `MappingElasticsearchConverter` now covers all these cases.
+The class that is internally used for this mapping is the
+`MappingElasticsearchConverter`.
 
 [[elasticsearch.mapping.meta-model]]
 == Meta Model Object Mapping
@@ -31,17 +20,16 @@ The metadata is taken from the entity's properties which can be annotated.
 The following annotations are available:
 
 * `@Document`: Applied at the class level to indicate this class is a candidate for mapping to the database.
-The most important attributes are:
+The most important attributes are (check the API documentation for the complete list of attributes):
 ** `indexName`: the name of the index to store this entity in.
 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.
 Default value is _true_.
-See <<elasticsearch.repositories.autocreation>>
-** `versionType`: Configuration of version management.
-Default value is _EXTERNAL_.
+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.
-* `@Transient`: By default all fields are mapped to the document when it is stored or retrieved, this annotation excludes the field.
+* `@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.
 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):
@@ -50,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].
 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 <<elasticsearch.mapping.meta-model.date-formats>>.
-** `pattern`: One or more custom date formats, see the next section <<elasticsearch.mapping.meta-model.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 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_.
 ** `analyzer`, `searchAnalyzer`, `normalizer` for specifying custom analyzers and normalizer.
 * `@GeoPoint`: Marks a field as _geo_point_ datatype.
@@ -61,7 +49,20 @@ 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.read-write]]
+==== Controlling which properties are written to and read from Elasticsearch
+
+This section details the annotations that define if the value of a property is written to or read from Elasticsearch.
+
+`@Transient`: A property annotated with this annotation will not be written to the mapping, it's value will not be sent to Elasticsearch and when documents are returned from Elasticsearch, this property will not be set in the resulting entity.
+
+`@ReadOnlyProperty`: A property with this annotation will not have its value written to Elasticsearch, but when returning data, the property will be filled with the value returned in the document from Elasticsearch.
+One use case for this are runtime fields defined in the index mapping.
+
+`@WriteOnlyProperty`: A property with this annotation will have its value stored in Elasticsearch but will not be set with any value when reading document.
+This can be used for example for synthesized fields which should go into the Elasticsearch index but are not used elsewhere.
+
+[[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.
@@ -70,7 +71,7 @@ This paragraph describes the use of
 
 There are two attributes of the `@Field` annotation that define which date format information is written to the mapping (also see https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-date-format.html#built-in-date-formats[Elasticsearch Built In Formats] and https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-date-format.html#custom-date-formats[Elasticsearch Custom Date Formats])
 
-The `format` attributes is used to define at least one of the predefined formats.
+The `format` attribute is used to define at least one of the predefined formats.
 If it is not defined, then a default value of __date_optional_time_ and _epoch_millis_ is used.
 
 The `pattern` attribute can be used to add additional custom format strings.
@@ -103,6 +104,9 @@ 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].
 
+Check the code of the `org.springframework.data.elasticsearch.annotations.DateFormat` enum for a complete list of predefined values and their patterns.
+
+[[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,18 +152,55 @@ class SomePersonData {
 Supported classes for the type `<T>` 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.
 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.
 A `FieldNamingStrategy` applies to all entities; it can be overwritten by setting a specific name with `@Field` on a property.
 
+[[elasticsearch.mapping.meta-model.annotations.non-field-backed-properties]]
+==== Non-field-backed properties
+
+Normally the properties used in an entity are fields of the entity class.
+There might be cases, when a property value is calculated in the entity and should be stored in Elasticsearch.
+In this case, the getter method (`getProperty()`) can be annotated with the `@Field` annotation, in addition to that the method must be annotated with `@AccessType(AccessType.Type
+.PROPERTY)`.
+The third annotation that is needed in such a case is `@WriteOnlyProperty`, as such a value is only written to Elasticsearch.
+A full example:
+
+====
+[source,java]
+----
+@Field(type = Keyword)
+@WriteOnlyProperty
+@AccessType(AccessType.Type.PROPERTY)
+public String getProperty() {
+	return "some value that is calculated here";
+}
+----
+====
+
+[[elasticsearch.mapping.meta-model.annotations.misc]]
+==== Other property annotations
+
+[[indexedindexname]]
+===== @IndexedIndexName
+
+This annotation can be set on a String property of an entity.
+This property will not be written to the mapping, it will not be stored in Elasticsearch and its value will not be read from an Elasticsearch document.
+After an entity is persisted, for example with a call to `ElasticsearchOperations.save(T entity)`, the entity returned from that call will contain the name of the index that an entity was saved to in that property.
+This is useful when the index name is dynamically set by a bean, or when writing to a write alias.
+
+Putting some value into such a property does not set the index into which an entity is stored!
+
 [[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.
@@ -170,7 +211,6 @@ Those type hints are represented as `_class` attributes within the document and
 [source,java]
 ----
 public class Person {              <1>
-
   @Id String id;
   String firstname;
   String lastname;
@@ -220,14 +260,15 @@ 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.
 
+[[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.
 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 alternativ 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:
 
 ====
 [source,java]
@@ -240,6 +281,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.
@@ -249,7 +291,6 @@ Geospatial types like `Point` & `GeoPoint` are converted into _lat/lon_ pairs.
 [source,java]
 ----
 public class Address {
-
   String city, street;
   Point location;
 }
@@ -265,6 +306,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,9 +347,10 @@ 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 <<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
 ====
@@ -332,9 +375,10 @@ 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 <<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.
 
 .Collections
@@ -369,19 +413,21 @@ public class Person {
 [[elasticsearch.mapping.meta-model.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
 ====
 [source,java]
 ----
 @Configuration
-public class Config extends AbstractElasticsearchConfiguration {
+public class Config extends ElasticsearchConfiguration  {
 
-  @Override
-  public RestHighLevelClient elasticsearchClient() {
-    return RestClients.create(ClientConfiguration.create("localhost:9200")).rest();
-  }
+	@Override
+	public ClientConfiguration clientConfiguration() {
+		return ClientConfiguration.builder() //
+				.connectedTo("localhost:9200") //
+				.build();
+	}
 
   @Bean
   @Override

src/main/antora/modules/ROOT/pages/elasticsearch/reactive-template.adoc

@@ -0,0 +1,65 @@
+[[elasticsearch.reactive.operations]]
+= Reactive Elasticsearch Operations
+
+`ReactiveElasticsearchOperations` is the gateway to executing high level commands against an Elasticsearch cluster using the `ReactiveElasticsearchClient`.
+
+The `ReactiveElasticsearchTemplate` is the default implementation of `ReactiveElasticsearchOperations`.
+
+To get started the `ReactiveElasticsearchOperations` needs to know about the actual client to work with.
+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]]
+== Reactive Operations Usage
+
+`ReactiveElasticsearchOperations` lets you save, find and delete your domain objects and map those objects to documents stored in Elasticsearch.
+
+Consider the following:
+
+.Use the ReactiveElasticsearchOperations
+====
+[source,java]
+----
+@Document(indexName = "marvel")
+public class Person {
+
+  private @Id String id;
+  private String name;
+  private int age;
+  // Getter/Setter omitted...
+}
+----
+
+[source,java]
+----
+
+ReactiveElasticsearchOperations operations;
+
+// ...
+
+operations.save(new Person("Bruce Banner", 42))                    <.>
+  .doOnNext(System.out::println)
+  .flatMap(person -> operations.get(person.id, Person.class))      <.>
+  .doOnNext(System.out::println)
+  .flatMap(person -> operations.delete(person))                    <.>
+  .doOnNext(System.out::println)
+  .flatMap(id -> operations.count(Person.class))                   <.>
+  .doOnNext(System.out::println)
+  .subscribe();                                                    <.>
+----
+
+The above outputs the following sequence on the console.
+
+[source,text]
+----
+> Person(id=QjWCWWcBXiLAnp77ksfR, name=Bruce Banner, age=42)
+> Person(id=QjWCWWcBXiLAnp77ksfR, name=Bruce Banner, age=42)
+> QjWCWWcBXiLAnp77ksfR
+> 0
+----
+
+<.> 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.
+<.> 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.
+<.> Don't forget to _subscribe()_.
+====

src/main/antora/modules/ROOT/pages/elasticsearch/repositories/cdi-integration.adoc

@@ -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.
+
+====

src/main/antora/modules/ROOT/pages/elasticsearch/repositories/elasticsearch-repositories.adoc

@@ -12,10 +12,10 @@ class Book {
     @Id
     private String id;
 
-    @Field(type = FieldType.text)
+    @Field(type = FieldType.Text)
     private String name;
 
-    @Field(type = FieldType.text)
+    @Field(type = FieldType.Text)
     private String summary;
 
     @Field(type = FieldType.Integer)
@@ -29,20 +29,21 @@ class Book {
 [[elasticsearch.repositories.autocreation]]
 == 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]]
 == 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:
+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]
@@ -53,7 +54,7 @@ interface BookRepository extends Repository<Book, String> {
         @HighlightField(name = "name"),
         @HighlightField(name = "summary")
     })
-    List<SearchHit<Book>> findByNameOrSummary(String text, String summary);
+    SearchHits<Book> findByNameOrSummary(String text, String summary);
 }
 ----
 ====
@@ -62,6 +63,31 @@ 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.
+Elasticsearch provides source filtering to reduce the amount of data that is transferred across the network to the
+application.
+
+When working with `Query` implementations and the `ElasticsearchOperations` this is easily possible by setting a
+source filter on the query.
+
+When using repository methods there is the `@SourceFilters` annotation:
+
+====
+[source,java]
+----
+interface BookRepository extends Repository<Book, String> {
+
+    @SourceFilters(includes = "name")
+    SearchHits<Book> findByName(String text);
+}
+----
+====
+
+In this example, all the properties of the returned `Book` objects would be `null` except the name.
+
 [[elasticsearch.annotation]]
 == Annotation based configuration
 
@@ -99,51 +125,17 @@ class ProductService {
 
 <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.
-<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.
 ====
 
-[[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]]
 == Spring Namespace
 
 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
 ====

src/main/antora/modules/ROOT/pages/elasticsearch/repositories/elasticsearch-repository-queries.adoc

@@ -6,15 +6,18 @@
 
 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.
-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 the @Query Annotation] ).
+
+Another possibility is the use of a search-template, (see xref:elasticsearch/repositories/elasticsearch-repository-queries.adoc#elasticsearch.query-methods.at-searchtemplate-query[Using the @SearchTemplateQuery Annotation] ).
 
 [[elasticsearch.query-methods.criterions]]
 == 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:
 
 .Query creation from method names
@@ -136,7 +139,7 @@ A list of supported keywords for Elasticsearch is shown below.
 
 
 | `GreaterThanEqual`
-| `findByPriceGreaterThan`
+| `findByPriceGreaterThanEqual`
 | `{ "query" : {
 "bool" : {
 "must" : [
@@ -298,6 +301,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:
@@ -310,11 +314,13 @@ Repository methods can be defined to have the following return types for returni
 * `SearchPage<T>`
 
 [[elasticsearch.query-methods.at-query]]
-== Using @Query Annotation
+== Using the @Query Annotation
 
 .Declare query on the method using the `@Query` annotation.
 ====
-The arguments passed to the method can be inserted into placeholders in the query string. the placeholders are of the form `?0`, `?1`, `?2` etc. for the first, second, third parameter and so on.
+The arguments passed to the method can be inserted into placeholders in the query string.
+The placeholders are of the form `?0`, `?1`, `?2` etc. for the first, second, third parameter and so on.
+
 [source,java]
 ----
 interface BookRepository extends ElasticsearchRepository<Book, String> {
@@ -339,15 +345,20 @@ It will be sent to Easticsearch as value of the query element; if for example th
 }
 ----
 ====
+
 .`@Query` annotation on a method taking a Collection argument
 ====
 A repository method such as
+
 [source,java]
 ----
 @Query("{\"ids\": {\"values\": ?0 }}")
 List<SampleEntity> getByIds(Collection<String> ids);
 ----
-would make an https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-ids-query.html[IDs query] to return all the matching documents. So calling the method with a `List` of `["id1", "id2", "id3"]` would produce the query body
+
+would make an https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-ids-query.html[IDs query] to return all the matching documents.
+So calling the method with a `List` of `["id1", "id2", "id3"]` would produce the query body
+
 [source,json]
 ----
 {
@@ -360,3 +371,222 @@ would make an https://www.elastic.co/guide/en/elasticsearch/reference/current/qu
 ----
 ====
 
+[[elasticsearch.query-methods.at-query.spel]]
+=== Using SpEL Expressions
+
+.Declare query on the method using the `@Query` annotation with SpEL expression.
+====
+https://docs.spring.io/spring-framework/reference/core/expressions.html[SpEL expression] is also supported when defining query in `@Query`.
+
+[source,java]
+----
+interface BookRepository extends ElasticsearchRepository<Book, String> {
+    @Query("""
+        {
+          "bool":{
+            "must":[
+              {
+                "term":{
+                  "name": "#{#name}"
+                }
+              }
+            ]
+          }
+        }
+        """)
+    Page<Book> findByName(String name, Pageable pageable);
+}
+----
+
+If for example the function is called with the parameter _John_, it would produce the following query body:
+
+[source,json]
+----
+{
+  "bool":{
+    "must":[
+      {
+        "term":{
+          "name": "John"
+        }
+      }
+    ]
+  }
+}
+----
+====
+
+.accessing parameter property.
+====
+Supposing that we have the following class as query parameter type:
+
+[source,java]
+----
+public record QueryParameter(String value) {
+}
+----
+
+It's easy to access the parameter by `#` symbol, then reference the property `value` with a simple `.`:
+
+[source,java]
+----
+interface BookRepository extends ElasticsearchRepository<Book, String> {
+    @Query("""
+            {
+              "bool":{
+                "must":[
+                  {
+                    "term":{
+                      "name": "#{#parameter.value}"
+                    }
+                  }
+                ]
+              }
+            }
+            """)
+    Page<Book> findByName(QueryParameter parameter, Pageable pageable);
+}
+----
+
+We can pass `new QueryParameter("John")` as the parameter now, and it will produce the same query string as above.
+====
+
+.accessing bean property.
+====
+https://docs.spring.io/spring-framework/reference/core/expressions/language-ref/bean-references.html[Bean property] is also supported to access.
+Given that there is a bean named `queryParameter` of type `QueryParameter`, we can access the bean with symbol `@` rather than `#`, and there is no need to declare a parameter of type `QueryParameter` in the query method:
+
+[source,java]
+----
+interface BookRepository extends ElasticsearchRepository<Book, String> {
+    @Query("""
+            {
+              "bool":{
+                "must":[
+                  {
+                    "term":{
+                      "name": "#{@queryParameter.value}"
+                    }
+                  }
+                ]
+              }
+            }
+            """)
+    Page<Book> findByName(Pageable pageable);
+}
+----
+====
+
+.SpEL and `Collection` param.
+====
+`Collection` parameter is also supported and is as easy to use as normal `String`, such as the following `terms` query:
+
+[source,java]
+----
+interface BookRepository extends ElasticsearchRepository<Book, String> {
+    @Query("""
+            {
+              "bool":{
+                "must":[
+                  {
+                    "terms":{
+                      "name": #{#names}
+                    }
+                  }
+                ]
+              }
+            }
+            """)
+    Page<Book> findByName(Collection<String> names, Pageable pageable);
+}
+----
+
+NOTE: collection values should not be quoted when declaring the elasticsearch json query.
+
+A collection of `names` like `List.of("name1", "name2")` will produce the following terms query:
+
+[source,json]
+----
+{
+  "bool":{
+    "must":[
+      {
+        "terms":{
+          "name": ["name1", "name2"]
+        }
+      }
+    ]
+  }
+}
+----
+====
+
+.access property in the `Collection` param.
+====
+https://docs.spring.io/spring-framework/reference/core/expressions/language-ref/collection-projection.html[SpEL Collection Projection] is convenient to use when values in the `Collection` parameter is not plain `String`:
+
+[source,java]
+----
+interface BookRepository extends ElasticsearchRepository<Book, String> {
+    @Query("""
+            {
+              "bool":{
+                "must":[
+                  {
+                    "terms":{
+                      "name": #{#parameters.![value]}
+                    }
+                  }
+                ]
+              }
+            }
+            """)
+    Page<Book> findByName(Collection<QueryParameter> parameters, Pageable pageable);
+}
+----
+
+This will extract all the `value` property values as a new `Collection` from `QueryParameter` collection, thus takes the same effect as above.
+====
+
+.alter parameter name by using `@Param`
+====
+When accessing the parameter by SpEL, it's also useful to alter the parameter name to another one by `@Param` annotation in Sping Data:
+
+[source,java]
+----
+interface BookRepository extends ElasticsearchRepository<Book, String> {
+    @Query("""
+            {
+              "bool":{
+                "must":[
+                  {
+                    "terms":{
+                      "name": #{#another.![value]}
+                    }
+                  }
+                ]
+              }
+            }
+            """)
+    Page<Book> findByName(@Param("another") Collection<QueryParameter> parameters, Pageable pageable);
+}
+----
+
+====
+
+[[elasticsearch.query-methods.at-searchtemplate-query]]
+== Using the @SearchTemplateQuery Annotation
+
+When using Elasticsearch search templates - (see xref:elasticsearch/misc.adoc#elasticsearch.misc.searchtemplates [Search Template support]) it is possible to specify that a repository method should use a template by adding the `@SearchTemplateQuery` annotation to that method.
+
+Let's assume that there is a search template stored with the name "book-by-title" and this template need a parameter named "title", then a repository method using that search template can be defined like this:
+
+[source,java]
+----
+interface BookRepository extends ElasticsearchRepository<Book, String> {
+    @SearchTemplateQuery(id = "book-by-title")
+    SearchHits<Book> findByTitle(String title);
+}
+----
+
+The parameters of the repository method are sent to the seacrh template as key/value pairs where the key is the parameter name and the value is taken from the actual value when the method is invoked.

src/main/antora/modules/ROOT/pages/elasticsearch/repositories/reactive-elasticsearch-repositories.adoc

@@ -1,11 +1,9 @@
 [[elasticsearch.reactive.repositories]]
 = Reactive Elasticsearch Repositories
 
-Reactive Elasticsearch repository support builds on the core repository support explained in <<repositories>> utilizing
-operations provided via <<elasticsearch.reactive.operations>> executed by a <<elasticsearch.clients.reactive>>.
+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].
 
-Spring Data Elasticsearch reactive repository support uses https://projectreactor.io/[Project Reactor] as its reactive
-composition library of choice.
+Spring Data Elasticsearch reactive repository support uses https://projectreactor.io/[Project Reactor] as its reactive composition library of choice.
 
 There are 3 main interfaces to be used:
 
@@ -79,7 +77,7 @@ interface ReactivePersonRepository extends ReactiveSortingRepository<Person, Str
 parameters.
 <9> Count all entities with matching `firstname`.
 <10> Check if at least one entity with matching `firstname` exists.
-<11> Delete all entites with matching `firstname`.
+<11> Delete all entities with matching `firstname`.
 ====
 
 [[elasticsearch.reactive.repositories.configuration]]

src/main/antora/modules/ROOT/pages/elasticsearch/routing.adoc

@@ -1,4 +1,3 @@
-
 [[elasticsearch.routing]]
 = Routing values
 
@@ -8,13 +7,15 @@ 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 <<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.
 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.
 ====
-

src/main/antora/modules/ROOT/pages/elasticsearch/scripted-and-runtime-fields.adoc

@@ -0,0 +1,228 @@
+[[elasticsearch.misc.scripted-and-runtime-fields]]
+= Scripted and runtime fields
+
+Spring Data Elasticsearch supports scripted fields and runtime fields.
+Please refer to the Elasticsearch documentation about scripting (https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-scripting.html) and runtime fields (https://www.elastic.co/guide/en/elasticsearch/reference/8.9/runtime.html) for detailed information about this.
+In the context of Spring Data Elasticsearch you can use
+
+* scripted fields that are used to return fields that are calculated on the result documents and added to the returned document.
+* runtime fields that are calculated on the stored documents and can be used in a query and/or be returned in the search result.
+
+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 enity that is used in these examples is a `Person` entity.
+This entity has a `birthDate` and an `age` property.
+Whereas the birthdate is fix, the age depends on the time when a query is issued and needs to be calculated dynamically.
+
+====
+[source,java]
+----
+import org.jspecify.annotations.Nullable;
+import org.springframework.data.annotation.Id;
+import org.springframework.data.elasticsearch.annotations.DateFormat;
+import org.springframework.data.elasticsearch.annotations.Document;
+import org.springframework.data.elasticsearch.annotations.Field;
+import org.springframework.data.elasticsearch.annotations.ScriptedField;
+
+import java.time.LocalDate;
+import java.time.format.DateTimeFormatter;
+
+import static org.springframework.data.elasticsearch.annotations.FieldType.*;
+
+import java.lang.Integer;
+
+@Document(indexName = "persons")
+public record Person(
+        @Id
+        @Nullable
+        String id,
+        @Field(type = Text)
+        String lastName,
+        @Field(type = Text)
+        String firstName,
+        @Field(type = Keyword)
+        String gender,
+        @Field(type = Date, format = DateFormat.basic_date)
+        LocalDate birthDate,
+        @Nullable
+        @ScriptedField Integer age                   <.>
+) {
+    public Person(String id,String lastName, String firstName, String gender, String birthDate) {
+        this(id,                                     <.>
+            lastName,
+            firstName,
+            LocalDate.parse(birthDate, DateTimeFormatter.ISO_LOCAL_DATE),
+            gender,
+            null);
+    }
+}
+
+----
+
+<.> the `age` property will be calculated and filled in search results.
+<.> a convenience constructor to set up the test data.
+====
+
+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.
+
+[[the-repository-interface]]
+== The repository interface
+
+The repository used in this example:
+
+====
+[source,java]
+----
+public interface PersonRepository extends ElasticsearchRepository<Person, String> {
+
+    SearchHits<Person> findAllBy(ScriptedField scriptedField);
+
+    SearchHits<Person> findByGenderAndAgeLessThanEqual(String gender, Integer age, RuntimeField runtimeField);
+}
+
+----
+====
+
+[[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.
+We show the code split up in different pieces to put the explanations in
+
+====
+[source,java]
+----
+import org.springframework.data.elasticsearch.core.ElasticsearchOperations;
+import org.springframework.data.elasticsearch.core.SearchHits;
+import org.springframework.data.elasticsearch.core.query.Criteria;
+import org.springframework.data.elasticsearch.core.query.CriteriaQuery;
+import org.springframework.data.elasticsearch.core.query.FetchSourceFilter;
+import org.springframework.data.elasticsearch.core.query.RuntimeField;
+import org.springframework.data.elasticsearch.core.query.ScriptData;
+import org.springframework.data.elasticsearch.core.query.ScriptType;
+import org.springframework.data.elasticsearch.core.query.ScriptedField;
+import org.springframework.data.elasticsearch.core.query.StringQuery;
+import org.springframework.stereotype.Service;
+
+import java.util.List;
+
+@Service
+public class PersonService {
+    private final ElasticsearchOperations operations;
+    private final PersonRepository repository;
+
+    public PersonService(ElasticsearchOperations operations, SaRPersonRepository repository) {
+        this.operations = operations;
+        this.repository = repository;
+    }
+
+    public void save() { <.>
+        List<Person> persons = List.of(
+                new Person("1", "Smith", "Mary", "f", "1987-05-03"),
+                new Person("2", "Smith", "Joshua", "m", "1982-11-17"),
+                new Person("3", "Smith", "Joanna", "f", "2018-03-27"),
+                new Person("4", "Smith", "Alex", "m", "2020-08-01"),
+                new Person("5", "McNeill", "Fiona", "f", "1989-04-07"),
+                new Person("6", "McNeill", "Michael", "m", "1984-10-20"),
+                new Person("7", "McNeill", "Geraldine", "f", "2020-03-02"),
+                new Person("8", "McNeill", "Patrick", "m", "2022-07-04"));
+
+        repository.saveAll(persons);
+    }
+----
+
+<.> a utility method to store some data in Elasticsearch.
+====
+
+[[scripted-fields]]
+=== Scripted fields
+
+The next piece shows how to use a scripted field to calculate and return the age of the persons.
+Scripted fields can only add something to the returned data, the age cannot be used in the query (see runtime fields for that).
+
+====
+[source,java]
+----
+    public SearchHits<Person> findAllWithAge() {
+
+        var scriptedField = ScriptedField.of("age",                               <.>
+                ScriptData.of(b -> b
+                        .withType(ScriptType.INLINE)
+                        .withScript("""
+                                Instant currentDate = Instant.ofEpochMilli(new Date().getTime());
+                                Instant startDate = doc['birth-date'].value.toInstant();
+                                return (ChronoUnit.DAYS.between(startDate, currentDate) / 365);
+                                """)));
+
+        // version 1: use a direct query
+        var query = new StringQuery("""
+                { "match_all": {} }
+                """);
+        query.addScriptedField(scriptedField);                                    <.>
+        query.addSourceFilter(FetchSourceFilter.of(b -> b.withIncludes("*")));    <.>
+
+        var result1 = operations.search(query, Person.class);                     <.>
+
+        // version 2: use the repository
+        var result2 = repository.findAllBy(scriptedField);                        <.>
+
+        return result1;
+    }
+----
+
+<.> define the `ScriptedField` that calculates the age of a person.
+<.> when using a `Query`, add the scripted field to the query.
+<.> when adding a scripted field to a `Query`, an additional source filter is needed to also retrieve the _normal_ fields from the document source.
+<.> get the data where the `Person` entities now have the values set in their `age` property.
+<.> when using the repository, all that needs to be done is adding the scripted field as method parameter.
+====
+
+[[runtime-fields]]
+=== Runtime fields
+
+When using runtime fields, the calculated value can be used in the query itself.
+In the following code this is used to run a query for a given gender and maximum age of persons:
+
+====
+[source,java]
+----
+    public SearchHits<Person> findWithGenderAndMaxAge(String gender, Integer maxAge) {
+
+        var runtimeField = new RuntimeField("age", "long", """                    <.>
+                                Instant currentDate = Instant.ofEpochMilli(new Date().getTime());
+                                Instant startDate = doc['birthDate'].value.toInstant();
+                                emit (ChronoUnit.DAYS.between(startDate, currentDate) / 365);
+                """);
+
+        // variant 1 : use a direct query
+        var query = CriteriaQuery.builder(Criteria
+                        .where("gender").is(gender)
+                        .and("age").lessThanEqual(maxAge))
+                .withRuntimeFields(List.of(runtimeField))                         <.>
+                .withFields("age")                                                <.>
+                .withSourceFilter(FetchSourceFilter.of(b -> b.withIncludes("*"))) <.>
+                .build();
+
+        var result1 = operations.search(query, Person.class);                     <.>
+
+        // variant 2: use the repository                                          <.>
+        var result2 = repository.findByGenderAndAgeLessThanEqual(gender, maxAge, runtimeField);
+
+        return result1;
+    }
+}
+----
+
+<.> define the runtime field that calculates the age of a person. // see https://asciidoctor.org/docs/user-manual/#builtin-attributes for builtin attributes.
+<.> when using `Query`, add the runtime field.
+<.> when adding a scripted field to a `Query`, an additional field parameter is needed to have the calculated value returned.
+<.> when adding a scripted field to a `Query`, an additional source filter is needed to also retrieve the _normal_ fields from the document source.
+<.> get the data filtered with the query and where the returned entites have the age property set.
+<.> when using the repository, all that needs to be done is adding the runtime field as method parameter.
+====
+
+In addition to define a runtime fields on a query, they can also be defined in the index by setting the `runtimeFieldsPath` property of the `@Mapping` annotation to point to a JSON file that contains the runtime field definitions.

src/main/antora/modules/ROOT/pages/elasticsearch/template.adoc

@@ -1,12 +1,12 @@
 [[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.
-* `DocumentOperations` defines actions to store, update and retrieve entities based on their id.
-* `SearchOperations` define the actions to search for multiple entities using queries
-* `ElasticsearchOperations` combines the `DocumentOperations` and `SearchOperations` interfaces.
+* javadoc:org.springframework.data.elasticsearch.core.IndexOperations[] defines actions on index level like creating or deleting an index.
+* javadoc:org.springframework.data.elasticsearch.core.DocumentOperations[] defines actions to store, update and retrieve entities based on their id.
+* javadoc:org.springframework.data.elasticsearch.core.SearchOperations[] define the actions to search for multiple entities using queries
+* javadoc:org.springframework.data.elasticsearch.core.ElasticsearchOperations[] combines the `DocumentOperations` and `SearchOperations` interfaces.
 
 These interfaces correspond to the structuring of the https://www.elastic.co/guide/en/elasticsearch/reference/current/rest-apis.html[Elasticsearch API].
 
@@ -21,45 +21,20 @@ The default implementations of the interfaces offer:
 ====
 .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.
-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`.
 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]
 
 ====
 
-[[elasticsearch.operations.resttemplate]]
-== ElasticsearchRestTemplate
-
-The `ElasticsearchRestTemplate` is an implementation of the `ElasticsearchOperations` interface using the <<elasticsearch.clients.rest>>.
-
-.ElasticsearchRestTemplate configuration
-====
-[source,java]
-----
-@Configuration
-public class RestClientConfig extends AbstractElasticsearchConfiguration {
-  @Override
-  public RestHighLevelClient elasticsearchClient() {       <1>
-    return RestClients.create(ClientConfiguration.localhost()).rest();
-  }
-
-  // no special bean creation needed                       <2>
-}
-----
-
-<1> Setting up the <<elasticsearch.clients.rest>>.
-<2> The base class `AbstractElasticsearchConfiguration` already provides the `elasticsearchTemplate` bean.
-====
-
 [[elasticsearch.operations.usage]]
 == Usage examples
 
-As both `ElasticsearchTemplate` and `ElasticsearchRestTemplate` implement the `ElasticsearchOperations` interface, the code to use them is not different.
 The example shows how to use an injected `ElasticsearchOperations` instance in a Spring REST controller.
-The decision, if this is using the `TransportClient` or the `RestClient` is made by providing the corresponding Bean with one of the configurations shown above.
+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
 ====
@@ -71,39 +46,33 @@ public class TestController {
 
   private  ElasticsearchOperations elasticsearchOperations;
 
-  public TestController(ElasticsearchOperations elasticsearchOperations) { <1>
+  public TestController(ElasticsearchOperations elasticsearchOperations) { <.>
     this.elasticsearchOperations = elasticsearchOperations;
   }
 
   @PostMapping("/person")
-  public String save(@RequestBody Person person) {                         <2>
-
-    IndexQuery indexQuery = new IndexQueryBuilder()
-      .withId(person.getId().toString())
-      .withObject(person)
-      .build();
-    String documentId = elasticsearchOperations.index(indexQuery);
-    return documentId;
+  public String save(@RequestBody Person person) {                         <.>
+    Person savedEntity = elasticsearchOperations.save(person);
+    return savedEntity.getId();
   }
 
   @GetMapping("/person/{id}")
-  public Person findById(@PathVariable("id")  Long id) {                   <3>
-    Person person = elasticsearchOperations
-      .queryForObject(GetQuery.getById(id.toString()), Person.class);
+  public Person findById(@PathVariable("id")  Long id) {                   <.>
+    Person person = elasticsearchOperations.get(id.toString(), Person.class);
     return person;
   }
 }
 
 ----
 
-<1> Let Spring inject the provided `ElasticsearchOperations` bean in the constructor.
-<2> Store some entity in the Elasticsearch cluster.
-<3> Retrieve the entity with a query by id.
+<.> Let Spring inject the provided `ElasticsearchOperations` bean in the constructor.
+<.> Store some entity in the Elasticsearch cluster.
+The id is read from the returned entity, as it might have been null in the `person` object and been created by Elasticsearch.
+<.> Retrieve the entity with a get by id.
 ====
 
 To see the full possibilities of `ElasticsearchOperations` please refer to the API documentation.
 
-include::reactive-elasticsearch-operations.adoc[leveloffset=+1]
 
 [[elasticsearch.operations.searchresulttypes]]
 == Search Result Types
@@ -112,7 +81,7 @@ When a document is retrieved with the methods of the  `DocumentOperations` inter
 When searching with the methods of the `SearchOperations` interface, additional information is available for each entity, for example the _score_ or the _sortValues_ of the found entity.
 
 In order to return this information, each entity is wrapped in a `SearchHit` object that contains this entity-specific additional information.
-These `SearchHit` objects themselves are returned within a `SearchHits` object which additionally contains informations about the whole search like the _maxScore_ or requested aggregations.
+These `SearchHit` objects themselves are returned within a `SearchHits` object which additionally contains informations about the whole search like the _maxScore_ or requested aggregations or the execution duration it took to complete the request.
 The following classes and interfaces are now available:
 
 .SearchHit<T>
@@ -150,13 +119,13 @@ An Iterator returned by the streaming functions of the `SearchOperations` interf
 [[elasticsearch.operations.queries]]
 == Queries
 
-Almost all of the methods defined in the `SearchOperations` and `ReactiveSearchOperations` interface take a `Query` parameter that defines the query to execute for searching. `Query` is an interface and Spring Data Elasticsearch provides three implementations: `CriteriaQuery`, `StringQuery` and `NativeSearchQuery`.
+Almost all of the methods defined in the `SearchOperations` and `ReactiveSearchOperations` interface take a `Query` parameter that defines the query to execute for searching. `Query` is an interface and Spring Data Elasticsearch provides three implementations: `CriteriaQuery`, `StringQuery` and `NativeQuery`.
 
 [[elasticsearch.operations.criteriaquery]]
 === CriteriaQuery
 
 `CriteriaQuery` based queries allow the creation of queries to search for data without knowing the syntax or basics of Elasticsearch queries.
-They allow the user to build queries by simply chaining and combining `Criteria` objects that specifiy the criteria the searched documents must fulfill.
+They allow the user to build queries by simply chaining and combining `Criteria` objects that specify the criteria the searched documents must fulfill.
 
 NOTE: when talking about AND or OR when combining criteria keep in mind, that in Elasticsearch AND are converted to a **must** condition and OR to a **should**
 
@@ -177,7 +146,7 @@ Conditions for the same field can be chained, they will be combined with a logic
 ====
 [source,java]
 ----
-Criteria criteria = new Criteria("price").greaterThan(42.0).lessThan(34.0L);
+Criteria criteria = new Criteria("price").greaterThan(42.0).lessThan(34.0);
 Query query = new CriteriaQuery(criteria);
 ----
 ====
@@ -230,7 +199,7 @@ The following code shows a query that searches for persons having the first name
 [source,java]
 ----
 
-Query query = new SearchQuery("{ \"match\": { \"firstname\": { \"query\": \"Jack\" } } } ");
+Query query = new StringQuery("{ \"match\": { \"firstname\": { \"query\": \"Jack\" } } } ");
 SearchHits<Person> searchHits = operations.search(query, Person.class);
 
 ----
@@ -238,22 +207,35 @@ SearchHits<Person> searchHits = operations.search(query, Person.class);
 
 Using `StringQuery` may be appropriate if you already have an Elasticsearch query to use.
 
-[[elasticsearch.operations.nativesearchquery]]
-=== NativeSearchQuery
+[[elasticsearch.operations.nativequery]]
+=== NativeQuery
 
-`NativeSearchQuery` is the class to use when you have a complex query, or a query that cannot be expressed by using the `Criteria` API, for example when building queries and using aggregates.
-It allows to use all the different `QueryBuilder` implementations from the Elasticsearch library therefore named "native".
+`NativeQuery` is the class to use when you have a complex query, or a query that cannot be expressed by using the `Criteria` API, for example when building queries and using aggregates.
+It allows to use all the different `co.elastic.clients.elasticsearch._types.query_dsl.Query` implementations from the Elasticsearch library therefore named "native".
 
-The following code shows how to search for persons with a given firstname and for the found documents have a terms aggregation that counts the number of occurences of the lastnames for these persons:
+The following code shows how to search for persons with a given `firstName` and for the found documents have a terms aggregation that counts the number of occurrences of the `lastName` for these persons:
 
 ====
 [source,java]
 ----
-Query query = new NativeSearchQueryBuilder()
-    .addAggregation(terms("lastnames").field("lastname").size(10)) //
-    .withQuery(QueryBuilders.matchQuery("firstname", firstName))
-    .build();
+Query query = NativeQuery.builder()
+	.withAggregation("lastNames", Aggregation.of(a -> a
+		.terms(ta -> ta.field("lastName").size(10))))
+	.withQuery(q -> q
+		.match(m -> m
+			.field("firstName")
+			.query(firstName)
+		)
+	)
+	.withPageable(pageable)
+	.build();
 
 SearchHits<Person> searchHits = operations.search(query, Person.class);
 ----
 ====
+
+[[elasticsearch.operations.searchtemplatequery]]
+=== SearchTemplateQuery
+
+This is a special implementation of the `Query` interface to be used in combination with a stored search template.
+See xref:elasticsearch/misc.adoc#elasticsearch.misc.searchtemplates[Search Template support] for further information.

src/main/antora/modules/ROOT/pages/elasticsearch/versions.adoc

@@ -0,0 +1,27 @@
+[[preface.versions]]
+= Versions
+
+The following table shows the Elasticsearch and Spring versions that are used by Spring Data release trains and the version of Spring Data Elasticsearch included in that.
+
+[cols="^,^,^,^",options="header"]
+|===
+| Spring Data Release Train | Spring Data Elasticsearch | Elasticsearch | Spring Framework
+| 2025.1 (in development) | 6.0.x | 9.0.4 | 7.0.x
+| 2025.0 | 5.5.x | 8.18.1 | 6.2.x
+| 2024.1 | 5.4.x | 8.15.5 | 6.1.x
+| 2024.0 | 5.3.xfootnote:oom[Out of maintenance] | 8.13.4 | 6.1.x
+| 2023.1 (Vaughan) | 5.2.xfootnote:oom[] | 8.11.1 | 6.1.x
+| 2023.0 (Ullmann) | 5.1.xfootnote:oom[] | 8.7.1 | 6.0.x
+| 2022.0 (Turing) | 5.0.xfootnote:oom[] | 8.5.3 | 6.0.x
+| 2021.2 (Raj) | 4.4.xfootnote:oom[] | 7.17.3 | 5.3.x
+| 2021.1 (Q) | 4.3.xfootnote:oom[] | 7.15.2 | 5.3.x
+| 2021.0 (Pascal) | 4.2.xfootnote:oom[] | 7.12.0 | 5.3.x
+| 2020.0 (Ockham) | 4.1.xfootnote:oom[] | 7.9.3 | 5.3.2
+| Neumann | 4.0.xfootnote:oom[] | 7.6.2 | 5.2.12
+| Moore | 3.2.xfootnote:oom[] |6.8.12 | 5.2.12
+| Lovelace | 3.1.xfootnote:oom[] | 6.2.2 | 5.1.19
+| Kay | 3.0.xfootnote:oom[] | 5.5.0 | 5.0.13
+| Ingalls | 2.1.xfootnote:oom[] | 2.4.0 | 4.3.25
+|===
+
+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].

src/main/antora/modules/ROOT/pages/index.adoc

@@ -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-{copyright-year} 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.

src/main/antora/modules/ROOT/pages/migration-guides.adoc

@@ -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.
+
+
+

src/main/antora/modules/ROOT/pages/migration-guides/migration-guide-3.2-4.0.adoc

@@ -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]]
 == 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]
 ----
@@ -28,13 +31,16 @@ public EntityMapper entityMapper() {
 You now have to remove this bean, the `ElasticsearchEntityMapper` interface has been removed.
 
 .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]]
 == 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 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 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.
 
 So for example the following code:
 
@@ -95,6 +101,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 +122,7 @@ Many functions and classes have been deprecated. These functions still work, but
 <T> T queryForObject(GetQuery query, Class<T> 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.
@@ -128,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 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.

src/main/antora/modules/ROOT/pages/migration-guides/migration-guide-4.0-4.1.adoc

@@ -9,7 +9,7 @@ This section describes breaking changes from version 4.0.x to 4.1.x and how remo
 .Definition of the id property
 It is possible to define a property of en entity as the id property by naming it either `id` or  `document`.
 This behaviour is now deprecated and will produce a warning.
-PLease us the `@Id` annotation to mark a property as being the id property.
+Please use the `@Id` annotation to mark a property as being the id property.
 
 .Index mappings
 In the `ReactiveElasticsearchClient.Indices` interface the `updateMapping` methods are deprecated in favour of the `putMapping` methods.
@@ -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<Boolean>` instead of a `Mono<Void>` to signal successful index creation.
 * the `updateMapping`  variants now return a `Mono<Boolean>` instead of a `Mono<Void>` to signal successful mappings storage.
 
-=== Return types of DocumentOperartions.bulkIndex methods
+[[elasticsearch-migration-guide-4.0-4.1.breaking-changes.returntypes-2]]
+=== Return types of DocumentOperations.bulkIndex methods
 
-These methods were returing a `List<String>` containing the ids of the new indexed records.
+These methods were returning a `List<String>` containing the ids of the new indexed records.
 Now they return a `List<IndexedObjectInformation>`; these objects contain the id and information about optimistic locking (seq_no and primary_term)

src/main/antora/modules/ROOT/pages/migration-guides/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.
@@ -14,7 +15,7 @@ The parameters of the `@Document` annotation that are relevant for  the index se
 == Removals
 
 The `@Score` annotation that was used to set the score return value in an entity was deprecated in version 4.0 and has been removed.
-Scroe values are returned in the `SearchHit` instances that encapsulate the returned entities.
+Score values are returned in the `SearchHit` instances that encapsulate the returned entities.
 
 The `org.springframework.data.elasticsearch.ElasticsearchException` class has been removed.
 The remaining usages have been replaced with `org.springframework.data.mapping.MappingException` and `org.springframework.dao.InvalidDataAccessApiUsageException`.
@@ -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 <<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.
 
+[[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<Long>` with the number of deleted documents, the non reactive versions were void. They now return a `Mono<ByQueryResponse>` which contains much more detailed information about the deleted documents and errors that might have occurred.
 
+[[elasticsearch-migration-guide-4.1-4.2.breaking-changes.method-return-types.multiget]]
 ==== multiget methods
 
 The implementations of _multiget_ previousl only returned the found entities in a `List<T>` for non-reactive implementations and in a `Flux<T>` for reactive implementations. If the request contained ids that were not found, the information that these are missing was not available. The user needed to compare the returned ids to the requested ones to find

src/main/antora/modules/ROOT/pages/migration-guides/migration-guide-4.2-4.3.adoc

@@ -15,12 +15,13 @@ 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.
 
-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]]
 == 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`.

src/main/antora/modules/ROOT/pages/migration-guides/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 `<T> Publisher<T> execute(ClientCallback<Publisher<T>> callback)` has been deprecated.
@@ -14,8 +15,10 @@ 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]]
 ==== `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).
@@ -23,11 +26,21 @@ 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.
+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.
+When the
+`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]]
 == New Elasticsearch client
 
@@ -38,6 +51,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) +
@@ -45,6 +59,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
@@ -61,8 +76,9 @@ public class SpringdataElasticTestApplication {
 ====
 
 Remove Spring Data Elasticsearch related properties from your application configuration.
-If Spring Data Elasticsearch was configured using a programmatic configuration (see <<elastisearch.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]]
 ==== Add dependencies
 
 The dependencies for the new Elasticsearch client are still optional in Spring Data Elasticsearch so they need to be added explicitly:
@@ -74,7 +90,7 @@ The dependencies for the new Elasticsearch client are still optional in Spring D
     <dependency>
         <groupId>co.elastic.clients</groupId>
         <artifactId>elasticsearch-java</artifactId>
-        <version>7.17.1</version>
+        <version>7.17.3</version>
         <exclusions>
             <exclusion>
                 <groupId>commons-logging</groupId>
@@ -85,7 +101,7 @@ The dependencies for the new Elasticsearch client are still optional in Spring D
     <dependency>
         <groupId>org.elasticsearch.client</groupId>
         <artifactId>elasticsearch-rest-client</artifactId> <!-- is Apache 2-->
-        <version>7.17.1</version>
+        <version>7.17.3</version>
         <exclusions>
             <exclusion>
                 <groupId>commons-logging</groupId>
@@ -108,8 +124,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`:
@@ -137,6 +155,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:

src/main/antora/modules/ROOT/pages/migration-guides/migration-guide-4.4-5.0.adoc

@@ -0,0 +1,167 @@
+[[elasticsearch-migration-guide-4.4-5.0]]
+= Upgrading from 4.4.x to 5.0.x
+
+This section describes breaking changes from version 4.4.x to 5.0.x and how removed features can be replaced by new introduced features.
+
+[[elasticsearch-migration-guide-4.4-4.5.deprecations]]
+== Deprecations
+
+[[custom-trace-level-logging]]
+=== Custom trace level logging
+
+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".
+
+[[elasticsearch-migration-guide-4.4-4.5.deprecations.package]]
+=== `org.springframework.data.elasticsearch.client.erhlc` package
+
+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]]
+=== Removal of deprecated code
+
+`DateFormat.none` and `DateFormat.custom` had been deprecated since version 4.2 and have been removed.
+
+The properties of `@Document` that were deprecated since 4.2 have been removed.
+Use the `@Settings` annotation for these.
+
+`@DynamicMapping` and `@DynamicMappingValue` have been removed.
+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.
+These now have been removed and so the dependency on Elasticsearch classes in these APIs has been cleaned.
+
+[[elasticsearch-migration-guide-4.4-5.0.breaking-changes-packages]]
+=== Package changes
+
+All the classes that are using or depend on the deprecated Elasticsearch `RestHighLevelClient` have been moved to the package `org.springframework.data.elasticsearch.client.erhlc`.
+By this change we now have a clear separation of code using the old deprecated Elasticsearch libraries, code using the new Elasticsearch client and code that is independent of the client implementation.
+Also the reactive implementation that was provided up to now has been moved here, as this implementation contains code that was copied and adapted from Elasticsearch libraries.
+
+If you are using `ElasticsearchRestTemplate` directly and not the `ElasticsearchOperations` interface you'll need to adjust your imports as well.
+
+When working with the `NativeSearchQuery` class, you'll need to switch to the `NativeQuery` class, which can take a
+`Query` instance coming 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
+`getProp()` to `prop()`:
+
+* `org.springframework.data.elasticsearch.core.AbstractReactiveElasticsearchTemplate.IndexResponseMetaData`
+* `org.springframework.data.elasticsearch.core.ActiveShardCount`
+* `org.springframework.data.elasticsearch.support.Version`
+* `org.springframework.data.elasticsearch.support.ScoreDoc`
+* `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`
+project.
+This introduces a dependency on that artifact.
+Users that do not use spring-web then face an error as this class cannot be found.
+
+In version 5.0 we introduce our own `HttpHeaders` to configure the clients.
+
+So if you are using headers in the client configuration, you need to replace `org.springframework.http.HttpHeaders`
+with `org.springframework.data.elasticsearch.support.HttpHeaders`.
+
+Hint: You can pass a `org.springframework.http
+.HttpHeaders` to the `addAll()` method of `org.springframework.data.elasticsearch.support.HttpHeaders`.
+
+[[elasticsearch-migration-guide-4.4-5.0.new-clients]]
+== New Elasticsearch client
+
+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`:
+
+====
+[source,java]
+----
+@Configuration
+public class NewRestClientConfig extends ElasticsearchConfiguration {
+
+	@Override
+	public ClientConfiguration clientConfiguration() {
+		return ClientConfiguration.builder() //
+			.connectedTo("localhost:9200") //
+			.build();
+	}
+}
+----
+====
+
+The configuration is done in the same way as with the old client, but it is not necessary anymore to create more than the configuration bean.
+With this configuration, the following beans will be available in the Spring application context:
+
+* a `RestClient` bean, that is the configured low level `RestClient` that is used by the Elasticsearch client
+* 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:
+
+====
+[source,java]
+----
+@Configuration
+public class NewRestClientConfig extends ReactiveElasticsearchConfiguration {
+
+	@Override
+	public ClientConfiguration clientConfiguration() {
+		return ClientConfiguration.builder() //
+			.connectedTo("localhost:9200") //
+			.build();
+	}
+}
+----
+====
+
+With this configuration, the following beans will be available in the Spring application context:
+
+* a `RestClient` bean, that is the configured low level `RestClient` that is used by the Elasticsearch client
+* an `ReactiveElasticsearchClient` bean, this is the new reactive client that uses the `RestClient`
+* an `ReactiveElasticsearchOperations` bean, available with the bean names _reactiveElasticsearchOperations_ and _reactiveElasticsearchTemplate_, this uses the `ReactiveElasticsearchClient`
+
+[[elasticsearch-migration-guide-4.4-5.0.old-client]]
+=== Still want to use the old client?
+
+The old deprecated `RestHighLevelClient` can still be used, but you will need to add the dependency explicitly to your application as Spring Data Elasticsearch does not pull it in automatically anymore:
+
+====
+[source,xml]
+----
+<!-- include the RHLC, specify version explicitly	-->
+<dependency>
+	<groupId>org.elasticsearch.client</groupId>
+	<artifactId>elasticsearch-rest-high-level-client</artifactId>
+	<version>7.17.5</version>
+	<exclusions>
+		<exclusion>
+			<groupId>commons-logging</groupId>
+			<artifactId>commons-logging</artifactId>
+		</exclusion>
+	</exclusions>
+</dependency>
+----
+====
+
+Make sure to specify the version 7.17.6 explicitly, otherwise maven will resolve to 8.5.0, and this does not exist.

src/main/antora/modules/ROOT/pages/migration-guides/migration-guide-5.0-5.1.adoc

@@ -0,0 +1,27 @@
+[[elasticsearch-migration-guide-5.0-5.1]]
+= Upgrading from 5.0.x to 5.1.x
+
+This section describes breaking changes from version 5.0.x to 5.1.x and how removed features can be replaced by new introduced features.
+
+[[elasticsearch-migration-guide-5.0-5.1.breaking-changes]]
+== Breaking Changes
+
+In the `org.springframework.data.elasticsearch.core.index.AliasData` class, which is used for alias information returned from Elasticsearch, the property `filter` (of type `Document`) is replaced by `filterQuery` which is of type
+`org.springframework.data.elasticsearch.core.query.Query`.
+
+`org.springframework.data.elasticsearch.annotations.Similarity` was an enum class until 5.1. This enum was used in the `@Field` annotation to specify a similarity value.
+But besides the values defined by the enum, it is possible to have similarities with custom names in Elasticsearch.
+Therefore, the annotation property was changed from the type of the enum to a simple `String`.
+The previous enum values like `Similarity.Default` do still exist as String constants, so existing code will compile unmodified.
+Adaptions are necessary when this enum was used at other places than as a property of the `@Field` annotation.
+
+[[elasticsearch-migration-guide-5.0-5.1.deprecations]]
+== Deprecations
+
+[[template-functions]]
+=== template functions
+
+The functions in the `IndexOperations` and `ReactiverIndexOperations` to manage index templates that were introduced in Spring Data Elasticsearch 4.1
+have been deprecated. They were using the old Elasticsearch API that was deprecated in Elasticsearch version 7.8. 
+
+Please use the new functions that are based on the composable index template API instead.

src/main/antora/modules/ROOT/pages/migration-guides/migration-guide-5.1-5.2.adoc

@@ -0,0 +1,40 @@
+[[elasticsearch-migration-guide-5.1-5.2]]
+= Upgrading from 5.1.x to 5.2.x
+
+This section describes breaking changes from version 5.1.x to 5.2.x and how removed features can be replaced by new introduced features.
+
+[[elasticsearch-migration-guide-5.1-5.2.breaking-changes]]
+== Breaking Changes
+
+[[bulk-failures]]
+=== Bulk failures
+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.
+
+The definition of the `FailureDetails` class (inner to `BulkFailureException`):
+[source,java]
+public record FailureDetails(Integer status, String errorMessage) {
+}
+
+[[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 `type` parameter of the `ScriptData` constructor is not nullable any longer.
+
+[[elasticsearch-migration-guide-5.1-5.2.deprecations]]
+== Deprecations
+
+[[removal-of-deprecated-code]]
+=== Removal of deprecated code
+
+* 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 `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.
+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 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 weren't used anymore and were no-ops.
+It has been removed from the `org.springframework.data.elasticsearch.core.query.IndexQuery` class as well.

src/main/antora/modules/ROOT/pages/migration-guides/migration-guide-5.2-5.3.adoc

@@ -0,0 +1,21 @@
+[[elasticsearch-migration-guide-5.2-5.3]]
+= Upgrading from 5.2.x to 5.3.x
+
+This section describes breaking changes from version 5.2.x to 5.3.x and how removed features can be replaced by new introduced features.
+
+[[elasticsearch-migration-guide-5.2-5.3.breaking-changes]]
+== Breaking Changes
+
+During the parameter replacement in `@Query` annotated repository methods previous versions wrote the String `"null"` into the query that was sent to Elasticsearch when the actual parameter value was `null`.
+As Elasticsearch does not store `null` values, this behaviour could lead to problems, for example whent the fields to be searched contains the string `"null"`.
+In Version 5.3 a `null` value in a parameter will cause a `ConversionException` to be thrown.
+If you are using `"null"` as the
+`null_value` defined in a field mapping, then pass that string into the query instead of a Java `null`.
+
+[[elasticsearch-migration-guide-5.2-5.3.deprecations]]
+== Deprecations
+
+=== Removals
+
+The deprecated classes `org.springframework.data.elasticsearch.ELCQueries`
+and `org.springframework.data.elasticsearch.client.elc.QueryBuilders` have been removed, use `org.springframework.data.elasticsearch.client.elc.Queries` instead.

src/main/antora/modules/ROOT/pages/migration-guides/migration-guide-5.3-5.4.adoc

@@ -0,0 +1,23 @@
+[[elasticsearch-migration-guide-5.3-5.4]]
+= Upgrading from 5.3.x to 5.4.x
+
+This section describes breaking changes from version 5.3.x to 5.4.x and how removed features can be replaced by new introduced features.
+
+[[elasticsearch-migration-guide-5.3-5.4.breaking-changes]]
+== Breaking Changes
+
+[[elasticsearch-migration-guide-5.3-5.4.breaking-changes.knn-search]]
+=== knn search
+The `withKnnQuery` method in `NativeQueryBuilder` has been replaced with `withKnnSearches` to build a `NativeQuery` with knn search.
+
+`KnnQuery` and `KnnSearch` are two different classes in elasticsearch java client and are used for different queries, with different parameters supported:
+
+- `KnnSearch`: is https://www.elastic.co/guide/en/elasticsearch/reference/8.13/search-search.html#search-api-knn[the top level `knn` query] in the elasticsearch request;
+- `KnnQuery`: is https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-knn-query.html[the `knn` query inside `query` clause];
+
+If `KnnQuery` is still preferable, please be sure to construct it inside `query` clause manually, by means of `withQuery(co.elastic.clients.elasticsearch._types.query_dsl.Query query)` clause in `NativeQueryBuilder`.
+
+[[elasticsearch-migration-guide-5.3-5.4.deprecations]]
+== Deprecations
+
+=== Removals

src/main/antora/modules/ROOT/pages/migration-guides/migration-guide-5.4-5.5.adoc

@@ -0,0 +1,30 @@
+[[elasticsearch-migration-guide-5.4-5.5]]
+= Upgrading from 5.4.x to 5.5.x
+
+This section describes breaking changes from version 5.4.x to 5.5.x and how removed features can be replaced by new introduced features.
+
+[[elasticsearch-migration-guide-5.4-5.5.breaking-changes]]
+== Breaking Changes
+
+[[elasticsearch-migration-guide-5.4-5.5.deprecations]]
+== Deprecations
+
+Some classes that probably are not used by a library user have been renamed, the classes with the old names are still there, but are deprecated:
+
+|===
+|old name|new name
+
+|ElasticsearchPartQuery|RepositoryPartQuery
+|ElasticsearchStringQuery|RepositoryStringQuery
+|ReactiveElasticsearchStringQuery|ReactiveRepositoryStringQuery
+|===
+
+=== Removals
+
+The following methods that had been deprecated since release 5.3 have been removed:
+```
+DocumentOperations.delete(Query, Class<?>)
+DocumentOperations.delete(Query, Class<?>, IndexCoordinates)
+ReactiveDocumentOperations.delete(Query, Class<?>)
+ReactiveDocumentOperations.delete(Query, Class<?>, IndexCoordinates)
+```

src/main/antora/modules/ROOT/pages/migration-guides/migration-guide-5.5-6.0.adoc

@@ -0,0 +1,27 @@
+[[elasticsearch-migration-guide-5.5-6.0]]
+= Upgrading from 5.5.x to 6.0.x
+
+This section describes breaking changes from version 5.5.x to 6.0.x and how removed features can be replaced by new introduced features.
+
+[[elasticsearch-migration-guide-5.5-6.0.breaking-changes]]
+== Breaking Changes
+
+From version 6.0 on, Spring Data Elasticsearch uses the Elasticsearch 9 libraries and as default the new `Rest5Client` provided by these libraries. It is still possible to use the old `RestClient`, check xref:elasticsearch/clients.adoc[Elasticsearch clients] for information. The configuration callbacks for this `RestClient` have been moved from `org.springframework.data.elasticsearch.client.elc.ElasticsearchClients` to the `org.springframework.data.elasticsearch.client.elc.rest_client.RestClients` class.
+
+In the `org.springframework.data.elasticsearch.core.query.UpdateQuery` class the type of the two fields `ifSeqNo` and `ifPrimaryTerm` has changed from `Integer` to `Long` to align with the normal query and the underlying Elasticsearch client.
+
+[[elasticsearch-migration-guide-5.5-6.0.deprecations]]
+== Deprecations
+
+All the code using the old `RestClient` has been moved to the `org.springframework.data.elasticsearch.client.elc.rest_client` package and has been deprecated. Users should switch to the classes from the `org.springframework.data.elasticsearch.client.elc.rest5_client` package.
+
+
+=== Removals
+
+The `org.springframework.data.elasticsearch.core.query.ScriptType` enum has been removed. To distinguish between an inline and a stored script set the appropriate values in the `org.springframework.data.elasticsearch.core.query.ScriptData` record.
+
+These methods have been removed because the Elasticsearch Client 9 does not support them anymore:
+```
+org.springframework.data.elasticsearch.client.elc.ReactiveElasticsearchIndicesClient.unfreeze(UnfreezeRequest)
+org.springframework.data.elasticsearch.client.elc.ReactiveElasticsearchIndicesClient.unfreeze(Function<UnfreezeRequest.Builder, ObjectBuilder<UnfreezeRequest>>)
+```

src/main/antora/modules/ROOT/pages/repositories.adoc

@@ -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.

src/main/antora/modules/ROOT/pages/repositories/core-concepts.adoc

@@ -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]

src/main/antora/modules/ROOT/pages/repositories/core-domain-events.adoc

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

src/main/antora/modules/ROOT/pages/repositories/core-extensions.adoc

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

src/main/antora/modules/ROOT/pages/repositories/create-instances.adoc

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

src/main/antora/modules/ROOT/pages/repositories/custom-implementations.adoc

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

src/main/antora/modules/ROOT/pages/repositories/definition.adoc

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

src/main/antora/modules/ROOT/pages/repositories/null-handling.adoc

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

src/main/antora/modules/ROOT/pages/repositories/projections.adoc

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

src/main/antora/modules/ROOT/pages/repositories/query-keywords-reference.adoc

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

src/main/antora/modules/ROOT/pages/repositories/query-methods-details.adoc

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

src/main/antora/modules/ROOT/pages/repositories/query-return-types-reference.adoc

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

src/main/antora/resources/antora-resources/antora.yml

@@ -0,0 +1,21 @@
+version: ${antora-component.version}
+prerelease: ${antora-component.prerelease}
+
+asciidoc:
+  attributes:
+    copyright-year: ${current.year}
+    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

src/main/asciidoc/index.adoc

@@ -1,50 +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-2021 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[]
-
-: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

src/main/asciidoc/preface.adoc

@@ -1,48 +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://repo.spring.io/libs-release
-* Milestone repository - https://repo.spring.io/libs-milestone
-* Snapshot repository - https://repo.spring.io/libs-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:
-
-[cols="^,^,^,^,^",options="header"]
-|===
-| Spring Data Release Train | Spring Data Elasticsearch | Elasticsearch | Spring Framework | Spring Boot
-| 2022.0 (Raj) | 4.4.x | 7.17.1 | 5.3.x | 2.7.x
-| 2021.1 (Q) | 4.3.x | 7.15.2 | 5.3.x | 2.6.x
-| 2021.0 (Pascal) | 4.2.x | 7.12.0 | 5.3.x | 2.5.x
-| 2020.0 (Ockham)footnote:oom[Out of maintenance] | 4.1.xfootnote:oom[] | 7.9.3 | 5.3.2 | 2.4.x
-| Neumannfootnote:oom[] | 4.0.xfootnote:oom[] | 7.6.2 | 5.2.12 |2.3.x
-| Moorefootnote:oom[] | 3.2.xfootnote:oom[] |6.8.12 | 5.2.12| 2.2.x
-| Lovelacefootnote:oom[] | 3.1.xfootnote:oom[] | 6.2.2 | 5.1.19 |2.1.x
-| Kayfootnote:oom[] | 3.0.xfootnote:oom[] | 5.5.0 | 5.0.13 | 2.0.x
-| Ingallsfootnote:oom[] | 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.clients.rest,high-level REST client>>.

src/main/asciidoc/reference/elasticsearch-clients.adoc

@@ -1,193 +0,0 @@
-[[elasticsearch.clients]]
-= Elasticsearch Clients
-
-This chapter illustrates configuration and usage of supported Elasticsearch client implementations.
-
-Spring Data Elasticsearch operates upon an Elasticsearch client that is connected to a single Elasticsearch node or a cluster.
-Although the Elasticsearch Client can be used to work with the cluster, applications using Spring Data Elasticsearch normally use the higher level abstractions of <<elasticsearch.operations>> and <<elasticsearch.repositories>>.
-
-[[elasticsearch.clients.rest]]
-== High Level REST Client
-
-The Java High Level REST Client is the default client of Elasticsearch, it is configured like shown:
-
-.High Level REST Client
-====
-[source,java]
-----
-@Configuration
-public class RestClientConfig extends AbstractElasticsearchConfiguration {
-
-    @Override
-    @Bean
-    public RestHighLevelClient elasticsearchClient() {
-
-        final ClientConfiguration clientConfiguration = ClientConfiguration.builder()  <1>
-            .connectedTo("localhost:9200")
-            .build();
-
-        return RestClients.create(clientConfiguration).rest();                         <2>
-    }
-}
-
-// ...
-
-  @Autowired
-  RestHighLevelClient highLevelClient;
-
-  RestClient lowLevelClient = highLevelClient.lowLevelClient();                        <3>
-
-// ...
-
-IndexRequest request = new IndexRequest("spring-data")
-  .id(randomID())
-  .source(singletonMap("feature", "high-level-rest-client"))
-  .setRefreshPolicy(IMMEDIATE);
-
-IndexResponse response = highLevelClient.index(request,RequestOptions.DEFAULT);
-----
-
-<1> Use the builder to provide cluster addresses, set default `HttpHeaders` or enable SSL.
-<2> Create the RestHighLevelClient.
-<3> It is also possible to obtain the `lowLevelRest()` client.
-====
-
-[[elasticsearch.clients.reactive]]
-== Reactive Client
-
-The `ReactiveElasticsearchClient` is a non official driver based on `WebClient`.
-It uses the request/response objects provided by the Elasticsearch core project.
-Calls are directly operated on the reactive stack, **not** wrapping async (thread pool bound) responses into reactive types.
-
-.Reactive REST Client
-====
-[source,java]
-----
-@Configuration
-public class ReactiveRestClientConfig extends AbstractReactiveElasticsearchConfiguration {
-
-    @Override
-    @Bean
-    public ReactiveElasticsearchClient reactiveElasticsearchClient() {
-        final ClientConfiguration clientConfiguration = ClientConfiguration.builder() <.>
-            .connectedTo("localhost:9200") //
-            .build();
-        return ReactiveRestClients.create(clientConfiguration);
-
-    }
-}
-// ...
-
-Mono<IndexResponse> response = client.index(request ->
-
-  request.index("spring-data")
-    .id(randomID())
-    .source(singletonMap("feature", "reactive-client"));
-);
-----
-
-<.> Use the builder to provide cluster addresses, set default `HttpHeaders` or enable SSL.
-====
-
-NOTE: The ReactiveClient response, especially for search operations, is bound to the `from` (offset) & `size` (limit) options of the request.
-
-[[elasticsearch.clients.configuration]]
-== Client Configuration
-
-Client behaviour can be changed via the `ClientConfiguration` that allows to set options for SSL, connect and socket timeouts, headers and other parameters.
-
-.Client Configuration
-====
-[source,java]
-----
-HttpHeaders httpHeaders = new HttpHeaders();
-httpHeaders.add("some-header", "on every request")                      <.>
-
-ClientConfiguration clientConfiguration = ClientConfiguration.builder()
-  .connectedTo("localhost:9200", "localhost:9291")                      <.>
-  .usingSsl()                                                           <.>
-  .withProxy("localhost:8888")                                          <.>
-  .withPathPrefix("ela")                                                <.>
-  .withConnectTimeout(Duration.ofSeconds(5))                            <.>
-  .withSocketTimeout(Duration.ofSeconds(3))                             <.>
-  .withDefaultHeaders(defaultHeaders)                                   <.>
-  .withBasicAuth(username, password)                                    <.>
-  .withHeaders(() -> {                                                  <.>
-    HttpHeaders headers = new HttpHeaders();
-    headers.add("currentTime", LocalDateTime.now().format(DateTimeFormatter.ISO_LOCAL_DATE_TIME));
-    return headers;
-  })
-  .withClientConfigurer(                                                <.>
-    ReactiveRestClients.WebClientConfigurationCallback.from(webClient -> {
-  	  // ...
-      return webClient;
-  	}))
-  .withClientConfigurer(                                                <.>
-    RestClients.RestClientConfigurationCallback.from(clientBuilder -> {
-  	  // ...
-      return clientBuilder;
-  	}))
-  . // ... other options
-  .build();
-
-----
-
-<.> Define default headers, if they need to be customized
-<.> Use the builder to provide cluster addresses, set default `HttpHeaders` or enable SSL.
-<.> Optionally enable SSL.
-<.> Optionally set a proxy.
-<.> Optionally set a path prefix, mostly used when different clusters a behind some reverse proxy.
-<.> Set the connection timeout.
-Default is 10 sec.
-<.> Set the socket timeout.
-Default is 5 sec.
-<.> Optionally set headers.
-<.> Add basic authentication.
-<.> A `Supplier<Header>` function can be specified which is called every time before a request is sent to Elasticsearch - here, as an example, the current time is written in a header.
-<.> for reactive setup a function configuring the `WebClient`
-<.> for non-reactive setup a function configuring the REST client
-====
-
-IMPORTANT: Adding a Header supplier as shown in above example allows to inject headers that may change over the time, like authentication JWT tokens.
-If this is used in the reactive setup, the supplier function *must not* block!
-
-=== Elasticsearch 7 compatibility headers
-
-When using Spring Data Elasticsearch 4 - which uses the Elasticsearch 7 client libraries - and accessing an Elasticsearch cluster that is running on version 8, it is necessary to set the compatibility headers
-https://www.elastic.co/guide/en/elasticsearch/reference/8.0/rest-api-compatibility.html[see Elasticsearch 
-documentation].
-
-For the imperative client this must be done by setting the default headers, for the reactive code this must be done using a header supplier:
-
-====
-[source,java]
-----
-
-HttpHeaders compatibilityHeaders = new HttpHeaders();
-compatibilityHeaders.add("Accept", "application/vnd.elasticsearch+json;compatible-with=7");
-compatibilityHeaders.add("Content-Type", "application/vnd.elasticsearch+json;"
-    + "compatible-with=7");
-
-ClientConfiguration clientConfiguration = ClientConfiguration.builder()
-    .connectedTo("localhost:9200")
-    .withProxy("localhost:8080")
-    .withBasicAuth("elastic","hcraescitsale")
-    .withDefaultHeaders(compatibilityHeaders)    // this variant for imperative code
-    .withHeaders(() -> compatibilityHeaders)     // this variant for reactive code
-    .build();
-		
-----
-====
-
-[[elasticsearch.clients.logging]]
-== Client Logging
-
-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.
-
-.Enable transport layer logging
-[source,xml]
-----
-<logger name="org.springframework.data.elasticsearch.client.WIRE" level="trace"/>
-----
-
-NOTE: The above applies to both the `RestHighLevelClient` and `ReactiveElasticsearchClient` when obtained via `RestClients` respectively `ReactiveRestClients`.

src/main/asciidoc/reference/elasticsearch-misc.adoc

@@ -1,263 +0,0 @@
-[[elasticsearch.misc]]
-= Miscellaneous Elasticsearch Operation Support
-
-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>> .
-
-[[elasticsearc.misc.index.settings]]
-== Index settings
-
-When creating Elasticsearch indices with Spring Data Elasticsearch different index settings can be defined by using the `@Setting` annotation.
-The following arguments are available:
-
-* `useServerConfiguration` does not send any settings parameters, so the Elasticsearch server configuration determines them.
-* `settingPath` refers to a JSON file defining the settings that must be resolvable in the classpath
-* `shards` the number of shards to use, defaults to _1_
-* `replicas` the number of replicas, defaults to _1_
-* `refreshIntervall`, defaults to _"1s"_
-* `indexStoreType`, defaults to _"fs"_
-
-
-It is as well possible to define https://www.elastic.co/guide/en/elasticsearch/reference/7.11/index-modules-index-sorting.html[index sorting] (check the linked Elasticsearch documentation for the possible field types and values):
-
-====
-[source,java]
-----
-@Document(indexName = "entities")
-@Setting(
-  sortFields = { "secondField", "firstField" },                                  <.>
-  sortModes = { Setting.SortMode.max, Setting.SortMode.min },                    <.>
-  sortOrders = { Setting.SortOrder.desc, Setting.SortOrder.asc },
-  sortMissingValues = { Setting.SortMissing._last, Setting.SortMissing._first })
-class Entity {
-    @Nullable
-    @Id private String id;
-
-    @Nullable
-    @Field(name = "first_field", type = FieldType.Keyword)
-    private String firstField;
-
-    @Nullable @Field(name = "second_field", type = FieldType.Keyword)
-    private String secondField;
-
-    // getter and setter...
-}
-----
-
-<.> when defining sort fields, use the name of the Java property (_firstField_), not the name that might be defined for Elasticsearch (_first_field_)
-<.> `sortModes`, `sortOrders` and `sortMissingValues` are optional, but if they are set, the number of entries must match the number of `sortFields` elements
-====
-
-[[elasticsearch.misc.mappings]]
-== 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.
-In addition to that it is possible to add the `@Mapping` annotation to a class.
-This annotation has the following properties:
-
-* `mappingPath` a classpath resource in JSON format; if this is not empty it is used as the mapping, no other mapping processing is done.
-* `enabled`  when set to false, this flag is written to the mapping and no further processing is done.
-* `dateDetection` and `numericDetection` set the corresponding properties in the mapping when not set to `DEFAULT`.
-* `dynamicDateFormats` when this String array is not empty, it defines the date formats used for automatic date detection.
-* `runtimeFieldsPath` a classpath resource in JSON format containing the definition of runtime fields which is written to the index mappings, for example:
-
-====
-[source,json]
-----
-{
-  "day_of_week": {
-    "type": "keyword",
-    "script": {
-      "source": "emit(doc['@timestamp'].value.dayOfWeekEnum.getDisplayName(TextStyle.FULL, Locale.ROOT))"
-    }
-  }
-}
-----
-====
-
-[[elasticsearch.misc.filter]]
-== Filter Builder
-
-Filter Builder improves query speed.
-
-====
-[source,java]
-----
-private ElasticsearchOperations operations;
-
-IndexCoordinates index = IndexCoordinates.of("sample-index");
-
-SearchQuery searchQuery = new NativeSearchQueryBuilder()
-  .withQuery(matchAllQuery())
-  .withFilter(boolFilter().must(termFilter("id", documentId)))
-  .build();
-
-Page<SampleEntity> sampleEntities = operations.searchForPage(searchQuery, SampleEntity.class, index);
-----
-====
-
-[[elasticsearch.scroll]]
-== Using Scroll For Big Result Set
-
-Elasticsearch has a scroll API for getting big result set in chunks.
-This is internally used by Spring Data Elasticsearch to provide the implementations of the `<T> SearchHitsIterator<T> SearchOperations.searchForStream(Query query, Class<T> clazz, IndexCoordinates index)` method.
-
-====
-[source,java]
-----
-IndexCoordinates index = IndexCoordinates.of("sample-index");
-
-SearchQuery searchQuery = new NativeSearchQueryBuilder()
-  .withQuery(matchAllQuery())
-  .withFields("message")
-  .withPageable(PageRequest.of(0, 10))
-  .build();
-
-SearchHitsIterator<SampleEntity> stream = elasticsearchTemplate.searchForStream(searchQuery, SampleEntity.class, index);
-
-List<SampleEntity> sampleEntities = new ArrayList<>();
-while (stream.hasNext()) {
-  sampleEntities.add(stream.next());
-}
-
-stream.close();
-----
-====
-
-There are no methods in the `SearchOperations` API to access the scroll id, if it should be necessary to access this, the following methods of the `ElasticsearchRestTemplate` can be used:
-
-====
-[source,java]
-----
-
-@Autowired ElasticsearchRestTemplate template;
-
-IndexCoordinates index = IndexCoordinates.of("sample-index");
-
-SearchQuery searchQuery = new NativeSearchQueryBuilder()
-  .withQuery(matchAllQuery())
-  .withFields("message")
-  .withPageable(PageRequest.of(0, 10))
-  .build();
-
-SearchScrollHits<SampleEntity> scroll = template.searchScrollStart(1000, searchQuery, SampleEntity.class, index);
-
-String scrollId = scroll.getScrollId();
-List<SampleEntity> sampleEntities = new ArrayList<>();
-while (scroll.hasSearchHits()) {
-  sampleEntities.addAll(scroll.getSearchHits());
-  scrollId = scroll.getScrollId();
-  scroll = template.searchScrollContinue(scrollId, 1000, SampleEntity.class);
-}
-template.searchScrollClear(scrollId);
-----
-====
-
-To use the Scroll API with repository methods, the return type must defined as `Stream` in the Elasticsearch Repository.
-The implementation of the method will then use the scroll methods from the ElasticsearchTemplate.
-
-====
-[source,java]
-----
-interface SampleEntityRepository extends Repository<SampleEntity, String> {
-
-    Stream<SampleEntity> findBy();
-
-}
-----
-====
-
-[[elasticsearch.misc.sorts]]
-== 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`.
-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.
-
-If the class to be retrieved has a `GeoPoint` property named _location_, the following `Sort` would sort the results by distance to the given point:
-
-====
-[source,java]
-----
-Sort.by(new GeoDistanceOrder("location", new GeoPoint(48.137154, 11.5761247)))
-----
-====
-
-[[elasticsearch.misc.runtime-fields]]
-== Runtime Fields
-
-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:
-
-=== 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).
-To use this approach in Spring Data Elasticsearch the user must provide a JSON file that contains the corresponding definition, for example:
-
-.runtime-fields.json
-====
-[source,json]
-----
-{
-  "day_of_week": {
-    "type": "keyword",
-    "script": {
-      "source": "emit(doc['@timestamp'].value.dayOfWeekEnum.getDisplayName(TextStyle.FULL, Locale.ROOT))"
-    }
-  }
-}
-----
-====
-
-The path to this JSON file, which must be present on the classpath, must then be set in the `@Mapping` annotation of the entity:
-
-====
-[source,java]
-----
-@Document(indexName = "runtime-fields")
-@Mapping(runtimeFieldsPath = "/runtime-fields.json")
-public class RuntimeFieldEntity {
-	// properties, getter, setter,...
-}
-
-----
-====
-
-=== Runtime fields definitions set on a Query
-
-The second way to define runtime fields is by adding the definitions to a search query (see https://www.elastic.co/guide/en/elasticsearch/reference/7.12/runtime-search-request.html).
-The following code example shows how to do this with Spring Data Elasticsearch :
-
-The entity used is a simple object that has a `price` property:
-
-====
-[source,java]
-----
-@Document(indexName = "some_index_name")
-public class SomethingToBuy {
-
-	private @Id @Nullable String id;
-	@Nullable @Field(type = FieldType.Text) private String description;
-	@Nullable @Field(type = FieldType.Double) private Double price;
-
-	// getter and setter
-}
-
-----
-====
-
-The following query uses a runtime field that calculates a `priceWithTax` value by adding 19% to the price and uses this value in the search query to find all entities where `priceWithTax` is higher or equal than a given value:
-
-====
-[source,java]
-----
-RuntimeField runtimeField = new RuntimeField("priceWithTax", "double", "emit(doc['price'].value * 1.19)");
-Query query = new CriteriaQuery(new Criteria("priceWithTax").greaterThanEqual(16.5));
-query.addRuntimeField(runtimeField);
-
-SearchHits<SomethingToBuy> searchHits = operations.search(query, SomethingToBuy.class);
-----
-====
-
-This works with every implementation of the `Query` interface.

src/main/asciidoc/reference/elasticsearch-new.adoc

@@ -1,60 +0,0 @@
-[[new-features]]
-= What's new
-
-[[new-features.4-4-0]]
-== New in Spring Data Elasticsearch 4.4
-
-* Introduction of new imperative and reactive clients using the classes from the new Elasticsearch Java client
-* Upgrade to Elasticsearch 7.17.1.
-
-[[new-features.4-3-0]]
-== New in Spring Data Elasticsearch 4.3
-
-* Upgrade to Elasticsearch 7.15.2.
-* Allow runtime_fields to be defined in the index mapping.
-* Add native support for range field types by using a range object.
-* Add repository search for nullable or empty properties.
-* Enable custom converters for single fields.
-* Supply a custom `Sort.Order` providing Elasticsearch specific parameters.
-
-[[new-features.4-2-0]]
-== New in Spring Data Elasticsearch 4.2
-
-* Upgrade to Elasticsearch 7.10.0.
-* Support for custom routing values
-
-[[new-features.4-1-0]]
-== New in Spring Data Elasticsearch 4.1
-
-* Uses Spring 5.3.
-* Upgrade to Elasticsearch 7.9.3.
-* Improved API for alias management.
-* Introduction of `ReactiveIndexOperations` for index management.
-* Index templates support.
-* Support for Geo-shape data with GeoJson.
-
-[[new-features.4-0-0]]
-== New in Spring Data Elasticsearch 4.0
-
-* Uses Spring 5.2.
-* Upgrade to Elasticsearch 7.6.2.
-* Deprecation of `TransportClient` usage.
-* Implements most of the mapping-types available for the index mappings.
-* Removal of the Jackson `ObjectMapper`, now using the <<elasticsearch.mapping.meta-model,MappingElasticsearchConverter>>
-* Cleanup of the API in the `*Operations` interfaces, grouping and renaming methods so that they match the Elasticsearch API, deprecating the old methods, aligning with other Spring Data modules.
-* Introduction of `SearchHit<T>` class to represent a found document together with the relevant result metadata for this document (i.e. _sortValues_).
-* Introduction of the `SearchHits<T>` class to represent a whole search result together with the metadata for the complete search result (i.e. _max_score_).
-* Introduction of `SearchPage<T>` class to represent a paged result containing a `SearchHits<T>` instance.
-* Introduction of the `GeoDistanceOrder` class to be able to create sorting by geographical distance
-* Implementation of Auditing Support
-* Implementation of lifecycle entity callbacks
-
-[[new-features.3-2-0]]
-== New in Spring Data Elasticsearch 3.2
-
-* Secured Elasticsearch cluster support with Basic Authentication and SSL transport.
-* Upgrade to Elasticsearch 6.8.1.
-* Reactive programming support with <<elasticsearch.reactive.operations>> and <<elasticsearch.reactive.repositories>>.
-* Introduction of the <<elasticsearch.mapping.meta-model,ElasticsearchEntityMapper>> as an alternative to the Jackson `ObjectMapper`.
-* Field name customization in `@Field`.
-* Support for Delete by Query.

src/main/asciidoc/reference/migration-guides.adoc

@@ -1,15 +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[]
-:leveloffset: -1

src/main/asciidoc/reference/reactive-elasticsearch-operations.adoc

@@ -1,124 +0,0 @@
-[[elasticsearch.reactive.operations]]
-= Reactive Elasticsearch Operations
-
-`ReactiveElasticsearchOperations` is the gateway to executing high level commands against an Elasticsearch cluster using the `ReactiveElasticsearchClient`.
-
-The `ReactiveElasticsearchTemplate` is the default implementation of `ReactiveElasticsearchOperations`.
-
-[[elasticsearch.reactive.template]]
-== Reactive Elasticsearch Template
-
-To get started the `ReactiveElasticsearchTemplate` needs to know about the actual client to work with.
-Please see <<elasticsearch.clients.reactive>> for details on the client.
-
-[[elasticsearch.reactive.template.configuration]]
-=== Reactive Template Configuration
-
-The easiest way of setting up the `ReactiveElasticsearchTemplate` is via `AbstractReactiveElasticsearchConfiguration` providing
-dedicated configuration method hooks for `base package`, the `initial entity set` etc.
-
-.The AbstractReactiveElasticsearchConfiguration
-====
-[source,java]
-----
-@Configuration
-public class Config extends AbstractReactiveElasticsearchConfiguration {
-
-  @Bean <1>
-  @Override
-  public ReactiveElasticsearchClient reactiveElasticsearchClient() {
-      // ...
-  }
-}
-----
-<1> Configure the client to use. This can be done by `ReactiveRestClients` or directly via `DefaultReactiveElasticsearchClient`.
-====
-
-NOTE: If applicable set default `HttpHeaders` via the `ClientConfiguration` of the `ReactiveElasticsearchClient`. See <<elasticsearch.clients.configuration>>.
-
-TIP: If needed the `ReactiveElasticsearchTemplate` can be configured with default `RefreshPolicy` and `IndicesOptions` that get applied to the related requests by overriding the defaults of `refreshPolicy()` and `indicesOptions()`.
-
-However one might want to be more in control over the actual components and use a more verbose approach.
-
-.Configure the ReactiveElasticsearchTemplate
-====
-[source,java]
-----
-@Configuration
-public class Config {
-
-  @Bean <1>
-  public ReactiveElasticsearchClient reactiveElasticsearchClient() {
-    // ...
-  }
-  @Bean <2>
-  public ElasticsearchConverter elasticsearchConverter() {
-    return new MappingElasticsearchConverter(elasticsearchMappingContext());
-  }
-  @Bean <3>
-  public SimpleElasticsearchMappingContext elasticsearchMappingContext() {
-    return new SimpleElasticsearchMappingContext();
-  }
-  @Bean <4>
-  public ReactiveElasticsearchOperations reactiveElasticsearchOperations() {
-    return new ReactiveElasticsearchTemplate(reactiveElasticsearchClient(), elasticsearchConverter());
-  }
-}
-----
-<1> Configure the client to use. This can be done by `ReactiveRestClients` or directly via `DefaultReactiveElasticsearchClient`.
-<2> Set up the `ElasticsearchConverter` used for domain type mapping utilizing metadata provided by the mapping context.
-<3> The Elasticsearch specific mapping context for domain type metadata.
-<4> The actual template based on the client and conversion infrastructure.
-====
-
-[[elasticsearch.reactive.template.usage]]
-=== Reactive Template Usage
-
-`ReactiveElasticsearchTemplate` lets you save, find and delete your domain objects and map those objects to documents stored in Elasticsearch.
-
-Consider the following:
-
-.Use the ReactiveElasticsearchTemplate
-====
-[source,java]
-----
-@Document(indexName = "marvel")
-public class Person {
-
-  private @Id String id;
-  private String name;
-  private int age;
-  // Getter/Setter omitted...
-}
-----
-
-[source,java]
-----
-template.save(new Person("Bruce Banner", 42))                    <1>
-  .doOnNext(System.out::println)
-  .flatMap(person -> template.findById(person.id, Person.class)) <2>
-  .doOnNext(System.out::println)
-  .flatMap(person -> template.delete(person))                    <3>
-  .doOnNext(System.out::println)
-  .flatMap(id -> template.count(Person.class))                   <4>
-  .doOnNext(System.out::println)
-  .subscribe(); <5>
-----
-
-The above outputs the following sequence on the console.
-
-[source,text]
-----
-> Person(id=QjWCWWcBXiLAnp77ksfR, name=Bruce Banner, age=42)
-> Person(id=QjWCWWcBXiLAnp77ksfR, name=Bruce Banner, age=42)
-> QjWCWWcBXiLAnp77ksfR
-> 0
-----
-<1> Insert a new `Person` document into the _marvel_ index under type _characters_. The `id` is generated on server side and set into the instance returned.
-<2> Lookup the `Person` with matching `id` in the _marvel_ index under type _characters_.
-<3> Delete the `Person` with matching `id`, extracted from the given instance, in the _marvel_ index under type _characters_.
-<4> Count the total number of documents in the _marvel_ index under type _characters_.
-<5> Don't forget to _subscribe()_.
-====
-
-

src/main/java/org/springframework/data/elasticsearch/BulkFailureException.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2022 the original author or authors.
+ * Copyright 2020-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -21,17 +21,27 @@ import java.util.Map;
 
 /**
  * @author Peter-Josef Meisch
+ * @author Illia Ulianov
  * @since 4.1
  */
 public class BulkFailureException extends DataRetrievalFailureException {
-	private final Map<String, String> failedDocuments;
+	private final Map<String, FailureDetails> failedDocuments;
 
-	public BulkFailureException(String msg, Map<String, String> failedDocuments) {
+	public BulkFailureException(String msg, Map<String, FailureDetails> failedDocuments) {
 		super(msg);
 		this.failedDocuments = failedDocuments;
 	}
 
-	public Map<String, String> getFailedDocuments() {
+	public Map<String, FailureDetails> getFailedDocuments() {
 		return failedDocuments;
 	}
+
+	/**
+	 * Details about a document saving failure.
+	 *
+	 * @author Illia Ulianov
+	 * @since 5.2
+	 */
+	public record FailureDetails(Integer status, String errorMessage) {
+	}
 }

src/main/java/org/springframework/data/elasticsearch/ElasticsearchErrorCause.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2022 the original author or authors.
+ * Copyright 2022-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -17,7 +17,7 @@ package org.springframework.data.elasticsearch;
 
 import java.util.List;
 
-import javax.annotation.Nullable;
+import org.jspecify.annotations.Nullable;
 
 /**
  * Object describing an Elasticsearch error

src/main/java/org/springframework/data/elasticsearch/NoSuchIndexException.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2019-2022 the original author or authors.
+ * Copyright 2019-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -25,6 +25,14 @@ public class NoSuchIndexException extends NonTransientDataAccessResourceExceptio
 
 	private final String index;
 
+	/**
+	 * @since 4.4
+	 */
+	public NoSuchIndexException(String index) {
+		super(String.format("Index %s not found.", index));
+		this.index = index;
+	}
+
 	public NoSuchIndexException(String index, Throwable cause) {
 		super(String.format("Index %s not found.", index), cause);
 		this.index = index;

src/main/java/org/springframework/data/elasticsearch/ResourceFailureException.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2021-2022 the original author or authors.
+ * Copyright 2021-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/main/java/org/springframework/data/elasticsearch/ResourceNotFoundException.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2021-2022 the original author or authors.
+ * Copyright 2022-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -15,20 +15,15 @@
  */
 package org.springframework.data.elasticsearch;
 
+import org.springframework.dao.NonTransientDataAccessResourceException;
+
 /**
- * TODO #1973 remove when the new Elasticsearch client is fully working
- *
  * @author Peter-Josef Meisch
+ * @since 5.1
  */
-public interface NewElasticsearchClientDevelopment {
+public class ResourceNotFoundException extends NonTransientDataAccessResourceException {
 
-	boolean forceEnable = false;
-
-	default boolean usesNewElasticsearchClient() {
-		return false;
-	}
-
-	default boolean newElasticsearchClient() {
-		return !forceEnable && usesNewElasticsearchClient();
+	public ResourceNotFoundException(String msg) {
+		super(msg);
 	}
 }

src/main/java/org/springframework/data/elasticsearch/RestStatusException.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2021-2022 the original author or authors.
+ * Copyright 2021-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/main/java/org/springframework/data/elasticsearch/UncategorizedElasticsearchException.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2022 the original author or authors.
+ * Copyright 2020-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -15,8 +15,8 @@
  */
 package org.springframework.data.elasticsearch;
 
+import org.jspecify.annotations.Nullable;
 import org.springframework.dao.UncategorizedDataAccessException;
-import org.springframework.lang.Nullable;
 
 /**
  * @author Peter-Josef Meisch

src/main/java/org/springframework/data/elasticsearch/VersionConflictException.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2023-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.data.elasticsearch;
+
+import org.springframework.dao.DataIntegrityViolationException;
+
+/**
+ * Exception that is thrown when a version conflict from the server is detected.
+ *
+ * @author Peter-Josef Meisch
+ * @since 5.2
+ */
+public class VersionConflictException extends DataIntegrityViolationException {
+	public VersionConflictException(String msg) {
+		super(msg);
+	}
+
+	public VersionConflictException(String msg, Throwable cause) {
+		super(msg, cause);
+	}
+}

src/main/java/org/springframework/data/elasticsearch/annotations/Alias.java

@@ -0,0 +1,79 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.data.elasticsearch.annotations;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Repeatable;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.springframework.core.annotation.AliasFor;
+
+/**
+ * Identifies an alias for the index.
+ *
+ * @author Youssef Aouichaoui
+ * @since 5.4
+ */
+@Inherited
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ ElementType.TYPE })
+@Repeatable(Aliases.class)
+public @interface Alias {
+	/**
+	 * @return Index alias name. Alias for {@link #alias}.
+	 */
+	@AliasFor("alias")
+	String value() default "";
+
+	/**
+	 * @return Index alias name. Alias for {@link #value}.
+	 */
+	@AliasFor("value")
+	String alias() default "";
+
+	/**
+	 * @return Query used to limit documents the alias can access.
+	 */
+	Filter filter() default @Filter;
+
+	/**
+	 * @return Used to route indexing operations to a specific shard.
+	 */
+	String indexRouting() default "";
+
+	/**
+	 * @return Used to route indexing and search operations to a specific shard.
+	 */
+	String routing() default "";
+
+	/**
+	 * @return Used to route search operations to a specific shard.
+	 */
+	String searchRouting() default "";
+
+	/**
+	 * @return Is the alias hidden?
+	 */
+	boolean isHidden() default false;
+
+	/**
+	 * @return Is it the 'write index' for the alias?
+	 */
+	boolean isWriteIndex() default false;
+}

src/main/java/org/springframework/data/elasticsearch/annotations/Aliases.java

@@ -0,0 +1,36 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.data.elasticsearch.annotations;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Container annotation that aggregates several {@link Alias} annotations.
+ *
+ * @author Youssef Aouichaoui
+ * @see Alias
+ * @since 5.4
+ */
+@Inherited
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ ElementType.TYPE })
+public @interface Aliases {
+	Alias[] value();
+}

src/main/java/org/springframework/data/elasticsearch/annotations/CompletionContext.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2019-2022 the original author or authors.
+ * Copyright 2019-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/main/java/org/springframework/data/elasticsearch/annotations/CompletionField.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2013-2022 the original author or authors.
+ * Copyright 2013-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/main/java/org/springframework/data/elasticsearch/annotations/CountQuery.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2021-2022 the original author or authors.
+ * Copyright 2021-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/main/java/org/springframework/data/elasticsearch/annotations/DateFormat.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2014-2022 the original author or authors.
+ * Copyright 2014-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -16,9 +16,11 @@
 package org.springframework.data.elasticsearch.annotations;
 
 /**
- * Values based on reference doc - https://www.elastic.co/guide/reference/mapping/date-format/. The patterns are taken
- * from this documentation and slightly adapted so that a Java {@link java.time.format.DateTimeFormatter} produces the
- * same values as the Elasticsearch formatter.
+ * Values based on <a href="https://www.elastic.co/guide/reference/mapping/date-format/">Elasticsearch reference
+ * documentation</a>. The patterns are taken from this documentation and slightly adapted so that a Java
+ * {@link java.time.format.DateTimeFormatter} produces the same values as the Elasticsearch formatter. Use
+ * <code>format = {}</code> to disable built-in date formats in the {@link Field} annotation. If you want to use only a
+ * custom date format pattern, you must set the <code>format</code> property to empty <code>{}</code>.
  *
  * @author Jakub Vavrik
  * @author Tim te Beek
@@ -26,19 +28,6 @@ package org.springframework.data.elasticsearch.annotations;
  * @author Sascha Woo
  */
 public enum DateFormat {
-	/**
-	 * @deprecated since 4.2, will be removed in a future version. Use <code>format = {}</code> to disable built-in date
-	 *             formats in the @Field annotation.
-	 */
-	@Deprecated
-	none(""), //
-	/**
-	 * @deprecated since 4.2, will be removed in a future version.It is no longer required for using a custom date format
-	 *             pattern. If you want to use only a custom date format pattern, you must set the <code>format</code>
-	 *             property to empty <code>{}</code>.
-	 */
-	@Deprecated
-	custom(""), //
 	basic_date("uuuuMMdd"), //
 	basic_date_time("uuuuMMdd'T'HHmmss.SSSXXX"), //
 	basic_date_time_no_millis("uuuuMMdd'T'HHmmssXXX"), //
@@ -50,40 +39,173 @@ public enum DateFormat {
 	basic_t_time("'T'HHmmss.SSSXXX"), //
 	basic_t_time_no_millis("'T'HHmmssXXX"), //
 	basic_week_date("YYYY'W'wwe"), // week-based-year!
+	/**
+	 * @since 5.3
+	 */
+	strict_basic_week_date("YYYY'W'wwe"), // week-based-year!
 	basic_week_date_time("YYYY'W'wwe'T'HHmmss.SSSX"), // here Elasticsearch uses a different zone format
+	/**
+	 * @since 5.3
+	 */
+	strict_basic_week_date_time("YYYY'W'wwe'T'HHmmss.SSSX"), // here Elasticsearch uses a different zone format
 	basic_week_date_time_no_millis("YYYY'W'wwe'T'HHmmssX"), //
+	/**
+	 * @since 5.3
+	 */
+	strict_basic_week_date_time_no_millis("YYYY'W'wwe'T'HHmmssX"), //
 	date("uuuu-MM-dd"), //
+	/**
+	 * @since 5.3
+	 */
+	strict_date("uuuu-MM-dd"), //
 	date_hour("uuuu-MM-dd'T'HH"), //
+	/**
+	 * @since 5.3
+	 */
+	strict_date_hour("uuuu-MM-dd'T'HH"), //
 	date_hour_minute("uuuu-MM-dd'T'HH:mm"), //
+	/**
+	 * @since 5.3
+	 */
+	strict_date_hour_minute("uuuu-MM-dd'T'HH:mm"), //
 	date_hour_minute_second("uuuu-MM-dd'T'HH:mm:ss"), //
+	/**
+	 * @since 5.3
+	 */
+	strict_date_hour_minute_second("uuuu-MM-dd'T'HH:mm:ss"), //
 	date_hour_minute_second_fraction("uuuu-MM-dd'T'HH:mm:ss.SSS"), //
+	/**
+	 * @since 5.3
+	 */
+	strict_date_hour_minute_second_fraction("uuuu-MM-dd'T'HH:mm:ss.SSS"), //
 	date_hour_minute_second_millis("uuuu-MM-dd'T'HH:mm:ss.SSS"), //
+	/**
+	 * @since 5.3
+	 */
+	strict_date_hour_minute_second_millis("uuuu-MM-dd'T'HH:mm:ss.SSS"), //
 	date_optional_time("uuuu-MM-dd['T'HH:mm:ss.SSSXXX]"), //
+	/**
+	 * @since 5.3
+	 */
+	strict_date_optional_time("uuuu-MM-dd['T'HH:mm:ss.SSSXXX]"), //
+	strict_date_optional_time_nanos("uuuu-MM-dd['T'HH:mm:ss.SSSSSSXXX]"), //
 	date_time("uuuu-MM-dd'T'HH:mm:ss.SSSXXX"), //
-	date_time_no_millis("uuuu-MM-dd'T'HH:mm:ssVV"), // here Elasticsearch uses the zone-id in it's implementation
+	/**
+	 * @since 5.3
+	 */
+	strict_date_time("uuuu-MM-dd'T'HH:mm:ss.SSSXXX"), //
+	date_time_no_millis("uuuu-MM-dd'T'HH:mm:ssVV"), // here Elasticsearch uses the zone-id in its implementation
+	/**
+	 * @since 5.3
+	 */
+	strict_date_time_no_millis("uuuu-MM-dd'T'HH:mm:ssVV"), // here Elasticsearch uses the zone-id in its implementation
 	epoch_millis("epoch_millis"), //
 	epoch_second("epoch_second"), //
 	hour("HH"), //
+	/**
+	 * @since 5.3
+	 */
+	strict_hour("HH"), //
 	hour_minute("HH:mm"), //
+	/**
+	 * @since 5.3
+	 */
+	strict_hour_minute("HH:mm"), //
 	hour_minute_second("HH:mm:ss"), //
+	/**
+	 * @since 5.3
+	 */
+	strict_hour_minute_second("HH:mm:ss"), //
 	hour_minute_second_fraction("HH:mm:ss.SSS"), //
+	/**
+	 * @since 5.3
+	 */
+	strict_hour_minute_second_fraction("HH:mm:ss.SSS"), //
 	hour_minute_second_millis("HH:mm:ss.SSS"), //
+	/**
+	 * @since 5.3
+	 */
+	strict_hour_minute_second_millis("HH:mm:ss.SSS"), //
 	ordinal_date("uuuu-DDD"), //
+	/**
+	 * @since 5.3
+	 */
+	strict_ordinal_date("uuuu-DDD"), //
 	ordinal_date_time("uuuu-DDD'T'HH:mm:ss.SSSXXX"), //
+	/**
+	 * @since 5.3
+	 */
+	strict_ordinal_date_time("uuuu-DDD'T'HH:mm:ss.SSSXXX"), //
 	ordinal_date_time_no_millis("uuuu-DDD'T'HH:mm:ssXXX"), //
+	/**
+	 * @since 5.3
+	 */
+	strict_ordinal_date_time_no_millis("uuuu-DDD'T'HH:mm:ssXXX"), //
 	time("HH:mm:ss.SSSXXX"), //
+	/**
+	 * @since 5.3
+	 */
+	strict_time("HH:mm:ss.SSSXXX"), //
 	time_no_millis("HH:mm:ssXXX"), //
+	/**
+	 * @since 5.3
+	 */
+	strict_time_no_millis("HH:mm:ssXXX"), //
 	t_time("'T'HH:mm:ss.SSSXXX"), //
+	/**
+	 * @since 5.3
+	 */
+	strict_t_time("'T'HH:mm:ss.SSSXXX"), //
 	t_time_no_millis("'T'HH:mm:ssXXX"), //
+	/**
+	 * @since 5.3
+	 */
+	strict_t_time_no_millis("'T'HH:mm:ssXXX"), //
 	week_date("YYYY-'W'ww-e"), //
+	/**
+	 * @since 5.3
+	 */
+	strict_week_date("YYYY-'W'ww-e"), //
 	week_date_time("YYYY-'W'ww-e'T'HH:mm:ss.SSSXXX"), //
+	/**
+	 * @since 5.3
+	 */
+	strict_week_date_time("YYYY-'W'ww-e'T'HH:mm:ss.SSSXXX"), //
 	week_date_time_no_millis("YYYY-'W'ww-e'T'HH:mm:ssXXX"), //
+	/**
+	 * @since 5.3
+	 */
+	strict_week_date_time_no_millis("YYYY-'W'ww-e'T'HH:mm:ssXXX"), //
 	weekyear(""), // no TemporalAccessor available for these 3
+	/**
+	 * @since 5.3
+	 */
+	strict_weekyear(""), // no TemporalAccessor available for these 3
 	weekyear_week(""), //
+	/**
+	 * @since 5.3
+	 */
+	strict_weekyear_week(""), //
 	weekyear_week_day(""), //
+	/**
+	 * @since 5.3
+	 */
+	strict_strict_weekyear_week_day(""), //
 	year("uuuu"), //
+	/**
+	 * @since 5.3
+	 */
+	strict_year("uuuu"), //
 	year_month("uuuu-MM"), //
-	year_month_day("uuuu-MM-dd"); //
+	/**
+	 * @since 5.3
+	 */
+	strict_year_month("uuuu-MM"), //
+	year_month_day("uuuu-MM-dd"), //
+	/**
+	 * @since 5.3
+	 */
+	strict_year_month_day("uuuu-MM-dd"); //
 
 	private final String pattern;
 

src/main/java/org/springframework/data/elasticsearch/annotations/Document.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2013-2022 the original author or authors.
+ * Copyright 2013-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -53,54 +53,18 @@ public @interface Document {
 	 */
 	String indexName();
 
-	/**
-	 * Use server-side settings when creating the index.
-	 *
-	 * @deprecated since 4.2, use the {@link Setting} annotation to configure settings
-	 */
-	@Deprecated
-	boolean useServerConfiguration() default false;
-
-	/**
-	 * Number of shards for the index {@link #indexName()}. Used for index creation. <br/>
-	 * With version 4.0, the default value is changed from 5 to 1 to reflect the change in the default settings of
-	 * Elasticsearch which changed to 1 as well in Elasticsearch 7.0.
-	 * ComposableAnnotationsUnitTest.documentAnnotationShouldBeComposable:60
-	 *
-	 * @deprecated since 4.2, use the {@link Setting} annotation to configure settings
-	 */
-	@Deprecated
-	short shards() default 1;
-
-	/**
-	 * Number of replicas for the index {@link #indexName()}. Used for index creation.
-	 *
-	 * @deprecated since 4.2, use the {@link Setting} annotation to configure settings
-	 */
-	@Deprecated
-	short replicas() default 1;
-
-	/**
-	 * Refresh interval for the index {@link #indexName()}. Used for index creation.
-	 *
-	 * @deprecated since 4.2, use the {@link Setting} annotation to configure settings
-	 */
-	@Deprecated
-	String refreshInterval() default "1s";
-
-	/**
-	 * Index storage type for the index {@link #indexName()}. Used for index creation.
-	 *
-	 * @deprecated since 4.2, use the {@link Setting} annotation to configure settings
-	 */
-	@Deprecated
-	String indexStoreType() default "fs";
-
 	/**
 	 * Configuration whether to create an index on repository bootstrapping.
 	 */
 	boolean createIndex() default true;
 
+	/**
+	 * If true, the index mapping will be written on repository bootstrapping even when the index already exists. This
+	 * allows for automatically updating the mapping with new properties. Changes on existing properties will lead to an
+	 * error from the Elasticsearch server.
+	 */
+	boolean alwaysWriteMapping() default false;
+
 	/**
 	 * Configuration of version management.
 	 */
@@ -120,6 +84,29 @@ public @interface Document {
 	 */
 	Dynamic dynamic() default Dynamic.INHERIT;
 
+	/**
+	 * Specifies if the id property should also be stored in the Elasticsearch document source. Default value is
+	 * {@literal true}
+	 *
+	 * @since 5.1
+	 */
+	boolean storeIdInSource() default true;
+
+	/**
+	 * Specifies if the version property should also be stored in the Elasticsearch document source. Default value is
+	 * true.
+	 *
+	 * @since 5.1
+	 */
+	boolean storeVersionInSource() default true;
+
+	/**
+	 * Aliases for the index.
+	 *
+	 * @since 5.4
+	 */
+	Alias[] aliases() default {};
+
 	/**
 	 * @since 4.3
 	 */

src/main/java/org/springframework/data/elasticsearch/annotations/Dynamic.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2021-2022 the original author or authors.
+ * Copyright 2021-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -46,7 +46,7 @@ public enum Dynamic {
 	/**
 	 * Inherit the dynamic setting from their parent object or from the mapping type.
 	 */
-	INHERIT("nherit");
+	INHERIT("inherit");
 
 	private final String mappedName;
 

src/main/java/org/springframework/data/elasticsearch/annotations/Field.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2013-2022 the original author or authors.
+ * Copyright 2013-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -37,9 +37,11 @@ import org.springframework.core.annotation.AliasFor;
  * @author Brian Kimmig
  * @author Morgan Lutz
  * @author Sascha Woo
+ * @author Haibo Liu
+ * @author Andriy Redko
  */
 @Retention(RetentionPolicy.RUNTIME)
-@Target({ ElementType.FIELD, ElementType.ANNOTATION_TYPE })
+@Target({ ElementType.FIELD, ElementType.ANNOTATION_TYPE, ElementType.METHOD })
 @Documented
 @Inherited
 public @interface Field {
@@ -53,9 +55,8 @@ public @interface Field {
 	String value() default "";
 
 	/**
-	 * The <em>name</em> to be used to store the field inside the document.
-	 * <p>
-	 * √5 If not set, the name of the annotated property is used.
+	 * The <em>name</em> to be used to store the field inside the document. If not set, the name of the annotated property
+	 * is used.
 	 *
 	 * @since 3.2
 	 */
@@ -129,6 +130,10 @@ public @interface Field {
 	boolean norms() default true;
 
 	/**
+	 * NOte that null_value setting are not supported in Elasticsearch for all types. For example setting a null_value on
+	 * a field with type text will throw an exception in the server when the mapping is written to Elasticsearch. Alas,
+	 * the Elasticsearch documentation does not specify on which types it is allowed on which it is not.
+	 *
 	 * @since 4.0
 	 */
 	String nullValue() default "";
@@ -141,7 +146,7 @@ public @interface Field {
 	/**
 	 * @since 4.0
 	 */
-	Similarity similarity() default Similarity.Default;
+	String similarity() default Similarity.Default;
 
 	/**
 	 * @since 4.0
@@ -196,6 +201,27 @@ public @interface Field {
 	 */
 	int dims() default -1;
 
+	/**
+	 * to be used in combination with {@link FieldType#Dense_Vector}
+	 *
+	 * @since 5.4
+	 */
+	String elementType() default FieldElementType.DEFAULT;
+
+	/**
+	 * to be used in combination with {@link FieldType#Dense_Vector}
+	 *
+	 * @since 5.4
+	 */
+	KnnSimilarity knnSimilarity() default KnnSimilarity.DEFAULT;
+
+	/**
+	 * to be used in combination with {@link FieldType#Dense_Vector}
+	 *
+	 * @since 5.4
+	 */
+	KnnIndexOptions[] knnIndexOptions() default {};
+
 	/**
 	 * Controls how Elasticsearch dynamically adds fields to the inner object within the document.<br>
 	 * To be used in combination with {@link FieldType#Object} or {@link FieldType#Nested}
@@ -211,4 +237,19 @@ public @interface Field {
 	 * @since 4.3
 	 */
 	boolean excludeFromSource() default false;
+
+	/**
+	 * when this field is a {{@link String}}, a {{@link java.util.Collection}} or a {{@link java.util.Map}} that is empty
+	 * this property controlls whether the empty value is sent to Elasticsearch.
+	 *
+	 * @since 5.1
+	 */
+	boolean storeEmptyValue() default true;
+
+	/**
+	 * overrides the field type in the mapping which otherwise will be taken from corresponding {@link FieldType}
+	 *
+	 * @since 5.4
+	 */
+	String mappedTypeName() default "";
 }

src/main/java/org/springframework/data/elasticsearch/annotations/FieldElementType.java

@@ -0,0 +1,26 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.data.elasticsearch.annotations;
+
+/**
+ * @author Haibo Liu
+ * @since 5.4
+ */
+public final class FieldElementType {
+	public final static String DEFAULT = "";
+	public final static String FLOAT = "float";
+	public final static String BYTE = "byte";
+}

src/main/java/org/springframework/data/elasticsearch/annotations/FieldType.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2013-2022 the original author or authors.
+ * Copyright 2013-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -61,7 +61,31 @@ public enum FieldType {
 	/** since 4.2 */
 	Wildcard("wildcard"), //
 	/** @since 4.2 */
-	Dense_Vector("dense_vector") //
+	Dense_Vector("dense_vector"), //
+	/**
+	 * @since 5.2
+	 */
+	Constant_Keyword("constant_keyword"), //
+	/**
+	 * @since 5.2
+	 */
+	Alias("alias"), //
+	/**
+	 * @since 5.2
+	 */
+	Version("version"), //
+	/**
+	 * @since 5.2
+	 */
+	Murmur3("murmur3"), //
+	/**
+	 * @since 5.2
+	 */
+	Match_Only_Text("match_only_text"), //
+	/**
+	 * @since 5.2
+	 */
+	Annotated_Text("annotated_text") //
 	;
 
 	private final String mappedName;

src/main/java/org/springframework/data/elasticsearch/annotations/Filter.java

@@ -0,0 +1,38 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.data.elasticsearch.annotations;
+
+import org.springframework.core.annotation.AliasFor;
+
+/**
+ * Query used to limit documents.
+ *
+ * @author Youssef Aouichaoui
+ * @since 5.4
+ */
+public @interface Filter {
+	/**
+	 * @return Query used to limit documents. Alias for {@link #query}.
+	 */
+	@AliasFor("query")
+	String value() default "";
+
+	/**
+	 * @return Query used to limit documents. Alias for {@link #value}.
+	 */
+	@AliasFor("value")
+	String query() default "";
+}

src/main/java/org/springframework/data/elasticsearch/annotations/GeoPointField.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2013-2022 the original author or authors.
+ * Copyright 2013-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/main/java/org/springframework/data/elasticsearch/annotations/GeoShapeField.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2017-2022 the original author or authors.
+ * Copyright 2017-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/main/java/org/springframework/data/elasticsearch/annotations/Highlight.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2022 the original author or authors.
+ * Copyright 2020-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/main/java/org/springframework/data/elasticsearch/annotations/HighlightField.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2022 the original author or authors.
+ * Copyright 2020-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/main/java/org/springframework/data/elasticsearch/annotations/HighlightParameters.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2022 the original author or authors.
+ * Copyright 2020-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -21,6 +21,7 @@ import java.lang.annotation.RetentionPolicy;
 
 /**
  * @author Peter-Josef Meisch
+ * @author Haibo Liu
  * @since 4.0
  */
 @Documented
@@ -59,6 +60,8 @@ public @interface HighlightParameters {
 
 	int numberOfFragments() default -1;
 
+	Query highlightQuery() default @Query;
+
 	String order() default "";
 
 	int phraseLimit() default -1;

src/main/java/org/springframework/data/elasticsearch/annotations/IndexOptions.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2019-2022 the original author or authors.
+ * Copyright 2019-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/main/java/org/springframework/data/elasticsearch/annotations/IndexPrefixes.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2019-2022 the original author or authors.
+ * Copyright 2019-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/main/java/org/springframework/data/elasticsearch/annotations/IndexedIndexName.java

@@ -0,0 +1,39 @@
+/*
+ * Copyright 2023-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.data.elasticsearch.annotations;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Annotation to mark a String property of an entity to be filled with the name of the index where the entity was stored
+ * after it is indexed into Elasticsearch. This can be used when the name of the index is dynamically created or when a
+ * document was indexed into a write alias.
+ * <p>
+ * This can not be used to specify the index where an entity should be written to.
+ *
+ * @author Peter-Josef Meisch
+ * @since 5.1
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ ElementType.FIELD, ElementType.ANNOTATION_TYPE })
+@Documented
+@Field(type = FieldType.Auto) // prevents the property being written to the index mapping
+public @interface IndexedIndexName {
+}

src/main/java/org/springframework/data/elasticsearch/annotations/InnerField.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2014-2022 the original author or authors.
+ * Copyright 2014-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -29,6 +29,8 @@ import java.lang.annotation.Target;
  * @author Aleksei Arsenev
  * @author Brian Kimmig
  * @author Morgan Lutz
+ * @author Haibo Liu
+ * @author Andriy Redko
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.ANNOTATION_TYPE)
@@ -109,7 +111,7 @@ public @interface InnerField {
 	/**
 	 * @since 4.0
 	 */
-	Similarity similarity() default Similarity.Default;
+	String similarity() default Similarity.Default;
 
 	/**
 	 * @since 4.0
@@ -149,4 +151,32 @@ public @interface InnerField {
 	 * @since 4.2
 	 */
 	int dims() default -1;
+
+	/**
+	 * to be used in combination with {@link FieldType#Dense_Vector}
+	 *
+	 * @since 5.4
+	 */
+	String elementType() default FieldElementType.DEFAULT;
+
+	/**
+	 * to be used in combination with {@link FieldType#Dense_Vector}
+	 *
+	 * @since 5.4
+	 */
+	KnnSimilarity knnSimilarity() default KnnSimilarity.DEFAULT;
+
+	/**
+	 * to be used in combination with {@link FieldType#Dense_Vector}
+	 *
+	 * @since 5.4
+	 */
+	KnnIndexOptions[] knnIndexOptions() default {};
+
+	/**
+	 * overrides the field type in the mapping which otherwise will be taken from corresponding {@link FieldType}
+	 *
+	 * @since 5.4
+	 */
+	String mappedTypeName() default "";
 }

src/main/java/org/springframework/data/elasticsearch/annotations/JoinTypeRelation.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2022 the original author or authors.
+ * Copyright 2020-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/main/java/org/springframework/data/elasticsearch/annotations/JoinTypeRelations.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2022 the original author or authors.
+ * Copyright 2020-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.