gotidb/pkg/engine/bolt/README.md

Bolt 存储引擎

设计原则

1. 文件大小限制：每个源代码文件不超过300行，以保持代码的可维护性和可读性。

2. 文件组织：

   • bolt.go - 主要结构和基本方法
   • bolt_query.go - 查询相关实现
   • bolt_utils.go - 工具函数和辅助方法
   • bolt_maintenance.go - 维护相关方法

3. 职责分离：

   • 每个文件都有明确的职责
   • 相关的功能被组织在同一个文件中
   • 避免文件之间的循环依赖

主要功能

1. 基本操作

   • 创建和初始化引擎
   • 打开和关闭数据库
   • 写入数据点

2. 查询功能

   • 最新值查询
   • 原始数据查询
   • 聚合查询
   • 值持续时间查询

3. 维护功能

   • 数据压缩
   • 空序列清理
   • 统计信息管理

数据组织

1. Bucket 结构

   • series_* - 存储序列数据
   • meta - 存储元数据
   • index - 存储序列索引

2. 键值设计

   • 序列数据：时间戳（8字节）作为键
   • 元数据：预定义的键（如 "stats"）
   • 索引：序列ID作为键和值

性能考虑

1. 并发控制

   • 使用读写锁控制并发访问
   • 细粒度的事务管理

2. 内存管理

   • 复用对象和缓冲区
   • 批量操作优化

3. 磁盘优化

   • 定期压缩
   • 空间回收

使用示例

// 创建引擎实例
config := &engine.BoltEngineConfig{
    Path: "/path/to/data.db",
}
eng, err := NewBoltEngine(config)
if err != nil {
    log.Fatal(err)
}

// 打开引擎
if err := eng.Open(); err != nil {
    log.Fatal(err)
}
defer eng.Close()

// 写入数据
points := []engine.DataPoint{
    {
        Timestamp: time.Now().UnixNano(),
        Value:     42.0,
        Labels:    map[string]string{"sensor": "temp"},
    },
}
if err := eng.Write(context.Background(), points); err != nil {
    log.Fatal(err)
}

注意事项

1. 在添加新功能时，确保遵循文件大小限制
2. 保持一致的错误处理和日志记录方式
3. 定期运行维护操作（压缩和清理）
4. 监控引擎统计信息以优化性能