tessl/maven-org-springframework-ai--spring-ai-vector-store

Common vector store functionality for Spring AI providing a portable abstraction layer for integrating vector databases with comprehensive filtering, similarity search, and observability support.

Overview

Eval results

Files

Quick Start Guide

Name: tessl/maven-org-springframework-ai--spring-ai-vector-store
Author: tessl

Get started with Spring AI Vector Store in minutes.

Installation

Maven

Add to your pom.xml:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-vector-store</artifactId>
    <version>1.1.2</version>
</dependency>

Gradle

Add to your build.gradle:

implementation 'org.springframework.ai:spring-ai-vector-store:1.1.2'

Basic Setup

Step 1: Create a Vector Store

import org.springframework.ai.embedding.EmbeddingModel;
import org.springframework.ai.vectorstore.SimpleVectorStore;

// SimpleVectorStore is perfect for getting started
SimpleVectorStore vectorStore = SimpleVectorStore.builder(embeddingModel).build();

Note: You need an EmbeddingModel instance. For getting started, use OpenAI's embedding model or a mock implementation.

Step 2: Add Documents

import org.springframework.ai.document.Document;
import java.util.List;
import java.util.Map;

List<Document> documents = List.of(
    new Document("Spring Boot makes it easy to create stand-alone applications", 
        Map.of("category", "framework", "year", 2024)),
    new Document("Java is a popular programming language", 
        Map.of("category", "language", "year", 2023)),
    new Document("Vector databases enable semantic search", 
        Map.of("category", "database", "year", 2024))
);

vectorStore.add(documents);

Step 3: Search for Similar Documents

import org.springframework.ai.vectorstore.SearchRequest;

// Simple search
List<Document> results = vectorStore.similaritySearch("What is Spring Boot?");

// Advanced search with configuration
SearchRequest request = SearchRequest.builder()
    .query("What is Spring Boot?")
    .topK(3)
    .similarityThreshold(0.7)
    .build();

List<Document> advancedResults = vectorStore.similaritySearch(request);

// Print results
advancedResults.forEach(doc -> {
    System.out.println("Content: " + doc.getContent());
    System.out.println("Metadata: " + doc.getMetadata());
});

Spring Boot Setup

Step 1: Configuration Class

Create a configuration class:

import org.springframework.ai.embedding.EmbeddingModel;
import org.springframework.ai.embedding.openai.OpenAiEmbeddingModel;
import org.springframework.ai.vectorstore.SimpleVectorStore;
import org.springframework.ai.vectorstore.VectorStore;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class VectorStoreConfig {
    
    @Bean
    public EmbeddingModel embeddingModel() {
        // Configure your embedding model
        return new OpenAiEmbeddingModel(
            System.getenv("OPENAI_API_KEY"),
            OpenAiEmbeddingOptions.builder()
                .withModel("text-embedding-ada-002")
                .build()
        );
    }
    
    @Bean
    public VectorStore vectorStore(EmbeddingModel embeddingModel) {
        return SimpleVectorStore.builder(embeddingModel).build();
    }
}

Step 2: Application Properties

Add to application.yml:

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
    vectorstore:
      initialize-schema: true

Or application.properties:

spring.ai.openai.api-key=${OPENAI_API_KEY}
spring.ai.vectorstore.initialize-schema=true

Step 3: Use in Your Service

import org.springframework.ai.vectorstore.VectorStore;
import org.springframework.ai.vectorstore.SearchRequest;
import org.springframework.stereotype.Service;

@Service
public class SearchService {
    
    private final VectorStore vectorStore;
    
    public SearchService(VectorStore vectorStore) {
        this.vectorStore = vectorStore;
    }
    
    public List<Document> search(String query) {
        return vectorStore.similaritySearch(
            SearchRequest.builder()
                .query(query)
                .topK(5)
                .similarityThreshold(0.7)
                .build()
        );
    }
    
    public void addDocument(String content, Map<String, Object> metadata) {
        Document doc = new Document(content, metadata);
        vectorStore.add(List.of(doc));
    }
}

Persistence (SimpleVectorStore)

SimpleVectorStore supports JSON persistence:

import java.io.File;
import java.io.IOException;

// Save state
vectorStore.save(new File("vectorstore.json"));

// Load state on startup
SimpleVectorStore store = SimpleVectorStore.builder(embeddingModel).build();
try {
    store.load(new File("vectorstore.json"));
    System.out.println("Loaded existing vector store");
} catch (IOException e) {
    System.out.println("Starting with empty vector store");
}

Spring Boot Initialization

@Configuration
public class VectorStoreConfig {
    
    @Bean
    public VectorStore vectorStore(EmbeddingModel embeddingModel) {
        SimpleVectorStore store = SimpleVectorStore.builder(embeddingModel).build();
        
        // Load existing data on startup
        File storeFile = new File("vectorstore.json");
        if (storeFile.exists()) {
            try {
                store.load(storeFile);
            } catch (IOException e) {
                // Handle error
            }
        }
        
        return store;
    }
}

Basic Filtering

Add metadata filters to your searches:

