HSEARCH-4950 Add new knn option to the documentation

Author: marko-bekhta

documentation/src/main/asciidoc/public/reference/_mapping-directfieldmapping.adoc

@@ -136,8 +136,6 @@ which generally gives much more flexibility.
 +
 include::../components/_incubating-warning.adoc[]
 +
-WARNING: Vector fields are only supported by the <<backend-lucene, Lucene backend>> for now.
-+
 Specific field type for vector fields to be used in a <<search-dsl-predicate-knn,vector search>>.
 +
 Vector fields accept values of type `float[]` or `byte[]` and *require* that

documentation/src/main/asciidoc/public/reference/_search-dsl-predicate.adoc

@@ -856,6 +856,13 @@ but can be <<search-dsl-predicate-common-constantScore,made constant with `.cons
 * The score of an `and` predicate can be <<search-dsl-predicate-common-boost,boosted>>
 with a call to `.boost(...)`.
 
+[[search-dsl-predicate-and-limitations]]
+=== Limitations
+
+Keep in mind that adding a <<search-dsl-predicate-knn,knn>> as an `and` clause will lead to an exception when using
+<<backend-elasticsearch-compatibility-elasticsearch,an Elastic distribution of Elasticsearch>>.
+See <<search-dsl-predicate-knn-limitations,`knn` limitations>> for more details.
+
 [[search-dsl-predicate-or]]
 == `or`: match any clause
 
@@ -1147,6 +1154,13 @@ but can be <<search-dsl-predicate-common-constantScore,made constant with `.cons
 * The score of a `bool` predicate can be <<search-dsl-predicate-common-boost,boosted>>
 with a call to `.boost(...)`.
 
+[[search-dsl-predicate-boolean-limitations]]
+=== Limitations
+
+Keep in mind that adding a <<search-dsl-predicate-knn,knn>> as a clause to a boolean predicates
+has some <<search-dsl-predicate-knn-limitations,limitations>> when using
+<<backend-elasticsearch-compatibility-elasticsearch,an Elastic distribution of Elasticsearch>>.
+
 [[search-dsl-predicate-simple-query-string]]
 == [[_simple_query_string_queries]] `simpleQueryString`: match a user-provided query string
 
@@ -1504,6 +1518,64 @@ include::{sourcedir}/org/hibernate/search/documentation/search/predicate/Predica
 ----
 ====
 
+[[search-dsl-predicate-knn-with-text-search]]
+=== Combining `knn` with other predicates
+
+A `knn` predicate can be combined with the regular text-search predicates. It can improve the quality of search results
+by increasing the score of documents that are more relevant based on vector embeddings characteristics:
+
+.Enriching regular text search with K-Nearest Neighbors search
+====
+[source, JAVA, indent=0, subs="+callouts"]
+----
+include::{sourcedir}/org/hibernate/search/documentation/search/predicate/PredicateDslIT.java[tags=knn-and-match]
+----
+<1> Find science fiction books.
+<2> Improve the score of science fiction books that have a cover similar to the one we are searching for.
+====
+
+[[search-dsl-predicate-knn-limitations]]
+=== Backend specifics and limitations
+
+With the Elasticsearch backend and when using <<backend-elasticsearch-compatibility-elasticsearch,Elasticsearch>>,
+a `knn` predicate can only be added as a top-level predicate,
+i.e. a predicate directly passed to a where clause of a search query,
+or as part of a top-level disjunction,
+i.e. as `should` clauses of a top-level <<search-dsl-predicate-boolean,`boolean` predicate>>
+(the same can be achieved by using an <<search-dsl-predicate-or,`or` predicate>>).
+A `knn` predicate can be combined with other predicate types by adding them through should clauses.
+Any other usages of a `knn` predicate, with this backend, would lead to an exception being thrown.
+See this section of the Elasticsearch link:{elasticsearchDocUrl}/knn-search.html#_combine_approximate_knn_with_other_features[documentation]
+in particular to learn more about how Elasticsearch combines regular queries with knn.
+<<backend-elasticsearch-compatibility-opensearch,OpenSearch>> does not have these limitation.
+
+.Multiple `knn` predicates added via `should` clauses
+====
+[source, JAVA, indent=0, subs="+callouts"]
+----
+include::{sourcedir}/org/hibernate/search/documentation/search/predicate/PredicateDslIT.java[tags=knn-should]
+----
+====
+
+The Elasticsearch backend, when using <<backend-elasticsearch-compatibility-elasticsearch,Elasticsearch>>,
+also allows configuring a backend-specific `knn` predicate option: the number of candidates.
+This option specifies a number of approximate nearest neighbor candidates to be found on each shard,
+then the results from each shard are merged and the top `k` are selected.
+When not specified explicitly, Hibernate Search will default the number of candidates value to `k`.
+See the Elasticsearch link:{elasticsearchDocUrl}/knn-search.html#tune-approximate-knn-for-speed-accuracy[documentation] for more details.
+<<backend-elasticsearch-compatibility-opensearch,OpenSearch>> does not expose this option.
+
+.Setting a number of candidates Elasticsearch-specific knn option
+====
+[source, JAVA, indent=0, subs="+callouts"]
+----
+include::{sourcedir}/org/hibernate/search/documentation/search/predicate/PredicateDslIT.java[tags=knn-candidates]
+----
+<1> Get an extended, Elasticsearch-specific, predicate factory.
+<2> Build a `knn` predicate as ususal.
+<3> Provide an Elasticsearch-specific predicate option.
+====
+
 [[search-dsl-predicate-knn-other]]
 === Other options
 

