160 lines
4.5 KiB
Markdown
160 lines
4.5 KiB
Markdown
# GoTiDB - 轻量级时序数据库
|
||
|
||
GoTiDB 是一个用 Go 语言编写的轻量级时序数据库，专为高效存储和查询时间序列数据而设计。它提供了简单而强大的 API，支持高吞吐量的数据写入和灵活的查询功能。
|
||
|
||
## 功能特点
|
||
|
||
- **高效存储**: 使用基于文件的存储引擎，针对时间序列数据进行了优化
|
||
- **灵活查询**: 支持原始数据查询、最新值查询和聚合查询
|
||
- **标签索引**: 使用多维标签索引，支持按标签快速过滤数据
|
||
- **时间窗口**: 高效的时间窗口索引，加速时间范围查询
|
||
- **数据压缩**: 支持自动压缩旧数据，节省存储空间
|
||
- **数据保留**: 自动清理过期数据，支持配置保留策略
|
||
- **并发安全**: 支持多个并发读写操作
|
||
- **可扩展**: 模块化设计，易于扩展和定制
|
||
|
||
## 安装
|
||
|
||
```bash
|
||
go get git.pyer.club/kingecg/gotidb
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
以下是一个简单的示例，展示如何使用 GoTiDB：
|
||
|
||
```go
|
||
package main
|
||
|
||
import (
|
||
"context"
|
||
"fmt"
|
||
"time"
|
||
|
||
"git.pyer.club/kingecg/gotidb/pkg/engine"
|
||
_ "git.pyer.club/kingecg/gotidb/pkg/engine/file" // 导入文件引擎
|
||
)
|
||
|
||
func main() {
|
||
// 创建引擎配置
|
||
config := &engine.FileEngineConfig{
|
||
DataDir: "/path/to/data",
|
||
SegmentSize: 1024 * 1024, // 1MB
|
||
MaxSegments: 10,
|
||
WriteBufferSize: 1000,
|
||
}
|
||
|
||
// 创建引擎
|
||
e, err := engine.NewEngine(engine.EngineConfig{
|
||
Type: "file",
|
||
FileConfig: config,
|
||
})
|
||
if err != nil {
|
||
fmt.Printf("Failed to create engine: %v\n", err)
|
||
return
|
||
}
|
||
|
||
// 打开引擎
|
||
if err := e.Open(); err != nil {
|
||
fmt.Printf("Failed to open engine: %v\n", err)
|
||
return
|
||
}
|
||
defer e.Close()
|
||
|
||
// 写入数据
|
||
points := []engine.DataPoint{
|
||
{
|
||
Timestamp: time.Now().UnixNano(),
|
||
Value: 42.0,
|
||
Labels: map[string]string{
|
||
"host": "server1",
|
||
"region": "us-west",
|
||
},
|
||
},
|
||
}
|
||
|
||
ctx := context.Background()
|
||
if err := e.Write(ctx, points); err != nil {
|
||
fmt.Printf("Failed to write points: %v\n", err)
|
||
return
|
||
}
|
||
|
||
// 查询数据
|
||
query := engine.Query{
|
||
Type: engine.QueryTypeRaw,
|
||
StartTime: time.Now().Add(-time.Hour).UnixNano(),
|
||
EndTime: time.Now().UnixNano(),
|
||
Tags: map[string]string{
|
||
"host": "server1",
|
||
},
|
||
}
|
||
|
||
result, err := e.Query(ctx, query)
|
||
if err != nil {
|
||
fmt.Printf("Failed to query: %v\n", err)
|
||
return
|
||
}
|
||
|
||
// 处理查询结果
|
||
for _, series := range result {
|
||
fmt.Printf("Series ID: %s\n", series.SeriesID)
|
||
for _, point := range series.Points {
|
||
fmt.Printf(" Timestamp: %s, Value: %f\n",
|
||
time.Unix(0, point.Timestamp).Format(time.RFC3339),
|
||
point.Value)
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
更多示例请参考 [examples](./examples) 目录。
|
||
|
||
## 配置选项
|
||
|
||
### 文件引擎配置
|
||
|
||
| 选项 | 描述 | 默认值 |
|
||
|------|------|--------|
|
||
| DataDir | 数据存储目录 | 必填 |
|
||
| SegmentSize | 段文件大小限制（字节） | 64MB |
|
||
| MaxSegments | 最大段文件数量 | 100 |
|
||
| WriteBufferSize | 写入缓冲区大小（数据点数） | 1000 |
|
||
| IndexCacheSize | 索引缓存大小（字节） | 32MB |
|
||
| UseCompression | 是否启用压缩 | false |
|
||
| CompressionLevel | 压缩级别（0-9） | 6 |
|
||
| CompactThreshold | 触发压缩的阈值（段文件数量比例） | 0.7 |
|
||
| MaxOpenFiles | 最大打开文件数 | 100 |
|
||
| SyncWrites | 是否同步写入（更安全但更慢） | false |
|
||
| RetentionPeriod | 数据保留时间 | 30d |
|
||
|
||
## 性能考虑
|
||
|
||
- **写入性能**: 使用写入缓冲区和异步刷新可以提高写入性能
|
||
- **查询性能**: 使用标签索引和时间窗口索引加速查询
|
||
- **存储效率**: 启用压缩可以减少存储空间占用，但会增加 CPU 使用率
|
||
- **内存使用**: 调整索引缓存大小可以平衡内存使用和查询性能
|
||
- **文件描述符**: 调整最大打开文件数以适应系统限制
|
||
|
||
## 架构
|
||
|
||
GoTiDB 的核心架构包括：
|
||
|
||
1. **引擎接口**: 定义了存储引擎的通用接口
|
||
2. **文件引擎**: 基于文件系统的存储引擎实现
|
||
3. **索引管理**: 标签索引和时间窗口索引
|
||
4. **查询处理**: 原始查询、最新值查询和聚合查询
|
||
5. **后台任务**: 数据压缩和过期数据清理
|
||
|
||
## 贡献
|
||
|
||
欢迎贡献代码、报告问题或提出改进建议！请遵循以下步骤：
|
||
|
||
1. Fork 项目
|
||
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
|
||
3. 提交更改 (`git commit -m 'Add some amazing feature'`)
|
||
4. 推送到分支 (`git push origin feature/amazing-feature`)
|
||
5. 创建 Pull Request
|
||
|
||
## 许可证
|
||
|
||
本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。 |