InfluxDB 行协议参考

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

行协议语法

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

行协议接受换行符 \n 并对空白字符敏感。

语法描述

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

数据类型

写入和查询的布尔语法

可接受的布尔语法因数据写入和数据查询而异。有关更多信息，请参见 常见问题解答。

字段类型不一致

在一次测量中，一个字段的类型在shard中不能不同，但可以在不同的shard之间不同。

要了解字段值类型差异如何影响 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 行协议允许用户对测量名称、标签键、标签值和字段键使用双引号和单引号。 但是，它会假设双引号或单引号是名称、键或值的一部分。 这会使查询语法变得复杂（请参见下面的示例）。

示例

无效的行协议 - 将时间戳用双引号括起来

> 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

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

特殊字符

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

• 在字符串字段值中，您必须转义：

  • 双引号: \" 转义双引号。

  • 反斜杠字符：如果你使用多个反斜杠，它们必须被转义。 InfluxDB 对反斜杠的解释如下：

    • \ or \\ interpreted as \
    • \\\ or \\\\ interpreted as \\
    • \\\\\ or \\\\\\ interpreted as \\\, and so on

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

  • commas
  • equal signs
  • spaces

例如，\, 用于转义逗号。

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

您不需要转义其他特殊字符。

示例

写一个带有特殊字符的点

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

额外的命名指南

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

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

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

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

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

InfluxDB 行协议实践

要了解如何将行协议写入数据库，请参见 Tools。

重复点

一个点是通过测量名称、标签集、字段集和时间戳唯一识别的

如果您写入的点具有与现有点匹配的时间戳，那么字段集将成为旧字段集和新字段集的并集，并且冲突将优先考虑新字段集。

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

重复的键

如果在一个测量中有一个标签键和字段键同名，则其中一个键在查询结果中将以 _1 结尾（在Chronograf中作为列标题）。例如， location 和 location_1。要查询重复的键，请去掉 _1 并在查询中使用 InfluxQL ::tag 或 ::field 语法，例如：

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