# 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) 文件。