InfluxDB Line 协议参考

InfluxDB Line 协议是一种基于文本的格式，用于将点写入 InfluxDB。

Line 协议语法

<measurement>[,<tag_key>=<tag_value>[,<tag_key>=<tag_value>]] <field_key>=<field_value>[,<field_key>=<field_value>] [<timestamp>]

Line 协议接受换行符 \n 并且对空格敏感。

注意 Line 协议不支持标签值或字段值中的换行符 \n。

语法描述

InfluxDB Line 协议告知 InfluxDB 数据的测量、标签集、字段集和时间戳。

性能提示

• 在将数据发送到 InfluxDB 之前，按标签键排序以匹配来自 Go bytes.Compare 函数 的结果。
• 为了显着提高压缩率，请对时间戳使用尽可能粗糙的 精度。
• 使用网络时间协议 (NTP) 同步主机之间的时间。InfluxDB 使用主机在 UTC 中的本地时间为数据分配时间戳。如果主机的时钟未与 NTP 同步，则主机写入 InfluxDB 的数据可能具有不准确的时间戳。

数据类型

布尔值写入和查询的语法

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

字段类型差异

在测量中，字段的类型在 分片 中不能不同，但在分片之间可以不同。

要了解字段值类型差异如何影响 SELECT * 查询，请参阅 InfluxDB 如何处理跨分片的字段类型差异？。

示例

将字段值 -1.234456e+78 作为浮点数写入 InfluxDB

> INSERT mymeas value=-1.234456e+78

InfluxDB 支持以科学计数法指定的字段值。

将字段值 1.0 作为浮点数写入 InfluxDB

> INSERT mymeas value=1.0

将字段值 1 作为浮点数写入 InfluxDB

> INSERT mymeas value=1

将字段值 1 作为整数写入 InfluxDB

> INSERT mymeas value=1i

将字段值 stringing along 作为字符串写入 InfluxDB

> INSERT mymeas value="stringing along"

始终用双引号引起来字符串字段值。有关引号的更多信息，请参见 下方。

将字段值 true 作为布尔值写入 InfluxDB

> INSERT mymeas value=true

不要用引号引起来布尔字段值。以下语句将 true 作为字符串字段值写入 InfluxDB

> INSERT mymeas value="true"

尝试将字符串写入先前接受浮点数的字段

如果浮点数和字符串的时间戳存储在同一个分片中

> INSERT mymeas value=3 1465934559000000000
> INSERT mymeas value="stringing along" 1465934559000000001
ERR: {"error":"field type conflict: input field \"value\" on measurement \"mymeas\" is type string, already exists as type float"}

如果浮点数和字符串的时间戳未存储在同一个分片中

> INSERT mymeas value=3 1465934559000000000
> INSERT mymeas value="stringing along" 1466625759000000000
>

引号、特殊字符和其他命名指南

引号

* InfluxDB Line 协议允许用户用双引号和单引号引起来测量名称、标签键、标签值和字段键。但是，它将假定双引号或单引号是名称、键或值的一部分。这可能会使查询语法复杂化（请参阅下面的示例）。

示例

无效的 Line 协议 - 双引号引起来时间戳

> INSERT mymeas value=9 "1466625759000000000"
ERR: {"error":"unable to parse 'mymeas value=9 \"1466625759000000000\"': bad timestamp"}

用双引号（或单引号）引起来时间戳会产生 bad timestamp 错误。

语义错误 - 双引号引起来布尔字段值

> INSERT mymeas value="true"
> SHOW FIELD KEYS FROM "mymeas"
name: mymeas
------------
fieldKey	 fieldType
value		   string

InfluxDB 假定所有用双引号引起来的字段值都是字符串。

语义错误 - 双引号引起来测量名称

> INSERT "mymeas" value=200
> SHOW MEASUREMENTS
name: measurements
------------------
name
"mymeas"
> SELECT * FROM mymeas
> SELECT * FROM "mymeas"
> SELECT * FROM "\"mymeas\""
name: "mymeas"
--------------
time				                        value
2016-06-14T20:36:21.836131014Z	 200

如果您在 Line 协议中用双引号引起来测量，则对该测量的任何查询都需要在 FROM 子句中使用双引号和转义 (\) 双引号。

特殊字符

您必须使用反斜杠字符 \ 来转义以下特殊字符

• 在字符串字段值中，您必须转义
  • 双引号
  • 反斜杠字符

例如，\" 转义双引号。

关于反斜杠的说明

• 如果您使用多个反斜杠，则必须转义它们。Influx 将反斜杠解释如下

  • \ 或 \\ 解释为 \
  • \\\ 或 \\\\ 解释为 \\
  • \\\\\ 或 \\\\\\ 解释为 \\\，依此类推

• 在标签键、标签值和字段键中，您必须转义

  • 逗号
  • 等号
  • 空格

例如，\, 转义逗号。

• 在测量中，您必须转义
  • 逗号
  • 空格

您无需转义其他特殊字符。

示例

写入带有特殊字符的点

> INSERT "measurement\ with\ quo⚡️es\ and\ emoji",tag\ key\ with\ sp🚀ces=tag\,value\,with"commas" field_k\ey="string field value, only \" need be esc🍭ped"

系统写入一个点，其中测量为 "measurement with quo⚡️es and emoji"，标签键为 tag key with sp🚀ces，标签值为 tag,value,with"commas"，字段键为 field_k\ey，字段值为 string field value, only " need be esc🍭ped。

其他命名指南

行开头的 # 是 Line 协议的有效注释字符。InfluxDB 将忽略所有后续字符，直到下一个换行符 \n。

测量名称、标签键、标签值、字段键和字段值区分大小写。

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

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

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

InfluxDB Line 协议实践

要了解如何将 Line 协议写入数据库，请参阅 工具。

重复点

点由测量名称、标签集、字段集和时间戳唯一标识

如果您将点写入具有与现有点匹配的时间戳的序列，则字段集将成为旧字段集和新字段集的并集，并且冲突有利于新字段集。

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

重复键

如果您在测量中具有名称相同的标签键和字段键，则其中一个键将在查询结果中返回并附加 _1（以及作为 Chronograf 中的列标题）。例如，location 和 location_1。要查询重复键，请删除 _1 并在查询中使用 InfluxQL ::tag 或 ::field 语法，例如

  SELECT "location"::tag, "location"::field FROM "database_name"."retention_policy"."measurement"