pgvector-dotnet

For Visual Basic users, install the Pgvector package. Configure the NpgsqlDataSourceBuilder with .UseVector() and ensure you call conn.ReloadTypes() after creating the extension.

dotnet add package Pgvector

Dim dataSourceBuilder As New NpgsqlDataSourceBuilder(connString)
dataSourceBuilder.UseVector()
Dim dataSource = dataSourceBuilder.Build()

Dim conn = dataSource.OpenConnection()

' Enable extension
Using cmd As New NpgsqlCommand("CREATE EXTENSION IF NOT EXISTS vector", conn)
    cmd.ExecuteNonQuery()
End Using

conn.ReloadTypes()

To use pgvector with EF Core, install the Pgvector.EntityFrameworkCore package. You need to:

1. Enable the extension in OnModelCreating using modelBuilder.HasPostgresExtension("vector").
2. Configure the connection in OnConfiguring using .UseVector().
3. Define model properties with the [Column(TypeName = "vector(n)")] attribute.

dotnet add package Pgvector.EntityFrameworkCore

using Pgvector.EntityFrameworkCore;

// In your DbContext
protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.HasPostgresExtension("vector");
}

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

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

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

To set up a local development environment, clone the repository, create a test database, and run the tests. To run a specific example, navigate to the example directory, create its required database, and use dotnet run.

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

# Run an example
cd examples/Loading
createdb pgvector_example
dotnet run

To use pgvector with Dapper, install the Pgvector.Dapper package. You must register a VectorTypeHandler with SqlMapper.AddTypeHandler and configure the NpgsqlDataSourceBuilder with .UseVector(). This allows Dapper to map Vector, HalfVector, and SparseVector types automatically.

dotnet add package Pgvector.Dapper

using Pgvector.Dapper;

// Register the type handler
SqlMapper.AddTypeHandler(new VectorTypeHandler());

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

var conn = dataSource.OpenConnection();

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

To use pgvector with Npgsql in C#, install the Pgvector package. You must configure the NpgsqlDataSourceBuilder using .UseVector() to enable vector support. After establishing a connection, you must ensure the vector extension is enabled in your PostgreSQL database and call conn.ReloadTypes() to allow the driver to recognize the new types.

dotnet add package Pgvector

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();

For F# users, install the Pgvector package. Use NpgsqlDataSourceBuilder.UseVector() to configure the data source. Extension management and queries are typically performed using the Sql helper module.

dotnet add package Pgvector

open Pgvector

let dataSourceBuilder = new NpgsqlDataSourceBuilder(connString)
dataSourceBuilder.UseVector()
use dataSource = dataSourceBuilder.Build()

// Enable extension
dataSource
|> Sql.fromDataSource
|> Sql.query "CREATE EXTENSION IF NOT EXISTS vector"
|> Sql.executeNonQuery

EF Core integration provides extension methods on Vector for distance calculations. Supported methods include L2Distance, MaxInnerProduct, CosineDistance, L1Distance, HammingDistance, and JaccardDistance.

// Get 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();

// Get items within a certain distance
var itemsWithinRange = await ctx.Items
    .Where(x => x.Embedding!.L2Distance(embedding) < 5)
    .ToListAsync();

Use the Vector class to represent dense vectors. You can instantiate a Vector from a float[] array and convert it back to an array using ToArray().

var vec = new Vector(new float[] { 1, 2, 3 });
var arr = vec.ToArray();

Use the HalfVector class to represent half-precision vectors. You can instantiate a HalfVector from a Half[] array and convert it back to an array using ToArray().

var vec = new HalfVector(new Half[] { (Half)1, (Half)2, (Half)3 });
var arr = vec.ToArray();

The VectorTypeInfoResolverFactory is used to integrate pgvector types into the Npgsql type mapping system. It provides resolvers that map PostgreSQL pgvector data types to their corresponding .NET types. This is typically used when configuring an Npgsql data source to ensure the driver understands how to serialize and deserialize vector types.

Supported mappings include:

• vector (PostgreSQL) $\leftrightarrow$ Vector (.NET)
• halfvec (PostgreSQL) $\leftrightarrow$ HalfVector (.NET) (Available on .NET 5.0 or greater)
• sparsevec (PostgreSQL) $\leftrightarrow$ SparseVector (.NET)

// Example of how this factory is typically used when configuring an Npgsql DataSource
var dataSourceBuilder = new NpgsqlDataSourceBuilder(connectionString);
dataSourceBuilder.UseVectorTypeInfoResolverFactory();
await using var dataSource = dataSourceBuilder.Build();