Skip to content

Commit cef7452

Browse files
committed
Update docs and whats-new for new vector module enhancements
1 parent a68e7ad commit cef7452

File tree

9 files changed

+72
-25
lines changed

9 files changed

+72
-25
lines changed

documentation/src/main/asciidoc/userguide/chapters/query/extensions/Vector.adoc

Lines changed: 22 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,14 @@ Currently, the following databases are supported:
1818
* https://docs.oracle.com/en/database/oracle/oracle-database/23/vecse/overview-node.html[Oracle database 23ai+]
1919
* https://mariadb.com/docs/server/reference/sql-structure/vectors/vector-overview[MariaDB 11.7+]
2020
* https://dev.mysql.com/doc/refman/9.4/en/vector-functions.html[MySQL 9.0+]
21+
* https://www.cockroachlabs.com/docs/stable/vector[CockroachDB 24.2+]
22+
* https://www.ibm.com/docs/en/db2/12.1.0?topic=list-vector-values[DB2 12.1+]
23+
* https://help.sap.com/docs/hana-cloud-database/sap-hana-cloud-sap-hana-database-vector-engine-guide/sap-hana-cloud-sap-hana-database-vector-engine-guide[SAP HANA Cloud QRC 4/2024+]
24+
* https://learn.microsoft.com/en-us/sql/t-sql/data-types/vector-data-type?view=sql-server-ver17[SQL Server 2025+]
2125

2226
In theory, the vector-specific functions could be implemented to work with every database that supports arrays.
27+
Since the performance strongly depends on the existence of a vector index and the search is potentially probabilistic,
28+
no emulation has been implemented yet.
2329

2430
[WARNING]
2531
====
@@ -93,40 +99,37 @@ Expressions of the vector type can be used with various vector functions.
9399
|===
94100
| Function | Purpose
95101

96-
| `cosine_distance()` | Computes the https://en.wikipedia.org/wiki/Cosine_similarity[cosine distance] between two vectors. Maps to the `<``=``>` operator for `pgvector` and maps to the `vector_distance(v1, v2, COSINE)` function for `Oracle AI Vector Search`.
102+
| `cosine_distance()` | Computes the https://en.wikipedia.org/wiki/Cosine_similarity[cosine distance] between two vectors.
97103

98-
| `euclidean_distance()` | Computes the https://en.wikipedia.org/wiki/Euclidean_distance[euclidean distance] between two vectors. Maps to the `<``-``>` operator for `pgvector` and maps to the
99-
`vector_distance(v1, v2, EUCLIDEAN)` function for `Oracle AI Vector Search`.
104+
| `euclidean_distance()` | Computes the https://en.wikipedia.org/wiki/Euclidean_distance[euclidean distance] between two vectors.
100105

101106
| `euclidean_squared_distance()` | Computes the https://en.wikipedia.org/wiki/Euclidean_distance#Squared_Euclidean_distance[squared euclidean distance] between two vectors.
102107

103-
| `l2_distance()` | Alias for `euclidean_distance()`
108+
| `l2_distance()` | Alias for `euclidean_distance()`.
104109

105-
| `l2_squared_distance()` | Alias for `euclidean_squared_distance()`
110+
| `l2_squared_distance()` | Alias for `euclidean_squared_distance()`.
106111

107-
| `taxicab_distance()` | Computes the https://en.wikipedia.org/wiki/Taxicab_geometry[taxicab distance] between two vectors. Maps to `vector_distance(v1, v2, MANHATTAN)` function for `Oracle AI Vector Search`.
112+
| `taxicab_distance()` | Computes the https://en.wikipedia.org/wiki/Taxicab_geometry[taxicab distance] between two vectors.
108113

109-
| `l1_distance()` | Alias for `taxicab_distance()`
114+
| `l1_distance()` | Alias for `taxicab_distance()`.
110115

111-
| `hamming_distance()` | Computes the https://en.wikipedia.org/wiki/Hamming_distance[hamming distance] between two vectors. Maps to `vector_distance(v1, v2, HAMMING)` function for `Oracle AI Vector Search`.
116+
| `hamming_distance()` | Computes the https://en.wikipedia.org/wiki/Hamming_distance[hamming distance] between two vectors.
112117

