documentation modification

Author: puppylpg

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

@@ -6,6 +6,17 @@ This section describes breaking changes from version 5.3.x to 5.4.x and how remo
 [[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
 

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

@@ -199,21 +199,21 @@
 	/**
 	 * to be used in combination with {@link FieldType#Dense_Vector}
 	 *
-	 * @since 5.3.1
+	 * @since 5.4
 	 */
 	String elementType() default FieldElementType.DEFAULT;
 
 	/**
 	 * to be used in combination with {@link FieldType#Dense_Vector}
 	 *
-	 * @since 5.3.1
+	 * @since 5.4
 	 */
 	KnnSimilarity knnSimilarity() default KnnSimilarity.DEFAULT;
 
 	/**
 	 * to be used in combination with {@link FieldType#Dense_Vector}
 	 *
-	 * @since 5.3.1
+	 * @since 5.4
 	 */
 	KnnIndexOptions[] knnIndexOptions() default {};
 

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

@@ -17,7 +17,7 @@
 
 /**
  * @author Haibo Liu
- * @since 5.3.1
+ * @since 5.4
  */
 public final class FieldElementType {
 	public final static String DEFAULT = "";

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

@@ -154,21 +154,21 @@
 	/**
 	 * to be used in combination with {@link FieldType#Dense_Vector}
 	 *
-	 * @since 5.3.1
+	 * @since 5.4
 	 */
 	String elementType() default FieldElementType.DEFAULT;
 
 	/**
 	 * to be used in combination with {@link FieldType#Dense_Vector}
 	 *
-	 * @since 5.3.1
+	 * @since 5.4
 	 */
 	KnnSimilarity knnSimilarity() default KnnSimilarity.DEFAULT;
 
 	/**
 	 * to be used in combination with {@link FieldType#Dense_Vector}
 	 *
-	 * @since 5.3.1
+	 * @since 5.4
 	 */
 	KnnIndexOptions[] knnIndexOptions() default {};
 }

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

@@ -17,7 +17,7 @@
 
 /**
  * @author Haibo Liu
- * @since 5.3.1
+ * @since 5.4
  */
 public enum KnnAlgorithmType {
 	HNSW("hnsw"),

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

@@ -17,7 +17,7 @@
 
 /**
  * @author Haibo Liu
- * @since 5.3.1
+ * @since 5.4
  */
 public @interface KnnIndexOptions {
 

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

@@ -17,7 +17,7 @@
 
 /**
  * @author Haibo Liu
- * @since 5.3.1
+ * @since 5.4
  */
 public enum KnnSimilarity {
 	L2_NORM("l2_norm"),

src/main/java/org/springframework/data/elasticsearch/client/elc/NativeQueryBuilder.java

@@ -213,6 +213,9 @@ public NativeQueryBuilder withQuery(org.springframework.data.elasticsearch.core.
 		return this;
 	}
 
+	/**
+	 * @since 5.4
+	 */
 	public NativeQueryBuilder withKnnSearches(List<KnnSearch> knnSearches) {
 		this.knnSearches = knnSearches;
 		return this;