九种数据模型，各有原生语义，共享一套引擎
SonnetDB 是一款多模型数据引擎。
它把时序、关系表、键值、JSON 文档、全文检索、向量检索、对象存储、消息队列和原生属性图——九类通常需要多个独立系统才能覆盖的数据能力——统一进同一个引擎，通过 SQL、标准 API 和管理工具访问。
SonnetDB 的核心价值是统一：九种数据模型保留各自的原生语义和访问方式，共用服务进程、权限入口和管理后台，并在同一引擎内协同工作。持久化与恢复仍有模型边界：数据库备份覆盖该数据库目录中的资源；Server 的 SonnetMQ 位于实例级 .system/mq，当前不包含在单库备份中，不能把单库恢复视为九模型一致性恢复。
部署形态保持灵活：既可作为库嵌入进程内直接使用，也可部署为独立服务，适用于本地应用、设备与边缘节点、业务系统、私有化环境等不同场景。
| 数据模型 | 一个引擎内直接提供 |
|---|---|
| 时序 | 设备指标、工业采集、时间窗口聚合、压缩、Retention |
| 关系表 | 业务表、主键、索引、JOIN、同库关系表轻事务、外键、EF Core |
| 键值 / 缓存 | 设备状态、会话、配置、TTL、前缀扫描、原子操作 |
| JSON 文档 | 文档集合、JSON path 查询、文档索引、文档向量索引 |
| 全文检索 | BM25 排序、多语言分词、模糊检索 |
| 向量检索 | HNSW 近邻索引 + 精确回退、Hybrid Search |
| 对象存储 | S3 风格 bucket、分片上传、Range 读取、Presigned URL；不承诺全量 S3/SigV4 兼容 |
| 消息队列 | SonnetMQ topic、消费者组、推送 / ack、重启 replay |
| 原生属性图（Graph Beta） | 顶点、边、标签、属性、双向原生邻接、SQL/PGQ GRAPH_TABLE、可选的嵌入式受限 GQL 风格只读入口 |
关系型 SQL 是一个实用子集，覆盖常见查询、聚合、JOIN、事务和多模型扩展，但不是完整的 SQL 标准实现。原生属性图的 Graph Beta 名称描述当前功能范围，不表示正式 Beta 语义/容量 gate 已通过，也不代表完整 GQL、Cypher 或 Neo4j 兼容；固定硬件、外部语义对拍和长稳生产门禁仍未完成。各能力的成熟度以对应的专题文档为准。
九种原生数据模型之外，SonnetDB 还把空间/轨迹、流处理/订阅、CDC/边缘同步、多模态 AI/RAG 和治理/恢复/观测列为五项平台能力，共十四项能力。每项能力的稳定 ID、真实入口、路线图归属、证据路径和当前边界见机器可读证据索引。公开状态只使用 supported、partial、planned、not_planned 和 beta；完整定义见能力成熟度口径。beta 只表示有限合同可用，不表示生产门禁已经通过。
3.0 在 HTTP/2 之上落地了一套覆盖七个基础数据面服务（消息队列、时序、SQL、向量、KV、对象、文档）的通用二进制帧协议。这些服务共享同一条高吞吐通道：时序批量写以列式紧凑二进制直传，SQL 结果以列式分块回传，向量检索的查询向量以原生 f32 二进制承载。SQL 分块限制的是响应编码缓冲；当前端点仍先取得完整的 SelectExecutionResult.Rows，大结果集的执行和结果内存会随数据量增长，尚不具备从执行器到客户端的全链路有界流式读取。当前 Graph Beta 又由 M40 #351 在同一端点追加 service=8 的受限单跳 Expand；原生属性图同时通过 API 和 SQL/PGQ 接入，其余图操作仍按各自 API/SQL 边界执行。REST 接口完整保留作兼容，客户端可通过连接串 Protocol 选项在 auto / frame-http2 / rest 之间自由切换。
| 使用方式 | 入口 |
|---|---|
| 嵌入式 | Tsdb.Open(...) 直接在进程内打开数据库目录 |
| 服务端 | Docker / HTTP API / Web Admin |
| .NET 生态 | ADO.NET、EF Core、IDistributedCache / EasyCaching Provider |
| 命令行 | sndb 本地 / 远程执行 SQL、备份和维护 |
| VS Code | 安装 SonnetDB 官方扩展，在编辑器内连接、浏览 schema、执行 SQL 和查看结果 |
| 二进制帧协议 | HTTP/2 上的高吞吐帧接入，覆盖七个基础服务，并提供 Graph service=8 单跳 Expand，REST 全保留作兼容 |
| 设备接入 | 内建 MQTT broker（设备直连落库）+ 外部 MQTT client（订阅现有 EMQX / Mosquitto） |
| 多语言 | C、Go、Rust、Java、Python、VB6、PureBasic 连接器 |
| AI / Agent | Web CopilotDock、MCP 工具入口 |
using SonnetDB.Engine;
using SonnetDB.Sql.Execution;
using var db = Tsdb.Open(new TsdbOptions
{
RootDirectory = "./demo-data",
});
SqlExecutor.Execute(db, """
CREATE MEASUREMENT cpu (
host TAG,
usage FIELD FLOAT
)
""");
SqlExecutor.Execute(db, """
INSERT INTO cpu (time, host, usage)
VALUES (1713676800000, 'server-01', 0.71)
""");
var result = (SelectExecutionResult)SqlExecutor.Execute(
db,
"SELECT time, host, usage FROM cpu WHERE host = 'server-01'")!;
foreach (var row in result.Rows)
{
Console.WriteLine($"{row[0]} {row[1]} {row[2]}");
}仓库的 Docker 发布工作流会额外构建并推送预编译镜像 iotsharp/sonnetdb 与 ghcr.io/<owner>/sonnetdb，可直接拉取：
docker run --rm -p 127.0.0.1:5080:5080 -v ./sonnetdb-data:/data iotsharp/sonnetdb:latest也可以从源码自行构建镜像：
docker build -f src/SonnetDB/Dockerfile -t sonnetdb .
docker run --rm -p 127.0.0.1:5080:5080 -v ./sonnetdb-data:/data sonnetdb启动后访问：
http://127.0.0.1:5080/admin/http://127.0.0.1:5080/help/
当 /data/.system 为空时，/admin/ 会进入首次安装流程。向导会根据主机名和本机硬件指纹生成稳定的服务器 ID，并默认填写组织名称、管理员用户名和随机 Bearer Token；管理员密码必须手动输入。
示例端口仅绑定主机 loopback。远程部署请先用 SONNETDB_USER / SONNETDB_PASSWORD 引导并验证 needsSetup=false 与管理员认证，再显式开放需要的接口，见 Docker 首次初始化与远程部署。
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);远程连接示例（支持 Data Source= URL 与 PostgreSQL 风格的 Host/Port/Username/Password 两种连接串）：
using var connection = new SndbConnection(
"Host=127.0.0.1;Port=5080;Database=metrics;Username=alice;Password=secret");
connection.Open();# 安装
dotnet tool install --global SonnetDB.Cli
# 本地直接使用
sndb local --path ./demo-data --command "SELECT count(*) FROM cpu"
# 保存 profile，下次免输路径
sndb local --path ./demo-data --save-profile home --default
sndb connect home --command "SELECT count(*) FROM cpu"
# 连接远程服务端
sndb remote --url http://127.0.0.1:5080 --database metrics --token your-token --repl更完整的 CLI、ADO.NET、文档客户端、嵌入式、远程和批量写入示例见 docs。
在 VS Code 扩展市场搜索 SonnetDB，或直接运行：
code --install-extension iotsharp.sonnetdb-vscode
| 组件 | 说明 |
|---|---|
src/SonnetDB.Core |
多模型核心库：时序、关系表、KV、文档、搜索、对象存储适配、本地消息队列、原生属性图、备份恢复和底层持久化。核心库不引入第三方运行时依赖 |
src/SonnetDB |
HTTP 服务端、首次安装流程、认证授权、SSE、MCP、Admin UI、Copilot 桥接、二进制帧端点、MQTT broker/client 和内置 /help 文档站点 |
src/SonnetDB.Data |
ADO.NET 提供程序，NuGet 包名 SonnetDB，命名空间 SonnetDB.Data；承接 Microsoft.Extensions.VectorData 的 SonnetDB adapter |
src/SonnetDB.EntityFrameworkCore |
EF Core Provider，提供 UseSonnetDB(...)、类型映射、查询翻译和 migrations SQL |
src/SonnetDB.Cli |
命令行工具 sndb：本地 / 远程连接、profile 管理、交互式 REPL |
extensions/SonnetDB.Caching.EasyCaching |
基于 SonnetDB KV keyspace 的 EasyCaching Provider |
extensions/SonnetDB.Caching.Distributed |
基于 SonnetDB KV keyspace 的 IDistributedCache Provider |
web |
管理后台前端（含 SonnetDB Studio、全局 CopilotDock 与 SPA 发布静态资源） |
src/SonnetDB.Studio |
基于 NativeWebHost 的 SonnetDB Studio 桌面壳 |
extensions/sonnetdb-vscode |
官方 VS Code 扩展：远程/托管本地连接、Explorer、SQL、结果视图与 Copilot |
docs |
JekyllNet 文档站点源码；构建镜像时生成并打包到 /help |
README 只保留项目概览和最短入门路径，完整说明在专题文档中：
| 主题 | 文档 |
|---|---|
| 入门、部署、首次安装 | 开始使用 |
| 时序建模、measurement / tag / field / time | 数据模型 |
| SQL 语法、函数、控制面 SQL | SQL 参考、SQL Cookbook |
| Web Admin、SQL 工作台、Copilot | SonnetDB Studio |
| Copilot Provider、模型分组、本地模型 | Copilot Provider 与模型目录 |
| 九模型管理工作台、Studio 桌面与 VS Code parity | 管理工具与三面能力矩阵 |
| VS Code 扩展安装、连接与开发 | 从 Marketplace 安装、SonnetDB for VS Code |
| 嵌入式 API、ADO.NET、EF Core、CLI | 嵌入式 API、ADO.NET、CLI |
| .NET 生态接入与 Profile 边界 | 生态接入、可运行样例 |
| SigLIP2 文搜图、图搜图与 Bucket 异步摄取 | 语义图片检索、工业图片样例 |
| 确定性文本分块、完整快照 diff 与有界 RAG 应用回调（Core building blocks） | RAG 摄取 Core |
| 批量写入、Line Protocol、JSON ingest | 批量写入 |
| KV、文档、全文、向量、Hybrid Search | KV Keyspace、Document Store、Document Quickstart、MongoDB-like 迁移、向量搜索 |
| Graph Beta 本地功能、SQL/PGQ、GQL 风格查询与 GraphRAG 合同（固定硬件/外部对拍/长稳发布门禁未完成） | Graph GQL 风格查询入口、知识图谱与 GraphRAG 合同、原生属性图路线与边界 |
| 二进制帧协议、MQTT 与 Sparkplug B 接入 | 帧协议、Sparkplug B |
| 地理空间、轨迹、预测、PID | 地理空间、预测、PID 控制 |
| 架构、目录布局、备份恢复 | 架构总览、文件格式、备份恢复 |
| 发布产物、Docker、安装包 | 发布与打包 |
| 性能与可靠性 | 基准说明、生态底座长稳与恢复、近期性能与可靠性变更 |
| 历史交付声明、证据边界与未兑现计划 | 变更日志核查、历史计划归档、后续路线图 |
性能数字请以 tests/SonnetDB.Benchmarks/README.md 和各报告的环境、命令与原始样本为准。已有报告包括本机嵌入式测试和同机容器对照，只能说明各自工作负载的结果，不代表生产部署性能。 历史九域性能报告 的原始证据已撤回，其中数字不能作为当前性能结论；固定硬件、ARM64、生产同语料和七天混合负载仍待重新取证。
- 嵌入式写入、范围查询、时间窗口聚合、向量召回和地理空间查询都有独立 benchmark。
- 时序 WAL 落盘强度分三级（进程内缓冲 / OS page cache / 每批 fsync）；segment 默认在发布前执行 fsync，时序 Delete 无条件同步 WAL。持久性取决于配置、操作系统及存储设备的落盘保证，现有崩溃恢复测试不构成任意断电或介质故障下零丢失的承诺；详见架构总览与近期性能与可靠性变更。
SonnetDB 提供独立的 parity 套件，与 PostgreSQL、MongoDB、InfluxDB、VictoriaMetrics、Redis、Qdrant、MinIO、NATS JetStream、Meilisearch 和 ClickHouse 对照已覆盖场景的行为。MongoDB 仅作为 Document 语义参考，明确不验证 wire protocol / BSON command / 官方 Driver 直连兼容。.github/workflows/parity.yml 配置每日运行 light / full 矩阵，能力、可靠性和算法准确度作为红绿门槛，性能数字只进入 warning/report。配置定时任务、样例报告和局部测试通过不等于完整外部栈与连续七天证据通过，当前完成状态应查阅 ROADMAP.md 的 M20 证据记录。可读样例见 tests/SonnetDB.Parity/reports/sample-run.md，路线见 docs/parity-roadmap.md。
为了避免误解，这里明确说清 SonnetDB 不是什么、当前的能力上限在哪里：
- 单机数据引擎：目前只支持单节点部署，没有内置复制、高可用、自动故障转移或分片集群。跨节点冗余需要在应用层或运维层自行处理。
- 多模型是能力组合，不是各项第一：把多种数据模型放进一个进程是为了减少组件数量，不是宣称在每个模型上都优于专用数据库。对时序、向量、关系有极致性能要求的场景，仍应评估对应的专用产品。
- SQL 是子集：SQL 方言覆盖常见查询、聚合、JOIN、事务和多模型扩展，但不保证完整的 SQL 标准兼容。
- 基准是同机粗测：README 与文档里的性能数字来自同一台开发机上的同机对照，用于横向参考和持续回归，不代表你的生产硬件表现。
在这些边界内，SonnetDB 的目标是把「一个组件覆盖常见数据需求」做得可靠、够快、够用。
C# / .NET 是 SonnetDB 的核心实现与主要集成生态；嵌入式、服务端、工业边缘、设备数据和 AI 应用都是具体部署方式或使用场景，不改变“多模型数据引擎”的核心产品类别。
- 核心库 safe-only，不使用
unsafe，且不引入第三方运行时依赖。 - 一个数据库目录承载持久化数据。
- 嵌入式和服务端共享 SQL / API 语义。
- 管理能力内置到 Server、Web Admin、CLI 和 Copilot 中。
- AI 能力通过 Copilot、MCP 和 provider 抽象服务于数据查询、诊断和运维，不把 SonnetDB 绑定到单一模型供应商。
欢迎扫码加入 SonnetDB 企业微信交流群，获取版本动态、提问和反馈：
- 提 issue / PR：GitHub Issues
- 路线图见 ROADMAP.md
- 变更记录见 CHANGELOG.md
- AI 协作规范见 AGENTS.md
- AI / Agent 快速索引见 llms.txt
- 面向任意大模型的完整机器上下文见 llms-full.txt
- 外部 Agent、MCP 与安全使用见 AI / Agent 指南