TSDB 专享版以集群为服务单元，在集群内使用 Database 隔离业务数据，以 Table 组织同类时序数据。应用通过访问令牌获得对指定 Database 或 Table 的读写权限。

数据层级

1集群
2└── Database
3    └── Table（Line Protocol 中的 measurement）
4        ├── Tag
5        ├── Field
6        └── time

• Database：业务数据的一级隔离边界，也可以配置默认 Retention。
• Table / measurement：一类测量数据，例如 cpu 或 temperature。
• Tag：字符串维度，例如主机、设备或地域，用于标识、过滤和分组数据。
• Field：随时间变化的测量值，支持字符串、有符号整数、无符号整数、浮点数和布尔值。
• time：数据点时间。写入时可以指定秒、毫秒、微秒或纳秒精度。

示例：

1cpu,host=server01,region=cn-north usage=0.64,status="ok" 1717420800000000000

其中，cpu 是 Table，host 和 region 是 Tag，usage 和 status 是 Field，最后的整数是时间戳。

Series 与 Tag 设计

一张 Table 的全部 Tag 列共同构成 series key。相同 Tag 组合表示同一条时间线，时间戳用于定位这条时间线上的数据点。

设计 Tag 时请注意：

• 选择经常用于筛选和分组、且取值集合相对稳定的维度。
• 不要把请求 ID、随机数、时间戳等高变化值作为 Tag。
• 新增 Tag 会扩展 series key；Tag 数量和 Tag 值组合越多，series 基数越高。
• 需要做数值计算或保存随时间变化内容的属性应使用 Field。

Tag 顺序影响查询效率

Table 的 Tag 列顺序在建表时确定：显式建表时按声明顺序，首次写入自动建表时按 Line Protocol 中 Tag 的出现顺序；之后新增的 Tag 排在已有 Tag 之后。数据按 Tag 顺序加时间排序组织，查询按靠前的 Tag 精确筛选时能更快跳过无关数据。

设计 Tag 顺序时建议：

• 把区分度最高、查询中最常用于精确筛选的 Tag 放在第一位。例如 IoT 场景把 deviceId 作为第一个 Tag，按设备查询时即可利用它快速筛选数据。
• 取值较少、主要用于分组统计的维度（如地域、机房）放在后面。
• Tag 顺序建表后不可调整，请在设计阶段确定，并优先通过显式建表固定顺序。

Schema-on-write

表结构不要求预先定义。首次写入新的 measurement 时，服务端自动创建对应 Table；首次出现新的 Tag 或 Field 时，服务端自动增加列并推断类型。

首次写入创建 Table 后，新表通常在约 5 秒后可以查询，实际时间可能受集群运行状态影响。请等待约 5 秒再进行首次查询；向已有 Table 写入不受影响。

列类型建立后，同名 Field 必须持续使用兼容类型，类型冲突的写入会被拒绝。生产环境建议提前确定 Table、Tag 和 Field 设计，并通过 Database / Table 管理 API 或 tsdb-cli 显式创建关键资源，避免错误写入形成非预期 Schema。

用户资源名称需要满足以下规则：

• 仅支持 ASCII 字母、数字、下划线 _ 和连字符 -。
• 首字符必须是字母或数字。
• 长度不超过 64 字节。
• Table 权限使用 Database.Table 表达，因此名称不能包含点号 .。

资源上限

超过 Database、Table 或列数量限制时，相关创建或写入请求返回 422。进入删除流程但尚未清理完成的资源仍可能占用额度。

Retention

Retention 决定数据保留时间：

• Database 级 Retention 是该 Database 的默认保留期。
• Table 级 Retention 覆盖 Database 级设置。
• Table 未设置 Retention 时继承 Database；Database 未设置 Retention 时永久保留。
• tsdb-cli 中使用 none 清除显式设置：Database 恢复永久保留，Table 恢复继承 Database。
• Retention 支持小时（h）、天（d）、周（w）、月（mo）和年（y）的组合，例如 30d、2w3d 或 1y6mo。

缩短 Retention 后，更早的数据会进入删除范围。修改前请确认业务、审计和合规要求。

访问令牌与权限

业务访问令牌可以授予三类权限：

manage 用于 Database 和 Table 等资源管理，不自动代替 Token 管理动作。创建业务令牌时，授予的权限不能超出当前令牌自身拥有的范围。

tsdb-cli 示例：

1# 对 metrics Database 只读
2tsdb-cli token create --name dashboard_reader \
3  --permission 'db:metrics:read'
4
5# 只允许读写 metrics.cpu Table
6tsdb-cli token create --name cpu_writer \
7  --permission 'table:metrics.cpu:read,write'
8
9# 只允许创建和查看业务访问令牌
10tsdb-cli token create --name token_operator \
11  --permission 'token:*:create,read'

创建或重新生成令牌时，明文只返回一次。重新生成成功后旧令牌立即失效；请先评估应用切换影响。

最小权限建议

• 写入应用只授予目标 Database 或 Table 的 write；需要回读验证时再增加 read。
• 查询应用只授予目标 Database 或 Table 的 read。
• 资源管理自动化按需授予 manage，Token 管理自动化单独授予 Token 动作。
• 为生产、测试和临时任务创建不同令牌，并为临时令牌设置合理过期时间。
• 不使用管理员访问令牌作为应用长期凭证。