Documentation

InfluxDB 企业版

InfluxDB 行协议教程

InfluxDB 行协议是一种用于将数据点写入数据库的基于文本的格式。
数据点必须采用行协议格式，以便 InfluxDB 能够成功解析并写入数据点（除非您使用的是 服务插件）。

使用虚构的温度数据，本页面介绍了InfluxDB行协议。它涵盖了：

最后一部分，将数据写入InfluxDB，描述了如何将数据导入InfluxDB以及InfluxDB如何处理行协议重复数据。

语法

单行文本以行协议格式表示InfluxDB中的一个数据点。 它通知InfluxDB该点的测量、标签集、字段集和 时间戳。

myMeasurement,tag1=val1,tag2=val2 field1="v1",field2=1i 0000000000000000000

在图表中移动到每个元素：

测量

您希望将数据写入的 measurement 的名称。测量在行协议中是必需的。

在这个例子中，测量名称是 weather。

标签集

您想要包含的标签与您的数据点。标签在行协议中是可选的。

避免使用保留的键 _field、_measurement 和 time。 如果保留键作为标签或字段键包含，则相关的点会被丢弃。

请注意，测量和标签集之间用逗号分隔，且没有空格。

使用等号 = 分隔标签键值对，且中间不要有空格：

<tag_key>=<tag_value>

用逗号分隔多个标签-值对，不加空格：

<tag_key>=<tag_value>,<tag_key>=<tag_value>

在这个例子中，标签集包含一个标签： location=us-midwest。向例子中添加另一个标签（season=summer）看起来是这样的：

weather,location=us-midwest,season=summer temperature=82 1465839830100400200

为了获得最佳性能，您应该在将标签发送到数据库之前按键排序。排序应与Go bytes.Compare function的结果匹配。

第一个空格

将测量值与字段集合分开，或者，如果您在数据点中包含标签集合，请用空格将标签集合和字段集合分开。空格在行协议中是必要的。

有效的行协议，没有标签集：

weather temperature=82 1465839830100400200

字段集合

您的数据点的字段。每个数据点在行协议中至少需要一个字段。

使用等号 = 分隔字段键值对，且不留空格：

<field_key>=<field_value>

用逗号分隔多个字段-值对且不带空格：

<field_key>=<field_value>,<field_key>=<field_value>

在这个例子中，字段集由一个字段组成： temperature=82。将另一个字段 (humidity=71) 添加到这个例子中看起来是这样的：

weather,location=us-midwest temperature=82,humidity=71 1465839830100400200

第二个空白

用空格分隔字段集和可选的时间戳。 如果您包含时间戳，则在行协议中需要空格。

时间戳

您的数据点的时间戳是纳秒精度的Unix时间。时间戳在行协议中是可选的。如果您未为数据点指定时间戳，InfluxDB将使用服务器的本地纳秒时间戳（UTC）。

在这个例子中，时间戳是 1465839830100400200 （在RFC3339格式中是 2016-06-13T17:43:50.1004002Z）。下面的行协议是相同的数据点，但没有时间戳。当InfluxDB将其写入数据库时，它使用您服务器的本地时间戳，而不是 2016-06-13T17:43:50.1004002Z。

weather,location=us-midwest temperature=82

使用 InfluxDB API 指定除了纳秒以外的时间戳精度，例如微秒、毫秒或秒。我们建议使用尽可能粗糙的精度，因为这可以显著提高压缩性能。有关更多信息，请参见 API Reference。

使用 NTP 在主机之间同步时间

使用网络时间协议（NTP）在主机之间同步时间。InfluxDB使用主机的本地时间（UTC）为数据分配时间戳；如果主机的时钟未与NTP同步，写入InfluxDB的数据的时间戳可能不准确。

数据类型

本节涵盖行协议主要组件的数据类型： measurements, tag keys, tag values, field keys, field values，和 timestamps。

测量、标签键、标签值和字段键始终是字符串。

因为 InfluxDB 将标签值存储为字符串，InfluxDB 不能对标签值进行数学运算。 此外，InfluxQL functions 不接受标签值作为主要参数。 在设计您的 schema 时考虑这些信息是个好主意。

时间戳是 Unix 时间戳。 最小有效时间戳为 -9223372036854775806 或 1677-09-21T00:12:43.145224194Z。 最大有效时间戳为 9223372036854775806 或 2262-04-11T23:47:16.854775806Z。 如上所述，默认情况下，InfluxDB 假定时间戳具有纳秒精度。 请参阅 API Reference 以了解如何指定其他精度。

