SonnetDB 5.1.1

dotnet add package SonnetDB --version 5.1.1
                    
NuGet\Install-Package SonnetDB -Version 5.1.1
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="SonnetDB" Version="5.1.1" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="SonnetDB" Version="5.1.1" />
                    
Directory.Packages.props
<PackageReference Include="SonnetDB" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add SonnetDB --version 5.1.1
                    
#r "nuget: SonnetDB, 5.1.1"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package SonnetDB@5.1.1
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=SonnetDB&version=5.1.1
                    
Install as a Cake Addin
#tool nuget:?package=SonnetDB&version=5.1.1
                    
Install as a Cake Tool

SonnetDB

SonnetDB NuGet 包提供 SonnetDB 的 ADO.NET 访问层。源码项目、程序集和命名空间仍为 SonnetDB.Data,统一支持本地嵌入式和远程 SonnetDB 连接。

本地嵌入式连接的 Data Source=./demo-data 指向数据库目录,不是单个数据库文件。目录布局与 SonnetDB.Core 一致,适合随应用进程内打开;远程连接则通过 HTTP 访问 SonnetDB Server。

本包未声明 IsAotCompatible=true。ADO.NET 基类和 DbDataReader.GetSchemaTable() 等路径在 BCL 内部存在反射边界;需要 Native AOT 的嵌入式场景建议直接使用 SonnetDB.Core 的 Tsdb API。远程客户端内部使用 source-generated JSON 上下文,但包级别仍按 ADO.NET 兼容边界声明为非 AOT 包。

安装

dotnet add package SonnetDB

本地嵌入式连接

using SonnetDB.Data;

using var connection = new SndbConnection("Data Source=./demo-data");
connection.Open();

using var command = connection.CreateCommand();
command.CommandText = "SELECT count(*) FROM cpu";

var count = (long)(command.ExecuteScalar() ?? 0L);
Console.WriteLine(count);

远程服务器连接

using SonnetDB.Data;

using var connection = new SndbConnection(
    "Data Source=sonnetdb+http://127.0.0.1:5080/metrics;Token=sonnetdb-admin-token");
connection.Open();

using var command = connection.CreateCommand();
command.CommandText = "SHOW DATABASES";

using var reader = command.ExecuteReader();
while (reader.Read())
{
    Console.WriteLine(reader.GetString(0));
}

整数精度边界

SQL INT 使用有符号 64 位整数,范围为 -9223372036854775808 至 9223372036854775807。超范围的整数字面量、整数运算及向 INT 的显式转换会报错;参数中的超范围 ulong 同样不能作为 INT 使用。需要保存更长整数的原文时使用 STRING 列并以字符串参数传入,此时比较和排序按字符串语义执行;如需有限范围的精确十进制运算,可显式转换为 DECIMAL,它不等同于任意精度整数。

ADO 参数不直接接受 System.Numerics.BigInteger,包括其数值恰好在 Int64 范围内的情况。赋值或 AddWithValue 时抛出 SndbParameterTypeException,稳定 Code 为 big_integer_unsupported;应用层须先检查范围再显式转为 long,超范围值转为不丢精度的字符串。这项检查发生在嵌入式、HTTP 和帧协议共同的 ADO 参数入口,早于 SQL 绑定或网络请求。

嵌入式与远程读取器的 INT 值都返回 long。结果包含非 NULL 整数行时,GetFieldType() 为 typeof(long),GetSchemaTable() 报告 DbType.Int64 和十进制精度 19;REST 流会在首行前提供推断出的类型。空结果或整列为 NULL 时,现有查询结果未携带声明列类型,读取器可能报告 object。远程协议拒绝超出 Int64 的裸 JSON 整数,不会把它悄悄降为 double;STRING 列保留原文。

Microsoft.Extensions.VectorData

SonnetDB.Data.VectorData 提供 Microsoft.Extensions.VectorData adapter。默认情况下,一个 VectorData collection 会映射为 SonnetDB DOCUMENT COLLECTION:record key 存为文档 id,数据字段和向量字段存入 JSON document,向量搜索通过 vector_search(...) 读取 JSON number array。

using Microsoft.Extensions.VectorData;
using SonnetDB.Data;
using SonnetDB.Data.VectorData;

await using var connection = new SndbConnection("Data Source=./demo-data");
using var store = new SonnetDBVectorStore(connection);

var collection = store.GetCollection<string, KnowledgeRecord>("knowledge");
await collection.EnsureCollectionExistsAsync();

await collection.UpsertAsync(new KnowledgeRecord
{
    Id = "kb-1",
    Title = "Pump alarm guide",
    Site = "north",
    Embedding = [1, 0, 0],
});

var results = await collection
    .SearchAsync(
        new ReadOnlyMemory<float>([1, 0, 0]),
        top: 5,
        new VectorSearchOptions<KnowledgeRecord>
        {
            IncludeVectors = true,
            Filter = record => record.Site == "north",
        })
    .ToArrayAsync();

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

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

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

    [VectorStoreVector(3, DistanceFunction = DistanceFunction.CosineDistance)]
    public float[] Embedding { get; set; } = [];
}

