Vorcyc.Quiver 4.0.4

Vorcyc Quiver 4.0.4

English Document | 中文文档

A pure .NET embedded vector database — zero native dependencies, in-process deployment, EF Core-style code-first modeling.

Item	Value
Version	4.0.4
Target Framework	.NET 10
License	MIT
NuGet
Source	https://github.com/vorcyc/Vorcyc.Quiver
WIKI	https://github.com/vorcyc/Vorcyc.Quiver/wiki
Namespace	Vorcyc.Quiver

Name Origin: Quiver — a container for arrows; a vector is mathematically an arrow.

Motivation

Quiver grew out of the limitations of its predecessor, Vorcyc.AwesomeAI.Ash: a fixed table structure, brute-force-only search, and no concurrency support — none of which were acceptable for production-grade vector retrieval. Inspired by EF Core's Code-First philosophy and Python's Annoy library, Quiver was redesigned from scratch around declarative modeling, multiple ANN index algorithms, and built-in concurrency safety. See Product Overview · Creation Overview for the full story.

What is Quiver?

Quiver is a pure .NET embedded vector database with zero native dependencies, running as an in-process library without requiring a standalone database server. It draws on EF Core's DbContext design pattern — annotate entity classes with attributes such as [QuiverKey], [QuiverVector], [QuiverLargeField], and [QuiverIndex], and the framework automatically handles model discovery, index construction, and persistence at runtime.

Core Capabilities

Typical Use Cases: Semantic search · RAG (Retrieval-Augmented Generation) · Face recognition · Image-to-image search · Recommendation systems · Multimodal retrieval

⚠️ Native AOT: Quiver is not compatible with Native AOT publishing (PublishAot=true). The framework uses runtime reflection for QuiverSet<T> discovery and compiles expression-tree accessors at startup. Target standard JIT / .NET 10 runtimes only.

Quick Start

1. Install

dotnet add package Vorcyc.Quiver

2. Define Entity

using Vorcyc.Quiver;

public class Document
{
	[QuiverKey]
	public string Id { get; set; } = string.Empty;

	public string Title { get; set; } = string.Empty;

	public string Category { get; set; } = string.Empty;

	[QuiverVector(384, DistanceMetric.Cosine)]
	public float[] Embedding { get; set; } = [];
}

3. Define Database Context

public class MyDocumentDb : QuiverDbContext
{
	public QuiverSet<Document> Documents { get; set; } = null!;

	public MyDocumentDb() : base(new QuiverDbOptions
	{
		DatabasePath = "documents.vdb",
		DefaultMetric = DistanceMetric.Cosine
	})
	{ }
}

4. Add, Search, Save

// DisposeAsync does NOT auto-save by default (SaveOnDispose defaults to false).
// Call SaveAsync() explicitly, or set SaveOnDispose = true in QuiverDbOptions.
await using var db = new MyDocumentDb();
await db.LoadAsync(); // silently returns if file doesn't exist

// Add entity
db.Documents.Add(new Document
{
	Id = "doc-001",
	Title = "Introduction to Vector Databases",
	Category = "Tutorial",
	Embedding = new float[384] // replace with your model's embedding output
});

// Search Top-5 most similar documents
float[] queryVector = new float[384];
var results = db.Documents.Search(
	e => e.Embedding,
	queryVector,
	topK: 5
);

foreach (var result in results)
	Console.WriteLine($"{result.Entity.Title}  similarity={result.Similarity:F4}");

await db.SaveAsync(); // explicitly save to disk

5. Incremental Append (Batch Ingest)

// Use synchronous `using` for batched ingest — `await using` calls SaveAsync()
// on dispose and would overwrite freshly appended segments if cleared first.
using var db = new MyDocumentDb();
await db.LoadAsync();

foreach (var batch in EnumerateBatches())
{
	foreach (var doc in batch) db.Documents.Add(doc);
	await db.AppendAsync();   // O(Δ) segment append, no full rewrite
	db.Documents.Clear();     // free memory; on-disk segments are unaffected
}

// Optional manual compaction (background merge can also do this automatically)
await db.SaveAsync();

End-to-End Flow

sequenceDiagram
	participant User as User Code
	participant Ctx as QuiverDbContext
	participant Set as QuiverSet
	participant Idx as IVectorIndex
	participant BSP as BinaryStorageProvider
	participant File as QDB\x04 file

	User->>Ctx: new MyDb(options)
	activate Ctx
	Ctx->>Ctx: InitializeSets() — reflect QuiverSet<T> properties
	Ctx->>Set: Activator.CreateInstance()
	Set->>Set: Scan [QuiverKey] / [QuiverVector] / [QuiverLargeField] / [QuiverIndex]
	Set->>Set: Compile expression-tree accessors
	Set->>Idx: CreateIndex() per vector field
	deactivate Ctx

	User->>Ctx: LoadAsync()
	Ctx->>BSP: Read header + segment table
	loop Each segment in order
		BSP-->>Ctx: EntityMeta / VectorBlob / Blob / Tombstone
		Ctx->>Set: rebuild entities + indexes
	end

	User->>Set: Add(entity)
	Set->>Set: Write lock → AddCore() → PrepareVectors()
	Set->>Idx: Add(id, vector)

	User->>Set: Search(selector, query, topK)
	Set->>Set: Read lock → NormalizeIfNeeded()
	Set->>Idx: Search(query, topK)
	Idx-->>Set: List<(id, similarity)>
	Set-->>User: List<QuiverSearchResult>

	alt Full snapshot
		User->>Ctx: SaveAsync()
		Ctx->>BSP: temp file + File.Move atomic replace
	else Segment append
		User->>Ctx: AppendAsync()
		Ctx->>BSP: append EntityMeta + VectorBlob, rewrite footer
	else Tombstone-only
		User->>Ctx: FlushTombstonesAsync()
		Ctx->>BSP: append Tombstone segment, rewrite footer
	end

	User->>Ctx: DisposeAsync()
	Ctx->>Ctx: SaveAsync() — persist current in-memory image

Documentation

Full chapter documentation is available in the English Wiki:

Keywords

Embedded Vector Database · Pure .NET · ANN · Approximate Nearest Neighbor Search · HNSW · IVF · KDTree · Code-First · Embedding · Semantic Search · Face Recognition · Image-to-Image Search · RAG · SIMD · Schema Migration · ISimilarity · Mmap · SQ8 Quantization · Matryoshka Truncation