字段值可以是浮点数、整数、字符串或布尔值：

  • 浮点数: 默认情况下，InfluxDB 假定所有数字字段值都是浮点数。

    将字段值 82 存储为浮点数：

    weather,location=us-midwest temperature=82 1465839830100400200

  • 整数: 在字段值后附加一个 i 以告诉 InfluxDB 将此数字存储为整数。

    将字段值 82 存储为整数：

    weather,location=us-midwest temperature=82i 1465839830100400200

  • 字符串：双引号字符串字段值（关于引用的更多信息请参见下面的行协议）。

    将字段值 too warm 存储为字符串：

    weather,location=us-midwest temperature="too warm" 1465839830100400200

  • 布尔值：用 t、T、true、True 或 TRUE 表示 TRUE。用 f、F、false、False 或 FALSE 表示 FALSE。

    将字段值 true 存储为布尔值：

    weather,location=us-midwest too_hot=true 1465839830100400200

    可接受的布尔语法在数据写入和数据查询中有所不同。有关更多信息，请参见 常见问题。

在一个测量中，字段的类型在一个 分片内不能不同，但在 分片之间可以不同。例如，如果InfluxDB尝试将整数存储在与浮点数相同的分片中，将整数写入先前接受浮点数的字段会失败：

> INSERT weather,location=us-midwest temperature=82 1465839830100400200
> INSERT weather,location=us-midwest temperature=81i 1465839830100400300
ERR: {"error":"field type conflict: input field \"temperature\" on measurement \"weather\" is type int64, already exists as type float"}

但是，如果将整数写入之前接受浮点数的字段，如果InfluxDB将整数存储在一个新的分片中，则该操作成功：

> INSERT weather,location=us-midwest temperature=82 1465839830100400200
> INSERT weather,location=us-midwest temperature=81i 1467154750000000000
>

请参见 常见问题解答 了解字段值类型差异如何影响 SELECT * 查询。

引用