113-
| `jaccard_distance()` | Computes the https://en.wikipedia.org/wiki/Jaccard_index[jaccard distance] between two vectors. Maps to the `<``%``>` operator for `pgvector` and maps to the
114-
`vector_distance(v1, v2, JACCARD)` function for `Oracle AI Vector Search`.
118+
| `jaccard_distance()` | Computes the https://en.wikipedia.org/wiki/Jaccard_index[jaccard distance] between two vectors.
115119

116-
| `inner_product()` | Computes the https://en.wikipedia.org/wiki/Inner_product_space[inner product] between two vectors
120+
| `inner_product()` | Computes the https://en.wikipedia.org/wiki/Inner_product_space[inner product] between two vectors.
117121

118-
| `negative_inner_product()` | Computes the negative inner product. Maps to the `<``#``>` operator for `pgvector` and maps to the
119-
`vector_distance(v1, v2, DOT)` function for `Oracle AI Vector Search`.
122+
| `negative_inner_product()` | Computes the negative inner product.
120123

121-
| `vector_dims()` | Determines the dimensions of a vector
124+
| `vector_dims()` | Determines the dimensions of a vector.
122125

123-
| `vector_norm()` | Computes the https://en.wikipedia.org/wiki/Euclidean_space#Euclidean_norm[Euclidean norm] of a vector
126+
| `vector_norm()` | Computes the https://en.wikipedia.org/wiki/Euclidean_space#Euclidean_norm[Euclidean norm] of a vector.
124127

125-
| `l2_norm()` | Alias for `vector_norm()`
128+
| `l2_norm()` | Alias for `vector_norm()`.
126129

127130
| `l2_normalize()` | Normalizes each component of a vector by dividing it with the https://en.wikipedia.org/wiki/Euclidean_space#Euclidean_norm[Euclidean norm] of the vector.
128131

129-
| `binary_quantize()` | Reduces a vector of size N to a binary vector with N bits, using 0 for values <= 0 and 1 for values > 0.
132+
| `binary_quantize()` | Reduces a vector of size N to a binary vector with N bits, using 0 for values \<= 0 and 1 for values > 0.
130133