// Text filter syntax
SearchRequest request = SearchRequest.builder()
    .query("programming concepts")
    .topK(5)
    .filterExpression("year >= 2024 && category == 'framework'")
    .build();

List<Document> results = vectorStore.similaritySearch(request);

See: Filtering Guide for comprehensive filtering documentation.

Common Patterns

Pattern 1: Add with Auto-Generated IDs

// Documents get auto-generated IDs if not specified
Document doc = new Document("content", Map.of("key", "value"));
vectorStore.add(List.of(doc));
// ID is automatically generated

Pattern 2: Add with Custom IDs

Document doc = new Document(
    "custom-id-123",
    "content",
    Map.of("key", "value")
);
vectorStore.add(List.of(doc));

Pattern 3: Delete Documents

// Delete by ID
vectorStore.delete(List.of("doc-id-1", "doc-id-2"));

// Delete by filter (if supported)
vectorStore.delete("year < 2020");

Pattern 4: Update Documents

To update a document, delete the old one and add the new version:

// Delete old version
vectorStore.delete(List.of("doc-id"));

// Add updated version
Document updated = new Document("doc-id", "new content", newMetadata);
vectorStore.add(List.of(updated));

Testing

Unit Test Example

import org.junit.jupiter.api.Test;
import static org.assertj.core.api.Assertions.assertThat;

@Test
void testVectorStoreSearch() {
    // Use SimpleVectorStore for tests
    VectorStore testStore = SimpleVectorStore.builder(mockEmbeddingModel).build();
    
    testStore.add(List.of(
        new Document("Spring Boot guide", Map.of("type", "tutorial")),
        new Document("Java basics", Map.of("type", "reference"))
    ));
    
    SearchRequest request = SearchRequest.builder()
        .query("Spring framework")
        .topK(1)
        .build();
    
    List<Document> results = testStore.similaritySearch(request);
    assertThat(results).hasSize(1);
    assertThat(results.get(0).getContent()).contains("Spring Boot");
}

Next Steps

Learn Filtering: See Filtering Guide for metadata-based filtering
Add Observability: See Observability Guide for metrics and tracing
Explore Examples: Check Real-World Scenarios
Production Setup: Switch to a production vector store (Pinecone, PgVector, etc.)

Common Issues

Issue: Embeddings are slow

Solution: Documents with existing embeddings skip re-computation:

float[] precomputedEmbedding = embeddingModel.embed("text").getOutput();
Document doc = new Document("text", metadata);
doc.setEmbedding(precomputedEmbedding);
vectorStore.add(List.of(doc));  // No re-embedding

Issue: No results found

Solutions:

Lower the similarity threshold
Check if documents were added successfully
Verify filter expressions are correct

// Try with lower threshold
SearchRequest relaxed = SearchRequest.builder()
    .query("query")
    .similarityThreshold(0.5)  // Lower threshold
    .topK(10)                   // More results
    .build();

Issue: Out of memory with large datasets

Solution: SimpleVectorStore is for small datasets. Use a production vector store:

// For production with large datasets
VectorStore prodStore = PineconeVectorStore.builder(embeddingModel)
    .apiKey(apiKey)
    .environment("us-west1-gcp")
    .build();

Complete Example

Here's a complete working example:

import org.springframework.ai.embedding.EmbeddingModel;
import org.springframework.ai.embedding.openai.OpenAiEmbeddingModel;
import org.springframework.ai.vectorstore.SimpleVectorStore;
import org.springframework.ai.vectorstore.SearchRequest;
import org.springframework.ai.document.Document;
import java.util.List;
import java.util.Map;

public class VectorStoreExample {
    
    public static void main(String[] args) {
        // 1. Create embedding model
        EmbeddingModel embeddingModel = new OpenAiEmbeddingModel(
            System.getenv("OPENAI_API_KEY")
        );
        
        // 2. Create vector store
        SimpleVectorStore vectorStore = SimpleVectorStore.builder(embeddingModel).build();
        
        // 3. Add documents
        List<Document> documents = List.of(
            new Document("Spring Boot tutorial", Map.of("category", "framework")),
            new Document("Java programming guide", Map.of("category", "language")),
            new Document("Vector databases overview", Map.of("category", "database"))
        );
        vectorStore.add(documents);
        
        // 4. Search
        SearchRequest request = SearchRequest.builder()
            .query("What is Spring Boot?")
            .topK(2)
            .similarityThreshold(0.7)
            .filterExpression("category == 'framework'")
            .build();
        
        List<Document> results = vectorStore.similaritySearch(request);
        
        // 5. Display results
        results.forEach(doc -> {
            System.out.println("Content: " + doc.getContent());
            System.out.println("Metadata: " + doc.getMetadata());
            System.out.println("---");
        });
        
        // 6. Save state
        try {
            vectorStore.save(new java.io.File("vectorstore.json"));
            System.out.println("Vector store saved");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Reference

Vector Store API - Complete API documentation
Configuration API - Configuration options
Real-World Scenarios - More examples

Install with Tessl CLI

npx tessl i tessl/maven-org-springframework-ai--spring-ai-vector-store

docs

examples

guides

reference