Using Oracle AI Vector Search With Spring AI

Table of Content#

Prerequisites
Setting up Oracle Vector Database
Integrating Spring AI with Oracle Vector Database
Common Operations
- Inserting Vector Data
- Performing Similarity Search
Best Practices
Example Usage
References

Prerequisites#

Oracle Database: You need to have an Oracle Database instance up and running. Ensure it has the necessary permissions and configurations to support vector data operations.
Java Development Kit (JDK): Installed on your development machine (preferably JDK 8 or higher).
Spring Boot: Familiarity with Spring Boot concepts as Spring AI is built on top of it. You'll need to set up a Spring Boot project.

Setting up Oracle Vector Database#

Enable Vector Data Types: In your Oracle Database, make sure the necessary extensions or configurations are in place to support vector data types. This might involve enabling specific database options during installation or configuration.
Create a Table for Vector Data:

CREATE TABLE vector_data (
    id NUMBER PRIMARY KEY,
    vector_column VECTOR(*, 1536) -- Using Oracle 23c+ VECTOR data type with 1536 dimensions
);

Here, VECTOR is the dedicated vector data type introduced in Oracle 23c AI Vector Search.

Integrating Spring AI with Oracle Vector Database#

Add Dependencies: In your pom.xml (for Maven projects), add the following dependencies:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-core</artifactId>
    <version>1.0.0</version> <!-- Use the latest version available -->
</dependency>
<dependency>
    <groupId>com.oracle.database.jdbc</groupId>
    <artifactId>ojdbc8</artifactId>
    <version>21.3.0.0</version> <!-- Adjust version as per your Oracle JDBC driver -->
</dependency>

Configure Data Source: In your Spring Boot application properties (application.properties or application.yml), configure the Oracle database connection:

spring.datasource.url=jdbc:oracle:thin:@//localhost:1521/your_database_service_name
spring.datasource.username=your_username
spring.datasource.password=your_password
spring.datasource.driver-class-name=oracle.jdbc.driver.OracleDriver

Create a Repository: Using Spring Data JPA (or a similar approach), create a repository interface to interact with the vector_data table:

import org.springframework.data.jpa.repository.JpaRepository;
import com.example.model.VectorData; // Assume VectorData is your entity class
 
public interface VectorDataRepository extends JpaRepository<VectorData, Long> {
    // You can add custom query methods for vector-specific operations later
}

Common Operations#

Inserting Vector Data#

Create an Entity Class:

import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;
import org.springframework.data.geo.Point; // Example, if using Spring's Point for vector representation (adjust as per your vector model)
 
@Entity
public class VectorData {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private float[] vector; // Using float array for high-dimensional vector representation
 
    // Getters and setters
    public Long getId() {
        return id;
    }
 
    public void setId(Long id) {
        this.id = id;
    }
 
    public float[] getVector() {
        return vector;
    }
 
    public void setVector(float[] vector) {
        this.vector = vector;
    }
}

Insert Data in a Service Class:

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import com.example.repository.VectorDataRepository;
import com.example.model.VectorData;
import org.springframework.data.geo.Point;
 
@Service
public class VectorDataService {
    @Autowired
    private VectorDataRepository repository;
 
    public void insertVectorData(Point vector) {
        VectorData data = new VectorData();
        data.setVector(vector);
        repository.save(data);
    }
}

Performing Similarity Search#

Custom Query (Using Oracle AI Vector Search Functions): In your VectorDataRepository, you can define a custom query for similarity search using VECTOR_DISTANCE:

import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.query.Param;
import java.util.List;
import com.example.model.VectorData;
 
public interface VectorDataRepository extends JpaRepository<VectorData, Long> {
    @Query(nativeQuery = true, value = "SELECT * FROM vector_data ORDER BY VECTOR_DISTANCE(vector_column, :query_vector) FETCH FIRST 10 ROWS ONLY")
    List<VectorData> findSimilarVectors(@Param("query_vector") float[] queryVector);
}

Here, VECTOR_DISTANCE is the dedicated Oracle AI Vector Search function for similarity search. The example uses 1536-dimensional vectors. 2. Use in a Service Class:

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import com.example.repository.VectorDataRepository;
import com.example.model.VectorData;
import org.springframework.data.geo.Point;
import java.util.List;
 
@Service
public class VectorDataService {
    @Autowired
    private VectorDataRepository repository;
 
    public List<VectorData> findSimilarVectors(Point queryVector) {
        return repository.findSimilarVectors(queryVector);
    }
}

Best Practices#

Indexing: Create appropriate indexes on the vector columns in Oracle. For spatial vectors (like in the example above), Oracle's spatial indexes can significantly speed up similarity search operations.
Data Normalization: Ensure that your vector data is normalized before insertion. This helps in more accurate similarity calculations.
Error Handling: In your Spring AI code, implement proper error handling for database operations. Catch exceptions related to database connectivity, query execution, etc., and handle them gracefully.

Example Usage#

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.CommandLineRunner;
import com.example.service.VectorDataService;
import org.springframework.data.geo.Point;
 
@SpringBootApplication
public class SpringAiOracleVectorApp implements CommandLineRunner {
    @Autowired
    private VectorDataService service;
 
    public static void main(String[] args) {
        SpringApplication.run(SpringAiOracleVectorApp.class, args);
    }
 
    @Override
    public void run(String... args) throws Exception {
        // Insert a sample vector
        Point sampleVector = new Point(1.0, 2.0); // Example vector coordinates (modify as per your vector model)
        service.insertVectorData(sampleVector);
 
        // Perform similarity search
        Point queryVector = new Point(1.1, 2.1); // Another example vector for query
        List<VectorData> similarVectors = service.findSimilarVectors(queryVector);
        System.out.println("Number of similar vectors found: " + similarVectors.size());
    }
}

References#

This blog provides a comprehensive guide to using Oracle Vector Database with Spring AI. By following the steps and best practices outlined, you can build powerful AI applications that leverage the capabilities of both technologies for efficient vector data management and similarity search.