Documentation

InfluxDB OSS v1

InfluxDB 行协议教程

此页面记录了 InfluxDB OSS 的早期版本。 InfluxDB OSS v2 是最新的稳定版本。 请参见相应的 InfluxDB v2 文档： 行协议。

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

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

语法数据类型引用特殊字符和关键字

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

语法

一行文本的行协议格式代表InfluxDB中的一个数据点。 它告知InfluxDB该点的测量、标签集、字段集和 时间戳。 下面的代码块展示了一段行协议的示例，并将其分解为各个组成部分：

weather,location=us-midwest temperature=82 1465839830100400200
  |    -------------------- --------------  |
  |             |             |             |
  |             |             |             |
+-----------+--------+-+---------+-+---------+
|measurement|,tag_set| |field_set| |timestamp|
+-----------+--------+-+---------+-+---------+

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

测量

您希望将数据写入的 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

在标签集中使用引号时，行协议支持以下表中所述的单引号和双引号：

元素双引号单引号
测量有限 *有限 *
标签键有限 *有限 *
标签值有限 *有限 *
字段键有限 *有限 *
字段值仅限字符串从不
时间戳从不从不

* 行协议接受测量名称、标签键、标签值和字段键中的双引号和单引号，但将它们解释为名称、键或值的一部分。

始终用双引号括起字符串字段值。

measurementName fieldKey="field string value" 1556813561098000000

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

空白字符 I

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

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

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

空白 II

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

时间戳

您的数据点的时间戳是纳秒精度的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）在主机之间同步时间。InfluxDB使用主机的本地时间（UTC）为数据分配时间戳；如果主机的时钟未与NTP同步，写入InfluxDB的数据的时间戳可能不准确。

数据类型

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

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

注意： 因为 InfluxDB 将标签值存储为字符串，InfluxDB 无法对标签值执行数学运算。 此外，InfluxQL 函数 不接受标签值作为主要参数。 在设计您的 模型 时考虑到这些信息是个好主意。

时间戳是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"}

  • 不要对测量名称、标签键、标签值和字段键加上双引号或单引号。 这是有效的行协议，但InfluxDB假设引号是名称的一部分。

    示例:

    > 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

将被解释为如下（注意单个和双反斜杠产生相同的记录）：

> SELECT * FROM "weather"
name: weather
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 OSS URL 是什么？

自定义你的 InfluxDB OSS URL，我们将为你更新代码示例。

默认
自定义

有关更多信息，请参见 InfluxDB OSS URLs。

感谢您的反馈!

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

谢谢！

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 企业版是建立在核心基础之上的商业版本，增加了历史查询能力、读取副本、高可用性、可扩展性和细粒度安全性。

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