Building AI-Powered Database Apps with Hibernate Vector and the Oracle Database 23ai — Part 1 — Using Hibernate Vector module with Oracle Vector Data Type

Oracle Database 23ai

by Juarez Junior

Introduction — Vector Data Type in Hibernate Vector Module

Vector search is rapidly transforming how we build intelligent, data-driven applications — think recommendation engines, semantic search, and AI-powered analytics. Combining Hibernate with Oracle Database 23ai and its advanced support for vector data types opens a world of possibilities with Hibernate Vector. This powerful extension enables Hibernate to work with Vector Databases such as Oracle Database 23ai.

This blog post explains how to combine Hibernate Vector, Jakarta Persistence, and the Oracle Database 23ai to create innovative GenAI applications.

Part 1 will introduce the Hibernate Vector module and how to use it with Oracle Database 23ai by creating Hibernate DB apps that work with vectors, and tables with embeddings of the VECTOR data type.

Part 2 will show you how to implement similarity search using the Hibernate Vector module, Oracle AI Vector Search, Oracle JDBC, and the Oracle Database 23ai.

So, without further ado, let’s get started!

Prerequisites

• JDK — Java Development Kit 17 or newer
• Oracle Database Free Release 23ai — Container Image
• Oracle JDBC Driver 23ai
• Your preferred Java IDE — Eclipse, IntelliJ, VS Code
• Apache Maven
• Gradle

Step 1: Configure Your Java Project

This assumes you know Java, Hibernate, Maven or Gradle, and relational database concepts. Start by creating a Maven project (or use your preferred build tool). Add the dependencies to your build configuration file.

Using Maven

  <dependencies>
        <!-- Oracle JDBC Driver -->
        <dependency>
            <groupId>com.oracle.database.jdbc</groupId>
            <artifactId>ojdbc17</artifactId>
            <version>23.7.0.25.01</version>
        </dependency>
        <!-- Oracle UCP -->
        <dependency>
            <groupId>com.oracle.database.jdbc</groupId>
            <artifactId>ucp17</artifactId>
            <version>23.7.0.25.01</version>
        </dependency>
        <!-- Hibernate Core -->
        <dependency>
            <groupId>org.hibernate.orm</groupId>
            <artifactId>hibernate-core</artifactId>
            <version>6.6.10.Final</version>
        </dependency>
        <!-- Hibernate Vector Module -->
        <dependency>
            <groupId>org.hibernate.orm</groupId>
            <artifactId>hibernate-vector</artifactId>
            <version>6.6.10.Final</version>
        </dependency>
        <!-- Jakarta EE -->
        <dependency>
            <groupId>jakarta.persistence</groupId>
            <artifactId>jakarta.persistence-api</artifactId>
            <version>3.2.0</version>
        </dependency>
        <dependency>
            <groupId>jakarta.transaction</groupId>
            <artifactId>jakarta.transaction-api</artifactId>
            <version>2.0.1</version>
        </dependency>

Using Gradle

dependencies {
    // Oracle JDBC Driver
    implementation 'com.oracle.database.jdbc:ojdbc17:23.7.0.25.01'
    
    // Oracle UCP
    implementation 'com.oracle.database.jdbc:ucp17:23.7.0.25.01'
    
    // Hibernate Core
    implementation 'org.hibernate.orm:hibernate-core:6.6.10.Final'
    
    // Hibernate Vector Module
    implementation 'org.hibernate.orm:hibernate-vector:6.6.10.Final'   
    
    // Jakarta EE
    implementation 'jakarta.persistence:jakarta.persistence-api:3.2.0'
    implementation 'jakarta.transaction:jakarta.transaction-api:2.0.1'
}

Step 2: Configure Hibernate

As usual, you must modify your Hibernate configuration file (hibernate.properties or hibernate.cfg.xml) to enable it to access your Oracle Database 23ai instance, as it supports Oracle AI Vector Search.

# Oracle JDBC driver
hibernate.connection.url=jdbc:oracle:thin:@<DB_HOST>:<DB_PORT>/FREEPDB1
hibernate.connection.username=<DB_USER>
hibernate.connection.password=<DB_PASSWORD>
hibernate.connection.driver_class=oracle.jdbc.OracleDriver
hibernate.dialect=org.hibernate.dialect.OracleDialect
hibernate.show_sql=false
hibernate.hbm2ddl.auto=update

# Oracle Universal Connection Pool (UCP)
hibenrate.connection.driver_class=oracle.jdbc.OracleDriver
hibernate.oracleucp.connectionFactoryClassName=oracle.jdbc.datasource.impl.OracleDataSource
hibernate.oracleucp.initialPoolSize=3
hibernate.oracleucp.minPoolSize=3
hibernate.oracleucp.maxPoolSize=5
hibernate.oracleucp.connectionPoolName=hibernateVectorPool
hibernate.oracleucp.dataSourceName=hibernateVectorDataSource
hibernate.oracleucp.connectionProperties={autoCommit=false}
hibernate.oracleucp.fastConnectionFailoverEnabled=false
hibernate.oracleucp.validateConnectionOnBorrow=true
hibernate.oracleucp.secondsToTrustIdleConnection=120
hibernate.oracleucp.inactiveConnectionTimeout=180
hibernate.oracleucp.maxStatements=20
hibernate.oracleucp.connectionWaitTimeout=30

Step 3: Create Java Entity With Vector Data Type

