Configuration

package org.springframework.ai.vectorstore.properties;

/**
 * Common configuration properties for vector stores.
 * Can be used with Spring Boot configuration properties binding.
 * 
 * These properties provide a consistent configuration interface across
 * all vector store implementations in the Spring AI ecosystem.
 */
public class CommonVectorStoreProperties {
    
    /**
     * Whether to initialize the vector store schema on startup.
     * Default: false
     * 
     * When true, the vector store will create necessary tables,
     * indexes, or collections on startup. This is useful for:
     * - Development environments (auto-setup)
     * - Testing (clean slate for each test run)
     * - First-time deployment
     * 
     * When false (recommended for production):
     * - Schema must be created manually or via migration scripts
     * - Prevents accidental schema modifications
     * - Allows for controlled schema versioning
     */
    private boolean initializeSchema = false;
    
    /**
     * Returns whether schema initialization is enabled.
     * 
     * @return true if schema should be initialized on startup, false otherwise
     */
    public boolean isInitializeSchema() {
        return initializeSchema;
    }
    
    /**
     * Sets whether schema initialization is enabled.
     * 
     * @param initializeSchema true to enable schema initialization
     */
    public void setInitializeSchema(boolean initializeSchema) {
        this.initializeSchema = initializeSchema;
    }
}

import org.springframework.ai.vectorstore.properties.CommonVectorStoreProperties;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class VectorStoreConfig {
    
    /**
     * Binds application properties with prefix "spring.ai.vectorstore"
     * to CommonVectorStoreProperties.
     */
    @Bean
    @ConfigurationProperties(prefix = "spring.ai.vectorstore")
    public CommonVectorStoreProperties vectorStoreProperties() {
        return new CommonVectorStoreProperties();
    }
    
    /**
     * Creates vector store with properties-based configuration.
     */
    @Bean
    public VectorStore vectorStore(
            EmbeddingModel embeddingModel,
            CommonVectorStoreProperties properties) {
        
        SimpleVectorStore store = SimpleVectorStore.builder(embeddingModel).build();
        
        // Initialize schema if configured
        if (properties.isInitializeSchema()) {
            initializeVectorStore(store);
        }
        
        return store;
    }
    
    private void initializeVectorStore(SimpleVectorStore store) {
        // Load initial data or create schema
        try {
            store.load(new ClassPathResource("vectorstore-initial.json"));
        } catch (Exception e) {
            // Start with empty store if initial data not found
            logger.info("Starting with empty vector store");
        }
    }
}

# Vector Store Configuration
spring.ai.vectorstore.initialize-schema=true

# Development environment - auto-initialize
spring.profiles.active=dev
spring.ai.vectorstore.initialize-schema=true

# Production environment - manual schema management
# spring.profiles.active=prod
# spring.ai.vectorstore.initialize-schema=false

spring:
  ai:
    vectorstore:
      initialize-schema: true

---
# Development profile
spring:
  config:
    activate:
      on-profile: dev
  ai:
    vectorstore:
      initialize-schema: true

---
# Production profile
spring:
  config:
    activate:
      on-profile: prod
  ai:
    vectorstore:
      initialize-schema: false

package org.springframework.ai.vectorstore;

/**
 * Constants for vector store type identification.
 * Used in observations, metrics, and logging to identify the underlying vector database provider.
 * 
 * These constants follow a consistent naming convention:
 * - Lowercase with underscores for multi-word names
 * - Descriptive of the actual database technology
 * - Aligned with OpenTelemetry semantic conventions where applicable
 */
public class SpringAIVectorStoreTypes {
    
    /**
     * Prefix for all vector store type constants.
     * Used as a namespace for vector store configuration properties.
     */
    public static final String VECTOR_STORE_PREFIX = "spring.ai.vectorstore";
    
    /**
     * Key for vector store type in observations and metrics.
     * Used as the property key for specifying the vector store type.
     */
    public static final String TYPE = VECTOR_STORE_PREFIX + ".type";
    
    // Cloud Provider Vector Stores
    
    /**
     * Azure AI Search (formerly Azure Cognitive Search).
     * Microsoft's cloud-based search and vector database service.
     */
    public static final String AZURE = "azure_ai_search";
    
    /**
     * Azure Cosmos DB with vector search capabilities.
     * Microsoft's globally distributed, multi-model database with vector support.
     */
    public static final String AZURE_COSMOS_DB = "azure_cosmos_db";
    
    // Open Source Vector Databases
    
    /**
     * Chroma vector database.
     * Open-source embedding database designed for AI applications.
     */
    public static final String CHROMA = "chroma";
    