documentation/src/test/java/org/hibernate/search/documentation/search/predicate/Book.java

@@ -44,6 +44,7 @@ public class Book {
 	private String comment;
 
 	private float[] coverImageEmbeddings;
+	private float[] alternativeCoverImageEmbeddings;
 
 	@ManyToMany
 	@IndexedEmbedded(structure = ObjectStructure.NESTED)
@@ -108,6 +109,14 @@ public void setCoverImageEmbeddings(float[] coverImageEmbeddings) {
 		this.coverImageEmbeddings = coverImageEmbeddings;
 	}
 
+	public float[] getAlternativeCoverImageEmbeddings() {
+		return alternativeCoverImageEmbeddings;
+	}
+
+	public void setAlternativeCoverImageEmbeddings(float[] alternativeCoverImageEmbeddings) {
+		this.alternativeCoverImageEmbeddings = alternativeCoverImageEmbeddings;
+	}
+
 	public List<Author> getAuthors() {
 		return authors;
 	}

documentation/src/test/java/org/hibernate/search/documentation/search/predicate/PredicateDslIT.java

@@ -18,6 +18,7 @@
 
 import jakarta.persistence.EntityManagerFactory;
 
+import org.hibernate.search.backend.elasticsearch.ElasticsearchExtension;
 import org.hibernate.search.documentation.testsupport.BackendConfigurations;
 import org.hibernate.search.documentation.testsupport.DocumentationSetupHelper;
 import org.hibernate.search.engine.search.common.BooleanOperator;
@@ -32,7 +33,9 @@
 import org.hibernate.search.mapper.orm.mapping.HibernateOrmSearchMappingConfigurer;
 import org.hibernate.search.mapper.orm.scope.SearchScope;
 import org.hibernate.search.mapper.orm.session.SearchSession;
+import org.hibernate.search.mapper.pojo.mapping.definition.programmatic.TypeMappingStep;
 import org.hibernate.search.util.common.data.RangeBoundInclusion;
+import org.hibernate.search.util.impl.integrationtest.backend.elasticsearch.dialect.ElasticsearchTestDialect;
 import org.hibernate.search.util.impl.integrationtest.common.extension.BackendConfiguration;
 
 import org.junit.jupiter.api.BeforeEach;
@@ -54,20 +57,33 @@ class PredicateDslIT {
 
 	private EntityManagerFactory entityManagerFactory;
 
+	private static boolean isVectorSearchSupported() {
+		return BackendConfiguration.isLucene()
+				|| ElasticsearchTestDialect.isActualVersion(
+						es -> !es.isLessThan( "8.0" ),
+						os -> !os.isLessThan( "2.0" ),
+						aoss -> true
+				);
+	}
+
 	@BeforeEach
 	void setup() {
 		entityManagerFactory = setupHelper.start().setup( Book.class, Author.class, EmbeddableGeoPoint.class );
 
 		DocumentationSetupHelper.SetupContext setupContext = setupHelper.start();
-		// NOTE: To keep this documentation example simple there is no testing with Elasticsearch/OpenSearch
-		// as not all versions have integration implemented e.g. Elasticsearch 7 or OpenSearch 1.3 will throw exceptions
-		if ( BackendConfiguration.isLucene() ) {
+		// NOTE: If backend does not support vector search it will lead to runtime exceptions, so we cannot  simply annotate
+		// the corresponding properties with @VectorField; instead we add it programmatically when it's possible
+		if ( isVectorSearchSupported() ) {
 			setupContext.withProperty(
 					HibernateOrmMapperSettings.MAPPING_CONFIGURER,
-					(HibernateOrmSearchMappingConfigurer) context -> context.programmaticMapping()
-							.type( Book.class )
-							.property( "coverImageEmbeddings" )
-							.vectorField( 128 )
+					(HibernateOrmSearchMappingConfigurer) context -> {
+						TypeMappingStep book = context.programmaticMapping()
+								.type( Book.class );
+						book.property( "coverImageEmbeddings" )
+								.vectorField( 128 );
+						book.property( "alternativeCoverImageEmbeddings" )
+								.vectorField( 128 );
+					}
 			);
 		}
 		entityManagerFactory = setupContext.setup( Book.class, Author.class, EmbeddableGeoPoint.class );
@@ -1110,14 +1126,14 @@ void knn() {
 		// NOTE: To keep this documentation example simple there is no testing with Elasticsearch/OpenSearch
 		// as not all versions have integration implemented e.g. Elasticsearch 7 or OpenSearch 1.3 will throw exceptions
 		assumeTrue(
-				BackendConfiguration.isLucene(),
+				isVectorSearchSupported(),
 				"This test only makes sense if the backend supports vectors"
 		);
 		withinSearchSession( searchSession -> {
 			// tag::knn[]
 			float[] coverImageEmbeddingsVector = /*...*/
 					// end::knn[]
-					new float[128];
+					floats( 128, 1.0f );
 			// tag::knn[]
 			List<Book> hits = searchSession.search( Book.class )
 					.where( f -> f.knn( 5 ).field( "coverImageEmbeddings" ).matching( coverImageEmbeddingsVector ) )
@@ -1132,7 +1148,7 @@ void knn() {
 			// tag::knn-filter[]
 			float[] coverImageEmbeddingsVector = /*...*/
 					// end::knn-filter[]
-					new float[128];
+					floats( 128, 1.0f );
 			// tag::knn-filter[]
 			List<Book> hits = searchSession.search( Book.class )
 					.where( f -> f.knn( 5 ).field( "coverImageEmbeddings" ).matching( coverImageEmbeddingsVector )
@@ -1143,6 +1159,74 @@ void knn() {
 					.extracting( Book::getId )
 					.containsExactlyInAnyOrder( BOOK1_ID, BOOK2_ID, BOOK3_ID );
 		} );
+
+		withinSearchSession( searchSession -> {
+			// tag::knn-should[]
+			float[] coverImageEmbeddingsVector = /*...*/
+					// end::knn-should[]
+					floats( 128, 1.0f );
+			// tag::knn-should[]
+			float[] alternativeCoverImageEmbeddingsVector = /*...*/
+					// end::knn-should[]
+					floats( 128, 1.0f );
+			// tag::knn-should[]
+			List<Book> hits = searchSession.search( Book.class )
+					.where( f -> f.bool()
+							.should( f.knn( 10 ).field( "coverImageEmbeddings" ).matching( coverImageEmbeddingsVector ) )
+							.should( f.knn( 5 ).field( "alternativeCoverImageEmbeddings" )
+									.matching( alternativeCoverImageEmbeddingsVector ) )
+					)
+					.fetchHits( 20 );
+			// end::knn-should[]
+			assertThat( hits )
+					.extracting( Book::getId )
+					.containsExactlyInAnyOrder( BOOK1_ID, BOOK2_ID, BOOK3_ID, BOOK4_ID );
+		} );
+
+		if ( !BackendConfiguration.isElasticsearch()
+				|| ElasticsearchTestDialect.isActualVersion(
+						es -> false,
+						os -> !os.isLessThan( "2.0" ),
+						aoss -> true
+				) ) {
+			withinSearchSession( searchSession -> {
+				// tag::knn-and-match[]
+				float[] coverImageEmbeddingsVector = /*...*/
+						// end::knn-and-match[]
+						floats( 128, 1.0f );
+				// tag::knn-and-match[]
+				List<Book> hits = searchSession.search( Book.class )
+						.where( f -> f.bool()
+								.must( f.match().field( "genre" ).matching( Genre.SCIENCE_FICTION ) ) // <1>
+								.should( f.knn( 10 ).field( "coverImageEmbeddings" ).matching( coverImageEmbeddingsVector ) ) // <2>
+						)
+						.fetchHits( 20 );
+				// end::knn-and-match[]
+				assertThat( hits )
+						.extracting( Book::getId )
+						.containsExactlyInAnyOrder( BOOK1_ID, BOOK2_ID, BOOK3_ID );
+			} );
+		}
+
+
+		if ( BackendConfiguration.isElasticsearch() ) {
+			withinSearchSession( searchSession -> {
+				// tag::knn-candidates[]
+				float[] coverImageEmbeddingsVector = /*...*/
+						// end::knn-candidates[]
+						floats( 128, 1.0f );
+				// tag::knn-candidates[]
+				List<Book> hits = searchSession.search( Book.class )
+						.where( f -> f.extension( ElasticsearchExtension.get() ) // <1>
+								.knn( 5 ).field( "coverImageEmbeddings" ).matching( coverImageEmbeddingsVector ) // <2>
+								.numberOfCandidates( 15 ) )// <3>
+						.fetchHits( 20 );
+				// end::knn-candidates[]
+				assertThat( hits )
+						.extracting( Book::getId )
+						.containsExactlyInAnyOrder( BOOK1_ID, BOOK2_ID, BOOK3_ID, BOOK4_ID );
+			} );
+		}
 	}
 
 	private MySearchParameters getSearchParameters() {
@@ -1208,6 +1292,7 @@ private void initData() {
 			book1.setGenre( Genre.SCIENCE_FICTION );
 			book1.getAuthors().add( isaacAsimov );
 			book1.setCoverImageEmbeddings( floats( 128, 1.0f ) );
+			book1.setAlternativeCoverImageEmbeddings( floats( 128, 10.0f ) );
 			isaacAsimov.getBooks().add( book1 );
 
 			Book book2 = new Book();
@@ -1219,6 +1304,7 @@ private void initData() {
 			book2.setComment( "Really liked this one!" );
 			book2.getAuthors().add( isaacAsimov );
 			book2.setCoverImageEmbeddings( floats( 128, 2.0f ) );
+			book2.setAlternativeCoverImageEmbeddings( floats( 128, 20.0f ) );
 			isaacAsimov.getBooks().add( book2 );
 
 			Book book3 = new Book();
@@ -1229,6 +1315,7 @@ private void initData() {
 			book3.setGenre( Genre.SCIENCE_FICTION );
 			book3.getAuthors().add( isaacAsimov );
 			book3.setCoverImageEmbeddings( floats( 128, 3.0f ) );
+			book3.setAlternativeCoverImageEmbeddings( floats( 128, 30.0f ) );
 			isaacAsimov.getBooks().add( book3 );
 
 			Book book4 = new Book();
@@ -1239,6 +1326,7 @@ private void initData() {
 			book4.setGenre( Genre.CRIME_FICTION );
 			book4.getAuthors().add( aLeeMartinez );
 			book4.setCoverImageEmbeddings( floats( 128, 4.0f ) );
+			book4.setAlternativeCoverImageEmbeddings( floats( 128, 40.0f ) );
 			aLeeMartinez.getBooks().add( book3 );
 
 			entityManager.persist( isaacAsimov );

integrationtest/backend/elasticsearch/src/test/java/org/hibernate/search/integrationtest/backend/elasticsearch/search/ElasticsearchKnnPredicateSpecificsIT.java

@@ -183,7 +183,7 @@ void knnPredicateInWrongPlace_aggregation() {
 					index.query().select()
 							.where( f -> f.matchAll() )
 							.aggregation( countsByParking, agg -> agg.terms().field( "object.nestedParking", Boolean.class )
-									.filter( f -> f.knn( 10 ).field( "location" ).matching(50.0f, 50.0f) ) )
+									.filter( f -> f.knn( 10 ).field( "location" ).matching( 50.0f, 50.0f ) ) )
 							.toQuery();
 				} );
 	}
@@ -230,7 +230,9 @@ private static class PredicateIndexBinding {
 			IndexSchemaObjectField nested = root.objectField( "object", ObjectStructure.NESTED );
 			object = nested.toReference();
 			nestedParking = nested.field( "nestedParking", f -> f.asBoolean().aggregable( Aggregable.YES ) ).toReference();
-			nestedRating = nested.field( "nestedRating", f -> f.asInteger().projectable( Projectable.YES ).sortable( Sortable.YES ) ).toReference();
+			nestedRating =
+					nested.field( "nestedRating", f -> f.asInteger().projectable( Projectable.YES ).sortable( Sortable.YES ) )
+							.toReference();
 		}
 
 	}