行协议（Line Protocol）是一种基于文本的格式，用于将数据点写入TSDB For InfluxDB®。

行协议

语法

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

使用换行符\n分隔每一行，每一行表示TSDB For InfluxDB®中的一个数据点。行协议是对空格敏感的。

语法描述

行协议告诉TSDB For InfluxDB®数据的measurement、tag set、field set和时间戳。

性能和设置提示：

• 在将数据点发送到数据库之前，将tag按tag key进行排序。排序结果应该与Go bytes.Compare function的结果匹配。
• 时间戳尽量使用最粗的精度，因为这可以显著提高压缩效果。
• 使用网络时间协议（Network Time Protocol，NTP）来同步主机（host）之间的时间。TSDB For InfluxDB®使用主机的本地UTC时间为数据分配时间戳；如果主机的时钟与NTP不同步，写入TSDB For InfluxDB®的数据的时间戳可能会不准确。

数据类型

写入和查询布尔值的语法

写入和查询布尔值的语法不一样。请查看FAQ获得更多相关信息。

field type差异

在measurement中，一个field的数据类型在一个shard内不会不一致，但是在不同的shard，它的数据类型可以不同。若想了解field value的数据类型差异如何影响SELECT *查询，请查看FAQ的相关章节。

示例

示例一：将field value 1.0作为浮点数写入TSDB For InfluxDB®

> INSERT mymeas value=1.0

示例二：将field value 1作为浮点数写入TSDB For InfluxDB®

> INSERT mymeas value=1

示例三：将field value -1.234456e+78作为浮点数写入TSDB For InfluxDB®

> INSERT mymeas value=-1.234456e+78

TSDB For InfluxDB®支持使用科学计数法指定field value。

示例四：将field value 1作为整数写入TSDB For InfluxDB®

> INSERT mymeas value=1i

示例五：将field value stringing along作为字符串写入TSDB For InfluxDB®

> INSERT mymeas value="stringing along"

始终使用双引号将字符串类型的field value括起来。更多关于引号的介绍，请查看下文引号一节。

示例六：将field value true作为布尔值写入TSDB For InfluxDB®

> INSERT mymeas value=true

请不要用引号将布尔类型的field value括起来。以下语句把true作为字符串写入TSDB For InfluxDB®：

> INSERT mymeas value="true"

示例七：尝试将字符串写入之前接受浮点数的field

如果浮点数和字符串上的时间戳存储在同一个shard:

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

如果浮点数和字符串上的时间戳不是存储在同一个shard:

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

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

引号

• 行协议允许用户使用双引号和单引号将measurement的名字、tag key、tag value和field key括起来。然而，它会把双引号和单引号当作是名字、key或value的一部分。这会使查询语法复杂化（请看下面的示例）。

示例

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

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

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

示例二：语义错误 - 用双引号将布尔类型的field value括起来

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

TSDB For InfluxDB®假设所有用双引号括起来的field value都是字符串。

示例三：语义错误 - 用双引号将measurement的名字括起来

> 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

如果您使用双引号将行协议中的measurement括起来，那么对该measurement的任意查询都需要在FROM子句中使用双引号并且将双引号转义(\)。

特殊字符

对于tag key、tag value和field key，始终使用反斜杠\来转义：

• 逗号 ,
• 等号 =
• 空格

对于measurement，始终使用反斜杠\来转义：

• 逗号 ,
• 空格

对于字符串类型的field value，使用反斜杠\来转义：

• 双引号 "

行协议不需要用户将反斜杠\转义。用户也不需要将其它的特殊字符转义。

示例

示例一：写入带特殊字符的数据点

> 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为"measurement with quo⚡️es and emoji"，tag key为tag key with sp⚡️ces，tag value为tag,value,with"commas"，field key为field_k\ey，field value为string field value, only " need be esc⚡️ped。

其它命名指南

在行的开头，#是行协议的有效注释字符。TSDB For InfluxDB®会忽略所有的后续字符，直到遇到下一个换行符\n。

measurement的名字、tag key、tag value、field key和field value都是大小写敏感的。

行协议将InfluxQL关键字作为标识符名字。通常，我们建议避免在schama中使用InfluxQL关键字，因为它可能会在查询数据时引起混淆。

关键字time是一个特例。time可以是一个连续查询名字、数据库名字、measurement的名字、保留策略名字、subscription的名字和用户名。在这些情况下，不需要在查询中用双引号将time括起来。time不能是field key或tag key；TSDB For InfluxDB®拒绝写入将time作为field key或tag key的数据，对于这种数据写入，TSDB For InfluxDB®会返回错误。请查阅FAQ获得更多相关信息。

在实践中的行协议

关于如何将行协议数据写入数据库，请查看工具章节。

重复数据点

measurement的名字、tag set和时间戳唯一标识一个数据点。如果您提交的数据具有相同measurement、tag set和时间戳但具有不同field set，那么数据的field set会变为旧field set和新field set的并集，如果有任何冲突以新field set为准。

有关此行为的完整示例和如何避免这种情况，请查看FAQ相关章节。

InfluxDB® is a trademark registered by InfluxData, which is not affiliated with, and does not endorse, TSDB for InfluxDB®.