Package sk.iway.iwcm.rag.vectorstore

Interface VectorStore

All Known Implementing Classes:
PgVectorStore
public interface VectorStore
Abstraction for vector storage and similarity search. Handles ONLY the embedding (vector) column via native SQL. Entity CRUD operations are handled by EmbeddingChunkRepository (JPA). Primary implementation uses PgVector (PostgreSQL + pgvector extension).

  • Method Details

    • updateEmbedding

      void updateEmbedding(Long id, float[] embedding)
      Update the embedding vector for an existing chunk entity. The entity must already be saved via EmbeddingChunkRepository.
      Parameters:
      id - the chunk entity ID
      embedding - the embedding vector

    • updateEmbeddingBatch

      void updateEmbeddingBatch(List<Long> ids, List<float[]> embeddings)
      Update embedding vectors for multiple existing chunk entities in a batch. All entities must already be saved via EmbeddingChunkRepository.
      Parameters:
      ids - the chunk entity IDs
      embeddings - the embedding vectors (must match ids in size and order)

    • search

      List<VectorSearchResult> search(float[] queryEmbedding, String embeddingProvider, String embeddingModel, RagEntityType entityType, Integer domainId, String language, int limit, Map<String,Object> bonusParams)
      Find the most similar chunks to the query embedding.
      Parameters:
      queryEmbedding - the query vector
      embeddingProvider - provider used to generate/query embeddings
      embeddingModel - model used to generate/query embeddings
      entityType - entity type to filter by (null for all)
      domainId - domain ID to filter by (null for all)
      language - language to filter by (null for all)
      limit - max number of results
      bonusParams - optional store-specific filters, such as document root groups
      Returns:
      list of search results ordered by similarity (descending)

    • searchFulltext

      List<VectorSearchResult> searchFulltext(String query, String embeddingProvider, String embeddingModel, RagEntityType entityType, Integer domainId, String language, int limit, Map<String,Object> bonusParams)
      Find relevant chunks by fulltext search in chunk text.
      Parameters:
      query - textual query
      embeddingProvider - provider used to filter rows
      embeddingModel - model used to filter rows
      entityType - entity type to filter by (null for all)
      domainId - domain ID to filter by (null for all)
      language - language to filter by (null for all)
      limit - max number of results
      bonusParams - optional store-specific filters, such as document root groups and fallback flags
      Returns:
      list of search results ordered by fulltext rank (descending)

    • isAvailable

      boolean isAvailable()
      Check if the vector store can be used in the current runtime configuration. This does not guarantee that required schema objects already exist.

    • isAvailableAndInitialized

      boolean isAvailableAndInitialized()
      Check if the vector store is available and schema is initialized. Implementations should return true only when operations can be executed safely.

    • initializeSchema

      boolean initializeSchema()
      Initialize the pgvector extension and create the table if needed.

    • resetDimensions

      boolean resetDimensions(int dimensions)
      Delete all stored embeddings and resize the vector column.
      Parameters:
      dimensions - new vector dimensions

    • getExistingEmbeddingsByHash

      @Deprecated(forRemoval=false) Map<String,float[]> getExistingEmbeddingsByHash(String entityType, long entityId, String embeddingProvider, String embeddingModel)
      Deprecated.
      use the domain-explicit overload for background processing
      Get existing embeddings for an entity, keyed by content hash.
      Parameters:
      entityType - entity type of the indexed object
      entityId - ID of the indexed object
      embeddingProvider - provider that generated the embeddings
      embeddingModel - model that generated the embeddings
      Returns:
      existing embeddings keyed by content hash

    • getExistingEmbeddingsByHash

      default Map<String,float[]> getExistingEmbeddingsByHash(String entityType, long entityId, String embeddingProvider, String embeddingModel, int domainId)
      Get existing embeddings for an entity and domain, keyed by content hash. Used to skip re-embedding unchanged chunks.
      Parameters:
      entityType - entity type of the indexed object
      entityId - ID of the indexed object
      embeddingProvider - provider that generated the embeddings
      embeddingModel - model that generated the embeddings
      domainId - domain that owns the indexed object
      Returns:
      existing embeddings keyed by content hash