KV Keyspace
KV Keyspace 是 SonnetDB Core 的轻量键值存储能力，面向内部 metadata、小对象、关系表和文档集合后续底座。当前版本先提供嵌入式库级 API，不新增 SQL 语法，也不把 KV 暴露为独立网络服务。
基本用法
using System.Text;
using SonnetDB.Engine;
using var db = Tsdb.Open(new TsdbOptions
{
RootDirectory = "./data",
});
var kv = db.Keyspaces.Open("devices");
kv.Put("device:1001", Encoding.UTF8.GetBytes("online"));
byte[]? value = kv.Get("device:1001");
foreach (var row in kv.ScanPrefix("device:", limit: 100))
{
Console.WriteLine($"{Encoding.UTF8.GetString(row.Key.Span)} v{row.Version}");
}
kv.Delete("device:1001");
API 边界
| API | 说明 |
|---|---|
Tsdb.Keyspaces.Open(name) |
打开或创建 keyspace。名称只允许字母、数字、点、下划线和短横线。 |
Put(key, value, expiresAtUtc?) |
写入或覆盖 key，返回单调递增版本号。可选 DateTimeOffset 指定到期时间；到期后读到 false/null，由后台 GC 真正回收。 |
PutMany(values, expiresAtUtc?) |
把多个 key 编码为单条原子 WAL batch；所有返回项共享同一个 batch commit 版本。 |
Get(key) / TryGet(key, out value) |
读取当前值，返回 value 副本。 |
Delete(key) |
删除 key。不存在时返回 false。 |
ScanPrefix(prefix, limit) |
按 key 字节序升序返回当前快照。 |
CreateSnapshot() |
写出完整快照并截断快照版本之前的 KV WAL。 |
Compact() |
写出不可变 KV 段文件并截断已压实版本之前的 KV WAL。 |
当前 key 和 value 都是字节序列。字符串重载使用 UTF-8 编码 key；value 编码由调用方决定。
持久化布局
每个 keyspace 存在于数据库目录的 kv/keyspaces/<name>/ 下：
<root>/
kv/
keyspaces/
devices/
wal/
active.SDBKVWAL
snapshots/
00000000000000000001.SDBKVSNP
segments/
00000000000000000002.SDBKVSEG
KV 使用独立文件格式，不复用时序写入路径的 .SDBWAL 或 .SDBSEG。因此新增 KV 不改变已有 measurement 的 WAL、Segment、Catalog 二进制格式。
当前 state 写格式为 v5：有序 key 使用每 16 条强制 restart 的前缀压缩，entry CRC 仍覆盖解压后的完整 key 与 value。读取路径兼容 v1-v4；写出 v5 后，旧版 SonnetDB 二进制不能直接降级打开该 state，降级前应使用当前版本导出/备份并由目标版本重新导入。
关系表 MVP 基于同一套 KV 存储能力实现，但目录独立放在 tables/rowstore/<table-name-hex>/，schema 放在 tables/tables.tblschema。这些文件同样不改变时序 measurement 的二进制格式。
崩溃恢复
启动时恢复顺序：
- 加载最新
segments/*.SDBKVSEG或snapshots/*.SDBKVSNP。 - 回放
wal/active.SDBKVWAL中高于该版本的记录。 - 遇到 WAL 尾部截断、header CRC 或 payload CRC 不匹配时停止在最后一条合法记录。
KV WAL v3 增加 mixed put/delete MutationBatch record。batch 由单个 header CRC + payload CRC 保护，恢复时只会整批应用或整批忽略；v1/v2 仍可读取，旧 active WAL 在打开时会先密封，再创建 v3 active WAL。该原子性边界仅限单个 keyspace，不包含跨 table/keyspace 事务。
KvOptions.SyncWalOnEveryWrite 默认开启，适合 metadata 和小对象场景。高吞吐场景可以关闭每写 fsync，再由调用方按需通过快照或压实形成更稳定的恢复点。
当前不做
- 不提供 KV SQL 语法。
- 不提供 MVCC 事务和跨 keyspace 事务。
- 不提供独立 TCP / HTTP KV 服务。
- 不引入 SharpDB 文件格式或 NetMQ 协议。