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

Spring AI Vector Store

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

The Spring AI Vector Store module provides a portable abstraction layer for integrating vector databases into Spring AI applications. It defines the core VectorStore interface for managing documents with embeddings, performing similarity searches, and filtering results based on metadata.

Package Information

Package: org.springframework.ai:spring-ai-vector-store
Version: 1.1.2
Language: Java 17+
Maven:
```
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-vector-store</artifactId>
    <version>1.1.2</version>
</dependency>
```
Gradle: implementation 'org.springframework.ai:spring-ai-vector-store:1.1.2'

Quick Start

import org.springframework.ai.vectorstore.SimpleVectorStore;
import org.springframework.ai.vectorstore.SearchRequest;
import org.springframework.ai.document.Document;

// Create vector store
SimpleVectorStore vectorStore = SimpleVectorStore.builder(embeddingModel).build();

// Add documents
vectorStore.add(List.of(
    new Document("Spring Boot tutorial", Map.of("category", "framework")),
    new Document("Java programming guide", Map.of("category", "language"))
));

// Search
SearchRequest request = SearchRequest.builder()
    .query("What is Spring Boot?")
    .topK(3)
    .similarityThreshold(0.7)
    .build();
List<Document> results = vectorStore.similaritySearch(request);

// Search with filtering
List<Document> filtered = vectorStore.similaritySearch(
    SearchRequest.builder()
        .query("programming")
        .filterExpression("category == 'framework'")
        .build()
);

See: Quick Start Guide for detailed setup instructions.

Core Concepts

VectorStore Interface

Main interface for vector database operations. Provides portable API for add, delete, and similarity search operations.

public interface VectorStore {
    void add(List<Document> documents);
    void delete(List<String> idList);
    List<Document> similaritySearch(SearchRequest request);
}

Implementations:

SimpleVectorStore - In-memory (development/testing)
Provider-specific implementations (Pinecone, Chroma, PgVector, etc.)

See: Vector Store API Reference

SearchRequest

Configuration for similarity searches with filtering and thresholds.

public class SearchRequest {
    public static final int DEFAULT_TOP_K = 4;
    public static final double SIMILARITY_THRESHOLD_ACCEPT_ALL = 0.0;
    
    public String getQuery();
    public int getTopK();
    public double getSimilarityThreshold();
    public Filter.Expression getFilterExpression();
}

Builder: SearchRequest.builder().query(...).topK(...).similarityThreshold(...).build()

Filter Expressions

Portable metadata filtering with SQL-like syntax.

Text Syntax:

"year >= 2023 && category == 'tech'"
"status IN ['active', 'pending']"
"(featured == true OR year >= 2023) && status != 'archived'"

Programmatic:

FilterExpressionBuilder b = new FilterExpressionBuilder();
Filter.Expression expr = b.and(
    b.gte("year", 2023),
    b.eq("category", "tech")
).build();

See: Filter Expressions API | Filtering Guide

Observability

Built-in Micrometer support for metrics and distributed tracing.

SimpleVectorStore store = SimpleVectorStore.builder(embeddingModel)
    .observationRegistry(observationRegistry)
    .customObservationConvention(new DefaultVectorStoreObservationConvention())
    .build();

Metrics: Operation duration, document counts, similarity thresholds
Tracing: Distributed trace spans with query details

See: Observation API Reference | Observability Guide

Quick Reference

Common Operations

Operation	Code	Notes
Add documents	`store.add(documents)`	Auto-embeds if needed
Delete by ID	`store.delete(List.of("id1", "id2"))`	Idempotent
Delete by filter	`store.delete("year < 2020")`	Not all stores support
Simple search	`store.similaritySearch("query")`	Uses defaults (topK=4)
Advanced search	`store.similaritySearch(request)`	With filters & thresholds
Save state	`store.save(new File("store.json"))`	SimpleVectorStore only
Load state	`store.load(new File("store.json"))`	SimpleVectorStore only

