feat: native vector search support (paradedb/paradedb#5685)

Author: rebasedming

CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to this project will be documented in this file. The format
 
 ## [Unreleased]
 
+### Added
+
+- Native vector search support: `vector(n)` column mapping for `float[]`
+  properties (`HasVectorType`), vector fields with metric operator classes in
+  ParadeDB indexes (`HasField(..., VectorMetric)`), and the `L2Distance`,
+  `CosineDistance`, and `InnerProduct` distance functions.
+
 ### Changed
 
 - **Breaking**: `HasBm25Index` and `Bm25IndexBuilder<TEntity>` are renamed to

NUGET-README.md

@@ -18,6 +18,7 @@ The official [Entity Framework Core](https://learn.microsoft.com/en-us/ef/core/)
 - [Autocomplete](examples/Autocomplete/Program.cs)
 - [More Like This](examples/MoreLikeThis/Program.cs)
 - [Hybrid Search (RRF)](examples/HybridRrf/Program.cs)
+- [Vector Search](examples/VectorSearch/Program.cs)
 - [RAG](examples/Rag/Program.cs)
 
 ## Contributing

README.md

@@ -47,13 +47,57 @@ The official [Entity Framework Core](https://learn.microsoft.com/en-us/ef/core/)
 | ParadeDB   | 0.25.0+                       |
 | PostgreSQL | 15+ (with ParadeDB extension) |
 
+## Vector Search
+
+ParadeDB indexes pgvector `vector` columns directly inside its BM25 index — no
+pgvector ORM plugin is required. Map a `float[]` property to a `vector(n)`
+column, pick a distance metric for the index, and order by the matching
+distance function:
+
+```csharp
+public class Item
+{
+    public int Id { get; set; }
+    public float[]? Embedding { get; set; }
+}
+
+// Model configuration
+modelBuilder.Entity<Item>(entity =>
+{
+    entity.Property(x => x.Embedding).HasVectorType(384);
+
+    entity
+        .HasParadeDbIndex("items_idx", x => x.Id)
+        .HasField(x => x.Embedding, VectorMetric.Cosine);
+});
+
+// Top-K query: a `@@@` predicate (`EF.Functions.All` for match-all here) and
+// a LIMIT (`Take`) are required for the index to serve the query
+float[] queryEmbedding = GetQueryEmbedding();
+
+var results = await db
+    .Items.Where(x => EF.Functions.All(x.Id))
+    .OrderBy(x => EF.Functions.CosineDistance(x.Embedding, queryEmbedding))
+    .Take(10)
+    .ToListAsync();
+```
+
+`VectorMetric.L2` (`<->`, the default), `VectorMetric.Cosine` (`<=>`), and
+`VectorMetric.InnerProduct` (`<#>`) map to the `vector_l2_ops`,
+`vector_cosine_ops`, and `vector_ip_ops` operator classes. The distance
+function used in `OrderBy` must match the metric of the index opclass —
+`L2Distance` with `L2`, `CosineDistance` with `Cosine`, and `InnerProduct`
+with `InnerProduct` — otherwise the query still returns correct results but
+falls back to a sequential scan instead of Top-K index pushdown.
+
 ## Examples
 
 - [Quickstart](examples/Quickstart/Program.cs)
 - [Faceted Search](examples/FacetedSearch/Program.cs)
 - [Autocomplete](examples/Autocomplete/Program.cs)
 - [More Like This](examples/MoreLikeThis/Program.cs)
 - [Hybrid Search (RRF)](examples/HybridRrf/Program.cs)
+- [Vector Search](examples/VectorSearch/Program.cs)
 - [RAG](examples/Rag/Program.cs)
 
 ## Contributing

examples/Directory.Packages.props

@@ -1,7 +1,3 @@
 <Project>
   <Import Project="..\Directory.Packages.props" />
-
-  <ItemGroup>
-    <PackageVersion Include="Pgvector.EntityFrameworkCore" Version="0.3.0" />
-  </ItemGroup>
 </Project>

examples/Examples.csproj

@@ -12,14 +12,13 @@
   </PropertyGroup>
 
   <Target Name="RequireExample" BeforeTargets="CoreCompile" Condition="'$(Example)' == ''">
-    <Error Text="Set the Example property to one of: Quickstart, FacetedSearch, Autocomplete, MoreLikeThis, HybridRrf, Rag." />
+    <Error Text="Set the Example property to one of: Quickstart, FacetedSearch, Autocomplete, MoreLikeThis, HybridRrf, VectorSearch, Rag." />
   </Target>
 
   <ItemGroup>
     <PackageReference Include="EFCore.NamingConventions" />
     <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" />
     <PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" />
-    <PackageReference Include="Pgvector.EntityFrameworkCore" />
   </ItemGroup>
 
   <ItemGroup>

examples/HybridRrf/Data/MockItemWithEmbedding.cs

@@ -1,9 +1,8 @@
-using Pgvector;
 using Shared;
 
 namespace HybridRrf.Data;
 
 public class MockItemWithEmbedding : MockItem
 {
-    public Vector? Embedding { get; set; }
+    public float[]? Embedding { get; set; }
 }

examples/HybridRrf/EmbeddingLoader.cs

@@ -0,0 +1,39 @@
+using HybridRrf.Data;
+using Microsoft.EntityFrameworkCore;
+
+namespace HybridRrf;
+
+public static class EmbeddingLoader
+{
+    public static async Task LoadAsync(AppDbContext db)
+    {
+        var csvPath = Path.Combine(
+            AppContext.BaseDirectory,
+            "HybridRrf",
+            "mock_items_embeddings.csv"
+        );
+        var lines = await File.ReadAllLinesAsync(csvPath);
+
+        var embeddings = new Dictionary<int, float[]>();
+
+        for (var i = 1; i < lines.Length; i++)
+        {
+            var parts = lines[i].Split(',', 3);
+            embeddings[int.Parse(parts[0])] = parts[2]
+                .Trim('"', '[', ']')
+                .Split(',', StringSplitOptions.TrimEntries)
+                .Select(float.Parse)
+                .ToArray();
+        }
+
+        var ids = embeddings.Keys.ToArray();
+        var items = await db.MockItems.Where(x => ids.Contains(x.Id)).ToListAsync();
+        foreach (var item in items)
+        {
+            item.Embedding = embeddings[item.Id];
+        }
+
+        await db.SaveChangesAsync();
+        Console.WriteLine($"Loaded {items.Count} embeddings");
+    }
+}

examples/HybridRrf/Program.cs

@@ -2,19 +2,10 @@
 using HybridRrf.Data;
 using Microsoft.EntityFrameworkCore;
 using ParadeDB.EntityFrameworkCore.Extensions;
-using Pgvector;
-using Pgvector.EntityFrameworkCore;
 using Shared;
 
 var options = new DbContextOptionsBuilder<AppDbContext>()
-    .UseNpgsql(
-        ExampleSetup.ConnectionString,
-        o =>
-        {
-            o.UseParadeDb();
-            o.UseVector();
-        }
-    )
+    .UseNpgsql(ExampleSetup.ConnectionString, o => o.UseParadeDb())
     .UseSnakeCaseNamingConvention()
     .Options;
 
@@ -27,7 +18,7 @@
 Console.WriteLine("RRF formula: score = sum(1 / (k + rank)) across all rankings");
 
 await ExampleSetup.SetupHybridAsync(dbContext);
-await LoadEmbeddingsAsync(dbContext);
+await EmbeddingLoader.LoadAsync(dbContext);
 
 await Demo(dbContext, "running shoes", QueryEmbeddings.Values);
 await Demo(dbContext, "footwear for exercise", QueryEmbeddings.Values);
@@ -40,14 +31,14 @@
 
 static async Task Demo(AppDbContext db, string query, Dictionary<string, float[]> queryEmbeddings)
 {
-    var results = await HybridSearch(db, query, new Vector(queryEmbeddings[query]));
+    var results = await HybridSearch(db, query, queryEmbeddings[query]);
     DisplayResults(query, results);
 }
 
 static async Task<List<(string Description, double RrfScore)>> HybridSearch(
     AppDbContext db,
     string query,
-    Vector queryEmbedding,
+    float[] queryEmbedding,
     int topK = 20,
     int rrfK = 60,
     int limit = 5
@@ -71,7 +62,7 @@ static async Task Demo(AppDbContext db, string query, Dictionary<string, float[]
         {
             x.Id,
             x.Description,
-            Distance = x.Embedding!.CosineDistance(queryEmbedding),
+            Distance = EF.Functions.CosineDistance(x.Embedding, queryEmbedding),
         })
         .OrderBy(x => x.Distance)
         .Take(topK)
@@ -101,31 +92,3 @@ static void DisplayResults(string query, List<(string Description, double RrfSco
         Console.WriteLine($"  {i + 1}. {desc, -60} (RRF: {results[i].RrfScore:F4})");
     }
 }
-
-static async Task LoadEmbeddingsAsync(AppDbContext db)
-{
-    var csvPath = Path.Combine(AppContext.BaseDirectory, "HybridRrf", "mock_items_embeddings.csv");
-    var lines = await File.ReadAllLinesAsync(csvPath);
-
-    var embeddings = new Dictionary<int, float[]>();
-
-    for (var i = 1; i < lines.Length; i++)
-    {
-        var parts = lines[i].Split(',', 3);
-        embeddings[int.Parse(parts[0])] = parts[2]
-            .Trim('"', '[', ']')
-            .Split(',', StringSplitOptions.TrimEntries)
-            .Select(float.Parse)
-            .ToArray();
-    }
-
-    var ids = embeddings.Keys.ToArray();
-    var items = await db.MockItems.Where(x => ids.Contains(x.Id)).ToListAsync();
-    foreach (var item in items)
-    {
-        item.Embedding = new Vector(embeddings[item.Id]);
-    }
-
-    await db.SaveChangesAsync();
-    Console.WriteLine($"Loaded {items.Count} embeddings");
-}

examples/README.md

@@ -47,6 +47,15 @@ ranking.
 dotnet run --project examples/Examples.csproj -p:Example=HybridRrf
 ```
 
+## Vector Search (`examples/VectorSearch`)
+
+Runs Top-K nearest-neighbor queries over a pgvector column with the native
+vector support, backed by a bm25 index when the server supports it.
+
+```bash
+dotnet run --project examples/Examples.csproj -p:Example=VectorSearch
+```
+
 ## RAG: Retrieval-Augmented Generation (`examples/Rag`)
 
 Builds a small QA flow that retrieves relevant context and sends it to an LLM

examples/VectorSearch/Program.cs

@@ -0,0 +1,63 @@
+using HybridRrf;
+using HybridRrf.Data;
+using Microsoft.EntityFrameworkCore;
+using ParadeDB.EntityFrameworkCore.Extensions;
+using Shared;
+
+var options = new DbContextOptionsBuilder<AppDbContext>()
+    .UseNpgsql(ExampleSetup.ConnectionString, o => o.UseParadeDb())
+    .UseSnakeCaseNamingConvention()
+    .Options;
+
+await using var dbContext = new AppDbContext(options);
+
+Console.WriteLine(new string('=', 70));
+Console.WriteLine("Vector Search");
+Console.WriteLine(new string('=', 70));
+Console.WriteLine("\nTop-K nearest-neighbor search over a pgvector column");
+
+await ExampleSetup.SetupHybridAsync(dbContext);
+await EmbeddingLoader.LoadAsync(dbContext);
+
+await dbContext.Database.ExecuteSqlRawAsync("DROP INDEX IF EXISTS mock_items_vector_idx");
+await dbContext.Database.ExecuteSqlRawAsync(
+    """
+    CREATE INDEX mock_items_vector_idx ON mock_items
+    USING paradedb (id, embedding vector_cosine_ops)
+    WITH (key_field='id');
+    """
+);
+Console.WriteLine("Created a paradedb index over the embedding column (cosine metric)");
+
+await Demo(dbContext, "running shoes");
+await Demo(dbContext, "wireless earbuds");
+return;
+
+static async Task Demo(AppDbContext db, string query)
+{
+    var queryEmbedding = QueryEmbeddings.Values[query];
+
+    // The @@@ predicate (EF.Functions.All) and the LIMIT are required for the
+    // ParadeDB index to serve the query; the ORDER BY metric must match the
+    // index opclass (cosine here)
+    var results = await db
+        .MockItems.Where(x => EF.Functions.All(x.Id))
+        .Select(x => new
+        {
+            x.Description,
+            Distance = EF.Functions.CosineDistance(x.Embedding, queryEmbedding),
+        })
+        .OrderBy(x => x.Distance)
+        .Take(5)
+        .ToListAsync();
+
+    Console.WriteLine($"\n{new string('=', 70)}");
+    Console.WriteLine($"Query: '{query}'");
+    Console.WriteLine(new string('=', 70));
+
+    for (var i = 0; i < results.Count; i++)
+    {
+        var desc = results[i].Description[..Math.Min(60, results[i].Description.Length)];
+        Console.WriteLine($"  {i + 1}. {desc, -60} (distance: {results[i].Distance:F4})");
+    }
+}