Mythosia.VectorDb.Qdrant 3.0.1

Mythosia.VectorDb.Qdrant

Qdrant vector store implementation for the Mythosia VectorDb abstraction layer.

Uses a single Qdrant collection (physical container) with payload-based logical isolation:

• _namespace — first-tier logical partition
• _scope — second-tier logical partition

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 3.0.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 — "documents" is a logical namespace within the collection
var record = new VectorRecord("doc-1", embedding, "Hello world");
await store.InNamespace("documents").UpsertAsync(record);

// 4. Search
var results = await store.InNamespace("documents")
    .SearchAsync(queryVector, topK: 5);

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. Hybrid search uses Qdrant's built-in prefetch + fusion (RRF/DBSF) for server-side scoring.

When used via the RAG pipeline:

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

Scope & Metadata Filtering

// Scope isolation (2nd-tier within namespace)
await store.InNamespace("docs").InScope("tenant-1").UpsertAsync(record);
var results = await store.InNamespace("docs").InScope("tenant-1")
    .SearchAsync(queryVector, topK: 10);

// Metadata filtering
var filter = new VectorFilter().Where("category", "science");
var results = await store.InNamespace("docs")
    .SearchAsync(queryVector, topK: 5, filter: filter);

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

Supported filter operators

Important: Unsupported operators produce no error but filter nothing in search queries. Use GetAsync / GetBatchAsync when these operators are required.

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: Gt, Gte, Lt, Lte, Like, Exists, NotExists are silently ignored in SearchAsync / HybridSearchAsync. They are only evaluated client-side in GetAsync / GetBatchAsync.

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 namespace + record Id (when namespace is set) or just record Id (when null) via MD5 hash. This ensures the same record Id in different namespaces produces distinct points within the shared collection. 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.InNamespace("documents").GetBatchAsync(new[] { "id-1", "id-2", "id-3" });

// Count total vectors in a namespace (excludes internal schema marker)
long count = await store.InNamespace("documents").CountAsync();

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

GetBatchAsync maps string IDs to deterministic Qdrant point UUIDs, calls the Qdrant batch RetrieveAsync API, and applies namespace/scope/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.InNamespace("documents").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.