Hibernate Vector provides seamless integration with vector-based data.

To see it in action, first, configure your entity model to include an attribute that mas to a Vector Data type column:

@Entity
@Table(name = "VECTOR_USER.vector_data")
public class VectorDataEntity {

  @Id
  @GeneratedValue(strategy = GenerationType.IDENTITY)
  private Long id;

  @Column(name = "embedding")
  @JdbcTypeCode(SqlTypes.VECTOR_FLOAT32)
  @Array(length = 3)
  private float[] embedding;

Here, the @JdbcTypeCode annotation ensures that Hibernate properly maps the vector field to Oracle’s native vector data type.

Step 4: Storing and Retrieving Vector Embeddings

Once your entity is set up, you can store and retrieve vectors using Hibernate:

Insert vector

  private void insertVector() {

    // Open a session
    try (Session session = sessionFactory.openSession()) {
      // Begin a transaction
      Transaction transaction = session.beginTransaction();

      // Create and save a HibernateVectorDataTypeEntity instance
      HibernateVectorDataTypeEntity entity = new HibernateVectorDataTypeEntity();

      // Set the embedding
      // float[] embeddingArray = new float[] { 1.0f, 2.0f, 3.0f };
      // VECTOR vectorValue = VECTOR.ofFloat32Values(embeddingArray);

      float[] embeddingArray = new float[] { 1.0f, 2.0f, 3.0f };
      entity.setEmbedding(embeddingArray);

      // Save the entity
      session.persist(entity);

      // Commit the transaction
      transaction.commit();
    }
  }

Note that you might usually need to use the VECTOR class to perform some final data type adjustments on the embedding array using methods such as VECTOR.ofFloat32Values(), as shown below.

However, that was not a requirement with Hibernate Vector:

// Set the embedding
// float[] embeddingArray = new float[] { 1.0f, 2.0f, 3.0f };
// VECTOR vectorValue = VECTOR.ofFloat32Values(embeddingArray);

float[] embeddingArray = new float[] { 1.0f, 2.0f, 3.0f };
entity.setEmbedding(embeddingArray);

Read vector

  public HibernateVectorDataTypeEntity readVector(long id) {

    try (Session session = sessionFactory.openSession()) {
      return session.get(HibernateVectorDataTypeEntity.class, id);
    }
  }

Update vector

  public void updateVector(HibernateVectorDataTypeEntity entity) {

    try (Session session = sessionFactory.openSession()) {
      Transaction transaction = session.beginTransaction();
      session.merge(entity);
      transaction.commit();
    }

  }

Delete vector

  public void deleteVector(long id) {

    try (Session session = sessionFactory.openSession()) {
      Transaction transaction = session.beginTransaction();
      HibernateVectorDataTypeEntity entity = session.get(HibernateVectorDataTypeEntity.class, id);
      if (entity != null) {
        session.remove(entity);
      }
      transaction.commit();
    } finally {
      sessionFactory.close();
    }

    sessionFactory = null;
    configuration = null;

  }

Below is the complete source code.

HibernateVectorDataTypeOracleDatabase.java

HibernateVectorDataTypeEntity.java

Step 5: Test the sample app

Now, you can run and test the application using your preferred IDE (or the CLI). You may want to set breakpoints to query the database and check the records.

Below are all the inserted records listed. Note that the first record (ID #1) had its values updated by the updateVector() method implementation (set to 4, 5, and 6).

All vectors

Then, we have the same list after deleting the same record (ID #1).

Vector deleted

Last but not least, note that you can enable query debugging if you want to have a look at the underlying HQL queries. Just go to your hibernate.properties file and change hibernate.show_sql from false to true.

HQL queries

Wrap-Up

That’s it! By integrating the Hibernate Vector module with the Oracle Database 23ai, Java developers can efficiently handle vector embeddings. The next blog posts will show you how to implement similarity search using Hibernate Vector and the Oracle Database, so stay tuned!

As one last tip, I invite you to check out the new Database Navigator tool published at JetBrains Marketplace. In a nutshell, it features a robust SQL and PL/SQL editor with advanced capabilities for managing database connections, executing scripts, editing database objects, and modifying data and code with IntelliJ!

I will soon post more examples of scenarios involving LangChain4J, the OracleEmbeddingStore, GraalVM, Micronaut, Quarkus, and other GenAI / Agentic AI-related topics!

That’s it! I hope you liked this blog post, thanks for reading!

References

Hibernate 6.6

Jakarta Persistence

Oracle Database 23ai

Oracle JDBC Driver 23ai (23.4+) — Maven Central

Oracle AI Vector Search Technical Architecture

Oracle Database Free Release 23ai — Container Image

Oracle® Database JDBC Java API Reference, Release 23ai

Database Navigator — JetBrains Marketplace

Quickstart: Connect to Oracle Database 23ai using IntelliJ IDEA

Developers Guide For Oracle JDBC on Maven Central

Develop Java applications with Oracle Database

Oracle Developers and Oracle OCI Free Tier

Join our Oracle Developers channel on Slack to discuss Java, GenAI, Agentic AI, JDK, JDBC, GraalVM, Micronaut, Spring Boot, Helidon, Quarkus, Reactive Streams, Cloud, DevOps, SRE, IaC, and other topics!

Build, test, and deploy your applications on Oracle Cloud — for free! Get access to OCI Cloud Free Tier!