SonnetDB 5.1.1
dotnet add package SonnetDB --version 5.1.1
NuGet\Install-Package SonnetDB -Version 5.1.1
<PackageReference Include="SonnetDB" Version="5.1.1" />
<PackageVersion Include="SonnetDB" Version="5.1.1" />
<PackageReference Include="SonnetDB" />
paket add SonnetDB --version 5.1.1
#r "nuget: SonnetDB, 5.1.1"
#:package SonnetDB@5.1.1
#addin nuget:?package=SonnetDB&version=5.1.1
#tool nuget:?package=SonnetDB&version=5.1.1
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 | Versions 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. |
-
net10.0
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.14)
- Microsoft.Extensions.VectorData.Abstractions (>= 10.11.0)
- SonnetDB.Core (>= 5.1.1)
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 |