Querydsl Vector
The Vector modules add type-safe similarity search over embedding columns.
Vectors are mapped to float[] and exposed as VectorPath in query types.
| Database | SQL templates | JPA (Hibernate) |
|---|---|---|
| PostgreSQL + pgvector | PGvectorTemplates |
yes |
| Oracle 23ai | OracleVectorTemplates |
yes |
| Db2 12.1.2+ | DB2VectorTemplates |
yes |
| SQL Server 2025 | SQLServerVectorTemplates |
yes, except l1Distance |
| MariaDB 11.7+ | MariaDBVectorTemplates |
l2Distance and cosineDistance only |
Operations
| Method | pgvector | Oracle and Db2 | SQL Server | MariaDB |
|---|---|---|---|---|
l2Distance |
<-> |
VECTOR_DISTANCE(.., EUCLIDEAN) |
VECTOR_DISTANCE('euclidean', ..) |
VEC_DISTANCE_EUCLIDEAN |
l2SquaredDistance |
(<->)^2 |
VECTOR_DISTANCE(.., EUCLIDEAN_SQUARED) |
SQUARE(VECTOR_DISTANCE('euclidean', ..)) |
POWER(VEC_DISTANCE_EUCLIDEAN, 2) |
cosineDistance |
<=> |
VECTOR_DISTANCE(.., COSINE) |
VECTOR_DISTANCE('cosine', ..) |
VEC_DISTANCE_COSINE |
innerProduct |
(<#>) * -1 |
VECTOR_DISTANCE(.., DOT) * -1 |
VECTOR_DISTANCE('dot', ..) * -1 |
- |
negativeInnerProduct |
<#> |
VECTOR_DISTANCE(.., DOT) |
VECTOR_DISTANCE('dot', ..) |
- |
l1Distance |
<+> |
VECTOR_DISTANCE(.., MANHATTAN) |
- | - |
dimensionCount |
vector_dims |
VECTOR_DIMENSION_COUNT |
VECTORPROPERTY(.., 'Dimensions') |
LENGTH(..) DIV 4 |
l2Norm |
vector_norm |
VECTOR_NORM |
VECTOR_NORM(.., 'norm2') |
- |
A - means the database has no such function, so the query fails.
You can use a float[] or another vector expression for each distance. Use
VectorExpressions.createConstantVector(float[]) to turn a value into an
expression. For example, use createConstantVector(question).dimensionCount().
In JPA, you must compare a constant with a vector property. This is because
Hibernate cannot figure out the type of a standalone array parameter. Sort by
distance in ascending order to find the nearest neighbours first. On pgvector,
using the operator form allows PostgreSQL to use HNSW and IVFFlat indexes.
SQL
<dependency>
<groupId>io.github.openfeign.querydsl</groupId>
<artifactId>querydsl-sql-vector</artifactId>
<version>7.1</version>
</dependency>
Use the vector templates for your database instead of the plain dialect templates:
SQLQueryFactory queryFactory =
new SQLQueryFactory(new Configuration(new PGvectorTemplates()), dataSource);
float[] question = embeddingModel.embed("how do I reset my password?");
List<String> titles = queryFactory
.select(document.title)
.from(document)
.orderBy(document.embedding.cosineDistance(question).asc())
.limit(5)
.fetch();
To use vectors with other extensions like PostGIS, add these things to your own
SQLTemplates subclass:
- The operators from
VectorOperatorSqlPatterns - The
PGvectorTypecustom type
The Db2 driver cannot send vector parameters, so DB2VectorType sends each
vector as text wrapped in VECTOR(?, n, FLOAT32). SQL Server needs the
mssql-jdbc driver, which provides microsoft.sql.Vector.
Code Generation
If you add querydsl-sql-vector to the querydsl-maven-plugin classpath,
vector columns are generated as VectorPath. This also works alongside
querydsl-sql-spatial:
<plugin>
<groupId>io.github.openfeign.querydsl</groupId>
<artifactId>querydsl-maven-plugin</artifactId>
<version>7.1</version>
...
<dependencies>
<dependency>
<groupId>io.github.openfeign.querydsl</groupId>
<artifactId>querydsl-sql-vector</artifactId>
<version>7.1</version>
</dependency>
</dependencies>
</plugin>
JPA
Map the column with Hibernate Vector
and add querydsl-vector to the annotation processor path:
@Entity
public class Document {
@Id Long id;
String title;
@JdbcTypeCode(SqlTypes.VECTOR)
@Array(length = 1536)
float[] embedding;
}
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<annotationProcessorPaths>
<path>
<groupId>io.github.openfeign.querydsl</groupId>
<artifactId>querydsl-apt</artifactId>
<version>7.1</version>
<classifier>jpa</classifier>
</path>
<path>
<groupId>io.github.openfeign.querydsl</groupId>
<artifactId>querydsl-vector</artifactId>
<version>7.1</version>
</path>
</annotationProcessorPaths>
</configuration>
</plugin>
If you put querydsl-vector in the processor path, every float[] property is
generated as a VectorPath. If you add org.hibernate.orm:hibernate-vector and
querydsl-vector at runtime, HQLTemplates renders the hibernate-vector
functions:
List<Document> nearest = queryFactory
.selectFrom(document)
.orderBy(document.embedding.l2Distance(question).asc())
.limit(10)
.fetch();
float[] Is Reserved for Vectors
With querydsl-vector on the processor path, other float[] properties lose
ArrayPath. Under any of the vector templates, every float[] binds as a
vector. To map a real[] column, register its type
explicitly:
configuration.register("table", "column", new ArrayType<>(float[].class, "real"));