本教程演示从创建集群到写入和查询第一条时序数据的基本流程。

前提条件

• 已创建 TSDB 专享版集群，集群状态为“运行中”。
• 已准备一台能访问集群内网地址的计算实例。
• 已从集群详情页获取内网访问地址、端口和管理员访问令牌；首次获取令牌的方法见管理管理员访问令牌。
• 已安装 tsdb-cli。

下载、校验和安装方法请查看下载与安装 CLI 工具。

1. 配置连接信息

将以下占位值替换为集群详情页显示的真实信息：

1export TSDB_HOST_URL='http://<内网访问地址>:<端口>'
2export TSDB_AUTH_TOKEN='<管理员访问令牌>'

本教程使用环境变量，便于连续执行多条命令。单次调用 tsdb-cli 时，也可以通过 --host 和 --token 参数传入连接信息。不要把访问令牌写入代码仓库、镜像或日志。

2. 创建数据库

创建保留期为 30 天的数据库：

1tsdb-cli database create --retention-period 30d quickstart

3. 创建业务访问令牌

为示例应用创建仅能读写 quickstart 数据库的业务访问令牌：

1tsdb-cli token create --name quickstart_app \
2  --permission 'db:quickstart:read,write'

命令只在本次响应中显示令牌明文。请立即保存，然后用该令牌替换环境变量中的管理员访问令牌：

1export TSDB_AUTH_TOKEN='<业务访问令牌>'

4. 写入数据

1tsdb-cli write -d quickstart \
2  'cpu,host=server01,region=cn-north usage=0.64'

此数据包含表名 cpu、两个 Tag host 和 region，以及一个 Field usage。未显式提供时间戳时，服务端使用接收数据时的时间。

如果 cpu Table 尚不存在，本次写入会自动创建 Table，新表通常在约 5 秒后可以查询，实际时间可能受集群运行状态影响。因此，首次建表后先等待 5 秒再查询：

1sleep 5

该等待只适用于首次写入创建 Table 的场景；向已有 Table 写入不受影响。

5. 查询数据

1tsdb-cli query -d quickstart \
2  'SELECT time, host, region, usage FROM cpu ORDER BY time DESC LIMIT 10'

如果命令返回刚写入的数据，说明数据库、令牌和网络配置正确。如果查询失败或结果为空，请依次检查网络能否连通集群地址、令牌是否具有 quickstart 数据库权限、首次建表后是否已等待约 5 秒；更多排查方法见常见问题。

6. 查看监控

进入集群的“监控”页面，选择与刚才写入相对应的时间范围，确认写入请求或写入行数等指标已有数据。

下一步

• 使用应用 SDK 接入前，请查看SDK 使用说明。
• 了解 Line Protocol 和写入参数，请查看使用 Line Protocol 写入数据。
• 为生产应用配置最小权限，请查看数据模型与权限。