HHH-18157 Document 23ai new features where necessary

This commit is contained in:
LLEFEVRE 2024-05-23 12:43:14 +02:00 committed by Christian Beikov
parent 51f0692240
commit 5cdcb2c582
5 changed files with 37 additions and 13 deletions

View File

@ -43,6 +43,7 @@ transitive dependencies based on the features being used or not.
|hibernate-envers| Entity versioning and auditing |hibernate-envers| Entity versioning and auditing
|hibernate-spatial| Support for spatial/GIS data types using https://github.com/GeoLatte/geolatte-geom[GeoLatte] |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-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,~"] [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-hikaricp| Support for https://github.com/brettwooldridge/HikariCP/[HikariCP] connection pooling
|hibernate-vibur| Support for https://www.vibur.org/[Vibur DBCP] 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-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-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-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 |hibernate-micrometer| Integration with https://micrometer.io[Micrometer] metrics

View File

@ -4,3 +4,4 @@
Addison-Wesley Professional. 2002. 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. - [[[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_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]

View File

@ -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. Hibernate provides support for queries via stored procedures and functions.
Most of the following documentation is equivalent for both. 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. 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] [source,xml]
---- ----

View File

@ -9,13 +9,13 @@
=== Overview === Overview
The Hibernate ORM Vector module contains support for mathematical vector types and functions. The Hibernate ORM Vector module contains support for mathematical vector types and functions.
This is useful for AI/ML topics like vector similarity search. 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 floats. 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. 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]] [[vector-module-setup]]
=== 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 = ...)`. 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]] [[vector-module-usage-example]]
==== ====
[source, JAVA, indent=0] [source, JAVA, indent=0]
@ -63,18 +72,30 @@ Expressions of the vector type can be used with various vector functions.
|=== |===
| Function | Purpose | Function | Purpose
| `cosine_distance()` | Computes the https://en.wikipedia.org/wiki/Cosine_similarity[cosine 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
| `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()` | `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()` | `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 | `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_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 | `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 addition of vectors.
`<vector1> - <vector2> = <vector3>`:: Element-wise subtraction of vectors. `<vector1> - <vector2> = <vector3>`:: Element-wise subtraction of vectors.

View File

@ -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. 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. 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. 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. 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 .Hibernate Spatial dialect function support
[cols=",,,,,,,," |options="header",] [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 | | | | | | | | |Basic functions on Geometry | | | | | | | |
|`int st_dimension(Geometry)` | SFS §2.1.1.1 | {yes} | {yes} | {yes} | {yes} | {yes} | {yes} | {yes} |`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} |`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]] [[spatial-configuration-dialect-oracle]]
Oracle10g/11g:: Oracle 19c/21c/23ai::
There is currently only support for the `SDO_GEOMETRY` type. There is currently only support for the `SDO_GEOMETRY` type.
+ +