From 5cdcb2c58238d6bd00a310dda16abc7a6d72815e Mon Sep 17 00:00:00 2001 From: LLEFEVRE Date: Thu, 23 May 2024 12:43:14 +0200 Subject: [PATCH] HHH-18157 Document 23ai new features where necessary --- .../asciidoc/quickstart/guides/obtaining.adoc | 2 + .../main/asciidoc/userguide/Bibliography.adoc | 1 + .../appendices/Legacy_Native_Queries.adoc | 2 +- .../chapters/query/extensions/Vector.adoc | 39 ++++++++++++++----- .../chapters/query/spatial/Spatial.adoc | 6 +-- 5 files changed, 37 insertions(+), 13 deletions(-) diff --git a/documentation/src/main/asciidoc/quickstart/guides/obtaining.adoc b/documentation/src/main/asciidoc/quickstart/guides/obtaining.adoc index 2ee4f55516..81a9a507dc 100644 --- a/documentation/src/main/asciidoc/quickstart/guides/obtaining.adoc +++ b/documentation/src/main/asciidoc/quickstart/guides/obtaining.adoc @@ -43,6 +43,7 @@ transitive dependencies based on the features being used or not. |hibernate-envers| Entity versioning and auditing |hibernate-spatial| Support for spatial/GIS data types using https://github.com/GeoLatte/geolatte-geom[GeoLatte] |hibernate-jpamodelgen| An annotation processor that generates a JPA-compliant metamodel, plus optional Hibernate extras +|hibernate-vector| Support for mathematical vector types and functions useful for AI/ML topics like vector similarity search and Retrieval-Augmented Generation (RAG) |=== [cols="40m,~"] @@ -53,6 +54,7 @@ transitive dependencies based on the features being used or not. |hibernate-hikaricp| Support for https://github.com/brettwooldridge/HikariCP/[HikariCP] connection pooling |hibernate-vibur| Support for https://www.vibur.org/[Vibur DBCP] connection pooling |hibernate-proxool| Support for https://proxool.sourceforge.net/[Proxool] connection pooling +|hibernate-ucp| Support for https://docs.oracle.com/en/database/oracle/oracle-database/23/jjucp/intro.html[Universal Connection Pool] connection pooling |hibernate-jcache| Integration with https://jcp.org/en/jsr/detail?id=107$$[JCache], allowing any compliant implementation as a second-level cache provider |hibernate-graalvm| Experimental extension to make it easier to compile applications as a https://www.graalvm.org/[GraalVM] native image |hibernate-micrometer| Integration with https://micrometer.io[Micrometer] metrics diff --git a/documentation/src/main/asciidoc/userguide/Bibliography.adoc b/documentation/src/main/asciidoc/userguide/Bibliography.adoc index b958d80eeb..ee2cbc8271 100644 --- a/documentation/src/main/asciidoc/userguide/Bibliography.adoc +++ b/documentation/src/main/asciidoc/userguide/Bibliography.adoc @@ -4,3 +4,4 @@ Addison-Wesley Professional. 2002. - [[[JPwH]]] Christian Bauer & Gavin King. https://www.manning.com/books/java-persistence-with-hibernate-second-edition[Java Persistence with Hibernate, Second Edition]. Manning Publications Co. 2015. - [[[jdbc]]] https://download.oracle.com/otndocs/jcp/jdbc-4_2-mrel2-spec/[JDBC Specification - Version 4.2] +- [[[jdbc]]] https://download.oracle.com/otndocs/jcp/jdbc-4_3-mrel3-spec/[JDBC Specification - Version 4.3] diff --git a/documentation/src/main/asciidoc/userguide/appendices/Legacy_Native_Queries.adoc b/documentation/src/main/asciidoc/userguide/appendices/Legacy_Native_Queries.adoc index ea446867c7..eeba9ba061 100644 --- a/documentation/src/main/asciidoc/userguide/appendices/Legacy_Native_Queries.adoc +++ b/documentation/src/main/asciidoc/userguide/appendices/Legacy_Native_Queries.adoc @@ -170,7 +170,7 @@ If your mapping has a discriminator you must use `` to spe Hibernate provides support for queries via stored procedures and functions. Most of the following documentation is equivalent for both. The stored procedure/function must return a resultset as the first out-parameter to be able to work with Hibernate. -An example of such a stored function in Oracle 9 and higher is as follows: +An example of such a stored function in Oracle 19c and higher is as follows: [source,xml] ---- diff --git a/documentation/src/main/asciidoc/userguide/chapters/query/extensions/Vector.adoc b/documentation/src/main/asciidoc/userguide/chapters/query/extensions/Vector.adoc index 41d7fc6252..75e42a184e 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/query/extensions/Vector.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/query/extensions/Vector.adoc @@ -9,13 +9,13 @@ === Overview 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. +This is useful for AI/ML topics like vector similarity search and Retrieval-Augmented Generation (RAG). +The module comes with support for a special `vector` data type that essentially represents an array of bytes, floats, or doubles. -So far, only the PostgreSQL extension `pgvector` is supported, but in theory, +So far, both the PostgreSQL extension `pgvector` and the Oracle database 23ai+ `AI Vector Search` feature are 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]. +For further details, refer to the https://github.com/pgvector/pgvector#querying[pgvector documentation] or the https://docs.oracle.com/en/database/oracle/oracle-database/23/vecse/overview-node.html[AI Vector Search documentation]. [[vector-module-setup]] === Setup @@ -44,6 +44,15 @@ so no further configuration is necessary to make the features available. Annotate a persistent attribute with `@JdbcTypeCode(SqlTypes.VECTOR)` and specify the vector length with `@Array(length = ...)`. +[WARNING] +==== +As Oracle AI Vector Search supports different types of elements (to ensure better performance and compatibility with embedding models), you can also use: + +- `@JdbcTypeCode(SqlTypes.VECTOR_INT8)` for `byte[]` +- `@JdbcTypeCode(SqlTypes.VECTOR_FLOAT32)` for `float[]` +- `@JdbcTypeCode(SqlTypes.VECTOR_FLOAT64)` for `double[]`. +==== + [[vector-module-usage-example]] ==== [source, JAVA, indent=0] @@ -63,18 +72,30 @@ Expressions of the vector type can be used with various vector functions. |=== | Function | Purpose -| `cosine_distance()` | Computes the https://en.wikipedia.org/wiki/Cosine_similarity[cosine distance] between two vectors. Maps to the `<``=``>` operator -| `euclidean_distance()` | Computes the https://en.wikipedia.org/wiki/Euclidean_distance[euclidean distance] between two vectors. Maps to the `<``-``>` operator +| `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`. + +| `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 +`vector_distance(v1, v2, EUCLIDEAN)` function for `Oracle AI Vector Search`. + | `l2_distance()` | Alias for `euclidean_distance()` -| `taxicab_distance()` | Computes the https://en.wikipedia.org/wiki/Taxicab_geometry[taxicab distance] between two vectors + +| `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`. + | `l1_distance()` | Alias for `taxicab_distance()` + +| `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`. + | `inner_product()` | Computes the https://en.wikipedia.org/wiki/Inner_product_space[inner product] between two vectors -| `negative_inner_product()` | Computes the negative inner product. Maps to the `<``#``>` operator + +| `negative_inner_product()` | Computes the negative inner product. Maps to the `<``#``>` operator for `pgvector` and maps to the +`vector_distance(v1, v2, DOT)` function for `Oracle AI Vector Search`. + | `vector_dims()` | Determines the dimensions of a vector + | `vector_norm()` | Computes the https://en.wikipedia.org/wiki/Euclidean_space#Euclidean_norm[Euclidean norm] of a vector |=== -In addition to these special vector functions, it is also possible to use vectors with the following builtin operators +In addition to these special vector functions, it is also possible to use vectors with the following builtin `pgvector` operators: ` + = `:: Element-wise addition of vectors. ` - = `:: Element-wise subtraction of vectors. diff --git a/documentation/src/main/asciidoc/userguide/chapters/query/spatial/Spatial.adoc b/documentation/src/main/asciidoc/userguide/chapters/query/spatial/Spatial.adoc index 975712d20f..4d3096d359 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/query/spatial/Spatial.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/query/spatial/Spatial.adoc @@ -13,7 +13,7 @@ Since 5.0, Hibernate Spatial is now part of the Hibernate ORM project, and it allows you to deal with geographic data in a standardized way. Hibernate Spatial provides a standardized, cross-database interface to geographic data storage and query functions. -It supports most of the functions described by the OGC Simple Feature Specification. Supported databases are Oracle 10g/11g, +It supports most of the functions described by the OGC Simple Feature Specification. Supported databases are Oracle 19c/21c/23ai, PostgreSQL/PostGIS, MySQL, Microsoft SQL Server, DB2, CockroachDB and H2/GeoDB. Spatial data types are not part of the Java standard library, and they are absent from the JDBC specification. @@ -72,7 +72,7 @@ functions largely correspond to those specified in the https://portal.opengeospa .Hibernate Spatial dialect function support [cols=",,,,,,,," |options="header",] |================================ -|Function | Description | PostgresSQL | Oracle 10g/11g | MySQL | SQLServer | H2GIS | DB2 | CockroachDB +|Function | Description | PostgresSQL | Oracle 19c/21c/23ai | MySQL | SQLServer | H2GIS | DB2 | CockroachDB |Basic functions on Geometry | | | | | | | | |`int st_dimension(Geometry)` | SFS §2.1.1.1 | {yes} | {yes} | {yes} | {yes} | {yes} | {yes} | {yes} |`String st_geometrytype(Geometry)` | SFS §2.1.1.1 | {yes} | {yes} | {yes} | {yes} | {yes} | {yes} | {yes} @@ -148,7 +148,7 @@ For more information, see this page in the MySQL reference guide (esp. the secti [[spatial-configuration-dialect-oracle]] -Oracle10g/11g:: +Oracle 19c/21c/23ai:: There is currently only support for the `SDO_GEOMETRY` type. +