diff --git a/documentation/src/main/asciidoc/userguide/Hibernate_User_Guide.adoc b/documentation/src/main/asciidoc/userguide/Hibernate_User_Guide.adoc index 139bc3df6d..0f6012da25 100644 --- a/documentation/src/main/asciidoc/userguide/Hibernate_User_Guide.adoc +++ b/documentation/src/main/asciidoc/userguide/Hibernate_User_Guide.adoc @@ -34,7 +34,7 @@ include::chapters/query/hql/QueryLanguage.adoc[] include::chapters/query/criteria/Criteria.adoc[] include::chapters/query/native/Native.adoc[] include::chapters/query/spatial/Spatial.adoc[] -include::chapters/query/types/TypesModule.adoc[] +include::chapters/query/extensions/Vector.adoc[] include::chapters/multitenancy/MultiTenancy.adoc[] include::chapters/envers/Envers.adoc[] include::chapters/beans/Beans.adoc[] diff --git a/documentation/src/main/asciidoc/userguide/chapters/query/types/TypesModule.adoc b/documentation/src/main/asciidoc/userguide/chapters/query/extensions/Vector.adoc similarity index 65% rename from documentation/src/main/asciidoc/userguide/chapters/query/types/TypesModule.adoc rename to documentation/src/main/asciidoc/userguide/chapters/query/extensions/Vector.adoc index 43fbb2c7f0..41d7fc6252 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/query/types/TypesModule.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/query/extensions/Vector.adoc @@ -1,32 +1,36 @@ -[[types-module]] -== Hibernate Types module +[[vector-module]] +== Hibernate Vector module :root-project-dir: ../../../../../../../.. -:types-project-dir: {root-project-dir}/hibernate-types -:example-dir-types: {types-project-dir}/src/test/java/org/hibernate/types +:vector-project-dir: {root-project-dir}/hibernate-vector +:example-dir-vector: {vector-project-dir}/src/test/java/org/hibernate/vector :extrasdir: extras -[[types-module-overview]] +[[vector-module-overview]] === Overview -The Hibernate ORM core module tries to be as minimal as possible and only model functionality -that is somewhat "standard" in the SQL space or can only be modeled as part of the core module. -To avoid growing that module further unnecessarily, support for certain special SQL types or functions -is separated out into the Hibernate ORM types module. +The Hibernate ORM Vector module contains support for mathematical vector types and functions. +This is useful for AI/ML topics like vector similarity search. +The module comes with support for a special `vector` data type that essentially represents an array of floats. -[[types-module-setup]] +So far, only the PostgreSQL extension `pgvector` is supported, but in theory, +the vector specific functions could be implemented to work with every database that supports arrays. + +For further details, refer to the https://github.com/pgvector/pgvector#querying[pgvector documentation]. + +[[vector-module-setup]] === Setup -You need to include the `hibernate-types` dependency in your build environment. +You need to include the `hibernate-vector` dependency in your build environment. For Maven, you need to add the following dependency: -[[types-module-setup-maven-example]] +[[vector-module-setup-maven-example]] .Maven dependency ==== [source,xml] ---- org.hibernate.orm - hibernate-types + hibernate-vector ${hibernate.version} ---- @@ -35,37 +39,27 @@ For Maven, you need to add the following dependency: The module contains service implementations that are picked up by the Java `ServiceLoader` automatically, so no further configuration is necessary to make the features available. -[[types-module-vector]] -=== Vector type support - -The Hibernate ORM types module comes with support for a special `vector` data type that essentially represents an array of floats. - -So far, only the PostgreSQL extension `pgvector` is supported, but in theory, -the vector specific functions could be implemented to work with every database that supports arrays. - -For further details, refer to the https://github.com/pgvector/pgvector#querying[pgvector documentation]. - -[[types-module-vector-usage]] +[[vector-module-usage]] ==== Usage Annotate a persistent attribute with `@JdbcTypeCode(SqlTypes.VECTOR)` and specify the vector length with `@Array(length = ...)`. -[[types-module-vector-usage-example]] +[[vector-module-usage-example]] ==== [source, JAVA, indent=0] ---- -include::{example-dir-types}/vector/PGVectorTest.java[tags=usage-example] +include::{example-dir-vector}/PGVectorTest.java[tags=usage-example] ---- ==== To cast the string representation of a vector to the vector data type, simply use an HQL cast i.e. `cast('[1,2,3]' as vector)`. -[[types-module-vector-functions]] +[[vector-module-functions]] ==== Functions Expressions of the vector type can be used with various vector functions. -[[types-module-vector-functions-overview]] +[[vector-module-functions-overview]] |=== | Function | Purpose @@ -88,89 +82,89 @@ In addition to these special vector functions, it is also possible to use vector `sum() = `:: Aggregate function support for element-wise summation of vectors. `avg() = `:: Aggregate function support for element-wise average of vectors. -[[types-module-vector-functions-cosine-distance]] +[[vector-module-functions-cosine-distance]] ===== `cosine_distance()` Computes the https://en.wikipedia.org/wiki/Cosine_similarity[cosine distance] between two vectors, which is `1 - inner_product( v1, v2 ) / ( vector_norm( v1 ) * vector_norm( v2 ) )`. Maps to the `<``=``>` pgvector operator. -[[types-module-vector-functions-cosine-distance-example]] +[[vector-module-functions-cosine-distance-example]] ==== [source, JAVA, indent=0] ---- -include::{example-dir-types}/vector/PGVectorTest.java[tags=cosine-distance-example] +include::{example-dir-vector}/PGVectorTest.java[tags=cosine-distance-example] ---- ==== -[[types-module-vector-functions-euclidean-distance]] +[[vector-module-functions-euclidean-distance]] ===== `euclidean_distance()` and `l2_distance()` Computes the https://en.wikipedia.org/wiki/Euclidean_distance[euclidean distance] between two vectors, which is `sqrt( sum( (v1_i - v2_i)^2 ) )`. Maps to the `<``-``>` pgvector operator. The `l2_distance()` function is an alias. -[[types-module-vector-functions-euclidean-distance-example]] +[[vector-module-functions-euclidean-distance-example]] ==== [source, JAVA, indent=0] ---- -include::{example-dir-types}/vector/PGVectorTest.java[tags=euclidean-distance-example] +include::{example-dir-vector}/PGVectorTest.java[tags=euclidean-distance-example] ---- ==== -[[types-module-vector-functions-taxicab-distance]] +[[vector-module-functions-taxicab-distance]] ===== `taxicab_distance()` and `l1_distance()` Computes the https://en.wikipedia.org/wiki/Taxicab_geometry[taxicab distance] between two vectors, which is `vector_norm(v1) - vector_norm(v2)`. The `l1_distance()` function is an alias. -[[types-module-vector-functions-taxicab-distance-example]] +[[vector-module-functions-taxicab-distance-example]] ==== [source, JAVA, indent=0] ---- -include::{example-dir-types}/vector/PGVectorTest.java[tags=taxicab-distance-example] +include::{example-dir-vector}/PGVectorTest.java[tags=taxicab-distance-example] ---- ==== -[[types-module-vector-functions-inner-product]] +[[vector-module-functions-inner-product]] ===== `inner_product()` and `negative_inner_product()` Computes the https://en.wikipedia.org/wiki/Inner_product_space[inner product] between two vectors, which is `sum( v1_i * v2_i )`. The `negative_inner_product()` function maps to the `<``#``>` pgvector operator, and the `inner_product()` function as well, but multiplies the result time `-1`. -[[types-module-vector-functions-inner-product-example]] +[[vector-module-functions-inner-product-example]] ==== [source, JAVA, indent=0] ---- -include::{example-dir-types}/vector/PGVectorTest.java[tags=inner-product-example] +include::{example-dir-vector}/PGVectorTest.java[tags=inner-product-example] ---- ==== -[[types-module-vector-functions-vector-dims]] +[[vector-module-functions-vector-dims]] ===== `vector_dims()` Determines the dimensions of a vector. -[[types-module-vector-functions-vector-dims-example]] +[[vector-module-functions-vector-dims-example]] ==== [source, JAVA, indent=0] ---- -include::{example-dir-types}/vector/PGVectorTest.java[tags=vector-dims-example] +include::{example-dir-vector}/PGVectorTest.java[tags=vector-dims-example] ---- ==== -[[types-module-vector-functions-vector-norm]] +[[vector-module-functions-vector-norm]] ===== `vector_norm()` Computes the https://en.wikipedia.org/wiki/Euclidean_space#Euclidean_norm[Euclidean norm] of a vector, which is `sqrt( sum( v_i^2 ) )`. -[[types-module-vector-functions-vector-norm-example]] +[[vector-module-functions-vector-norm-example]] ==== [source, JAVA, indent=0] ---- -include::{example-dir-types}/vector/PGVectorTest.java[tags=vector-norm-example] +include::{example-dir-vector}/PGVectorTest.java[tags=vector-norm-example] ---- ==== diff --git a/hibernate-types/src/main/resources/META-INF/services/org.hibernate.boot.model.FunctionContributor b/hibernate-types/src/main/resources/META-INF/services/org.hibernate.boot.model.FunctionContributor deleted file mode 100644 index 5322d02d11..0000000000 --- a/hibernate-types/src/main/resources/META-INF/services/org.hibernate.boot.model.FunctionContributor +++ /dev/null @@ -1 +0,0 @@ -org.hibernate.types.vector.PGVectorFunctionContributor \ No newline at end of file diff --git a/hibernate-types/src/main/resources/META-INF/services/org.hibernate.boot.model.TypeContributor b/hibernate-types/src/main/resources/META-INF/services/org.hibernate.boot.model.TypeContributor deleted file mode 100644 index 319ae864a3..0000000000 --- a/hibernate-types/src/main/resources/META-INF/services/org.hibernate.boot.model.TypeContributor +++ /dev/null @@ -1 +0,0 @@ -org.hibernate.types.vector.PGVectorTypeContributor \ No newline at end of file diff --git a/hibernate-types/hibernate-types.gradle b/hibernate-vector/hibernate-vector.gradle similarity index 90% rename from hibernate-types/hibernate-types.gradle rename to hibernate-vector/hibernate-vector.gradle index 9f49131d97..f0277a6bde 100644 --- a/hibernate-types/hibernate-types.gradle +++ b/hibernate-vector/hibernate-vector.gradle @@ -5,7 +5,7 @@ * See the lgpl.txt file in the root directory or . */ -description = 'Hibernate\'s type extensions' +description = 'Hibernate\'s extensions for vector support' apply from: rootProject.file( 'gradle/published-java-module.gradle' ) diff --git a/hibernate-types/src/main/java/org/hibernate/types/vector/PGVectorFunctionContributor.java b/hibernate-vector/src/main/java/org/hibernate/vector/PGVectorFunctionContributor.java similarity index 99% rename from hibernate-types/src/main/java/org/hibernate/types/vector/PGVectorFunctionContributor.java rename to hibernate-vector/src/main/java/org/hibernate/vector/PGVectorFunctionContributor.java index b7dfc6d29e..d6a294c3f8 100644 --- a/hibernate-types/src/main/java/org/hibernate/types/vector/PGVectorFunctionContributor.java +++ b/hibernate-vector/src/main/java/org/hibernate/vector/PGVectorFunctionContributor.java @@ -4,7 +4,7 @@ * License: GNU Lesser General Public License (LGPL), version 2.1 or later. * See the lgpl.txt file in the root directory or . */ -package org.hibernate.types.vector; +package org.hibernate.vector; import org.hibernate.boot.model.FunctionContributions; import org.hibernate.boot.model.FunctionContributor; diff --git a/hibernate-types/src/main/java/org/hibernate/types/vector/PGVectorTypeContributor.java b/hibernate-vector/src/main/java/org/hibernate/vector/PGVectorTypeContributor.java similarity index 98% rename from hibernate-types/src/main/java/org/hibernate/types/vector/PGVectorTypeContributor.java rename to hibernate-vector/src/main/java/org/hibernate/vector/PGVectorTypeContributor.java index d027d23d83..791e3c6ae7 100644 --- a/hibernate-types/src/main/java/org/hibernate/types/vector/PGVectorTypeContributor.java +++ b/hibernate-vector/src/main/java/org/hibernate/vector/PGVectorTypeContributor.java @@ -4,7 +4,7 @@ * License: GNU Lesser General Public License (LGPL), version 2.1 or later. * See the lgpl.txt file in the root directory or . */ -package org.hibernate.types.vector; +package org.hibernate.vector; import java.lang.reflect.Type; diff --git a/hibernate-types/src/main/java/org/hibernate/types/vector/VectorArgumentTypeResolver.java b/hibernate-vector/src/main/java/org/hibernate/vector/VectorArgumentTypeResolver.java similarity index 98% rename from hibernate-types/src/main/java/org/hibernate/types/vector/VectorArgumentTypeResolver.java rename to hibernate-vector/src/main/java/org/hibernate/vector/VectorArgumentTypeResolver.java index a7ddf8bb04..9dd8d2874b 100644 --- a/hibernate-types/src/main/java/org/hibernate/types/vector/VectorArgumentTypeResolver.java +++ b/hibernate-vector/src/main/java/org/hibernate/vector/VectorArgumentTypeResolver.java @@ -4,7 +4,7 @@ * License: GNU Lesser General Public License (LGPL), version 2.1 or later. * See the lgpl.txt file in the root directory or . */ -package org.hibernate.types.vector; +package org.hibernate.vector; import java.util.List; diff --git a/hibernate-types/src/main/java/org/hibernate/types/vector/VectorArgumentValidator.java b/hibernate-vector/src/main/java/org/hibernate/vector/VectorArgumentValidator.java similarity index 98% rename from hibernate-types/src/main/java/org/hibernate/types/vector/VectorArgumentValidator.java rename to hibernate-vector/src/main/java/org/hibernate/vector/VectorArgumentValidator.java index 3332487ea5..8e4766ef36 100644 --- a/hibernate-types/src/main/java/org/hibernate/types/vector/VectorArgumentValidator.java +++ b/hibernate-vector/src/main/java/org/hibernate/vector/VectorArgumentValidator.java @@ -4,7 +4,7 @@ * License: GNU Lesser General Public License (LGPL), version 2.1 or later. * See the lgpl.txt file in the root directory or . */ -package org.hibernate.types.vector; +package org.hibernate.vector; import java.util.List; diff --git a/hibernate-types/src/main/java/org/hibernate/types/vector/VectorJdbcType.java b/hibernate-vector/src/main/java/org/hibernate/vector/VectorJdbcType.java similarity index 98% rename from hibernate-types/src/main/java/org/hibernate/types/vector/VectorJdbcType.java rename to hibernate-vector/src/main/java/org/hibernate/vector/VectorJdbcType.java index 1a5dd893e3..031ef391d8 100644 --- a/hibernate-types/src/main/java/org/hibernate/types/vector/VectorJdbcType.java +++ b/hibernate-vector/src/main/java/org/hibernate/vector/VectorJdbcType.java @@ -4,7 +4,7 @@ * License: GNU Lesser General Public License (LGPL), version 2.1 or later. * See the lgpl.txt file in the root directory or . */ -package org.hibernate.types.vector; +package org.hibernate.vector; import java.sql.CallableStatement; import java.sql.ResultSet; diff --git a/hibernate-vector/src/main/resources/META-INF/services/org.hibernate.boot.model.FunctionContributor b/hibernate-vector/src/main/resources/META-INF/services/org.hibernate.boot.model.FunctionContributor new file mode 100644 index 0000000000..50860d311b --- /dev/null +++ b/hibernate-vector/src/main/resources/META-INF/services/org.hibernate.boot.model.FunctionContributor @@ -0,0 +1 @@ +org.hibernate.vector.PGVectorFunctionContributor \ No newline at end of file diff --git a/hibernate-vector/src/main/resources/META-INF/services/org.hibernate.boot.model.TypeContributor b/hibernate-vector/src/main/resources/META-INF/services/org.hibernate.boot.model.TypeContributor new file mode 100644 index 0000000000..51a46ab722 --- /dev/null +++ b/hibernate-vector/src/main/resources/META-INF/services/org.hibernate.boot.model.TypeContributor @@ -0,0 +1 @@ +org.hibernate.vector.PGVectorTypeContributor \ No newline at end of file diff --git a/hibernate-types/src/test/java/org/hibernate/types/vector/PGVectorTest.java b/hibernate-vector/src/test/java/org/hibernate/vector/PGVectorTest.java similarity index 99% rename from hibernate-types/src/test/java/org/hibernate/types/vector/PGVectorTest.java rename to hibernate-vector/src/test/java/org/hibernate/vector/PGVectorTest.java index d1b5bf26c0..902c90b194 100644 --- a/hibernate-types/src/test/java/org/hibernate/types/vector/PGVectorTest.java +++ b/hibernate-vector/src/test/java/org/hibernate/vector/PGVectorTest.java @@ -4,7 +4,7 @@ * License: GNU Lesser General Public License (LGPL), version 2.1 or later. * See the lgpl.txt file in the root directory or . */ -package org.hibernate.types.vector; +package org.hibernate.vector; import java.util.List; diff --git a/settings.gradle b/settings.gradle index 742e4ee370..e6a0f078a8 100644 --- a/settings.gradle +++ b/settings.gradle @@ -300,7 +300,7 @@ include 'hibernate-spatial' include 'hibernate-platform' include 'hibernate-community-dialects' -include 'hibernate-types' +include 'hibernate-vector' include 'hibernate-c3p0' include 'hibernate-proxool'