Skip to content

k.DB.sequenceDb ​

站点本地顺序键值存储 — 高性能数字主键序列与日志数据库

适用上下文前置条件典型用途
服务端 KScript(k.api、<script env="server">、定时任务)开箱即用,无需表结构或连接串;路径须满足 validPath,不替代关系型 SQL(sqlite)或后台表(indexedDb)顺序追加日志、事件流与时间序列记录,按 1-based 数字主键及范围检索过滤

快速上手 ​

打开顺序数据库文件,按 1-based 自增主键写入日志、范围检索并清理:

js
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 — 数据库实例。

js
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。

js
k.DB.sequenceDb.deleteDb("app_logs")
k.DB.sequenceDb.deleteDb("analytics", "events")

validPath(part) ​

校验相对路径片段或数据库名称是否合法。仅允许字母、数字、-、_、.、\、/、:,且必须至少包含一个字母或数字。

参数类型必填说明
partstring是要校验的路径片段或名称

返回值:boolean。合法返回 true,否则返回 false。

js
const ok = k.DB.sequenceDb.validPath("audit-events_2026")
const bad = k.DB.sequenceDb.validPath("...")

SequenceDb 属性与方法 ​

firstKey / lastKey ​

只读属性,分别返回当前数据库中的最小数字键与最大数字键;数据库为空时返回 0。

参数:无。

返回值:number。最小或最大数字键;空库为 0。

js
const db = k.DB.sequenceDb.openDb("app_logs")
const first = db.firstKey
const last = db.lastKey

add(obj) / add(key, obj) ​

向数据库追加一条记录并返回生成的数字键(自动主键从 1 开始递增)。

重载参数说明
add(obj)obj: any自动分配 1-based 自增整数主键并写入记录
add(key, obj)key: number, obj: any使用指定的递增整数主键写入记录;若打开库时设置了 keyFieldName 且 key > 0,会自动在记录中写入该字段

返回值:number — 写入后的记录主键。

js
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) ​

根据数字主键读取单条记录。

参数类型必填说明
idnumber是记录主键

返回值:any — 记录对象;记录不存在或已被删除时返回 null。

js
const item = db.get(2)

range(lowBound, highBound, ascending) ​

按数字主键闭区间返回记录列表。

参数类型必填说明
lowBoundnumber是起始主键下界
highBoundnumber是结束主键上界
ascendingboolean是true 为升序,false 为降序

返回值:any[] — 区间内的记录数组。

js
const ascItems = db.range(1, 100, true)
const descItems = db.range(1, 100, false)

count(lowBound, highBound) ​

统计指定主键区间内的记录条数。

参数类型必填说明
lowBoundnumber是起始主键下界
highBoundnumber是结束主键上界

返回值:number — 区间内的记录数量。

js
const total = db.count(1, 100)

update(key, obj) ​

按数字主键更新整条记录内容。

参数类型必填说明
keynumber是要更新的记录主键
objany是更新后的记录对象

返回值:void。

js
db.update(2, { level: "warn", msg: "slow-updated" })

delete(key) ​

按数字主键删除记录。

参数类型必填说明
keynumber是要删除的记录主键

返回值:void。

js
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。

js
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[] — 匹配的记录数组。

js
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。

js
const tempDb = k.DB.sequenceDb.openDb("temp_logs")
tempDb.close()
k.DB.sequenceDb.deleteDb("temp_logs")

注意事项 ​

  1. 命名规则:相对 path 与 name 须满足 validPath 字符集限制,否则抛出参数校验异常。
  2. 主键规则:自动分配主键从 1 开始;使用 add(key, obj) 时,手动传入的 key 须保持递增整数顺序。
  3. 服务端执行:仅在站点的 env="server" 环境(API、CodeBlock、定时任务等)中使用。

TypeScript 定义 ​

ts
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;
}

相关文档 ​