HHH-18157 Document 23ai new features where necessary

loiclefevre · beikov · commit 5cdcb2c58238 · 2024-05-23T12:46:32.000+02:00
diff --git 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
@@ -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
@@ -170,7 +170,7 @@ If your mapping has a discriminator you must use `<return-discriminator>` 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
@@ -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:
 
 `<vector1> + <vector2> = <vector3>`:: Element-wise addition of vectors.
 `<vector1> - <vector2> = <vector3>`:: 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
@@ -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.
 +
