API Reference

/**
 * Creates a builder for constructing QdrantEmbeddingStore instances
 * @return Builder instance
 */
public static QdrantEmbeddingStore.Builder builder();

/**
 * Builder class for QdrantEmbeddingStore
 */
public static class Builder {
    /**
     * Sets the name of the collection (REQUIRED)
     * @param collectionName The collection name
     * @return Builder instance
     */
    public Builder collectionName(String collectionName);

    /**
     * Sets the host of the Qdrant instance
     * @param host The host (default: "localhost")
     * @return Builder instance
     */
    public Builder host(String host);

    /**
     * Sets the GRPC port of the Qdrant instance
     * @param port The port (default: 6334)
     * @return Builder instance
     */
    public Builder port(int port);

    /**
     * Sets whether to use TLS (HTTPS)
     * @param useTls True to enable TLS (default: false)
     * @return Builder instance
     */
    public Builder useTls(boolean useTls);

    /**
     * Sets the field name for text segment in the payload
     * @param payloadTextKey The payload key (default: "text_segment")
     * @return Builder instance
     */
    public Builder payloadTextKey(String payloadTextKey);

    /**
     * Sets the Qdrant API key for authentication
     * @param apiKey The API key (default: null)
     * @return Builder instance
     */
    public Builder apiKey(String apiKey);

    /**
     * Sets a custom Qdrant client instance
     * @param client The QdrantClient instance
     * @return Builder instance
     */
    public Builder client(QdrantClient client);

    /**
     * Builds the QdrantEmbeddingStore instance
     * @return QdrantEmbeddingStore instance
     * @throws NullPointerException if collectionName is not set
     */
    public QdrantEmbeddingStore build();
}

/**
 * Constructor with full configuration
 * @param collectionName The name of the Qdrant collection
 * @param host The host of the Qdrant instance
 * @param port The GRPC port of the Qdrant instance
 * @param useTls Whether to use TLS (HTTPS)
 * @param payloadTextKey The field name for text segment in Qdrant payload
 * @param apiKey The Qdrant API key (nullable)
 */
public QdrantEmbeddingStore(
    String collectionName,
    String host,
    int port,
    boolean useTls,
    String payloadTextKey,
    String apiKey
);

/**
 * Constructor with custom client
 * @param client A Qdrant client instance
 * @param collectionName The name of the Qdrant collection
 * @param payloadTextKey The field name for text segment in Qdrant payload
 */
public QdrantEmbeddingStore(
    QdrantClient client,
    String collectionName,
    String payloadTextKey
);

/**
 * Adds an embedding and returns a generated ID
 * @param embedding The embedding to add
 * @return The generated ID (UUID format)
 */
public String add(Embedding embedding);

/**
 * Adds an embedding with a specified ID
 * @param id The ID to assign (must be UUID format)
 * @param embedding The embedding to add
 */
public void add(String id, Embedding embedding);

/**
 * Adds an embedding with text segment and metadata
 * @param embedding The embedding to add
 * @param textSegment The associated text segment with metadata
 * @return The generated ID (UUID format)
 */
public String add(Embedding embedding, TextSegment textSegment);

/**
 * Adds multiple embeddings in bulk with generated IDs
 * @param embeddings List of embeddings to add
 * @return List of generated IDs
 */
public List<String> addAll(List<Embedding> embeddings);

/**
 * Adds multiple embeddings with specified IDs and optional text segments
 * @param ids List of IDs (must be UUID format)
 * @param embeddings List of embeddings
 * @param textSegments List of text segments (can be null)
 * @throws RuntimeException if operation fails
 */
public void addAll(
    List<String> ids,
    List<Embedding> embeddings,
    List<TextSegment> textSegments
);

/**
 * Searches for similar embeddings based on a query
 * @param request Search request containing query embedding, max results, min score, and optional filter
 * @return Search results with matching embeddings and scores
 */
public EmbeddingSearchResult<TextSegment> search(EmbeddingSearchRequest request);

/**
 * Search request configuration
 */
interface EmbeddingSearchRequest {
    Embedding queryEmbedding();
    int maxResults();
    double minScore();
    Filter filter();  // Optional metadata filter

    static Builder builder();
}

/**
 * Search results container
 */
interface EmbeddingSearchResult<T> {
    List<EmbeddingMatch<T>> matches();
}

/**
 * Individual search result match
 */
interface EmbeddingMatch<T> {
    double score();         // Relevance score (cosine similarity)
    String embeddingId();   // UUID of the embedding
    Embedding embedding();  // The embedding vector
    T embedded();          // The associated TextSegment (may be null)
}

/**
 * Removes a single embedding by ID
 * @param id The ID of the embedding to remove
 * @throws IllegalArgumentException if id is null or blank
 */
public void remove(String id);

/**
 * Removes multiple embeddings by their IDs
 * @param ids Collection of IDs to remove
 */
public void removeAll(Collection<String> ids);

/**
 * Removes all embeddings matching the specified filter
 * @param filter Metadata filter to match embeddings for removal
 */
public void removeAll(Filter filter);

/**
 * Removes all embeddings from the collection
 */
public void removeAll();

/**
 * Deletes all points from the Qdrant collection
 */
public void clearStore();

/**
 * Closes the underlying GRPC client connection
 */
public void close();

// Equality filters
new IsEqualTo(String key, Object value);          // Supports String, UUID, Integer, Long
new IsNotEqualTo(String key, Object value);       // Supports String, UUID, Integer, Long

// Comparison filters
new IsGreaterThan(String key, Number value);
new IsGreaterThanOrEqualTo(String key, Number value);
new IsLessThan(String key, Number value);
new IsLessThanOrEqualTo(String key, Number value);

// Collection filters
new IsIn(String key, Collection<?> values);       // Supports String, UUID, Integer, Long
new IsNotIn(String key, Collection<?> values);    // Supports String, UUID, Integer, Long

// String filters
new ContainsString(String key, String value);

new And(Filter left, Filter right);
new Or(Filter left, Filter right);
new Not(Filter expression);

// Supported Java types in Metadata:
// - String
// - Integer (int)
// - Long (long)
// - Double (double)
// - Float (float)
// - UUID

// RuntimeException - Thrown for GRPC operation failures
// - Wraps InterruptedException or ExecutionException
// - Occurs during add, remove, search, or clearStore operations

// IllegalArgumentException - Thrown for invalid parameters
// - null or blank ID in remove(String id)

// NullPointerException - Thrown by builder
// - Missing required collectionName in build()

// UnsupportedOperationException - Thrown for unsupported operations
// - Unsupported filter types during filter conversion
// - Unsupported value types in metadata

// Default values
static final String DEFAULT_HOST = "localhost";
static final int DEFAULT_PORT = 6334;
static final boolean DEFAULT_USE_TLS = false;
static final String DEFAULT_PAYLOAD_TEXT_KEY = "text_segment";