Oracle Vector Store

Use the Spring AI Oracle vector store to add document embeddings and similarity search to Spring Boot applications.

The Oracle vector store uses Oracle AI Database Vector Search through the Spring AI VectorStore interface. Use this guide with Spring AI 1.1.7 or a compatible version and Oracle AI Database 23.4 or later.

Contents

Add Spring Boot Starter Dependencies

Add the Oracle vector store starter to your Maven build.

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-vector-store-oracle</artifactId>
</dependency>

For Gradle, add the starter as an implementation dependency.

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-vector-store-oracle'
}

The vector store requires an EmbeddingModel bean. For example, add the OpenAI model starter when your application uses OpenAI embeddings.

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>

For Gradle, add the OpenAI starter as an implementation dependency.

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-openai'
}

Use the Spring AI dependency management and repository configuration that matches your selected Spring AI release.

Configure the Data Source and Vector Store

Configure the Oracle JDBC data source and Oracle vector store properties in application.yml.

spring:
  datasource:
    url: jdbc:oracle:thin:@//localhost:1521/freepdb1
    username: mlops
    password: mlops
  ai:
    vectorstore:
      oracle:
        index-type: IVF
        distance-type: COSINE
        dimensions: 1536
        initialize-schema: true

Set initialize-schema to true when you want Spring AI to create the required vector store table during application startup. In current Spring AI releases, schema initialization is not enabled by default.

Note: Re-create the vector store table if you change the embedding dimension after table creation.

Use the Vector Store

Autowire VectorStore in your Spring application, add documents, and run similarity search requests.

@Autowired
VectorStore vectorStore;

List<Document> documents = List.of(
    new Document(
        "Spring AI applications can store embeddings in Oracle AI Database.",
        Map.of("author", "john", "article_type", "blog")
    ),
    new Document(
        "Oracle AI Vector Search supports semantic similarity queries.",
        Map.of("author", "jill", "article_type", "guide")
    )
);

vectorStore.add(documents);

List<Document> results = vectorStore.similaritySearch(
    SearchRequest.builder()
        .query("Spring vector search")
        .topK(5)
        .build()
);

Use the same VectorStore interface when you later change model providers or compose the vector store with Spring AI retrieval workflows.

Configure Vector Store Properties

Use the following properties to customize the Oracle vector store.

Property Description Default
spring.ai.vectorstore.oracle.index-type Nearest neighbor index type. Use NONE for exact search, IVF for an inverted file index, or HNSW for a multilayer graph index. NONE
spring.ai.vectorstore.oracle.distance-type Search distance type. Valid values include COSINE, DOT, EUCLIDEAN, EUCLIDEAN_SQUARED, and MANHATTAN. COSINE
spring.ai.vectorstore.oracle.forced-normalization Enables vector normalization before insertion and similarity search. Enable this setting when using a similarity threshold. false
spring.ai.vectorstore.oracle.dimensions Embedding dimension used for the vector column when the table is created. 65535
spring.ai.vectorstore.oracle.remove-existing-vector-store-table Drops the existing vector store table during application startup. false
spring.ai.vectorstore.oracle.initialize-schema Creates the required vector store schema during application startup. false
spring.ai.vectorstore.oracle.search-accuracy Accuracy target for indexed approximate search. Use an integer from 1 through 100, or keep the disabled default. -1

If vectors are normalized, then DOT or COSINE distance can provide good search performance.

Caution: Use remove-existing-vector-store-table only in development or controlled rebuild workflows because it drops existing vector store data.

Filter by Metadata

Use Spring AI metadata filters to constrain vector search results by document metadata.

List<Document> results = vectorStore.similaritySearch(
    SearchRequest.builder()
        .query("The World")
        .topK(TOP_K)
        .similarityThreshold(SIMILARITY_THRESHOLD)
        .filterExpression("author in ['john', 'jill'] && article_type == 'blog'")
        .build()
);

You can also build the same filter expression programmatically.

FilterExpressionBuilder b = new FilterExpressionBuilder();

List<Document> results = vectorStore.similaritySearch(
    SearchRequest.builder()
        .query("The World")
        .topK(TOP_K)
        .similarityThreshold(SIMILARITY_THRESHOLD)
        .filterExpression(
            b.and(
                b.in("author", "john", "jill"),
                b.eq("article_type", "blog")
            ).build()
        )
        .build()
);

Spring AI converts these portable filter expressions to Oracle vector store filters.

Configure the Vector Store Manually

Use manual configuration when you do not want to use Spring Boot auto-configuration.

Add Spring JDBC, the Oracle JDBC driver, and the Oracle vector store dependency to your Maven build.

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-jdbc</artifactId>
</dependency>
<dependency>
    <groupId>com.oracle.database.jdbc</groupId>
    <artifactId>ojdbc11</artifactId>
    <scope>runtime</scope>
</dependency>
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-oracle-store</artifactId>
</dependency>

Create an OracleVectorStore bean with JdbcTemplate and an EmbeddingModel.

@Bean
public VectorStore vectorStore(JdbcTemplate jdbcTemplate, EmbeddingModel embeddingModel) {
    return OracleVectorStore.builder(jdbcTemplate, embeddingModel)
        .tableName("my_vectors")
        .indexType(OracleVectorStoreIndexType.IVF)
        .distanceType(OracleVectorStoreDistanceType.COSINE)
        .dimensions(1536)
        .searchAccuracy(95)
        .initializeSchema(true)
        .build();
}

Use manual configuration to set options in Java code or to integrate with existing data source configuration.

Run Oracle Database Locally

For local development, start Oracle Database Free in a Docker container.

docker run --rm --name oracle23ai -p 1521:1521 -e APP_USER=mlops -e APP_USER_PASSWORD=mlops -e ORACLE_PASSWORD=mlops gvenzl/oracle-free:23-slim

Connect to the local pluggable database as the application user.

sql mlops/mlops@localhost/freepdb1

Use the matching JDBC URL in Spring Boot configuration.

jdbc:oracle:thin:@//localhost:1521/freepdb1

Access the Native Oracle Client

Use getNativeClient() when your application needs access to the underlying Oracle JDBC connection.

OracleVectorStore vectorStore = context.getBean(OracleVectorStore.class);
Optional<OracleConnection> nativeClient = vectorStore.getNativeClient();

if (nativeClient.isPresent()) {
    OracleConnection connection = nativeClient.get();
    // Use the native client for Oracle-specific operations.
}

The native client lets you call Oracle-specific APIs that are outside the Spring AI VectorStore abstraction.

Review Reference Links