    /**
     * Elasticsearch with vector search capabilities.
     * Distributed search and analytics engine with k-NN vector search.
     */
    public static final String ELASTICSEARCH = "elasticsearch";
    
    /**
     * Milvus vector database.
     * Open-source vector database built for scalable similarity search.
     */
    public static final String MILVUS = "milvus";
    
    /**
     * Neo4j graph database with vector search.
     * Graph database with native vector search capabilities.
     */
    public static final String NEO4J = "neo4j";
    
    /**
     * OpenSearch with vector search capabilities.
     * Open-source fork of Elasticsearch with k-NN vector search.
     */
    public static final String OPENSEARCH = "opensearch";
    
    /**
     * Qdrant vector database.
     * Open-source vector similarity search engine with extended filtering support.
     */
    public static final String QDRANT = "qdrant";
    
    /**
     * Weaviate vector database.
     * Open-source vector search engine with GraphQL API.
     */
    public static final String WEAVIATE = "weaviate";
    
    // Cloud-Managed Vector Databases
    
    /**
     * Pinecone vector database (cloud-managed).
     * Fully managed vector database service optimized for machine learning applications.
     */
    public static final String PINECONE = "pinecone";
    
    /**
     * MongoDB Atlas with vector search.
     * MongoDB's cloud database service with vector search capabilities.
     */
    public static final String MONGODB_ATLAS = "mongodb_atlas";
    
    // Traditional Databases with Vector Extensions
    
    /**
     * PostgreSQL with pgvector extension.
     * PostgreSQL database with pgvector extension for vector similarity search.
     */
    public static final String PGVECTOR = "pgvector";
    
    /**
     * Oracle Database with vector search.
     * Oracle Database with AI Vector Search capabilities.
     */
    public static final String ORACLE = "oracle";
    
    /**
     * MariaDB with vector capabilities.
     * MariaDB database with vector search support.
     */
    public static final String MARIADB = "mariadb";
    
    /**
     * SAP HANA Database.
     * SAP HANA in-memory database with vector engine.
     */
    public static final String HANADB = "hanadb";
    
    // Distributed Systems
    
    /**
     * Apache Cassandra with vector search.
     * Distributed NoSQL database with vector search capabilities.
     */
    public static final String CASSANDRA = "cassandra";
    
    /**
     * VMware GemFire (Tanzu GemFire).
     * Distributed in-memory data grid with vector search.
     */
    public static final String GEMFIRE = "gemfire";
    
    // Key-Value Stores with Vector Support
    
    /**
     * Redis with vector search capabilities (RedisSearch, RediSearch).
     * In-memory data structure store with vector similarity search via RedisSearch module.
     */
    public static final String REDIS = "redis";
    
    /**
     * Typesense search engine with vector capabilities.
     * Fast, typo-tolerant search engine with vector search support.
     */
    public static final String TYPESENSE = "typesense";
    
    // In-Memory Implementation
    
    /**
     * SimpleVectorStore - in-memory implementation for testing and development.
     * Lightweight in-memory vector store suitable for development, testing, and small datasets.
     */
    public static final String SIMPLE = "simple";
}

import org.springframework.ai.vectorstore.SpringAIVectorStoreTypes;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class VectorStoreLogger {
    private static final Logger logger = LoggerFactory.getLogger(VectorStoreLogger.class);
    
    public void logVectorStoreType(String type) {
        logger.info("Using vector store type: {}", type);
    }
    
    public void logSimpleStore() {
        logVectorStoreType(SpringAIVectorStoreTypes.SIMPLE);
        // Logs: Using vector store type: simple
    }
    
    public void logPineconeStore() {
        logVectorStoreType(SpringAIVectorStoreTypes.PINECONE);
        // Logs: Using vector store type: pinecone
    }
    
    public void logPgVectorStore() {
        logVectorStoreType(SpringAIVectorStoreTypes.PGVECTOR);
        // Logs: Using vector store type: pgvector
    }
}

import org.springframework.ai.vectorstore.observation.VectorStoreObservationContext;
import org.springframework.ai.vectorstore.SpringAIVectorStoreTypes;

public class CustomVectorStore extends AbstractObservationVectorStore {
    
    @Override
    public String getName() {
        return SpringAIVectorStoreTypes.PGVECTOR;  // or appropriate type
    }
    
    @Override
    protected VectorStoreObservationContext.Builder createObservationContextBuilder(String operationName) {
        return VectorStoreObservationContext
            .builder(SpringAIVectorStoreTypes.PGVECTOR, operationName)
            .collectionName("documents")
            .dimensions(1536)
            .similarityMetric("cosine");
    }
}

