Documentation.

Author: mp911de

spring-data-jpa/src/main/java/org/springframework/data/jpa/repository/query/JpaParametersParameterAccessor.java

@@ -82,7 +82,7 @@ protected Object potentiallyUnwrap(Object parameterValue) {
 	 * @return
 	 */
 	public ScoringFunction getScoringFunction() {
-		return doWithScore(Score::getFunction, Score.class::isInstance, () -> ScoringFunction.UNSPECIFIED);
+		return doWithScore(Score::getFunction, Score.class::isInstance, ScoringFunction::unspecified);
 	}
 
 	/**

spring-data-jpa/src/main/java/org/springframework/data/jpa/repository/query/JpaQueryCreator.java

@@ -76,10 +76,7 @@ public class JpaQueryCreator extends AbstractQueryCreator<String, JpqlQueryBuild
 			VectorScoringFunctions.EUCLIDEAN, new DistanceFunction("euclidean_distance", Sort.Direction.ASC), //
 			VectorScoringFunctions.TAXICAB, new DistanceFunction("taxicab_distance", Sort.Direction.ASC), //
 			VectorScoringFunctions.HAMMING, new DistanceFunction("hamming_distance", Sort.Direction.ASC), //
-			VectorScoringFunctions.INNER_PRODUCT, new DistanceFunction("negative_inner_product", Sort.Direction.ASC), //
-
-			// TODO: Do we need both, dot and inner product? Aren't these the same in some sense?
-			VectorScoringFunctions.DOT, new DistanceFunction("negative_inner_product", Sort.Direction.ASC));
+			VectorScoringFunctions.DOT_PRODUCT, new DistanceFunction("negative_inner_product", Sort.Direction.ASC));
 
 	record DistanceFunction(String distanceFunction, Sort.Direction direction) {
 
@@ -100,7 +97,6 @@ record DistanceFunction(String distanceFunction, Sort.Direction direction) {
 	 * Create a new {@link JpaQueryCreator}.
 	 *
 	 * @param tree must not be {@literal null}.
-	 * @param searchQuery
 	 * @param type must not be {@literal null}.
 	 * @param provider must not be {@literal null}.
 	 * @param templates must not be {@literal null}.
@@ -121,6 +117,7 @@ public JpaQueryCreator(PartTree tree, boolean searchQuery, ReturnedType type, Pa
 		JpqlQueryTemplates templates, Metamodel metamodel) {
 
 		super(tree);
+
 		this.searchQuery = searchQuery;
 		this.tree = tree;
 		this.returnedType = type;
@@ -585,7 +582,9 @@ private static String getDistanceFunction(ScoringFunction scoringFunction) {
 			DistanceFunction distanceFunction = JpaQueryCreator.DISTANCE_FUNCTIONS.get(scoringFunction);
 
 			if (distanceFunction == null) {
-				throw new IllegalArgumentException("Unsupported ScoringFunction: %s".formatted(scoringFunction.getName()));
+				throw new IllegalArgumentException(
+						"Unsupported ScoringFunction: %s. Make sure to declare a supported ScoringFunction when creating Score/Similarity instances."
+								.formatted(scoringFunction.getName()));
 			}
 
 			return distanceFunction.distanceFunction();

spring-data-jpa/src/main/java/org/springframework/data/jpa/repository/query/JpqlQueryBuilder.java

@@ -496,7 +496,7 @@ default Select select(JpqlQueryBuilder.PathExpression path) {
 		/**
 		 * Select a single attribute.
 		 *
-		 * @param path
+		 * @param selection
 		 * @return
 		 */
 		@CheckReturnValue

spring-data-jpa/src/main/java/org/springframework/data/jpa/repository/query/ParameterMetadataProvider.java

@@ -217,7 +217,7 @@ ScoringFunction getScoringFunction() {
 			return accessor.getScoringFunction();
 		}
 
-		return ScoringFunction.UNSPECIFIED;
+		return ScoringFunction.unspecified();
 	}
 
 	ParameterBinding getVectorBinding() {

spring-data-jpa/src/main/java/org/springframework/data/jpa/repository/query/SimilarityNormalizer.java

@@ -32,9 +32,9 @@
 public class SimilarityNormalizer {
 
 	/**
-	 * Identity normalizer for {@link ScoringFunction#UNSPECIFIED} scoring function without altering the score.
+	 * Identity normalizer for {@link ScoringFunction#unspecified()} scoring function without altering the score.
 	 */
-	public static final SimilarityNormalizer IDENTITY = new SimilarityNormalizer(ScoringFunction.UNSPECIFIED,
+	public static final SimilarityNormalizer IDENTITY = new SimilarityNormalizer(ScoringFunction.unspecified(),
 			DoubleUnaryOperator.identity(), DoubleUnaryOperator.identity());
 
 	/**
@@ -52,16 +52,15 @@ public class SimilarityNormalizer {
 	/**
 	 * Normalizer for Negative Inner Product (Dot) scores using {@code negative_inner_product(…)} as the scoring function.
 	 */
-	public static final SimilarityNormalizer DOT = new SimilarityNormalizer(VectorScoringFunctions.DOT,
+	public static final SimilarityNormalizer DOT_PRODUCT = new SimilarityNormalizer(VectorScoringFunctions.DOT_PRODUCT,
 			it -> (1 - it) / 2, it -> 1 - (it * 2));
 
 	private static final Map<ScoringFunction, SimilarityNormalizer> NORMALIZERS = new HashMap<>();
 
 	static {
 		NORMALIZERS.put(EUCLIDEAN.scoringFunction, EUCLIDEAN);
 		NORMALIZERS.put(COSINE.scoringFunction, COSINE);
-		NORMALIZERS.put(DOT.scoringFunction, DOT);
-		NORMALIZERS.put(VectorScoringFunctions.INNER_PRODUCT, DOT);
+		NORMALIZERS.put(DOT_PRODUCT.scoringFunction, DOT_PRODUCT);
 	}
 
 	private final ScoringFunction scoringFunction;

spring-data-jpa/src/test/java/org/springframework/data/jpa/repository/PgVectorIntegrationTests.java

@@ -49,6 +49,7 @@
 import org.springframework.core.io.ClassPathResource;
 import org.springframework.data.domain.Range;
 import org.springframework.data.domain.Score;
+import org.springframework.data.domain.ScoringFunction;
 import org.springframework.data.domain.SearchResult;
 import org.springframework.data.domain.SearchResults;
 import org.springframework.data.domain.Similarity;
@@ -109,7 +110,7 @@ void shouldApplyVectorSearchWithDistance(VectorScoringFunctions functions) {
 	}
 
 	static Set<VectorScoringFunctions> scoringFunctions() {
-		return EnumSet.of(VectorScoringFunctions.COSINE, VectorScoringFunctions.INNER_PRODUCT,
+		return EnumSet.of(VectorScoringFunctions.COSINE, VectorScoringFunctions.DOT_PRODUCT,
 				VectorScoringFunctions.EUCLIDEAN);
 	}
 
@@ -169,6 +170,21 @@ void shouldRunStringQueryWithDistance() {
 		assertThat(result.getScore().getFunction()).isEqualTo(VectorScoringFunctions.COSINE);
 	}
 
+	@Test
+	void shouldRunStringQueryWithFloatDistance() {
+
+		SearchResults<WithVector> results = repository.searchAnnotatedByCountryAndEmbeddingWithin("de", VECTOR, 2);
+
+		assertThat(results).hasSize(3).extracting(SearchResult::getContent).extracting(WithVector::getCountry)
+				.containsOnly("de", "de", "de");
+		assertThat(results).extracting(SearchResult::getContent).extracting(WithVector::getDescription)
+				.containsSequence("two", "one", "four");
+
+		SearchResult<WithVector> result = results.getContent().get(0);
+		assertThat(result.getScore().getValue()).isGreaterThanOrEqualTo(0);
+		assertThat(result.getScore().getFunction()).isEqualTo(ScoringFunction.unspecified());
+	}
+
 	@Test
 	void shouldApplyVectorSearchWithRange() {
 
@@ -320,6 +336,14 @@ AND cosine_distance(w.embedding, :embedding) <= :distance
 		SearchResults<WithVector> searchAnnotatedByCountryAndEmbeddingWithin(String country, Vector embedding,
 				Score distance);
 
+		@Query("""
+				SELECT w, cosine_distance(w.embedding, :embedding) as distance FROM org.springframework.data.jpa.repository.PgVectorIntegrationTests$WithVector w
+				WHERE w.country = ?1
+					AND cosine_distance(w.embedding, :embedding) <= :distance
+				ORDER BY distance asc""")
+		SearchResults<WithVector> searchAnnotatedByCountryAndEmbeddingWithin(String country, Vector embedding,
+				float distance);
+
 		SearchResults<WithVector> searchAllByCountryAndEmbeddingWithin(String country, Vector embedding,
 				Range<Similarity> distance);
 

spring-data-jpa/src/test/java/org/springframework/data/jpa/repository/query/SimilarityNormalizerUnitTests.java

@@ -58,13 +58,19 @@ void normalizesCosine() {
 	@Test
 	void normalizesNegativeInnerProduct() {
 
-		assertThat(SimilarityNormalizer.DOT.getSimilarity(-0.8465620279312134)).isCloseTo(0.9232810139656067, offset(0.01));
-		assertThat(SimilarityNormalizer.DOT.getSimilarity(-1.0626180171966553)).isCloseTo(1.0313090085983276, offset(0.01));
-		assertThat(SimilarityNormalizer.DOT.getSimilarity(-2.0293400287628174)).isCloseTo(1.5146700143814087, offset(0.01));
+		assertThat(SimilarityNormalizer.DOT_PRODUCT.getSimilarity(-0.8465620279312134)).isCloseTo(0.9232810139656067,
+				offset(0.01));
+		assertThat(SimilarityNormalizer.DOT_PRODUCT.getSimilarity(-1.0626180171966553)).isCloseTo(1.0313090085983276,
+				offset(0.01));
+		assertThat(SimilarityNormalizer.DOT_PRODUCT.getSimilarity(-2.0293400287628174)).isCloseTo(1.5146700143814087,
+				offset(0.01));
 
-		assertThat(SimilarityNormalizer.DOT.getScore(0.9232810139656067)).isCloseTo(-0.8465620279312134, offset(0.01));
-		assertThat(SimilarityNormalizer.DOT.getScore(1.0313090085983276)).isCloseTo(-1.0626180171966553, offset(0.01));
-		assertThat(SimilarityNormalizer.DOT.getScore(1.5146700143814087)).isCloseTo(-2.0293400287628174, offset(0.01));
+		assertThat(SimilarityNormalizer.DOT_PRODUCT.getScore(0.9232810139656067)).isCloseTo(-0.8465620279312134,
+				offset(0.01));
+		assertThat(SimilarityNormalizer.DOT_PRODUCT.getScore(1.0313090085983276)).isCloseTo(-1.0626180171966553,
+				offset(0.01));
+		assertThat(SimilarityNormalizer.DOT_PRODUCT.getScore(1.5146700143814087)).isCloseTo(-2.0293400287628174,
+				offset(0.01));
 	}
 
 }

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

@@ -14,6 +14,7 @@
 ** xref:jpa/stored-procedures.adoc[]
 ** xref:jpa/specifications.adoc[]
 ** xref:repositories/query-by-example.adoc[]
+** xref:repositories/vector-search.adoc[]
 ** xref:jpa/transactions.adoc[]
 ** xref:jpa/locking.adoc[]
 ** xref:auditing.adoc[]

src/main/antora/modules/ROOT/pages/repositories/vector-search.adoc

@@ -0,0 +1,8 @@
+:vector-search-intro-include: data-jpa::partial$vector-search-intro-include.adoc
+:vector-search-model-include: data-jpa::partial$vector-search-model-include.adoc
+:vector-search-repository-include: data-jpa::partial$vector-search-repository-include.adoc
+:vector-search-scoring-include: data-jpa::partial$vector-search-scoring-include.adoc
+:vector-search-method-derived-include: data-jpa::partial$vector-search-method-derived-include.adoc
+:vector-search-method-annotated-include: data-jpa::partial$vector-search-method-annotated-include.adoc
+
+include::{commons}@data-commons::page$repositories/vector-search.adoc[]

src/main/antora/modules/ROOT/partials/vector-search-intro-include.adoc

@@ -0,0 +1,31 @@
+To use Hibernate Vector Search, you need to add the following dependencies to your project.
+
+The following example shows how to set up dependencies in Maven and Gradle:
+
+[tabs]
+======
+Maven::
++
+[source,xml,indent=0,subs="verbatim,quotes",role="primary"]
+----
+<dependencies>
+    <dependency>
+      <groupId>org.hibernate.orm</groupId>
+      <artifactId>hibernate-vector</artifactId>
+      <version>${hibernate.version}</version>
+    </dependency>
+</dependencies>
+
+----
+
+Gradle::
++
+====
+[source,groovy,indent=0,subs="verbatim,quotes",role="secondary"]
+----
+dependencies {
+    implementation 'org.hibernate.orm:hibernate-vector:${hibernateVersion}'
+}
+----
+====
+======

src/main/antora/modules/ROOT/partials/vector-search-method-annotated-include.adoc

@@ -0,0 +1,29 @@
+Annotated search methods must define the entire JPQL query to run a Vector Search.
+
+.Using `@Query` Search Methods
+====
+[source,java]
+----
+interface CommentRepository extends Repository<Comment, String> {
+
+  @Query("""
+      SELECT c, cosine_distance(c.embedding, :embedding) as distance FROM Comment c
+      WHERE c.country = ?1
+        AND cosine_distance(c.embedding, :embedding) <= :distance
+      ORDER BY distance asc""")
+  SearchResults<WithVector> searchAnnotatedByCountryAndEmbeddingWithin(String country, Vector embedding,
+      Score distance);
+
+  @Query("""
+      SELECT c FROM Comment c
+      WHERE c.country = ?1
+        AND cosine_distance(c.embedding, :embedding) <= :distance
+      ORDER BY cosine_distance(c.embedding, :embedding) asc""")
+  List<WithVector> findAnnotatedByCountryAndEmbeddingWithin(String country, Vector embedding, Score distance);
+
+}
+----
+====
+
+Vector Search methods are not required to include a score or distance in their projection.
+When using annotated search methods returning `SearchResults`, the execution mechanism assumes that if a second projection column is present that this one holds the score value.

src/main/antora/modules/ROOT/partials/vector-search-method-derived-include.adoc

@@ -0,0 +1,16 @@
+.Using `Near` and `Within` Keywords in Repository Search Methods
+====
+[source,java]
+----
+interface CommentRepository extends Repository<Comment, String> {
+
+  SearchResults<Comment> searchByEmbeddingNear(Vector vector, Score score);
+
+  SearchResults<Comment> searchByEmbeddingWithin(Vector vector, Range<Similarity> range);
+
+  SearchResults<Comment> searchByCountryAndEmbeddingWithin(String country, Vector vector, Range<Similarity> range);
+}
+----
+====
+
+Derived Search Methods can define domain model attributes and Vector parameters.

src/main/antora/modules/ROOT/partials/vector-search-model-include.adoc

@@ -0,0 +1,18 @@
+====
+[source,java]
+----
+class Comment {
+
+  @Id String id;
+  String country;
+  String comment;
+
+  @Column(name = "the_embedding")
+  @JdbcTypeCode(SqlTypes.VECTOR)
+  @Array(length = 5)
+  Vector embedding;
+
+  // getters, setters, …
+}
+----
+====

src/main/antora/modules/ROOT/partials/vector-search-repository-include.adoc

@@ -0,0 +1,22 @@
+.Using `SearchResult<T>` in a Repository Search Method
+====
+[source,java]
+----
+interface CommentRepository extends Repository<Comment, String> {
+
+  SearchResults<Comment> searchByCountryAndEmbeddingNear(String country, Vector vector, Score distance,
+    Limit limit);
+
+  @Query("""
+      SELECT c, cosine_distance(c.embedding, :embedding) as distance FROM Comment c
+      WHERE c.country = ?1
+        AND cosine_distance(c.embedding, :embedding) <= :distance
+      ORDER BY distance asc""")
+  SearchResults<WithVector> searchAnnotatedByCountryAndEmbeddingWithin(String country, Vector embedding,
+      Score distance);
+
+}
+
+SearchResults<Comment> results = repository.searchByCountryAndEmbeddingNear("en", Vector.of(…), Score.of(0.9), Limit.of(10));
+----
+====

src/main/antora/modules/ROOT/partials/vector-search-scoring-include.adoc

@@ -0,0 +1,33 @@
+Hibernate translates distance function calls to native database functions for PGvector and Oracle.
+Their result is typically a distance.
+When using `Similarity` instead of `Score`, Spring Data normalizes distance scores into a similarity score between 0 and 1. The higher the score, the more similar the two vectors are.
+// END
+
+.Using `Score` and `Similarity` in a Repository Search Methods
+====
+[source,java]
+----
+interface CommentRepository extends Repository<Comment, String> {
+
+  SearchResults<Comment> searchByEmbeddingNear(Vector vector, Score score);
+
+  SearchResults<Comment> searchByEmbeddingNear(Vector vector, Similarity similarity);
+
+  SearchResults<Comment> searchByEmbeddingNear(Vector vector, Range<Similarity> range);
+}
+
+repository.searchByEmbeddingNear(Vector.of(…), Score.of(0.9, ScoringFunction.cosine()));                <1>
+
+repository.searchByEmbeddingNear(Vector.of(…), Similarity.of(0.9, ScoringFunction.cosine()));           <2>
+
+repository.searchByEmbeddingNear(Vector.of(…), Similarity.between(0.5, 1, ScoringFunction.euclidean()));<3>
+----
+
+<1> Run a search and return results with a score of `0.9` or smaller using the Cosine distance.
+<2> Run a search and normalize the score into a similarity value.
+Return results with a similarity of `0.9`  or greater using Cosine scoring.
+<3> Run a search and normalize the score into a similarity value.
+Return results with a similarity of between `0.5` and `1.0`  or greater using Euclidean scoring.
+====
+
+NOTE: JPA requires a `ScoringFunction` to be provided when creating `Score` or `Similarity` instances to select a scoring function.