SqlServerVectorConnector 1.1.3636

SqlServerVectorConnector

SqlServerVectorConnector is a SQL Server 2025 connector for Microsoft.Extensions.VectorData. It stores each vector collection as a SQL table, uses SQL Server's native VECTOR(n) column type, and performs similarity search with VECTOR_DISTANCE.

What it supports

• VectorStore and VectorStoreCollection<TKey, TRecord> integration
• Automatic table creation per collection
• CRUD operations over typed records
• Similarity search over one or more vector properties
• Optional filtered retrieval and filtered vector search (fixed TOP handling)
• Dynamic collections backed by Dictionary<string, object?>
• Configurable schema, defaulting to dbo (schema names are validated to prevent injection)
• Built‑in retry logic for transient SqlExceptions (deadlocks, timeouts) with exponential back‑off
• Optional logging via ILogger<SqlServerCollection<TKey,TRecord>> (null‑logger fallback)

Requirements

• .NET 8
• SQL Server 2025 or later
• Microsoft.Extensions.VectorData.Abstractions 10.6.0-compatible consumer code

Install

dotnet add package SqlServerVectorConnector

Quick start

Define a record type with Vector Data attributes:

using Microsoft.Extensions.VectorData;
using SqlServerVectorConnector;

public sealed class DocumentRecord
{
    [VectorStoreKey]
    public string Id { get; set; } = string.Empty;

    [VectorStoreData]
    public string Title { get; set; } = string.Empty;

    [VectorStoreData]
    public string Content { get; set; } = string.Empty;

    [VectorStoreVector(1536, DistanceFunction = DistanceFunction.CosineSimilarity)]
    public ReadOnlyMemory<float> Embedding { get; set; }
}

Create a store and collection:

using SqlServerVectorConnector;

var connectionString = "Server=.;Database=VectorDb;Trusted_Connection=True;TrustServerCertificate=True";

var vectorStore = new SqlServerVectorStore(
    connectionString,
    new SqlServerVectorStoreOptions
    {
        Schema = "dbo"
    });

// Optional logger can be supplied; if omitted a no‑op logger is used.
var logger = LoggerFactory.Create(builder => builder.AddConsole()).CreateLogger<SqlServerCollection<string, DocumentRecord>>();
var documents = vectorStore.GetCollection<string, DocumentRecord>("Documents", logger);
await documents.EnsureCollectionExistsAsync();

Insert or update records:

await documents.UpsertAsync(new DocumentRecord
{
    Id = "doc-1",
    Title = "SQL Server 2025 vectors",
    Content = "Native vector support is built into SQL Server 2025.",
    Embedding = new ReadOnlyMemory<float>(embeddingValues)
});

Run a vector search:

await foreach (var result in documents.SearchAsync(
    new ReadOnlyMemory<float>(queryEmbedding),
    top: 5))
{
    Console.WriteLine($"{result.Record.Title} ({result.Score})");
}

Run a filtered vector search:

await foreach (var result in documents.SearchAsync(
    new ReadOnlyMemory<float>(queryEmbedding),
    top: 5,
    new VectorSearchOptions<DocumentRecord>
    {
        Filter = record => record.Title.Contains("SQL"),
        IncludeVectors = false,
        ScoreThreshold = 0.5
    }))
{
    Console.WriteLine(result.Record.Id);
}

Retrieve records without vector search:

var record = await documents.GetAsync("doc-1");

await foreach (var item in documents.GetAsync(
    record => record.Title.Contains("SQL"),
    top: 10))
{
    Console.WriteLine(item.Title);
}

Configuration

Store-level configuration:

var store = new SqlServerVectorStore(
    connectionString,
    new SqlServerVectorStoreOptions
    {
        Schema = "vectors"
    });

Collection-level configuration is available through SqlServerCollectionOptions, which extends VectorStoreCollectionOptions and also allows overriding the target schema.

Supported CLR types

Key property types:

• string
• int
• long
• Guid

Data property types:

• string
• bool / bool?
• int / int?
• long / long?
• float / float?
• double / double?
• decimal / decimal?
• DateTime / DateTime?
• DateTimeOffset / DateTimeOffset?
• Guid / Guid?
• byte[]

Vector property types:

• ReadOnlyMemory<float>
• ReadOnlyMemory<float>?
• float[]

Notes

• Each collection maps to a table in the configured schema.
• Vector columns are created as VECTOR(n).
• Search uses VECTOR_DISTANCE and maps cosine similarity to a descending relevance score.
• This connector targets SQL Server's native vector support rather than external vector extensions.