Class Store

java.lang.Object
com.oracle.coherence.rag.api.Store
public class Store extends Object
Main REST API controller for Coherence RAG document store operations.

This JAX-RS resource provides comprehensive REST endpoints for managing document stores in the Coherence RAG framework, including document ingestion, chunking, embedding generation, vector search, and chat functionality. It serves as the primary interface for client applications to interact with the RAG system.

Key features include:

  • Document management - import, retrieve, and delete documents
  • Automatic document chunking and embedding generation
  • Hybrid search - combining vector similarity and full-text search
  • Real-time chat interface with RAG-enhanced responses
  • Configurable indexing strategies (HNSW, binary quantization, Lucene)
  • Streaming response support for chat interactions
  • Cross-origin resource sharing (CORS) support
  • Performance monitoring and statistics

The store operates asynchronously using dedicated background threads for document processing and batch embedding generation, ensuring responsive API performance even during heavy document ingestion periods.

Document processing pipeline:

  1. Documents are imported via URI and published to processing topics
  2. DocumentProcessor thread loads and chunks documents
  3. BatchingEmbedder thread generates embeddings in efficient batches
  4. Processed chunks are stored in both Coherence caches and optionally, external vector store

The API supports configurable search strategies including:

  • Pure vector search using embedding similarity
  • Full-text search using Lucene indexing
  • Hybrid search with configurable result fusion weights
  • Optional re-ranking using specialized scoring models