Filter Operators

Operator	Syntax	Example
Equals	`==`	`category == 'tech'`
Not equals	`!=`	`status != 'archived'`
Greater than	`>`	`year > 2020`
Greater or equal	`>=`	`price >= 100`
Less than	`<`	`count < 50`
Less or equal	`<=`	`rating <= 4.5`
In array	`IN`	`status IN ['active', 'pending']`
Not in array	`NOT IN`	`category NOT IN ['spam', 'test']`
Is null	`IS NULL`	`deletedAt IS NULL`
Is not null	`IS NOT NULL`	`publishedAt IS NOT NULL`
Logical AND	`&&`	`year >= 2023 && active == true`
Logical OR	`\|\|`	`featured == true \|\| year >= 2023`
Negation	`NOT`	`NOT (price > 100)`
Grouping	`( )`	`(a OR b) && c`

SearchRequest Defaults

Parameter	Default	Range/Options
topK	4	>= 0
similarityThreshold	0.0 (accept all)	[0.0, 1.0]
filterExpression	null	Filter.Expression or text

Vector Store Types

Type	Constant	Use Case
SimpleVectorStore	`SpringAIVectorStoreTypes.SIMPLE`	Development, testing, small datasets
Pinecone	`SpringAIVectorStoreTypes.PINECONE`	Production, cloud-managed
Chroma	`SpringAIVectorStoreTypes.CHROMA`	Open-source, self-hosted
PgVector	`SpringAIVectorStoreTypes.PGVECTOR`	PostgreSQL extension
MongoDB Atlas	`SpringAIVectorStoreTypes.MONGODB_ATLAS`	MongoDB with vector search
Redis	`SpringAIVectorStoreTypes.REDIS`	In-memory with persistence

Architecture Overview

Core Abstraction Layer

VectorStore: Main interface combining DocumentWriter and VectorStoreRetriever
SearchRequest: Immutable search configuration
SimpleVectorStore: In-memory reference implementation

Filter System

Filter.Expression: Portable filter model (records-based)
FilterExpressionBuilder: Programmatic DSL
FilterExpressionTextParser: SQL-like text parser
FilterExpressionConverter: Strategy for provider-specific conversion

Observability Layer

AbstractObservationVectorStore: Template base with Micrometer support
VectorStoreObservationContext: Metadata for metrics/tracing
VectorStoreObservationConvention: Customizable metric naming

See: Complete Architecture Overview

Essential Imports

// Core vector store
import org.springframework.ai.vectorstore.VectorStore;
import org.springframework.ai.vectorstore.SimpleVectorStore;
import org.springframework.ai.vectorstore.SearchRequest;
import org.springframework.ai.document.Document;

// Filtering
import org.springframework.ai.vectorstore.filter.Filter;
import org.springframework.ai.vectorstore.filter.FilterExpressionBuilder;
import org.springframework.ai.vectorstore.filter.FilterExpressionTextParser;

// Observability
import org.springframework.ai.vectorstore.observation.AbstractObservationVectorStore;
import org.springframework.ai.vectorstore.observation.VectorStoreObservationContext;
import org.springframework.ai.vectorstore.observation.DefaultVectorStoreObservationConvention;
import io.micrometer.observation.ObservationRegistry;

// Configuration
import org.springframework.ai.vectorstore.properties.CommonVectorStoreProperties;
import org.springframework.ai.vectorstore.SpringAIVectorStoreTypes;

Spring Boot Integration

@Configuration
public class VectorStoreConfig {
    
    @Bean
    @ConfigurationProperties(prefix = "spring.ai.vectorstore")
    public CommonVectorStoreProperties vectorStoreProperties() {
        return new CommonVectorStoreProperties();
    }
    
    @Bean
    public VectorStore vectorStore(
            EmbeddingModel embeddingModel,
            ObservationRegistry observationRegistry) {
        return SimpleVectorStore.builder(embeddingModel)
            .observationRegistry(observationRegistry)
            .build();
    }
}