131134
| `subvector()` | Creates a subvector from a given vector, a 1-based start index and a count.
132135
|===
@@ -187,7 +190,7 @@ include::{example-dir-vector}/FloatVectorTest.java[tags=euclidean-squared-distan
187190
===== `taxicab_distance()` and `l1_distance()`
188191

189192
Computes the https://en.wikipedia.org/wiki/Taxicab_geometry[taxicab distance] between two vectors,
190-
which is `vector_norm(v1) - vector_norm(v2)`.
193+
which is `vector_norm(v1) - vector_norm(v2)`. Maps to the `<``+``>` pgvector operator.
191194
The `l1_distance()` function is an alias.
192195

193196
[[vector-module-functions-taxicab-distance-example]]
@@ -298,7 +301,7 @@ include::{example-dir-vector}/FloatVectorTest.java[tags=binary-quantize-example]
298301
====
299302

300303
[[vector-module-functions-subvector]]
301-
===== `binary_quantize()`
304+
===== `subvector()`
302305

303306
Creates a subvector from a given vector, a 1-based start index and a count.
304307

hibernate-core/src/main/java/org/hibernate/type/SqlTypes.java

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -709,27 +709,32 @@ public class SqlTypes {
709709
* A type code representing a bit precision vector type for databases
710710
* like {@link org.hibernate.dialect.PostgreSQLDialect PostgreSQL} and
711711
* {@link org.hibernate.dialect.OracleDialect Oracle 23ai}.
712+
* @since 7.2
712713
*/
713714
public static final int VECTOR_BINARY = 10_004;
714715

715716
/**
716717
* A type code representing a half-precision floating-point vector type for databases
717718
* like {@link org.hibernate.dialect.PostgreSQLDialect PostgreSQL}.
719+
* @since 7.2
718720
*/
719721
public static final int VECTOR_FLOAT16 = 10_005;
720722

721723
/**
722724
* A type code representing a sparse single-byte integer vector type for Oracle 23ai database.
725+
* @since 7.2
723726
*/
724727
public static final int SPARSE_VECTOR_INT8 = 10_006;
725728

726729
/**
727730
* A type code representing a sparse single-precision floating-point vector type for Oracle 23ai database.
731+
* @since 7.2
728732
*/
729733
public static final int SPARSE_VECTOR_FLOAT32 = 10_007;
730734

731735
/**
732736
* A type code representing a sparse double-precision floating-point vector type for Oracle 23ai database.
737+
* @since 7.2
733738
*/
734739
public static final int SPARSE_VECTOR_FLOAT64 = 10_008;
735740

hibernate-vector/src/main/java/org/hibernate/vector/AbstractSparseVector.java

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414
/**
1515
* Base class for sparse vectors.
1616
*
17-
* @since 7.1
17+
* @since 7.2
1818
*/
1919
public abstract class AbstractSparseVector<E> extends AbstractList<E> {
2020

hibernate-vector/src/main/java/org/hibernate/vector/SparseByteVector.java

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
/**
1111
* {@link java.util.List} implementation for a sparse byte vector.
1212
*
13-
* @since 7.1
13+
* @since 7.2
1414
*/
1515
public class SparseByteVector extends AbstractSparseVector<Byte> {
1616

hibernate-vector/src/main/java/org/hibernate/vector/SparseDoubleVector.java

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
/**
1111
* {@link List} implementation for a sparse byte vector.
1212
*
13-
* @since 7.1
13+
* @since 7.2
1414
*/
1515
public class SparseDoubleVector extends AbstractSparseVector<Double> {
1616

hibernate-vector/src/main/java/org/hibernate/vector/SparseFloatVector.java

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
/**
1111
* {@link List} implementation for a sparse byte vector.
1212
*
13-
* @since 7.1
13+
* @since 7.2
1414
*/
1515
public class SparseFloatVector extends AbstractSparseVector<Float> {
1616

hibernate-vector/src/main/java/org/hibernate/vector/internal/VectorDdlType.java

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111
/**
1212
* DDL type for vector types.
1313
*
14-
* @since 7.1
14+
* @since 7.2
1515
*/
1616
public class VectorDdlType extends DdlTypeImpl {
1717

hibernate-vector/src/main/java/org/hibernate/vector/internal/VectorHelper.java

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313
/**
1414
* Helper for vector related functionality.
1515
*
16-
* @since 7.1
16+
* @since 7.2
1717
*/
1818
public class VectorHelper {
1919

whats-new.adoc

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,3 +11,42 @@ Describes the new features and capabilities added to Hibernate ORM in {version}.
1111

1212
IMPORTANT: If migrating from earlier versions, be sure to also check out the link:{migrationGuide}[Migration Guide] for discussion of impactful changes.
1313

14+
[[vector-module-enhancements]]
15+
== Hibernate-Vector module enhancements
16+
17+
Support for binary, float16 and sparse vectors were added.
18+
19+
====
20+
[source, java, indent=0]
21+
----
22+
@Entity
23+
public class MyEntity {
24+
@Id
25+
UUID id;
26+
@JdbcTypeCode(SqlTypes.VECTOR_BINARY)
27+
@Array(length = 24) // Refers to the bit count
28+
byte[] binaryVector;
29+
@JdbcTypeCode(SqlTypes.VECTOR_FLOAT16)
30+
@Array(length = 3)
31+
float[] float16Vector;
32+
@Array(length = 3)
33+
SparseFloatVector sparseFloat32Vector;
34+
}
35+
----
36+
====
37+
38+
The Hibernate Vector module currently ships with 3 sparse vector types:
39+
40+
* `SparseByteVector`
41+
* `SparseFloatVector`
42+
* `SparseDoubleVector`
43+
44+
In addition to accessing the sparse indices and values, they also implement the `List` interface to provide access
45+
as if it were a dense vector.
46+
47+
Also, support for vectors in the following databases was added:
48+
49+
* https://dev.mysql.com/doc/refman/9.4/en/vector-functions.html[MySQL 9.0+]
50+
* https://www.ibm.com/docs/en/db2/12.1.0?topic=list-vector-values[DB2 12.1+]
51+
* https://help.sap.com/docs/hana-cloud-database/sap-hana-cloud-sap-hana-database-vector-engine-guide/sap-hana-cloud-sap-hana-database-vector-engine-guide[SAP HANA Cloud QRC 4/2024+]
52+
* https://learn.microsoft.com/en-us/sql/t-sql/data-types/vector-data-type?view=sql-server-ver17[SQL Server 2025+]

0 commit comments

Comments
 (0)