InfluxDB 行协议教程

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

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

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

语法

数据类型

引用

特殊字符和关键字

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

语法

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

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

在图表中移动每个元素

Measurement

您要将数据写入到的measurement的名称。Measurement 在行协议中是必需的。

在示例中，measurement 名称是 weather。

标签集

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

注意： 避免使用保留键 _field、_measurement 和 time。如果保留键作为标签或字段键包含在内，则关联的点将被丢弃。

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

使用等号 = 分隔标签键值对，且没有空格

<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

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

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

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

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

measurementName fieldKey="field string value" 1556813561098000000

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

空格 I

使用空格分隔 measurement 和字段集，或者，如果您在数据点中包含标签集，则使用空格分隔标签集和字段集。空格在行协议中是必需的。

没有标签集的有效行协议

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 参考。

设置提示

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

数据类型

本节介绍行协议主要组成部分的数据类型：measurements、标签键、标签值、字段键、字段值和时间戳。

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

注意： 由于 InfluxDB 将标签值存储为字符串，因此 InfluxDB 无法对标签值执行数学运算。此外，InfluxQL 函数不接受标签值作为主要参数。在设计schema时，最好考虑该信息。

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

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

浮点数 - 默认情况下，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
```
注意： 数据写入和数据查询的可接受布尔值语法有所不同。有关更多信息，请参阅常见问题解答。

在 measurement 中，字段的类型在一个shard中不能不同，但在不同的 shard 中可以不同。例如，如果 InfluxDB 尝试将整数存储在与浮点数相同的 shard 中，则将整数写入先前接受浮点数的字段将失败

> 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 将整数存储在一个新的 shard 中，则将整数写入先前接受浮点数的字段将成功

> 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"}

不要用双引号或单引号引起来 measurement 名称、标签键、标签值和字段键。它是有效的行协议，但 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" 中的数据，您需要用双引号引起来 measurement 名称并转义 measurement 的双引号

> 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

对于 measurements，始终使用反斜杠字符 \ 进行转义

逗号 ,

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 关键字作为标识符名称。通常，我们建议避免在您的 schema 中使用 InfluxQL 关键字，因为这可能会在查询数据时引起混淆。

关键字 time 是一种特殊情况。time 可以是连续查询名称、数据库名称、measurement 名称、保留策略名称、订阅名称和用户名称。在这些情况下，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 参考。

CLI

使用 InfluxDB 命令行界面 (CLI) 将数据写入 InfluxDB。启动 CLI，使用相关的数据库，并在行协议前面加上 INSERT

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

您还可以使用 CLI 从文件导入行协议。

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

重复点

点由 measurement 名称、标签集和时间戳唯一标识。如果您提交具有相同 measurement、标签集和时间戳但具有不同字段集的行协议，则字段集将成为旧字段集和新字段集的并集，其中任何冲突都偏向于新字段集。

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

此页是否对您有帮助？

感谢您的反馈！

支持和反馈

感谢您成为我们社区的一份子！我们欢迎并鼓励您提供关于 InfluxDB 和本文档的反馈和错误报告。要获得支持，请使用以下资源

拥有年度或支持合同的客户可以联系 InfluxData 支持。

编辑此页提交文档问题提交 InfluxDB 问题

InfluxDB 行协议教程

语法

Measurement

标签集

空格 I

字段集

空格 II

时间戳

设置提示

数据类型

引用

特殊字符和关键字

特殊字符

关键字

将数据写入 InfluxDB

将数据导入数据库

InfluxDB API

CLI

重复点

支持和反馈

Flux 的未来

InfluxDB 3 Core 和 Enterprise

InfluxDB 行协议教程

语法

Measurement

标签集

空格 I

字段集

空格 II

时间戳

设置提示

数据类型

引用

特殊字符和关键字

特殊字符

关键字

将数据写入 InfluxDB

将数据导入数据库

InfluxDB API

CLI

重复点

支持和反馈

您的 InfluxDB OSS URL 是什么？

默认

自定义

感谢您的反馈！

Flux 的未来

InfluxDB 3 Core 和 Enterprise