measurement 仍用于时序数据和时序 VECTOR(N) 列;通用 VectorData collection 不默认映射到 measurement,避免把非时序记录强行绑定到时间轴。

SonnetMQ 高层客户端

SonnetDB.Data.Mq 提供 producer/consumer builder,统一支持嵌入式和远程 MQ。producer 的 MaxInFlight 和 consumer 的 Prefetch 都是有界值;consumer 同时提供 PullAsync/PushAsync 异步枚举、manual/auto ACK、取消和 graceful drain。

using var mq = new SndbMqClient("Data Source=./demo-data;Mode=Embedded");
await using var producer = mq.Producer("events").MaxInFlight(4).Build();
await producer.PublishAsync(new byte[] { 1, 2, 3 });
await producer.DrainAsync();

await using var consumer = mq.Consumer("events", "workers")
    .Prefetch(32)
    .ManualAck()
    .Build();
await foreach (var delivery in consumer.PullAsync(cancellationToken))
{
    await HandleAsync(delivery.Message, cancellationToken);
    await delivery.AckAsync(cancellationToken);
}

该高层入口复用现有 publish/pull/ack 合同,不提供 nack、redelivery、DLQ 或 exactly-once;详见 MQ 高层客户端。

Document Store

SonnetDB.Data.Documents 提供嵌入式与远程共用的 SndbDocumentClient。类型化 builder 会生成 SonnetDB 自有 Document DTO,不要求手写 filter 操作符或构造 JsonElement;它不表示 MongoDB Driver 或 wire protocol 兼容。

using SonnetDB.Data.Documents;

using var documents = new SndbDocumentClient("Data Source=./demo-data");
await documents.CreateCollectionAsync("devices");

var filter = new SndbDocumentFilterBuilder()
    .Equal("$.site", "north")
    .GreaterThanOrEqual("$.score", 5)
    .Build();
var sort = new SndbDocumentSortBuilder()
    .Descending("$.score")
    .Build();

var cursor = documents.FindCursor(
    "devices",
    new SndbDocumentFindOptions(Filter: filter, Sort: sort, Limit: 100));
await foreach (var document in cursor.ReadAllAsync())
    Console.WriteLine(document.Json);

continuation token 绑定集合、查询形状、快照版本和过期时间。无效、错配、过期或快照失效时会抛出带 DocumentCursorErrorCodes 稳定 code 的 DocumentCursorException,调用方应重新发起查询,不能静默从头读取。

FindOneAndUpdateAsync 在一个文档原子边界内返回 before/after image。BulkWriteAsync 可混合 insert、replace、update、delete 与 upsert,ordered 失败整批零变更,unordered 把有效项作为一个 collection 内原子批次提交;逐项结果包含稳定错误码。可选 requestId 在 24 小时内绑定长度前缀请求指纹,安全重试会返回 Replayed=true,同一 ID 携带不同 payload 会返回 idempotency_conflict。

完整可运行代码见仓库中的 samples/SonnetDB.DocumentQuickstart;MongoDB 迁移边界、CLI dump/NDJSON 导入和机器差异目录见 docs/mongodb-migration.md 与 docs/document-mongodb-gap.json。这些入口不表示 MongoDB wire protocol、BSON command 或官方 Driver 兼容。

发布包和默认示例配置见仓库根目录 docs/releases/。

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (8)

Showing the top 5 NuGet packages that depend on SonnetDB:

Package Downloads
mooSQL.Ext.Core

一个纯粹、高可用、自由的面向数据库的连接库

mooSQL.Ext

一个纯粹、高可用、自由的面向数据库的连接库

SonnetDB.EntityFrameworkCore

SonnetDB 的 Entity Framework Core 关系型 Provider,提供 UseSonnetDB、SQL 生成、类型映射、迁移 SQL 和基础查询翻译。

SonnetDB.Caching

SonnetDB KV-backed EasyCaching and IDistributedCache providers.

SonnetDB.Caching.EasyCaching

SonnetDB KV-backed EasyCaching provider.

GitHub repositories (1)

Showing the top 1 popular GitHub repositories that depend on SonnetDB:

Repository Stars
IoTSharp/IoTSharp
IoTSharp is an open-source IoT platform for data collection, processing, visualization, and device management.
Version Downloads Last Updated
5.1.1 0 11/15/2026
5.0.0 227 11/4/2026
4.5.0-preview.ef266.5 252 10/13/2026
4.0.0 521 9/27/2026
3.1.0 471 8/24/2026
3.0.1 267 7/8/2026
3.0.0 173 7/7/2026
2.5.0 324 6/26/2026
2.2.0 161 6/16/2026
2.1.1 217 6/15/2026
2.1.0 151 6/14/2026
2.0.0 161 6/14/2026
1.2.0 210 5/8/2026
1.1.0 148 5/6/2026
1.0.0 410 4/26/2026
0.2.1 144 5/3/2026
0.2.0 137 5/3/2026
0.1.0 139 5/3/2026