Since:
25.09
Author:
Aleks Seovic 2025.07.04

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final record 
    Store.ChatRequest
    Request object for chat operations with RAG context retrieval.
    static final class 
    Store.ChunkResult
    Represents a search result containing a document chunk with relevance score.
    static final record 
    Store.Doc
    Record representing a document with its ID and text content.
    static final record 
    Store.DocChunk
    Record representing a single document chunk with its content and embedding.
    static final record 
    Store.DocChunks
    Record representing a collection of document chunks for a specific document.
    static final record 
    Store.SearchRequest
    Request object for search operations with hybrid search capabilities.
    static final record 
    Store.SearchResult
    Response object containing search results with timing information.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Store(Session session, String name, EmbeddingModelSupplier embeddingModelSupplier, StreamingChatModelSupplier chatModelSupplier)
    Constructs a new Store instance with the specified configuration.

  • Method Summary

    Modifier and Type
    Method
    Description
    jakarta.ws.rs.core.Response
    addDocumentChunks(Store.DocChunks[] aDocs)
    Adds pre-processed document chunks to the store.
    jakarta.ws.rs.core.Response
    chat(Store.ChatRequest request)
    Provides RAG-enhanced conversational AI functionality.
    jakarta.ws.rs.core.Response
    clearStore()
    Clears all document chunks from the store.
    void
    cors()
    Handles CORS preflight requests for the root store endpoint.
    void
    corsChat()
    Handles CORS preflight requests for chat endpoints.
    void
    corsChunks()
    Handles CORS preflight requests for chunk-related endpoints.
    void
    corsChunkStats()
    Handles CORS preflight requests for chunk statistics endpoints.
    void
    corsDocs()
    Handles CORS preflight requests for document-related endpoints.
    void
    corsDocStats()
    Handles CORS preflight requests for document statistics endpoints.
    void
    corsStats()
    Handles CORS preflight requests for general statistics endpoints.
    jakarta.ws.rs.core.Response
    createIndex(IndexConfig<?> indexConfig)
    Creates a new vector index for the store.
    jakarta.ws.rs.core.Response
    getConfig()
    Retrieves the current configuration for this store.
    jakarta.ws.rs.core.Response
    getDocumentChunks(String docId)
    Retrieves document chunks for a specific document.
    jakarta.ws.rs.core.Response
    getDocumentChunkStats()
    Retrieves statistics about document chunks in the store.
    jakarta.ws.rs.core.Response
    getDocuments(String docId)
    Retrieves documents from the store.
    jakarta.ws.rs.core.Response
    importDocuments(List<String> uris, jakarta.ws.rs.core.SecurityContext securityContext)
    Imports documents from the specified URIs for processing.
    jakarta.ws.rs.core.Response
    removeIndex()
    Removes the current vector index from the store.
    jakarta.ws.rs.core.Response
    resetStats()
    Resets performance and usage statistics for the store.
    jakarta.ws.rs.core.Response
    search(Store.SearchRequest req)
    Performs hybrid search combining vector similarity and full-text search.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • Store

      public Store(Session session, String name, EmbeddingModelSupplier embeddingModelSupplier, StreamingChatModelSupplier chatModelSupplier)
      Constructs a new Store instance with the specified configuration.

      This constructor initializes all the necessary components for the store, including distributed maps, topics, indexes, statistics, and management. The asynchronous import pipeline is started lazily by document import requests after security checks pass.

      Parameters:
      session - the Coherence session for accessing distributed resources
      name - the unique name of this store
      embeddingModelSupplier - supplier for embedding model instances
      chatModelSupplier - supplier for chat model instances

  • Method Details

    • cors

      @OPTIONS @CrossOrigin public void cors()
      Handles CORS preflight requests for the root store endpoint.

      This method enables cross-origin resource sharing for web applications that need to access the store API from different domains.

    • corsDocs

      @OPTIONS @CrossOrigin @Path("docs") public void corsDocs()
      Handles CORS preflight requests for document-related endpoints.

      This method enables cross-origin access to document import and retrieval operations.

    • corsDocStats

      @OPTIONS @CrossOrigin @Path("docs/stats") public void corsDocStats()
      Handles CORS preflight requests for document statistics endpoints.

      This method enables cross-origin access to document statistics and monitoring information.

    • corsStats

      @OPTIONS @CrossOrigin @Path("stats") public void corsStats()
      Handles CORS preflight requests for general statistics endpoints.

      This method enables cross-origin access to store-wide statistics and performance metrics.

    • corsChunks

      @OPTIONS @CrossOrigin @Path("chunks") public void corsChunks()
      Handles CORS preflight requests for chunk-related endpoints.

      This method enables cross-origin access to document chunk operations and retrieval.

    • corsChunkStats

      @OPTIONS @CrossOrigin @Path("chunks/stats") public void corsChunkStats()
      Handles CORS preflight requests for chunk statistics endpoints.

      This method enables cross-origin access to chunk-level statistics and performance information.

    • corsChat

      @OPTIONS @CrossOrigin @Path("chat") public void corsChat()
      Handles CORS preflight requests for chat endpoints.

      This method enables cross-origin access to the RAG-enhanced chat functionality.

    • getConfig

      @GET @Consumes("application/json") @Path("config") public jakarta.ws.rs.core.Response getConfig()
      Retrieves the current configuration for this store.

      This endpoint returns the store's configuration including embedding model, chat model, normalization settings, and indexing configuration.

      Returns:
      Response containing the store configuration

    • removeIndex

      @DELETE @Consumes("application/json") @Path("index") public jakarta.ws.rs.core.Response removeIndex()
      Removes the current vector index from the store.

      This operation removes any existing vector index (HNSW, binary quantization, etc.) from the document chunks. The underlying data is preserved but vector search performance will be impacted until a new index is created.

      Returns:
      Response with 202 Accepted if index was removed, 304 Not Modified if no index exists

    • createIndex

      @POST @Consumes("application/json") @Path("index") public jakarta.ws.rs.core.Response createIndex(IndexConfig<?> indexConfig)
      Creates a new vector index for the store.

      This operation creates a vector index based on the provided configuration. Any existing index is removed first to ensure clean state. Supported index types include HNSW for approximate nearest neighbor search, binary quantization for memory efficiency, and simple vector storage.

      Parameters:
      indexConfig - configuration specifying the index type and parameters
      Returns:
      Response with 202 Accepted if index was created successfully

    • search

      @POST @Consumes("application/json") @Produces("application/json") @Path("search") public jakarta.ws.rs.core.Response search(Store.SearchRequest req)
      Performs hybrid search combining vector similarity and full-text search.

      This endpoint executes a comprehensive search across document chunks using both vector embeddings and full-text indexing. Results can be optionally re-ranked using specialized scoring models for improved relevance.

      The search process includes:

      • Vector similarity search using embedding models
      • Full-text search using Lucene indexing (if enabled)
      • Result fusion with configurable weighting
      • Optional re-ranking using cross-encoder models

      Parameters:
      req - the search request containing query, parameters, and options
      Returns:
      Response containing search results with execution timing

    • clearStore

      @DELETE public jakarta.ws.rs.core.Response clearStore()
      Clears all document chunks from the store.

      This operation removes all document chunks and their embeddings from the store. The operation is irreversible and all documents will need to be re-imported. Vector indexes and configurations are preserved.

      Returns:
      Response with 204 No Content indicating successful clearing

    • resetStats

      @DELETE @Path("stats") public jakarta.ws.rs.core.Response resetStats()
      Resets performance and usage statistics for the store.

      This operation clears all accumulated statistics and performance metrics for the store, providing a clean slate for monitoring.

      Returns:
      Response with 204 No Content indicating successful reset

    • getDocuments

      @GET @Path("docs") @Produces("application/json") public jakarta.ws.rs.core.Response getDocuments(@QueryParam("docId") String docId)
      Retrieves documents from the store.

      This endpoint can list all document IDs in the store or retrieve a specific document by its ID. When no docId parameter is provided, it returns an array of all document IDs. When a docId is provided, it returns the full document content.

      Parameters:
      docId - optional document ID to retrieve specific document
      Returns:
      Response containing document list or specific document content, 404 Not Found if specific document doesn't exist

    • importDocuments

      @POST @Path("docs") @Consumes("application/json") public jakarta.ws.rs.core.Response importDocuments(List<String> uris, @Context jakarta.ws.rs.core.SecurityContext securityContext)
      Imports documents from the specified URIs for processing.

      This endpoint queues documents for asynchronous processing. Documents are loaded from the provided URIs, chunked, embedded, and stored automatically by background processing threads.

      Supported URI schemes:

      • http/https - Web documents
      • file - Local file system
      • s3 - AWS S3 storage
      • azure.blob - Azure Blob Storage
      • gcs - Google Cloud Storage
      • oci.os - OCI Object Storage

      Parameters:
      uris - list of document URIs to import
      Returns:
      Response with 204 No Content indicating documents were queued

    • getDocumentChunks

      @GET @Path("chunks") @Produces("application/json") public jakarta.ws.rs.core.Response getDocumentChunks(@QueryParam("docId") String docId)
      Retrieves document chunks for a specific document.

      This endpoint returns all chunks for the specified document, including their text content, metadata, and vector embeddings. The chunks are returned in their original order from the document.

      Parameters:
      docId - the document ID to retrieve chunks for
      Returns:
      Response containing document chunks with embeddings, 404 Not Found if document doesn't exist

    • addDocumentChunks

      @POST @Path("chunks") @Consumes("application/json") public jakarta.ws.rs.core.Response addDocumentChunks(Store.DocChunks[] aDocs)
      Adds pre-processed document chunks to the store.

      This endpoint allows direct addition of document chunks with their embeddings, bypassing the normal document loading and processing pipeline. This is useful for batch operations or when chunks are processed externally.

      Parameters:
      aDocs - array of documents containing chunks to add
      Returns:
      Response with 204 No Content indicating chunks were added

    • getDocumentChunkStats

      @GET @Produces("application/json") @Path("chunks/stats") public jakarta.ws.rs.core.Response getDocumentChunkStats()
      Retrieves statistics about document chunks in the store.

      This endpoint returns detailed statistics about chunk distribution and memory usage across cluster members. The statistics are retrieved from the Coherence management interface.

      Returns:
      Response containing chunk statistics from cluster members

    • chat

      @POST @Path("chat") @Consumes("application/json") @Produces("text/plain") public jakarta.ws.rs.core.Response chat(Store.ChatRequest request)
      Provides RAG-enhanced conversational AI functionality.

      This endpoint creates a chat assistant that combines context retrieval with conversational AI. The assistant retrieves relevant document chunks based on the question and uses them as context for generating responses. The response is streamed in real-time as tokens are generated.

      Parameters:
      request - the chat request containing question and parameters
      Returns:
      Response containing streamed AI-generated answer with retrieved context