#JIA2JIA2/moonbitRealTimeDB

#特性

#核心功能

• 基本 CRUD：set/get/delete/contains/size/keys/values/entries
• 订阅机制：watch(key)、watch_prefix(prefix)、watch_all 三种订阅
• TTL 过期：基于逻辑时钟，支持 advance/expire_now
• 批量操作：mset/mget/mdelete
• 原子操作：incr/decr、touch/persist、setnx
• O(1) 取消订阅：订阅者用 Map 索引
• 回调安全：回调内 unwatch 安全

#高可用功能

• 事务支持：begin/commit/rollback、死锁检测、超时处理
• 持久化：WAL 预写日志、快照保存、崩溃恢复
• 监控指标：QPS、延迟、内存使用、Prometheus 集成
• 连接池：连接复用、健康检查、空闲超时

#高性能数据管道

• 零拷贝批量导入：≥500,000 条/秒
• 流式处理：P99 延迟 ≤100μs
• 内存池复用：复用率 ≥80%
• 批量订阅聚合：100ms 窗口
• 数据压缩：gzip/zstd/lz4
• 转换管道：Map/Filter/FlatMap/KeyBy/Reduce
• 优先级调度：1~10 级优先级
• 并行导入：1~16 并行度
• 自适应批处理：动态调整批次大小
• 零拷贝读取：内存映射、引用返回

#二级索引

• Hash 索引：等值查询 O(1)
• B+树索引：范围查询 O(log n)
• 前缀树索引：前缀匹配 O(m)
• 复合索引：最左前缀原则
• 索引选择器：智能选择最优索引
• 查询引擎：等值/范围/前缀查询
• 统计收集：基数、碎片率、命中率
• 碎片整理：定期优化索引存储

#实时数据流引擎

• 窗口聚合：滚动/滑动/会话窗口
• 聚合函数：Count/Sum/Avg/Max/Min
• 过滤订阅：等值/范围/前缀/正则
• 状态存储：内存优先、TTL 过期
• 检查点服务：Exactly-Once 语义
• 水位线服务：乱序容忍、迟到数据处理
• 背压控制：流量整形、优先级调度

#扩展模块

• 分布式集群：节点管理、分片、路由
• 多租户：租户隔离与配额
• SQL 引擎：语句解析、查询优化与执行；SELECT 支持过滤、投影、排序、 LIMIT/OFFSET、DISTINCT、GROUP BY/HAVING、聚合函数与 CASE WHEN，DELETE 支持按 WHERE 条件删除记录
• 数据湖集成：湖仓同步
• 跨集群复制：副本管理与同步
• 特征存储：在线特征读写
• GraphQL：GraphQL 查询服务
• 版本控制：快照、分支、合并、时间点查询
• 时间序列：降采样、保留策略、连续查询
• 向量检索：高维向量存储、IVF 倒排索引、元数据过滤、最近邻检索与向量删除

#安装

import {
  "JIA2JIA2/moonbitRealTimeDB/src/core@0.1.0",
}

import { "JIA2JIA2/moonbitRealTimeDB/src/api" }

let db = @api.DB::new()
let idx = @api.IndexManager::new()

#快速开始

let db = @core.DB::new()

// 基本操作
db.set("key", @core.Str("value"))
let value = db.get("key") // Some(@core.Str("value"))

// 带 TTL 的设置
db.set("temp", @core.Int(42), ttl=10)

// 订阅
let _ = db.watch("key", fn(e) {
  println(e.to_string())
})
db.set("key", @core.Str("new")) // 触发回调

// 推进时间，清理过期键
let _ = db.advance(10)

#SQL 查询与删除

let executor = @sql_engine.create_query_executor()
executor.set_db(Some(db))

// SELECT：返回结果行
let select = @sql_engine.parse_sql("SELECT name FROM users WHERE age > 18").unwrap()
let rows = executor.execute_statement(select)

// DELETE：返回被删除记录的键
let delete = @sql_engine.parse_sql("DELETE FROM users WHERE age < 18").unwrap()
let deleted = executor.execute_statement(delete)

#API 文档

#值类型

• Str(String) - 字符串
• Int(Int) - 整数
• Float(Double) - 浮点数
• Bool(Bool) - 布尔值
• Null - 空值
• Arr(Array[Value]) - 数组
• Map(Map[String, Value]) - 映射

#核心方法

#订阅方法

#批量操作

#原子操作

#事务支持

#持久化

#监控指标

#连接池

#二级索引 API

#流引擎 API

#SQL 引擎 API

#测试

moon test           # 运行全部测试（当前 399 个）
moon coverage analyze > uncovered.log   # 查看未覆盖代码

#架构设计

#模块结构

moonbitRealTimeDB/
├── moon.mod                  # 模块定义（名称/版本/依赖）
└── src/                      # 全部代码统一目录
    ├── core/                 # 核心数据库引擎（realtime_db.mbt + 测试）
    ├── api/                  # 统一 API 门面包
    ├── transaction/          # 事务支持
    ├── persistence/          # 持久化（WAL + 快照）
    ├── monitor/              # 监控指标
    ├── connection/           # 连接池
    ├── perf_pipeline/        # 高性能数据管道
    ├── index/                # 二级索引
    ├── stream_engine/        # 实时数据流引擎
    ├── cluster/              # 分布式集群
    ├── multi_tenant/         # 多租户管理
    ├── sql_engine/           # SQL 查询引擎
    ├── lake_integration/     # 数据湖集成
    ├── replication/          # 跨集群复制
    ├── feature_store/        # 特征存储
    ├── graphql/              # GraphQL 接口
    ├── versioning/           # 数据版本控制
    ├── timeseries/           # 时间序列引擎
    ├── vector_search/        # 向量检索引擎
    └── cmd/main/             # CLI 入口

#统一 API 入口

import { "JIA2JIA2/moonbitRealTimeDB/src/api" }

let db = @api.DB::new()
let idx = @api.IndexManager::new()

门面包仅重导出核心类型与各模块的主 Manager 类型，避免跨模块同名类型 （如 Snapshot、Pipeline）冲突。需要更多类型时按需直接导入对应模块。

#设计原则

1. 非线程安全：单线程模型，如需并发访问需外部加锁
2. 逻辑时钟：TTL 基于逻辑时钟，用 advance 推进时间、expire_now 清理过期键
3. 事件驱动：所有数据变更都通过事件通知订阅者
4. WAL 优先：所有写操作先写入 WAL，再更新内存

#开发规范

#包与文件组织

#moon.pkg 依赖约定

import {
  "JIA2JIA2/moonbitRealTimeDB/src/core" @realtime_db,
  "JIA2JIA2/moonbitRealTimeDB/src/persistence",
}

#代码风格

///|
/// 类型文档注释
pub(all) struct MyType {
  /// 字段文档
  field : String
}

///|
/// 函数文档注释
pub fn MyType::my_method(self : MyType, param : String) -> Result[String, MyError] {
  // 实现
}

#常用命令

moon check          # 类型检查（CI 门禁，要求 0 error / 0 warning）
moon fmt            # 格式化代码（moon fmt --check 只检查不改动）
moon test           # 运行测试
moon info           # 重新生成 pkg.generated.mbti
moon build          # 构建
moon run src/cmd/main -- "help"   # 运行 CLI（每条命令作为一个带引号参数）

#性能指标

#许可证