InfluxDB Line Protocol 教程

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

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

本页使用虚构的温度数据介绍 InfluxDB Line Protocol。它涵盖了

语法

数据类型

引用

特殊字符和关键字

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

语法

Line Protocol 格式的单行文本表示 InfluxDB 中的一个数据点。它告知 InfluxDB 该点的 measurement、tag set、field set 和时间戳。以下代码块显示了 Line Protocol 的示例，并将其分解为各个组成部分

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

在图中移动每个元素

Measurement

您要将数据写入的 measurement 的名称。Measurement 在 Line Protocol 中是必需的。

在示例中，measurement 名称为 weather。

Tag Set

您要包含在数据点中的 tag(s)。Tag 在 Line Protocol 中是可选的。

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

请注意，measurement 和 tag set 用逗号分隔，没有空格。

使用等号 = 分隔 tag 键值对，没有空格

<tag_key>=<tag_value>

使用逗号分隔多个 tag 值对，没有空格

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

在示例中，tag set 由一个 tag 组成：location=us-midwest。向示例添加另一个 tag (season=summer) 如下所示

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

在 tag set 中使用引号时，Line Protocol 支持单引号和双引号，如下表所述

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

^* Line Protocol 接受 measurement 名称、tag 键、tag 值和 field 键中的双引号和单引号，但将其解释为名称、键或值的一部分。

始终使用双引号引用字符串 field 值。

measurementName fieldKey="field string value" 1556813561098000000

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

空格 I

使用空格分隔 measurement 和 field set，或者，如果您在数据点中包含 tag set，则使用空格分隔 tag set 和 field set。空格在 Line Protocol 中是必需的。

没有 tag set 的有效 Line Protocol

weather temperature=82 1465839830100400200

Field Set

数据点的 field(s)。每个数据点在 Line Protocol 中都需要至少一个 field。

使用等号 = 分隔 field 键值对，没有空格

<field_key>=<field_value>

使用逗号分隔多个 field 值对，没有空格

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

在示例中，field set 由一个 field 组成：temperature=82。向示例添加另一个 field (humidity=71) 如下所示

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

空格 II

使用空格分隔 field set 和可选的时间戳。如果您包含时间戳，则空格在 Line Protocol 中是必需的。

时间戳

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

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

weather,location=us-midwest temperature=82

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

设置提示

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

数据类型

本节介绍 Line Protocol 主要组成部分的数据类型：measurements、tag 键、tag 值、field 键、field 值和时间戳。

Measurements、tag 键、tag 值和 field 键始终是字符串。

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

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

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

浮点数 - 默认情况下，InfluxDB 假定所有数值 field 值均为浮点数。
将 field 值 82 存储为浮点数
```
weather,location=us-midwest temperature=82 1465839830100400200
```
整数 - 在 field 值后附加 i，以告知 InfluxDB 将数字存储为整数。
将 field 值 82 存储为整数
```
weather,location=us-midwest temperature=82i 1465839830100400200
```
字符串 - 使用双引号引用字符串 field 值（有关 Line Protocol 中引用的更多信息，请参阅下文）。
将 field 值 too warm 存储为字符串
```
weather,location=us-midwest temperature="too warm" 1465839830100400200
```
布尔值 - 使用 t、T、true、True 或 TRUE 指定 TRUE。使用 f、F、false、False 或 FALSE 指定 FALSE。
将 field 值 true 存储为布尔值
```
weather,location=us-midwest too_hot=true 1465839830100400200
```
注意： 数据写入和数据查询的可接受布尔语法有所不同。有关更多信息，请参阅常见问题。

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

> 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 将整数存储在新分片中，则将整数写入先前接受浮点数的 field 会成功

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

有关 field 值类型差异如何影响 SELECT * 查询的信息，请参阅常见问题。

引用

本节介绍何时不应以及何时应在 Line Protocol 中使用双引号 (") 或单引号 (') 引用。从从不引用到请务必引用

永远不要使用双引号或单引号引用时间戳。这不是有效的 Line Protocol。

示例

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

永远不要使用单引号引用 field 值（即使它们是字符串！）。这也不是有效的 Line Protocol。

示例

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

不要使用双引号或单引号引用 measurement 名称、tag 键、tag 值和 field 键。它是有效的 Line Protocol，但 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

不要使用双引号引用浮点数、整数或布尔值的 field 值。InfluxDB 将假定这些值是字符串。
示例
```
> INSERT weather,location=us-midwest temperature="82"
> SELECT * FROM weather WHERE temperature >= 70
>
```

请务必使用双引号引用字符串的 field 值。

示例

> 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

特殊字符和关键字

特殊字符

对于 tag 键、tag 值和 field 键，始终使用反斜杠字符 \ 来转义

逗号 ,

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

对于字符串 field 值，使用反斜杠字符 \ 来转义

双引号 "

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

Line Protocol 不要求用户转义反斜杠字符 \，但如果您这样做也不会报错。例如，插入以下内容

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

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

> 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

关键字

Line Protocol 接受 InfluxQL 关键字作为标识符名称。通常，我们建议避免在您的架构中使用 InfluxQL 关键字，因为它可能会在查询数据时引起混淆。

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

将数据写入 InfluxDB

将数据导入数据库

现在您已经了解了有关 InfluxDB Line Protocol 的所有信息，那么您实际上如何将 Line Protocol 导入 InfluxDB？在这里，我们将给出两个快速示例，然后将您指向工具部分以获取更多信息。

InfluxDB API

使用 InfluxDB API 将数据写入 InfluxDB。向 /write 端点发送 POST 请求，并在请求正文中提供您的 Line Protocol

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

有关查询字符串参数、状态代码、响应和更多示例的深入描述，请参阅 API 参考。

CLI

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

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

您还可以使用 CLI 从文件导入 Line Protocol。

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

重复点

点由 measurement 名称、tag set 和时间戳唯一标识。如果您提交具有相同 measurement、tag set 和时间戳但具有不同 field set 的 Line Protocol，则 field set 将变为旧 field set 和新 field set 的并集，其中任何冲突都支持新 field set。

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

此页面对您有帮助吗？

感谢您的反馈！

支持和反馈

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

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

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

InfluxDB Line Protocol 教程

语法

Measurement

Tag Set

空格 I

Field Set

空格 II

时间戳

设置提示

数据类型

引用

特殊字符和关键字

特殊字符

关键字

将数据写入 InfluxDB

将数据导入数据库

InfluxDB API

CLI

重复点

支持和反馈

Flux 的未来

InfluxDB 3 开源现在处于公开 Alpha 阶段

InfluxDB Line Protocol 教程

语法

Measurement

Tag Set

空格 I

Field Set

空格 II

时间戳

设置提示

数据类型

引用

特殊字符和关键字

特殊字符

关键字

将数据写入 InfluxDB

将数据导入数据库

InfluxDB API

CLI

重复点

支持和反馈

您的 InfluxDB OSS URL 是什么？

默认

自定义

感谢您的反馈！

Flux 的未来

InfluxDB 3 开源现在处于公开 Alpha 阶段