k.DB.sequenceDb
站点本地顺序键值存储 — 高性能数字主键序列与日志数据库
| 适用上下文 | 前置条件 | 典型用途 |
|---|---|---|
服务端 KScript(k.api、<script env="server">、定时任务) | 开箱即用,无需表结构或连接串;路径须满足 validPath,不替代关系型 SQL(sqlite)或后台表(indexedDb) | 顺序追加日志、事件流与时间序列记录,按 1-based 数字主键及范围检索过滤 |
快速上手
打开顺序数据库文件,按 1-based 自增主键写入日志、范围检索并清理:
k.api.post(() => {
const db = k.DB.sequenceDb.openDb("demo_logs")
const id1 = db.add({ level: "info", msg: "started" })
const id2 = db.add({ level: "error", msg: "timeout" })
const item = db.get(id2)
const matches = db.findAll((row) => row.level === "error")
const total = db.count(id1, id2)
k.DB.sequenceDb.deleteDb("demo_logs")
return { firstKey: id1, lastKey: id2, item, matchesCount: matches.length, total }
})方法速查
| 方法 / 属性 | 说明 | 返回值 |
|---|---|---|
openDb(name) / openDb(path, name, keyFieldName?) | 打开或创建站点本地 .data 顺序数据库(进程内按路径复用) | SequenceDb |
deleteDb(name) / deleteDb(path, name) | 关闭句柄、清除缓存并删除 .data 文件 | void |
validPath(part) | 校验子目录路径或数据库名称是否合法 | boolean |
db.firstKey / db.lastKey | 只读最小/最大数字主键(空库返回 0) | number |
db.add(obj) / db.add(key, obj) | 追加记录并返回 1-based 自增主键或指定递增主键 | number |
db.get(id) | 按数字主键读取单条记录(不存在返回 null) | any |
db.range(lowBound, highBound, ascending) | 按闭区间主键范围返回记录数组 | any[] |
db.count(lowBound, highBound) | 统计闭区间主键范围内的记录数量 | number |
db.update(key, obj) / db.delete(key) | 按数字主键更新或删除记录 | void |
db.find(js, ...) / db.findAll(js, ...) | 使用断言回调在全库或区间内检索匹配记录 | any / any[] |
db.close() | 释放底层文件句柄(删除请直接用 deleteDb()) | void |
打开与管理数据库(KWormDb)
openDb(name) / openDb(path, name) / openDb(path, name, keyFieldName)
打开或创建指定名称的顺序数据库文件(若文件名未以 .data 结尾会自动补全)。同一文件路径的实例会在服务端进程内复用;传入的相对子路径与名称须满足 validPath 规则。
| 重载 | 参数 | 说明 |
|---|---|---|
openDb(name) | name: string | 在站点顺序库根目录打开或创建数据库 |
openDb(path, name) | path: string, name: string | 在指定相对子目录 path 下打开或创建数据库 |
openDb(path, name, keyFieldName) | path: string, name: string, keyFieldName: string | 打开或创建数据库,并指定主键字段名;调用 add(key, obj)(且 key > 0)时会自动把 key 写入对象的 keyFieldName 字段 |
返回值:SequenceDb — 数据库实例。
const db = k.DB.sequenceDb.openDb("app_logs")
const eventsDb = k.DB.sequenceDb.openDb("analytics", "events", "eventId")deleteDb(name) / deleteDb(path, name)
关闭数据库句柄、移除缓存并删除对应的 .data 数据文件。
| 重载 | 参数 | 说明 |
|---|---|---|
deleteDb(name) | name: string | 删除根目录下的指定顺序数据库 |
deleteDb(path, name) | path: string, name: string | 删除指定相对子目录下的顺序数据库 |
返回值:void。
k.DB.sequenceDb.deleteDb("app_logs")
k.DB.sequenceDb.deleteDb("analytics", "events")validPath(part)
校验相对路径片段或数据库名称是否合法。仅允许字母、数字、-、_、.、\、/、:,且必须至少包含一个字母或数字。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
part | string | 是 | 要校验的路径片段或名称 |
返回值:boolean。合法返回 true,否则返回 false。
const ok = k.DB.sequenceDb.validPath("audit-events_2026")
const bad = k.DB.sequenceDb.validPath("...")SequenceDb 属性与方法
firstKey / lastKey
只读属性,分别返回当前数据库中的最小数字键与最大数字键;数据库为空时返回 0。
参数:无。
返回值:number。最小或最大数字键;空库为 0。
const db = k.DB.sequenceDb.openDb("app_logs")
const first = db.firstKey
const last = db.lastKeyadd(obj) / add(key, obj)
向数据库追加一条记录并返回生成的数字键(自动主键从 1 开始递增)。
| 重载 | 参数 | 说明 |
|---|---|---|
add(obj) | obj: any | 自动分配 1-based 自增整数主键并写入记录 |
add(key, obj) | key: number, obj: any | 使用指定的递增整数主键写入记录;若打开库时设置了 keyFieldName 且 key > 0,会自动在记录中写入该字段 |
返回值:number — 写入后的记录主键。
const db = k.DB.sequenceDb.openDb("app_logs")
const k1 = db.add({ level: "info", msg: "boot" })
const k2 = db.add({ level: "warn", msg: "slow" })
const keyedDb = k.DB.sequenceDb.openDb("analytics", "events", "eventId")
keyedDb.add(501, { title: "order-created" })get(id)
根据数字主键读取单条记录。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | number | 是 | 记录主键 |
返回值:any — 记录对象;记录不存在或已被删除时返回 null。
const item = db.get(2)range(lowBound, highBound, ascending)
按数字主键闭区间返回记录列表。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
lowBound | number | 是 | 起始主键下界 |
highBound | number | 是 | 结束主键上界 |
ascending | boolean | 是 | true 为升序,false 为降序 |
返回值:any[] — 区间内的记录数组。
const ascItems = db.range(1, 100, true)
const descItems = db.range(1, 100, false)count(lowBound, highBound)
统计指定主键区间内的记录条数。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
lowBound | number | 是 | 起始主键下界 |
highBound | number | 是 | 结束主键上界 |
返回值:number — 区间内的记录数量。
const total = db.count(1, 100)update(key, obj)
按数字主键更新整条记录内容。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
key | number | 是 | 要更新的记录主键 |
obj | any | 是 | 更新后的记录对象 |
返回值:void。
db.update(2, { level: "warn", msg: "slow-updated" })delete(key)
按数字主键删除记录。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
key | number | 是 | 要删除的记录主键 |
返回值:void。
db.delete(2)find(js) / find(js, lowKey, highKey, ascending?)
使用断言回调函数查找第一条匹配的记录。
| 重载 | 参数 | 说明 |
|---|---|---|
find(js) | js: Function | 遍历全库查找第一条使回调返回 true 的记录 |
find(js, lowKey, highKey, ascending?) | js: Function, lowKey: number, highKey: number, ascending?: boolean | 在 [lowKey, highKey] 区间内按指定方向(默认 false 降序)查找第一条匹配记录 |
回调返回值须为布尔值
断言回调 js(item) 必须返回布尔值(true / false;null 或 undefined 视为不匹配)。运行时会对非空返回值调用 C# Convert.ToBoolean(),因此不要返回非空字符串(如 "yes")或对象等任意 JS 真值,否则会抛出类型转换异常(FormatException / InvalidCastException)。
返回值:any — 匹配到的首条记录对象;未找到时返回 null。
const errItem = db.find((item) => item.level === "error")
const rangeItem = db.find((item) => item.level === "warn", 1, 10, true)findAll(js) / findAll(js, lowKey, highKey, ascending?)
使用断言回调函数查找所有匹配的记录。与 find() 相同,回调必须返回布尔值(true / false,或 null/undefined),切勿返回非空字符串或对象等任意 JS 真值。
| 重载 | 参数 | 说明 |
|---|---|---|
findAll(js) | js: Function | 扫描全库返回所有使回调返回 true 的记录(默认降序) |
findAll(js, lowKey, highKey, ascending?) | js: Function, lowKey: number, highKey: number, ascending?: boolean | 在 [lowKey, highKey] 区间内按指定方向(默认 false 降序)返回所有匹配记录 |
返回值:any[] — 匹配的记录数组。
const warnings = db.findAll((item) => item.level !== "info")
const ranged = db.findAll((item) => item.level !== "info", 1, 10, false)close()
释放底层数据库文件句柄。
close() 与 deleteDb() 生命周期说明
服务端会按文件路径缓存已打开的 SequenceDb 实例。若只需删除数据库,请直接调用 deleteDb(...)(会自动关闭句柄、清理缓存并删除数据文件);若对仍在使用的数据库单独调用 close() 而未随后调用 deleteDb(),后续同一请求链或缓存命中时继续读写该句柄会失败。
参数:无。
返回值:void。
const tempDb = k.DB.sequenceDb.openDb("temp_logs")
tempDb.close()
k.DB.sequenceDb.deleteDb("temp_logs")注意事项
- 命名规则:相对
path与name须满足validPath字符集限制,否则抛出参数校验异常。 - 主键规则:自动分配主键从
1开始;使用add(key, obj)时,手动传入的key须保持递增整数顺序。 - 服务端执行:仅在站点的
env="server"环境(API、CodeBlock、定时任务等)中使用。
TypeScript 定义
interface KWormDb {
openDb(name: string): SequenceDb;
openDb(path: string, name: string): SequenceDb;
openDb(path: string, name: string, keyFieldName: string): SequenceDb;
deleteDb(name: string): void;
deleteDb(path: string, name: string): void;
validPath(part: string): boolean;
}
interface SequenceDb {
firstKey: number;
lastKey: number;
add(obj: any): number;
add(key: number, obj: any): number;
get(id: number): any;
range(lowBound: number, highBound: number, ascending: boolean): any[];
update(key: number, obj: any): void;
delete(key: number): void;
count(lowBound: number, highBound: number): number;
find(js: Function): any;
find(js: Function, lowKey: number, highKey: number, ascending?: boolean): any;
findAll(js: Function): any[];
findAll(js: Function, lowKey: number, highKey: number, ascending?: boolean): any[];
close(): void;
}相关文档
- k.DB 概述
- k.DB.indexedDb — 结构化动态表
- k.DB.keyValue — 字符串键值对
- k.DB.sqlite — SQLite 关系型数据库