package org.springframework.ai.vectorstore.aot;

import org.springframework.aot.hint.RuntimeHints;
import org.springframework.aot.hint.RuntimeHintsRegistrar;

/**
 * Registers runtime hints for Spring AOT and GraalVM native image compilation.
 * Ensures vector store classes are accessible via reflection in native images.
 * 
 * This class is automatically discovered and applied by Spring Boot's AOT processing
 * when building native images. It registers:
 * - Reflection hints for vector store classes
 * - Serialization hints for data transfer objects
 * - Resource hints for configuration files
 * - Proxy hints for dynamic proxies
 */
public class VectorStoreRuntimeHints implements RuntimeHintsRegistrar {
    
    /**
     * Registers runtime hints for vector store classes.
     * Called during AOT processing to configure reflection, serialization,
     * and resource access for native image compilation.
     * 
     * This method ensures that:
     * - Vector store implementation classes can be instantiated via reflection
     * - Configuration properties can be bound
     * - Filter expressions can be parsed and evaluated
     * - Observation contexts can be created and populated
     * 
     * @param hints RuntimeHints to register configuration in
     * @param classLoader ClassLoader for loading classes
     */
    @Override
    public void registerHints(RuntimeHints hints, ClassLoader classLoader) {
        // Implementation registers necessary hints for:
        // - VectorStore implementations
        // - Filter expression classes
        // - Observation context classes
        // - Configuration property classes
    }
}

import org.springframework.ai.vectorstore.aot.VectorStoreRuntimeHints;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.ImportRuntimeHints;

@Configuration
@ImportRuntimeHints(VectorStoreRuntimeHints.class)
public class NativeImageConfig {
    // Configuration for native image support
    // This is usually not needed as Spring Boot auto-configures it
}

# With Maven
./mvnw -Pnative native:compile

# With Gradle
./gradlew nativeCompile

# Run native image
./target/my-app

# Build Docker image with native executable
./mvnw -Pnative spring-boot:build-image

# Additional native image arguments if needed
Args = --initialize-at-build-time=org.springframework.ai.vectorstore.SpringAIVectorStoreTypes \
       --initialize-at-run-time=org.springframework.ai.vectorstore.SimpleVectorStore

import org.springframework.ai.embedding.EmbeddingModel;
import org.springframework.ai.embedding.openai.OpenAiEmbeddingModel;
import org.springframework.ai.openai.OpenAiEmbeddingOptions;
import org.springframework.ai.vectorstore.SimpleVectorStore;
import org.springframework.ai.vectorstore.VectorStore;
import org.springframework.ai.vectorstore.properties.CommonVectorStoreProperties;
import org.springframework.ai.vectorstore.observation.DefaultVectorStoreObservationConvention;
import org.springframework.ai.document.TokenCountBatchingStrategy;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import io.micrometer.observation.ObservationRegistry;

@Configuration
@EnableConfigurationProperties
public class VectorStoreConfiguration {
    
    /**
     * Common vector store properties from application configuration.
     */
    @Bean
    @ConfigurationProperties(prefix = "spring.ai.vectorstore")
    public CommonVectorStoreProperties vectorStoreProperties() {
        return new CommonVectorStoreProperties();
    }
    
    /**
     * Embedding model for vectorization.
     */
    @Bean
    public EmbeddingModel embeddingModel() {
        return new OpenAiEmbeddingModel(
            System.getenv("OPENAI_API_KEY"),
            OpenAiEmbeddingOptions.builder()
                .withModel("text-embedding-ada-002")
                .withDimensions(1536)
                .build()
        );
    }
    
    /**
     * SimpleVectorStore with full configuration.
     */
    @Bean
    public VectorStore vectorStore(
            EmbeddingModel embeddingModel,
            ObservationRegistry observationRegistry,
            CommonVectorStoreProperties properties) {
        
        SimpleVectorStore store = SimpleVectorStore.builder(embeddingModel)
            .observationRegistry(observationRegistry)
            .customObservationConvention(new DefaultVectorStoreObservationConvention())
            .batchingStrategy(new TokenCountBatchingStrategy())
            .build();
        
        // Initialize schema if configured
        if (properties.isInitializeSchema()) {
            initializeVectorStore(store);
        }
        
        return store;
    }
    
    /**
     * Initialize vector store (e.g., load from file).
     */
    private void initializeVectorStore(SimpleVectorStore store) {
        try {
            File storeFile = new File("vectorstore.json");
            if (storeFile.exists()) {
                store.load(storeFile);
                logger.info("Loaded vector store from file");
            } else {
                logger.info("Starting with empty vector store");
            }
        } catch (Exception e) {
            logger.warn("Could not load vector store, starting fresh", e);
        }
    }
}

