TSDB 专享版的数据写入接口兼容 InfluxDB 3 V3 Line Protocol API。应用需要使用对目标 Database 或 Table 具有 write 权限的业务访问令牌。

1POST /api/v3/write_lp

准备工作

1. 确认集群状态为“运行中”。
2. 获取集群访问地址、目标 Database 名称和业务访问令牌。
3. 确认业务令牌具有目标 Database 或 Table 的 write 权限。
4. 设计稳定的 measurement、Tag、Field 和时间戳精度。

本文示例使用连接地址与认证中定义的 TSDB_HOST_URL、TSDB_AUTH_TOKEN 和 TSDB_DATABASE_NAME 环境变量。

Line Protocol 格式

1<measurement>,<tag_key>=<tag_value> <field_key>=<field_value> <timestamp>

示例：

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

• measurement 对应 Table。
• Tag 是字符串维度，多个 Tag 使用逗号分隔。
• Field 保存测量值，至少需要一个 Field。
• 时间戳可以省略；省略时由服务端使用摄入时间。生产写入建议明确时间戳和精度。

首次写入新的 measurement、Tag 或 Field 时，服务端会按写入内容建立 Schema，后续同名 Field 需要保持类型兼容。首次写入新 measurement 会自动创建对应的 Table，新表通常在约 5 秒后可以查询；验证首次写入结果前请先等待约 5 秒，向已有 Table 写入不受影响。

请求参数

时间戳数值必须与 precision 一致。精度配置错误可能使数据落入错误时间范围。

写入单行数据

1curl -X POST \
2  "$TSDB_HOST_URL/api/v3/write_lp?db=$TSDB_DATABASE_NAME&precision=nanosecond" \
3  -H "Authorization: Bearer $TSDB_AUTH_TOKEN" \
4  --data-binary \
5  'cpu,host=server01,region=cn-north usage=0.64 1717420800000000000'

全部写入成功时返回 204 No Content，响应体为空。

批量与 gzip 压缩写入

每行表示一个数据点，多行使用换行符分隔。批量写入可以使用 gzip 压缩：

1gzip -c data.lp | curl -X POST \
2  "$TSDB_HOST_URL/api/v3/write_lp?db=$TSDB_DATABASE_NAME&precision=nanosecond" \
3  -H "Authorization: Bearer $TSDB_AUTH_TOKEN" \
4  -H 'Content-Encoding: gzip' \
5  --data-binary @-

压缩请求按解压后的大小检查请求体上限（默认 10 MiB，以集群配置为准）。收到 413 时，请减小单批数据量后再试。

处理部分写入

accept_partial=true 时，请求中合法行可以成功写入，非法行会在错误响应的 data 中返回原始行、行号和错误原因。触发 Database、Table 或列数量上限时返回 422，其他部分写入错误通常返回 400。

处理步骤：

1. 解析错误响应中的失败行列表。
2. 记录本批次哪些行已经成功、哪些行失败。
3. 修正失败行后只重试尚未成功的部分。
4. 不要在未确认成功范围时直接重放整批数据。

如果业务要求整批数据要么全部成功、要么全部拒绝，请显式设置 accept_partial=false。

常见状态码

写入建议

• 使用业务语义稳定、基数可控的 Tag，避免把请求 ID 或时间戳作为 Tag。
• 同名 Field 始终使用一致的数据类型。
• 批次大小和并发度应通过真实业务负载验证，不把单次压测结果直接作为所有场景的固定值。
• 为客户端设置超时和有上限的退避重试；重试前先判断请求是否可能已经部分成功。
• 写入后使用有限时间范围的 SQL 查询验证关键数据。