application.yml:

spring:
  ai:
    vectorstore:
      initialize-schema: true

See: Configuration API Reference

Documentation Structure

Guides (Step-by-Step)

Quick Start Guide - Getting started with vector stores
Filtering Guide - Working with filter expressions
Observability Guide - Setting up metrics and tracing

Examples (Real-World Usage)

Real-World Scenarios - Common use cases and patterns
Edge Cases - Handling errors and edge cases

Reference (Detailed API)

Vector Store API - Complete VectorStore interface documentation
Filter Expressions API - Complete filtering system
Observation API - Complete observability features
Configuration API - Configuration properties and options
Complete Overview - Comprehensive documentation

Common Patterns

Pattern 1: Basic CRUD

// Add
vectorStore.add(documents);

// Search
List<Document> results = vectorStore.similaritySearch("query");

// Delete
vectorStore.delete(List.of("id1", "id2"));

Pattern 2: Filtered Search

SearchRequest request = SearchRequest.builder()
    .query("Spring Boot")
    .topK(10)
    .filterExpression("year >= 2023 && category == 'framework'")
    .build();
List<Document> results = vectorStore.similaritySearch(request);

Pattern 3: Persistence (SimpleVectorStore)

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

// Load
SimpleVectorStore store = SimpleVectorStore.builder(embeddingModel).build();
store.load(new File("vectorstore.json"));

Pattern 4: With Observability

SimpleVectorStore store = SimpleVectorStore.builder(embeddingModel)
    .observationRegistry(observationRegistry)
    .customObservationConvention(new DefaultVectorStoreObservationConvention())
    .build();
// Operations automatically tracked

See: Real-World Scenarios for more patterns

External Dependencies

This module depends on core Spring AI interfaces:

Document: Core document class with ID, text, metadata, embeddings
EmbeddingModel: Interface for text-to-vector conversion
DocumentWriter: Interface for writing documents
VectorStoreRetriever: Interface for similarity search
BatchingStrategy: Strategy for batching operations
Resource: Spring Framework resource abstraction

Performance Considerations

SimpleVectorStore: Suitable for < 10,000 documents, development/testing
Batching: Configure BatchingStrategy for large document sets
Filter Location: Server-side filters (in SearchRequest) vs client-side (similarity threshold)
Embedding Caching: Documents with embeddings skip re-computation

See: Real-World Scenarios - Performance Tuning

Error Handling

Common scenarios:

Duplicate IDs: May throw RuntimeException (provider-dependent)
Empty Results: Returns empty list, check threshold and filters
Unsupported Operations: Filter-based deletion not universally supported
Parse Errors: FilterExpressionParseException for invalid filter syntax

See: Edge Cases for detailed error handling

Migration Guide

The portable API enables easy migration between vector stores:

// Development
VectorStore devStore = SimpleVectorStore.builder(embeddingModel).build();

// Production
VectorStore prodStore = PineconeVectorStore.builder(embeddingModel)
    .apiKey(apiKey)
    .environment("us-west1-gcp")
    .build();

// Same API for both
List<Document> results = store.similaritySearch(request);

Next Steps

Get Started: Follow the Quick Start Guide
Learn Filtering: Read the Filtering Guide
Add Observability: See the Observability Guide
Explore Examples: Check Real-World Scenarios
Deep Dive: Reference the Complete API Documentation

Additional Resources

Vector Store API Reference - Complete interface documentation
Filter Expressions API - Complete filtering system
Observation API - Complete observability
Configuration API - All configuration options
Complete Overview - Comprehensive guide

Install with Tessl CLI

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

Workspace: tessl
Visibility: Public
Created: 26 days ago
Last updated: 26 days ago
Describes: pkg:maven/org.springframework.ai/spring-ai-vector-store@1.1.x