[velo]

Adds type-safe vector similarity search for SQL and JPA. The layout follows spatial: a shared module plus a SQL module.

Usage

float[] question = embeddingModel.embed("how do I reset my password?");

List<String> titles = queryFactory
    .select(document.title)
    .from(document)
    .where(document.embedding.cosineDistance(question).lt(0.3))
    .orderBy(document.embedding.cosineDistance(question).asc())
    .limit(5)
    .fetch();

With PGvectorTemplates this renders order by (document.embedding <=> ?) asc limit ?. That operator form is what pgvector's HNSW and IVFFlat indexes need.

Modules

querydsl-vector

• VectorExpression / VectorPath (over float[]) provide l2Distance, l2SquaredDistance, cosineDistance, innerProduct, negativeInnerProduct, l1Distance, dimensionCount() and l2Norm().
• VectorExpressions.createConstantVector(float[]) turns a value into an expression, so a constant can appear on either side.
• FloatArrayVectorPathExtension maps float[] to VectorPath when the module is on the annotation processor path.
• HibernateVectorOperatorPatterns maps the operators to the HQL functions that hibernate-vector registers. HQLTemplates loads it reflectively, the same way it loads spatial.

querydsl-sql-vector

• PGvectorTemplates uses the <->, <=>, <#> and <+> operators, plus vector_dims and vector_norm.
• OracleVectorTemplates uses VECTOR_DISTANCE(.., EUCLIDEAN|EUCLIDEAN_SQUARED|COSINE|DOT|MANHATTAN), VECTOR_DIMENSION_COUNT and VECTOR_NORM.
• VectorOperatorSqlPatterns exposes the operator maps, so vectors can be combined with other dialect extensions such as PostGIS.
• PGvectorType binds a PGobject typed vector. An untyped parameter is ambiguous in PostgreSQL: vector_dims($1) and $1 <-> $2 fail as "not unique" because pgvector overloads them for halfvec. OracleVectorType binds with OracleType.VECTOR_FLOAT32.
• SqlVectorCodegenExtension maps vector columns to float[], so the SQL exporter generates them as new VectorPath(forProperty(...)) on a plain RelationalPathBase. It does not bind the entity path type, so it works alongside querydsl-sql-spatial (covered by VectorCodegenTest).

Changes to existing code

• Configuration registered template custom types before the built-in array types, so the generic float[] array mapping overwrote the vector type. Custom types are explicit overrides, so they now register last. None of the existing template custom types are arrays, so their behaviour is unchanged.
• MetaDataSerializer used a create<Type> factory for every custom com.querydsl path type. It now uses one only when the entity path base class actually declares it, and otherwise falls back to the generic new XPath(forProperty(...)). Spatial output is unchanged.

Database coverage

The integration tests run on PostgreSQL + pgvector and on Oracle 23ai, through both SQL and JPA/Hibernate.

• pgvector gets a new pgvector compose service (pgvector/pgvector:0.8.1-pg16, port 5433), which keeps the PostGIS image untouched.
• Oracle reuses the existing Oracle Free container.

Both modules are added to SQL_MODULES and ORACLE_MODULES, and the PostgreSQL job now also starts pgvector.

Left out for now:

• MySQL Community has no distance functions.
• MariaDB and SQL Server 2025 would each need a new or upgraded container. They are follow-ups.

Known limitation

In JPA, a constant vector must be compared with a vector property. Hibernate binds a standalone float[] parameter as a plain array, so createConstantVector(q).dimensionCount() does not work there. SQL has no such restriction.

With querydsl-vector on the processor path, every float[] property becomes a VectorPath, and under the vector templates every float[] binds as a vector. A real[] column needs an explicit ArrayType registration; the docs cover this.

Docs

Adds docs/tutorials/vector.md and a row in the backend table on the landing page.