本节讨论何时不使用双引号 (") 或单引号 (') 在行协议中引用。
从永不引用到请务必引用：

  • 绝不要使用双引号或单引号包围时间戳——例如：

    > INSERT weather,location=us-midwest temperature=82 "1465839830100400200"
ERR: {"error":"unable to parse 'weather,location=us-midwest temperature=82 \"1465839830100400200\"': bad timestamp"}

  • 切勿使用单引号包围字段值，即使它们是字符串——例如：

    > INSERT weather,location=us-midwest temperature='too warm'
ERR: {"error":"unable to parse 'weather,location=us-midwest temperature='too warm'': invalid boolean"}

  • 除非引号是名称的一部分，否则请勿对测量名称、标签键、标签值和字段键使用双引号或单引号——例如：

    > INSERT weather,location=us-midwest temperature=82 1465839830100400200
> INSERT "weather",location=us-midwest temperature=87 1465839830100400200

    > SHOW MEASUREMENTS
name: measurements
------------------
name
"weather"
weather

    要查询 "weather" 中的数据，您需要将度量名称用双引号括起来，并转义度量的双引号：

    > SELECT * FROM "\"weather\""

name: "weather"
---------------
time				            location	 temperature
2016-06-13T17:43:50.1004002Z	us-midwest	 87

  • 不要对浮点数、整数或布尔值的字段值进行双引号。 InfluxDB 将带引号的字段值解析为字符串—例如：

    > INSERT weather,location=us-midwest temperature="82"
> SELECT * FROM weather WHERE temperature >= 70
>

  • 对字符串类型的字段值使用双引号–例如：

    > INSERT weather,location=us-midwest temperature="too warm"
> SELECT * FROM weather
name: weather
-------------
time				            location	 temperature
2016-06-13T19:10:09.995766248Z	us-midwest	 too warm

特殊字符和关键字

特殊字符

对于标签键、标签值和字段键，始终使用反斜杠字符 \ 进行转义：

  • 逗号 (,)

    weather,location=us\,midwest temperature=82 1465839830100400200

  • 等号 (=)

    weather,location=us-midwest temp\=rature=82 1465839830100400200

  • 空格

    weather,location\ place=us-midwest temperature=82 1465839830100400200

对于测量，总是使用反斜杠字符 \ 来转义：

  • 逗号 (,)

    wea\,ther,location=us-midwest temperature=82 1465839830100400200

  • 空格

    wea\ ther,location=us-midwest temperature=82 1465839830100400200

对于字符串字段值，使用反斜杠字符 \ 进行转义：

  • 双引号 (")

    weather,location=us-midwest temperature="too\"hot\"" 1465839830100400200

行协议不需要您转义反斜杠字符 \，但如果您愿意，可以这样做—例如：

weather,location=us-midwest temperature_str="too hot/cold" 1465839830100400201
weather,location=us-midwest temperature_str="too hot\cold" 1465839830100400202
weather,location=us-midwest temperature_str="too hot\\cold" 1465839830100400203
weather,location=us-midwest temperature_str="too hot\\\cold" 1465839830100400204
weather,location=us-midwest temperature_str="too hot\\\\cold" 1465839830100400205
weather,location=us-midwest temperature_str="too hot\\\\\cold" 1465839830100400206

被解释为：

time                location   temperature_str
----                --------   ---------------
1465839830100400201 us-midwest too hot/cold
1465839830100400202 us-midwest too hot\cold
1465839830100400203 us-midwest too hot\cold
1465839830100400204 us-midwest too hot\\cold
1465839830100400205 us-midwest too hot\\cold
1465839830100400206 us-midwest too hot\\\cold

请注意，单个和双个反斜杠产生相同的记录。

所有其他特殊字符也不需要转义。 例如，行协议可以毫无问题地处理表情符号：

> INSERT we⛅️ther,location=us-midwest temper🔥ture=82 1465839830100400200
> SELECT * FROM "we⛅️ther"
name: we⛅️ther
------------------
time			              location	   temper🔥ture
1465839830100400200	 us-midwest	 82

关键词

行协议接受 InfluxQL 关键字 作为 标识符 名称。 一般来说，我们建议避免在您的模式中使用 InfluxQL 关键字，因为这可能会导致 混淆 在查询数据时。

关键字 time 是一个特例。 time 可以是一个 连续查询 名称， 数据库名称， 测量 名称， 保留策略 名称， 订阅 名称，以及 用户 名称。 在这些情况下，time 在查询中不需要双引号。 time 不能是 字段关键字 或 标签关键字； InfluxDB 拒绝将 time 作为字段关键字或标签关键字的写入，并返回错误。 有关更多信息，请参见 常见问题解答。

将数据写入InfluxDB

获取数据库中的数据

现在你对InfluxDB行协议了解了所有内容，如何将行协议实际发送到InfluxDB呢？在这里，我们将提供两个快速示例，然后指引你到工具部分以获取更多信息。

InfluxDB API

使用 InfluxDB API 将数据写入 InfluxDB。
向 /write 端点发送 POST 请求，并在请求主体中提供您的行协议：

curl -i -XPOST "http://localhost:8086/write?db=science_is_cool" --data-binary 'weather,location=us-midwest temperature=82 1465839830100400200'

有关查询字符串参数、状态码、响应的详细描述以及更多示例，请参见API Reference。

命令行界面

使用InfluxDB命令行界面（CLI）将数据写入InfluxDB。 启动 CLI，使用相关的 数据库，并在您的行协议前放置 INSERT：

INSERT weather,location=us-midwest temperature=82 1465839830100400200

您也可以使用 CLI 从文件中 import 行协议。

有几种方法可以将数据写入InfluxDB。 有关更多信息，请参见工具部分， 了解InfluxDB API、CLI和可用的服务插件（ UDP、Graphite、CollectD和 OpenTSDB）。

重复点

一个点通过测量名称、标签集和时间戳唯一标识。 如果您提交具有相同测量、标签集和时间戳的行协议， 但具有不同的字段集，则字段集成为旧字段集和新字段集的并集， 其中任何冲突都优先考虑新的字段集。

有关此行为的完整示例以及如何避免它，请参见 InfluxDB如何处理重复点？

© 2025 InfluxData, Inc.

你在哪里运行InfluxDB？

自定义您的 InfluxDB 企业 URL，我们将为您更新代码示例。

默认
自定义

有关更多信息，请参见 InfluxDB Enterprise HTTP settings。

感谢您的反馈!

让我们知道我们可以做得更好的地方：

谢谢！

No thanks

Flux的未来

Flux 正在进入维护模式。您可以像现在一样继续使用它，而无需对您的代码进行任何更改。

阅读更多

InfluxDB 3 开源版本现已公开Alpha测试

InfluxDB 3 Open Source is now available for alpha testing, licensed under MIT or Apache 2 licensing.

我们将发布两个产品作为测试版的一部分。

InfluxDB 3 核心，是我们新的开源产品。 它是一个用于时间序列和事件数据的实时数据引擎。 InfluxDB 3 企业版是建立在核心基础之上的商业版本，增加了历史查询能力、读取副本、高可用性、可扩展性和细粒度安全性。

有关如何开始的更多信息，请查看：