使用 v3 write_lp API 写入数据
使用 /api/v3/write_lp 端点将数据写入 InfluxDB 3 Core。
此端点接受与早期版本的 InfluxDB 相同的 行协议 语法，并支持以下内容：
查询参数
?accept_partial=<BOOLEAN>：接受或拒绝部分写入（默认为true）。?no_sync=<BOOLEAN>：控制何时确认写入。no_sync=true：在 WAL 持久化完成之前确认写入。no_sync=false：在 WAL 持久化完成后确认写入（默认）。
?precision=<PRECISION>：指定时间戳的精度。默认情况下，InfluxDB 3 Core 使用时间戳的量级自动检测精度（auto）。为避免任何歧义，您可以指定数据中时间戳的精度。InfluxDB 3 Core
/api/v3/write_lpAPI 端点支持以下时间戳精度：auto（自动检测，默认）nanosecond（纳秒）microsecond（微秒）millisecond（毫秒）second（秒）
自动精度检测
当您使用 precision=auto（或省略该参数）时，InfluxDB 3 Core 会根据时间戳值的量级自动检测时间戳精度。
- 时间戳 < 5e9 → 秒精度（乘以 1,000,000,000 转换为纳秒）
- 时间戳 < 5e12 → 毫秒精度（乘以 1,000,000）
- 时间戳 < 5e15 → 微秒精度（乘以 1,000）
- 更大的时间戳 → 纳秒精度（无需转换）
精度示例
以下示例演示了如何使用不同的时间戳精度写入数据。
# Auto precision (default) - timestamp magnitude determines precision
curl "https://:8181/api/v3/write_lp?db=sensors" \
--header "Authorization: Bearer DATABASE_TOKEN" \
--data-raw "cpu,host=server1 usage=50.0 1708976567"时间戳 1708976567 被自动检测为秒。
# Explicit nanosecond precision
curl "https://:8181/api/v3/write_lp?db=sensors&precision=nanosecond" \
--header "Authorization: Bearer DATABASE_TOKEN" \
--data-raw "cpu,host=server1 usage=50.0 1708976567000000000"# Millisecond precision
curl "https://:8181/api/v3/write_lp?db=sensors&precision=millisecond" \
--header "Authorization: Bearer DATABASE_TOKEN" \
--data-raw "cpu,host=server1 usage=50.0 1708976567000"# Second precision
curl "https://:8181/api/v3/write_lp?db=sensors&precision=second" \
--header "Authorization: Bearer DATABASE_TOKEN" \
--data-raw "cpu,host=server1 usage=50.0 1708976567"配置 gzip 压缩
/api/v3/write_lp 端点支持 gzip 编码的请求体，以实现高效的数据传输。
将 gzip 压缩数据发送到 InfluxDB 时，请在您的 InfluxDB API 请求中包含 Content-Encoding: gzip 标头。
多成员 gzip 支持
InfluxDB 3 Core 支持多成员 gzip 有效负载（根据 RFC 1952 连接的 gzip 文件）。这允许您：
- 将多个 gzip 文件连接起来并在单个请求中发送
- 与 InfluxDB v1 和 v2 写入端点保持兼容
- 使用标准压缩工具简化批量操作
示例：写入连接的 gzip 文件
# Create multiple gzip files
echo "cpu,host=server1 usage=50.0 1708976567" | gzip > batch1.gz
echo "cpu,host=server2 usage=60.0 1708976568" | gzip > batch2.gz
# Concatenate and send in a single request
cat batch1.gz batch2.gz | curl "https://:8181/api/v3/write_lp?db=sensors" \
--header "Authorization: Bearer DATABASE_TOKEN" \
--header "Content-Encoding: gzip" \
--data-binary @-请求主体
- 行协议
POST /api/v3/write_lp?db=mydb&precision=nanosecond&accept_partial=true&no_sync=false以下示例使用 cURL 通过 Home sensor sample data 发送写入请求，但您也可以使用任何 HTTP 客户端。
InfluxDB 客户端库
InfluxData 提供受支持的 InfluxDB 3 客户端库，您可以将它们集成到您的代码中，将数据构建为时间序列点，然后将它们以行协议形式写入 InfluxDB 3 Core 数据库。有关更多信息，请参阅 如何使用 InfluxDB 客户端库写入数据。
部分写入
/api/v3/write_lp 端点允许您使用 accept_partial 参数接受或拒绝部分写入。此参数会更改 API 在写入请求包含无效行协议或架构冲突时的行为。
例如，以下行协议包含两个点，每个点都为 temp 字段使用了不同的数据类型，这会导致架构冲突。
home,room=Sunroom temp=96 1735545600
home,room=Sunroom temp="hi" 1735549200接受部分写入
使用 accept_partial=true（默认），InfluxDB 会：
- 接受并写入行
1 - 拒绝行
2 - 返回
400 Bad Request状态码和以下响应体：
< HTTP/1.1 400 Bad Request
...
{
"error": "partial write of line protocol occurred",
"data": [
{
"original_line": "home,room=Sunroom temp=hi 1735549200",
"line_number": 2,
"error_message": "invalid column type for column 'temp', expected iox::column_type::field::float, got iox::column_type::field::string"
}
]
}不接受部分写入
使用 accept_partial=false，InfluxDB 会：
- 拒绝批次中的 *所有* 点。
- 返回
400 Bad Request状态码和以下响应体：
< HTTP/1.1 400 Bad Request
...
{
"error": "parsing failed for write_lp endpoint",
"data": {
"original_line": "home,room=Sunroom temp=hi 1735549200",
"line_number": 2,
"error_message": "invalid column type for column 'temp', expected iox::column_type::field::float, got iox::column_type::field::string"
}
}有关摄入路径和数据流的更多信息，请参阅 数据持久性。
写入响应
默认情况下，InfluxDB 3 Core 在将 WAL 文件刷新到对象存储（每秒发生一次）后确认写入。为了获得高写入吞吐量，您可以发送多个并发写入请求。
使用 no_sync 以获得即时写入响应
为了降低写入延迟，请使用 no_sync 写入选项，该选项在 WAL 持久化完成 *之前* 确认写入。当 no_sync=true 时，InfluxDB 会验证数据，将数据写入 WAL，然后立即响应客户端，而无需等待持久化到对象存储。
在优先考虑高吞吐量写入而非绝对持久性的情况下，使用 no_sync=true 是最佳选择。
- 默认行为（
no_sync=false）：在确认写入之前等待数据写入对象存储。降低数据丢失的风险，但会增加响应的延迟。 - 使用
no_sync=true：降低写入延迟，但在发生崩溃导致 WAL 持久化之前，会增加数据丢失的风险。
以下示例会立即返回响应，而无需等待 WAL 持久化。
curl "https://:8181/api/v3/write_lp?db=sensors&no_sync=true" \
--data-raw "home,room=Sunroom temp=96"响应头
InfluxDB 3 Core 的所有 HTTP 响应都包含以下标准头：
cluster-uuid
cluster-uuid 响应头包含您的 InfluxDB 3 Core 实例的目录 UUID。此头包含在所有 HTTP API 响应中，包括：
- 写入请求（
/api/v3/write_lp、/api/v2/write、/write） - 查询请求
- 管理操作
- 身份验证失败
- CORS 预检请求
用例
cluster-uuid 头使您能够：
- 识别集群实例：以编程方式确定哪个 InfluxDB 实例处理了请求。
- 监控部署：在负载均衡或多集群环境中跟踪跨多个 InfluxDB 实例的请求。
- 调试和故障排除：在分布式系统中将客户端请求与特定服务器实例相关联。
示例响应
curl -v "https://:8181/api/v3/write_lp?db=sensors" \
--header "Authorization: Bearer DATABASE_TOKEN" \
--data-raw "cpu,host=server1 usage=50.0"响应头包含 cluster-uuid。
< HTTP/1.1 204 No Content
< cluster-uuid: 01234567-89ab-cdef-0123-456789abcdef
< date: Tue, 19 Nov 2025 20:00:00 GMT此页面是否有帮助？
感谢您的反馈！
支持和反馈
感谢您成为我们社区的一员！我们欢迎并鼓励您对 InfluxDB 3 Core 和本文档提供反馈和错误报告。要获得支持，请使用以下资源
具有年度合同或支持合同的客户可以 联系 InfluxData 支持。