Pgvector 0.2.0-rc.2

pgvector-dotnet

pgvector support for C#

Supports Npgsql, Dapper, and Entity Framework Core

Getting Started

Follow the instructions for your database library:

• Npgsql
• Dapper
• Entity Framework Core

Npgsql

Run:

dotnet add package Pgvector

Import the library

using Pgvector.Npgsql;

Create a connection

var dataSourceBuilder = new NpgsqlDataSourceBuilder(connString);
dataSourceBuilder.UseVector();
await using var dataSource = dataSourceBuilder.Build();

var conn = dataSource.OpenConnection();

Enable the extension

await using (var cmd = new NpgsqlCommand("CREATE EXTENSION IF NOT EXISTS vector", conn))
{
    await cmd.ExecuteNonQueryAsync();
}

conn.ReloadTypes();

Create a table

await using (var cmd = new NpgsqlCommand("CREATE TABLE items (id serial PRIMARY KEY, embedding vector(3))", conn))
{
    await cmd.ExecuteNonQueryAsync();
}

Insert a vector

await using (var cmd = new NpgsqlCommand("INSERT INTO items (embedding) VALUES ($1)", conn))
{
    var embedding = new Vector(new float[] { 1, 1, 1 });
    cmd.Parameters.AddWithValue(embedding);
    await cmd.ExecuteNonQueryAsync();
}

Get the nearest neighbors

await using (var cmd = new NpgsqlCommand("SELECT * FROM items ORDER BY embedding <-> $1 LIMIT 5", conn))
{
    var embedding = new Vector(new float[] { 1, 1, 1 });
    cmd.Parameters.AddWithValue(embedding);

    await using (var reader = await cmd.ExecuteReaderAsync())
    {
        while (await reader.ReadAsync())
        {
            Console.WriteLine((Vector)reader.GetValue(0));
        }
    }
}

Add an approximate index

await using (var cmd = new NpgsqlCommand("CREATE INDEX ON items USING ivfflat (embedding vector_l2_ops) WITH (lists = 100)", conn))
{
    await cmd.ExecuteNonQueryAsync();
}

Use vector_ip_ops for inner product and vector_cosine_ops for cosine distance

See a full example

Dapper

Run:

dotnet add package Pgvector.Dapper

Import the library

using Pgvector.Dapper;
using Pgvector.Npgsql;

Create a connection

SqlMapper.AddTypeHandler(new VectorTypeHandler());

var dataSourceBuilder = new NpgsqlDataSourceBuilder(connString);
dataSourceBuilder.UseVector();
await using var dataSource = dataSourceBuilder.Build();

var conn = dataSource.OpenConnection();

Enable the extension

conn.Execute("CREATE EXTENSION IF NOT EXISTS vector");
conn.ReloadTypes();

Define a class

public class Item
{
    public int Id { get; set; }
    public Vector? Embedding { get; set; }
}

Create a table

conn.Execute("CREATE TABLE items (id serial PRIMARY KEY, embedding vector(3))");

Insert a vector

var embedding = new Vector(new float[] { 1, 1, 1 });
conn.Execute(@"INSERT INTO items (embedding) VALUES (@embedding)", new { embedding });

Get the nearest neighbors

var embedding = new Vector(new float[] { 1, 1, 1 });
var items = conn.Query<Item>("SELECT * FROM items ORDER BY embedding <-> @embedding LIMIT 5", new { embedding });
foreach (Item item in items)
{
    Console.WriteLine(item.Embedding);
}

Add an approximate index

conn.Execute("CREATE INDEX ON items USING ivfflat (embedding vector_l2_ops) WITH (lists = 100)");
// or
conn.Execute("CREATE INDEX ON items USING hnsw (embedding vector_l2_ops)");

Use vector_ip_ops for inner product and vector_cosine_ops for cosine distance

See a full example

Entity Framework Core

Run:

dotnet add package Pgvector.EntityFrameworkCore

Import the library

using Pgvector.EntityFrameworkCore;

Enable the extension

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.HasPostgresExtension("vector");
}

Configure the connection

protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
{
    optionsBuilder.UseNpgsql("connString", o => o.UseVector());
}

Define a model

public class Item
{
    public int Id { get; set; }

    [Column(TypeName = "vector(3)")]
    public Vector? Embedding { get; set; }
}

Insert a vector

ctx.Items.Add(new Item { Embedding = new Vector(new float[] { 1, 1, 1 }) });
ctx.SaveChanges();

Get the nearest neighbors

var embedding = new Vector(new float[] { 1, 1, 1 });
var items = await ctx.Items
    .OrderBy(x => x.Embedding!.L2Distance(embedding))
    .Take(5)
    .ToListAsync();

foreach (Item item in items)
{
    if (item.Embedding != null)
    {
        Console.WriteLine(item.Embedding);
    }
}

Also supports MaxInnerProduct and CosineDistance

Get the distance

var items = await ctx.Items
    .Select(x => new { Entity = x, Distance = x.Embedding!.L2Distance(embedding) })
    .ToListAsync();

Get items within a certain distance

var items = await ctx.Items
    .Where(x => x.Embedding!.L2Distance(embedding) < 5)
    .ToListAsync();

Add an approximate index

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Item>()
        .HasIndex(i => i.Embedding)
        .HasMethod("ivfflat") // or hnsw
        .HasOperators("vector_l2_ops");
}

Use vector_ip_ops for inner product and vector_cosine_ops for cosine distance

See a full example

History

• Pgvector
• Pgvector.Dapper
• Pgvector.EntityFrameworkCore

Contributing

Everyone is encouraged to help improve this project. Here are a few ways you can help:

• Report bugs
• Fix bugs and submit pull requests
• Write, clarify, or fix documentation
• Suggest or add new features

To get started with development:

git clone https://github.com/pgvector/pgvector-dotnet.git
cd pgvector-dotnet
createdb pgvector_dotnet_test
dotnet test