Table 管理
更新时间：2026-07-24
本页覆盖 Table 的列出、创建、Retention 更新和删除接口。公共请求约定、PermissionSpec 和错误处理见数据库资源管理 API。
列出 Table
列出指定 Database 中当前访问令牌可见的 Table。
Http
1GET /api/v3/configure/table?db=mydb&format=json
2Authorization: Bearer <token>Query 参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
db |
string | 是 | 目标 Database。 |
format |
string | 否 | 输出格式。 |
响应示例
JSON
1[
2 {"table": "cpu"},
3 {"table": "mem"}
4]Database 不存在或当前令牌无权访问时返回 404。具有表级权限的令牌只会看到被授权的 Table。
创建 Table
在指定 Database 中创建 Table，并声明 Tag、Field 和可选的表级 Retention。调用令牌需要所属 Database 的 manage 权限。
Http
1POST /api/v3/configure/table
2Authorization: Bearer <token>
3Content-Type: application/json请求体
JSON
1{
2 "db": "mydb",
3 "table": "cpu",
4 "tags": ["host", "region"],
5 "fields": [{"name": "usage", "type": "float64"}],
6 "retention_period": "7d"
7}| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
db |
string | 是 | Database 名称。 |
table |
string | 是 | Table 名称。 |
tags |
array | 是 | Tag 列名列表。 |
fields |
array | 是 | Field 列表。每项包含 name 和 type。 |
fields[].type |
string | 是 | utf8、int64、uint64、float64 或 bool。 |
retention_period |
string | 否 | 表级 Retention。省略时继承 Database。 |
响应
创建成功返回 200 OK，响应体为空。
同名 Field 的类型应在后续写入中保持一致。不要使用高基数、持续增长的属性作为 Tag。
更新 Table Retention
更新指定 Table 的 Retention。调用令牌需要所属 Database 的 manage 权限。
Http
1PUT /api/v3/configure/table
2Authorization: Bearer <token>
3Content-Type: application/json请求体
JSON
1{"db": "mydb", "table": "cpu", "retention_period": "3d"}| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
db |
string | 是 | Database 名称。 |
table |
string | 是 | Table 名称。 |
retention_period |
string / null | 否 | 省略表示不更新；null 表示清除表级设置并继承 Database；其他值表示设置新的表级 Retention。 |
响应
更新成功返回 200 OK，响应体为空。
缩短 Retention 前请确认历史数据的保留要求。
删除 Table
永久删除指定 Table 及其中的数据。调用令牌需要所属 Database 的 manage 权限。
Http
1DELETE /api/v3/configure/table?db=mydb&table=cpu&scope=full
2Authorization: Bearer <token>Query 参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
db |
string | 是 | Database 名称。 |
table |
string | 是 | 要删除的 Table 名称。 |
scope |
string | 是 | 当前仅支持 full，表示永久删除。 |
响应
删除成功返回 200 OK，响应体为空。
该操作不可恢复。删除前请确认没有应用继续写入或查询该 Table。
评价此篇文章