Mythosia.VectorDb.Qdrant 4.2.0

Mythosia.VectorDb.Qdrant

v4.2.0: Includes text-only and configurable hybrid search. See the release notes for compatibility and fixes.

Qdrant vector store implementation for the Mythosia VectorDb abstraction layer.

Uses a single Qdrant collection (physical container) with payload-based metadata filtering for logical isolation. All isolation keys (e.g. namespace, scope, category) are standard metadata entries — there are no framework-reserved keys.

Migration from v1.0.0

v1.0.0 collections are dense-only. v2.0.0 uses hybrid-capable collections and writes a schema marker so the tooling can detect whether migration is needed.

Install the migration tool first:

Install-Package Mythosia.VectorDb.Tools

If docs is the collection you want to migrate, run:

mythosia-vectordb migrate qdrant --endpoint localhost:6334 --source docs --replace

This migrates through a staging collection, then recreates docs with the new schema and copies the migrated data back into docs.

If your Qdrant server is remote or authenticated, add --api-key your-api-key and use your remote endpoint URL.

Stop application writes before migration if consistency matters.

Installation

dotnet add package Mythosia.VectorDb.Qdrant

Current package version:

dotnet add package Mythosia.VectorDb.Qdrant --version 4.2.0

Quick Start

using Mythosia.VectorDb;
using Mythosia.VectorDb.Qdrant;

// 1. Configure — CollectionName is the physical Qdrant collection
var options = new QdrantOptions
{
    Host           = "localhost",
    Port           = 6334,
    CollectionName = "my_vectors",                  // physical collection
    Dimension      = 1536,                          // must match your embedding model
    DistanceStrategy = QdrantDistanceStrategy.Cosine
};

// 2. Create the store
using var store = new QdrantStore(options);

// 3. Upsert records
var record = new VectorRecord("doc-1", embedding, "Hello world");
record.Metadata["namespace"] = "documents";         // optional logical isolation via metadata
await store.UpsertAsync(record);

// 4. Search — use VectorFilter.Where() for logical isolation
var filter = new VectorFilter().Where("namespace", "documents");
var results = await store.SearchAsync(queryVector, topK: 5, filter: filter);

Options

Hybrid Search (v2.0.0)

QdrantStore always provisions/uses hybrid-capable storage (dense + sparse) and supports native IVectorStore.HybridSearchAsync. Choose retrieval mode at query time (SearchAsync for vector-only, HybridSearchAsync for native hybrid):

var options = new QdrantOptions
{
    Host              = "localhost",
    Port              = 6334,
    CollectionName    = "my_vectors",
    Dimension         = 1536
};

var store = new QdrantStore(options);

On upsert, BM25 sparse vectors are automatically computed from the record's Content and stored alongside the dense embedding. Direct legacy HybridSearchAsync uses Qdrant’s prefetch + fusion (RRF/DBSF). The new HybridSearchOptions overload instead retrieves active candidate legs and merges them with normalized weighted RRF, preserving its explicit weight, candidate multiplier and smoothing options. TextSearchAsync searches the named sparse vector without sending a dense query vector.

Via the RAG pipeline, UseHybridSearch(...) now selects configurable weighted RRF. QdrantOptions.HybridFusionStrategy continues to control direct legacy calls only:

var store = await RagStore.BuildAsync(config => config
    .AddDocument("docs.txt")
    .UseOpenAIEmbedding(apiKey)
    .UseVectorStore(new QdrantStore(new QdrantOptions
    {
        Host = "localhost",
        Dimension = 1536
    }))
    .UseHybridSearch()
);

Metadata Filtering

// Logical isolation via metadata
var filter = new VectorFilter().Where("namespace", "docs");
var results = await store.SearchAsync(queryVector, topK: 10, filter: filter);

// Multiple metadata conditions
var filter = new VectorFilter()
    .Where("namespace", "docs")
    .Where("category", "science");
var results = await store.SearchAsync(queryVector, topK: 5, filter: filter);

// Minimum score threshold
var filter = new VectorFilter { MinScore = 0.7 };
var results = await store.SearchAsync(queryVector, topK: 5, filter: filter);

Filter operators for vector and legacy hybrid search

The v4.2.0 TextSearchAsync and configurable HybridSearchAsync paths support Eq, Ne, In, NotIn, Exists, NotExists, and nested And / Or groups. Unsupported range and Like filters throw NotSupportedException before a request is sent. Ne / NotIn exclude records missing the metadata key.

VectorFilter

For the full operator reference and fluent API examples (Where, WhereNot, WhereIn, WhereLike, WhereExists, Or, And, WithMinScore, etc.), see the Mythosia.VectorDb.Abstractions README.

Qdrant-specific note: Check the operator support for the search overload you use. The text/configurable-hybrid paths reject unsupported filters; vector and legacy hybrid search keep the behavior in the table above.

Resource Disposal

QdrantStore implements IDisposable. When created via the standard constructor, it owns the internal QdrantClient and disposes it on Dispose():

using var store = new QdrantStore(options);
// QdrantClient disposed automatically

When injecting a pre-configured client, the caller retains ownership and is responsible for disposal:

using Qdrant.Client;

var client = new QdrantClient("my-qdrant-cloud.example.com", 6334, https: true, apiKey: "my-key");
var store = new QdrantStore(options, client);
// store.Dispose() will NOT dispose client — caller must dispose it separately

Payload Layout

Records are stored as Qdrant points with the following payload keys:

ID Mapping

Point IDs are deterministic UUIDs derived from record Id via MD5 hash. The original string ID is preserved in the _id payload field.

Batch Get & Count

// Fetch multiple records by ID — single Qdrant gRPC RetrieveAsync call
var records = await store.GetBatchAsync(new[] { "id-1", "id-2", "id-3" });

// Count total vectors (excludes internal schema marker)
long count = await store.CountAsync();

// Count with metadata filter
long filtered = await store.CountAsync(
    new VectorFilter().Where("category", "finance"));

GetBatchAsync maps string IDs to deterministic Qdrant point UUIDs, calls the Qdrant batch RetrieveAsync API, and applies metadata conditions client-side. CountAsync uses the Qdrant server-side CountAsync API and always excludes the internal schema marker point from the result.

Vector Replacement

ReplaceByFilterAsync is available via the IVectorStore default interface method. It performs sequential DeleteByFilterAsync → UpsertBatchAsync. Qdrant does not support server-side transactions, so sequential execution is the best available behavior:

var filter = new VectorFilter().Where("full_path", "/docs/file.md");
await store.ReplaceByFilterAsync(filter, newRecords);

Connection Verification

Call VerifyConnectionAsync to test gRPC connectivity before running queries:

var store = new QdrantStore(new QdrantOptions
{
    Host = "localhost",
    Port = 6334,
    CollectionName = "my_vectors",
    Dimension = 1536
});

try
{
    await store.VerifyConnectionAsync();
    Console.WriteLine("Connected!");
}
catch (Exception ex)
{
    Console.WriteLine($"Connection failed: {ex.Message}");
}

License

See repository root for license information.

Filters on the new retrieval paths

TextSearchAsync and configurable hybrid search apply equality, membership, existence and nested AND/OR filters before candidate truncation. String range and LIKE conditions fail explicitly rather than disappearing. Ne/NotIn exclude records missing the key; empty In matches no records. Flat meta.* payload keys are addressed literally, with no stored-data migration. Keys containing quotes or backslashes cannot be represented by the supported path grammar and are rejected. The legacy filter limitations listed above do not describe these new methods.