# tsbs_query_modifier

**Repository Path**: KiweeL/tsbs_query_modifier

## Basic Information

- **Project Name**: tsbs_query_modifier
- **Description**: 用于修改 TSBS `tsbs_generate_queries` 生成的 `.dat` 查询文件中的 SQL 时间范围，适合在 TDengine TSBS 与 KaiwuDB TSBS 对比测试前，对查询时间窗口进行统一和重写。

- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-11
- **Last Updated**: 2026-03-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# tsbs_query_modifier

用于修改 TSBS `tsbs_generate_queries` 生成的 `.dat` 查询文件中的 SQL 时间范围，适合在 TDengine TSBS 与 KaiwuDB TSBS 对比测试前，对查询时间窗口进行统一和重写。

## 背景

在实际测试中，TSBS 原始查询文件存在以下问题：

1. `tsbs_generate_queries` 生成的查询 SQL 往往要求时间跨度大于 12 小时，而场景三、四的实际数据只有约 3 分钟，导致部分原本 8 小时跨度的查询出现空查询。
2. 不同时间范围会显著影响查询性能。如果 TDengine 和 KaiwuDB 使用的查询 SQL 时间范围不同，横向对比结果说服力不足。
3. 生成的 `.dat` 文件并不都是纯文本，尤其 KaiwuDB 的文件中混合了 Go `gob` 二进制编码和 SQL 文本。直接用编辑器修改后再保存，容易破坏编码格式，导致 TSBS 无法读取。

本工具用于解决这 3 个问题。

## 功能

1. 修改单个 `.dat` 文件中所有 SQL 的时间范围。
   保留每条 SQL 原始时间跨度，只重写起始时间，并据此重新计算结束时间。
2. 同时处理 TDengine TSBS 和 KaiwuDB TSBS 生成的两个 `.dat` 文件。
   相同索引的 SQL 会被改写为一致的时间范围，便于公平对比。
3. 支持指定“起始时间可选范围”。
   每条 SQL 的新起始时间会在该范围内随机生成，结束时间按原始跨度推导。

例如针对场景三、四，可将起始时间范围设置为 `2016-01-01T00:00:00Z` 到 `2016-01-01T00:03:00Z`，保证所有查询都命中实际存在的数据时间段。

## 支持的文件类型

- TDengine TSBS 查询文件
  文件中 SQL 为文本，时间条件形如 `ts >= 1451606407646 AND ts < 1451610007646`
- KaiwuDB TSBS 查询文件
  文件内部为 Go `gob` 编码，SQL 中时间条件形如 `k_timestamp >= '2016-01-01 22:34:21.773' AND k_timestamp < '2016-01-02 06:34:21.773'`

程序会根据文件内容自动判断处理方式。

## 工作原理

- 保留每条 SQL 原始时间跨度不变
- 仅重新生成起始时间
- 结束时间 = 新起始时间 + 原始时间跨度
- 在双文件模式下，共享同一份“索引 -> 时间范围”映射
  这意味着两个文件中相同索引的 SQL 会得到相同的新时间范围

注意：`-start-time` 和 `-end-time` 约束的是“新起始时间”的随机范围，不是查询结束时间的硬边界。若某条 SQL 原始跨度较长，则新结束时间可能晚于 `-end-time`。

## 环境要求

- Go 环境，用于执行 `go run`

当前仓库未包含 `go.mod`，可直接使用单文件方式运行：

```bash
go run modify_time_range.go [flags]
```

也可以自行编译：

```bash
go build -o tsbs_query_modifier modify_time_range.go
```

## 使用方法

### 1. 修改单个文件

```bash
go run modify_time_range.go \
  -input queries.dat \
  -output queries.modified.dat \
  -start-time 2016-01-01T00:00:00Z \
  -end-time 2016-01-01T00:03:00Z
```

适用于只处理一个 TDengine 或 KaiwuDB 查询文件的场景。

### 2. 同时修改两个文件，并保证相同索引 SQL 的时间范围一致

```bash
go run modify_time_range.go \
  -input1 tdengine_queries.dat \
  -output1 tdengine_queries.modified.dat \
  -input2 kaiwudb_queries.dat \
  -output2 kaiwudb_queries.modified.dat \
  -start-time 2016-01-01T00:00:00Z \
  -end-time 2016-01-01T00:03:00Z
```

建议在对比 TDengine 与 KaiwuDB 时使用这一模式。两个文件必须在同一次命令执行中处理，才能保证索引同步。

## 参数说明

| 参数 | 说明 |
| --- | --- |
| `-input` | 单文件模式输入文件 |
| `-output` | 单文件模式输出文件 |
| `-input1` | 双文件模式下的第一个输入文件 |
| `-output1` | 双文件模式下的第一个输出文件 |
| `-input2` | 双文件模式下的第二个输入文件 |
| `-output2` | 双文件模式下的第二个输出文件 |
| `-start-time` | 新起始时间随机范围下界，格式为 RFC3339 |
| `-end-time` | 新起始时间随机范围上界，格式为 RFC3339 |

默认值：

```text
-start-time 2016-01-01T00:00:00Z
-end-time   2016-01-02T00:00:00Z
```

## 时间格式要求

命令行时间参数必须使用 RFC3339 格式，例如：

- `2016-01-01T00:00:00Z`
- `2016-01-01T08:00:00+08:00`

## 适用示例

### 场景三、四：数据只有 3 分钟

如果原始 SQL 存在 8 小时或更长的时间跨度，但真实数据只覆盖 `2016-01-01 00:00:00` 到 `2016-01-01 00:03:00`，则可执行：

```bash
go run modify_time_range.go \
  -input1 td.dat \
  -output1 td.modified.dat \
  -input2 kw.dat \
  -output2 kw.modified.dat \
  -start-time 2016-01-01T00:00:00Z \
  -end-time 2016-01-01T00:03:00Z
```

这样每条 SQL 的新起始时间都会落在 3 分钟数据窗口内，从而避免大量空查询，同时保持原始查询跨度不变。

## 输出说明

- 工具不会覆盖原始输入文件
- 修改结果写入新的输出文件
- 日志会输出处理成功或失败信息

## 注意事项

1. 双文件同步依赖“查询顺序一致”。
   如果两个 `.dat` 文件中的 SQL 顺序不一致，即使索引相同，也无法保证它们逻辑上对应同一条查询。
2. 本工具按源码中的固定模式匹配 SQL 时间条件。
   若查询格式与当前正则不一致，相关 SQL 不会被替换。
3. `HumanDescription` 中的时间也会同步改写，用于保持描述信息与 SQL 时间一致。
4. 仓库当前代码中虽然存在目录处理函数，但命令行入口未暴露目录批量处理参数；目前文档中的正式用法仅包含单文件和双文件两种模式。

## 实现说明

- TDengine 文件按文本方式读取和写回
- KaiwuDB 文件按 Go `gob` 编码逐条解码、修改后再重新编码
- 通过程序化读写避免手工编辑 `.dat` 文件导致编码损坏

## 文件说明

- [modify_time_range.go](/data/tsbs_query_modifier/modify_time_range.go)
  主程序，包含参数解析、文件识别和时间范围改写逻辑