spring:
  ai:
    vectorstore:
      initialize-schema: true
    openai:
      api-key: ${OPENAI_API_KEY}
      embedding:
        options:
          model: text-embedding-ada-002
          dimensions: 1536

# Micrometer/Observability configuration
management:
  metrics:
    export:
      prometheus:
        enabled: true
      datadog:
        enabled: false
        api-key: ${DATADOG_API_KEY:}
  tracing:
    sampling:
      probability: 1.0  # Sample 100% in dev, reduce in prod
  observations:
    key-values:
      application: vector-store-app
      environment: ${SPRING_PROFILES_ACTIVE:dev}

# Logging configuration
logging:
  level:
    org.springframework.ai.vectorstore: DEBUG
    org.springframework.ai.embedding: DEBUG

# Vector Store Configuration
spring.ai.vectorstore.initialize-schema=true

# OpenAI Configuration
spring.ai.openai.api-key=${OPENAI_API_KEY}
spring.ai.openai.embedding.options.model=text-embedding-ada-002
spring.ai.openai.embedding.options.dimensions=1536

# Observability
management.metrics.export.prometheus.enabled=true
management.tracing.sampling.probability=1.0
management.observations.key-values.application=vector-store-app
management.observations.key-values.environment=${spring.profiles.active:dev}

# Logging
logging.level.org.springframework.ai.vectorstore=DEBUG
logging.level.org.springframework.ai.embedding=DEBUG

spring:
  ai:
    vectorstore:
      initialize-schema: true  # Auto-create schema in dev

# Use SimpleVectorStore for development
vector-store:
  type: simple
  persistence-file: dev-vectorstore.json

# Enhanced logging for development
logging:
  level:
    org.springframework.ai: DEBUG
    io.micrometer.observation: DEBUG

# Disable security for local development
management:
  security:
    enabled: false

spring:
  ai:
    vectorstore:
      initialize-schema: false  # Schema managed separately in prod

# Use production-grade vector database
vector-store:
  type: pinecone  # or pgvector, chroma, etc.
  connection-url: ${VECTOR_DB_URL}
  api-key: ${VECTOR_DB_API_KEY}

# Enhanced observability in production
management:
  metrics:
    export:
      prometheus:
        enabled: true
        step: 1m
      datadog:
        enabled: true
        api-key: ${DATADOG_API_KEY}
        step: 1m
  tracing:
    sampling:
      probability: 0.1  # Sample 10% of requests in prod
  observations:
    key-values:
      application: vector-store-app
      environment: production
      datacenter: ${DATACENTER:us-east-1}

# Production logging
logging:
  level:
    org.springframework.ai: INFO
    io.micrometer.observation: INFO
  pattern:
    console: "%d{yyyy-MM-dd HH:mm:ss} - %msg%n"
  file:
    name: /var/log/vector-store-app.log

spring:
  ai:
    vectorstore:
      initialize-schema: true  # Fresh schema for each test

# Use in-memory for tests
vector-store:
  type: simple

# Disable observability overhead in tests
management:
  metrics:
    export:
      prometheus:
        enabled: false
  tracing:
    enabled: false

# Test logging
logging:
  level:
    org.springframework.ai.vectorstore: WARN

import org.springframework.ai.vectorstore.SpringAIVectorStoreTypes;

String storeType = SpringAIVectorStoreTypes.SIMPLE;
// Observation context will show: db.system=simple

// Configuration
@Bean
public VectorStore simpleVectorStore(EmbeddingModel embeddingModel) {
    return SimpleVectorStore.builder(embeddingModel).build();
}

String storeType = SpringAIVectorStoreTypes.PINECONE;
// Observation context will show: db.system=pinecone

// Configuration (example - actual implementation may vary)
@Bean
public VectorStore pineconeVectorStore(EmbeddingModel embeddingModel) {
    return PineconeVectorStore.builder(embeddingModel)
        .apiKey(pineconeApiKey)
        .environment("us-west1-gcp")
        .indexName("production-index")
        .build();
}

String storeType = SpringAIVectorStoreTypes.PGVECTOR;
// Observation context will show: db.system=pgvector

// Configuration (example)
@Bean
public VectorStore pgVectorStore(
        EmbeddingModel embeddingModel,
        DataSource dataSource) {
    return PgVectorStore.builder(embeddingModel)
        .dataSource(dataSource)
        .tableName("vector_store")
        .dimensions(1536)
        .build();
}

String storeType = SpringAIVectorStoreTypes.CHROMA;
// Observation context will show: db.system=chroma

// Configuration (example)
@Bean
public VectorStore chromaVectorStore(EmbeddingModel embeddingModel) {
    return ChromaVectorStore.builder(embeddingModel)
        .host("localhost")
        .port(8000)
        .collectionName("documents")
        .build();
}

String storeType = SpringAIVectorStoreTypes.MONGODB_ATLAS;
// Observation context will show: db.system=mongodb_atlas

// Configuration (example)
@Bean
public VectorStore mongoDbAtlasVectorStore(
        EmbeddingModel embeddingModel,
        MongoClient mongoClient) {
    return MongoDbAtlasVectorStore.builder(embeddingModel)
        .mongoClient(mongoClient)
        .databaseName("vector_db")
        .collectionName("embeddings")
        .indexName("vector_index")
        .build();
}

version: '3.8'

services:
  # Chroma vector database
  chroma:
    image: chromadb/chroma:latest
    ports:
      - "8000:8000"
    volumes:
      - chroma-data:/chroma/chroma
    environment:
      - IS_PERSISTENT=TRUE

  # PostgreSQL with pgvector
  postgres:
    image: pgvector/pgvector:pg16
    ports:
      - "5432:5432"
    environment:
      - POSTGRES_USER=vectorstore
      - POSTGRES_PASSWORD=vectorstore
      - POSTGRES_DB=vectorstore
    volumes:
      - postgres-data:/var/lib/postgresql/data
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql

  # Redis with RedisSearch
  redis:
    image: redis/redis-stack:latest
    ports:
      - "6379:6379"
      - "8001:8001"
    volumes:
      - redis-data:/data

  # Prometheus for metrics
  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
      - prometheus-data:/prometheus

  # Grafana for visualization
  grafana:
    image: grafana/grafana:latest
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin
    volumes:
      - grafana-data:/var/lib/grafana

volumes:
  chroma-data:
  postgres-data:
  redis-data:
  prometheus-data:
  grafana-data:

-- Enable pgvector extension
CREATE EXTENSION IF NOT EXISTS vector;

-- Create vector store table
CREATE TABLE IF NOT EXISTS vector_store (
    id VARCHAR(255) PRIMARY KEY,
    content TEXT NOT NULL,
    metadata JSONB,
    embedding vector(1536)
);

-- Create index for vector similarity search
CREATE INDEX IF NOT EXISTS vector_store_embedding_idx 
ON vector_store USING ivfflat (embedding vector_cosine_ops)
WITH (lists = 100);

import org.springframework.boot.test.context.TestConfiguration;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Primary;

@TestConfiguration
public class VectorStoreTestConfig {
    
    @Bean
    @Primary
    public VectorStore testVectorStore(EmbeddingModel embeddingModel) {
        // Use SimpleVectorStore for tests
        return SimpleVectorStore.builder(embeddingModel).build();
    }
    
    @Bean
    @Primary
    public EmbeddingModel mockEmbeddingModel() {
        // Use mock embedding model for faster tests
        return new MockEmbeddingModel();
    }
}

import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.ActiveProfiles;
import org.springframework.test.context.DynamicPropertyRegistry;
import org.springframework.test.context.DynamicPropertySource;
import org.testcontainers.containers.PostgreSQLContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;

@SpringBootTest
@Testcontainers
@ActiveProfiles("test")
public class VectorStoreIntegrationTest {
    
    @Container
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("pgvector/pgvector:pg16")
        .withDatabaseName("testdb")
        .withUsername("test")
        .withPassword("test");
    
    @DynamicPropertySource
    static void registerPgProperties(DynamicPropertyRegistry registry) {
        registry.add("spring.datasource.url", postgres::getJdbcUrl);
        registry.add("spring.datasource.username", postgres::getUsername);
        registry.add("spring.datasource.password", postgres::getPassword);
        registry.add("spring.ai.vectorstore.initialize-schema", () -> "true");
    }
    
    @Test
    void testVectorStoreOperations() {
        // Test with real PostgreSQL + pgvector
    }
}

spring:
  ai:
    vectorstore:
      batch-size: 100  # Number of documents to batch
      max-tokens-per-batch: 8000  # Maximum tokens per batch

spring:
  datasource:
    hikari:
      maximum-pool-size: 20
      minimum-idle: 5
      connection-timeout: 30000
      idle-timeout: 600000
      max-lifetime: 1800000

spring:
  cache:
    type: caffeine
    caffeine:
      spec: maximumSize=1000,expireAfterWrite=10m

# Cache embeddings to avoid re-computation
embedding:
  cache:
    enabled: true
    max-size: 10000
    ttl: 1h