全部产品
云市场

行协议参考

更新时间:2019-04-19 15:50:31

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

行协议

语法

  1. <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和时间戳。

元素(element) 可选/必需 描述 类型(请查看数据类型获得更多信息)
measurement 必需 measurement的名字。TSDB For InfluxDB®中每个数据点接受一个measurement。 字符串
tag set 可选 一个数据点上全部的tag key-value pairs。 tag key和tag value都是字符串。
field set 必需。数据点必须至少有一个field。 一个数据点上全部的field key-value pairs。 field key是字符串,field value可以是浮点数、整数或者布尔值。
时间戳 可选。如果没有指定数据点的时间戳,那么TSDB For InfluxDB®使用服务器本地的纳秒级时间戳(UTC格式)作为数据点的时间戳。 数据点的时间戳。TSDB For InfluxDB®中每个数据点接受一个时间戳。 Unix纳秒级时间戳。使用HTTP API指定除纳秒之外其它精度的时间戳。

性能和设置提示:

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

数据类型

数据类型 元素(element) 描述
浮点数 field value IEEE-754 64位浮点数。这是默认的数值类型。例如:11.01.e+781.E+78
整数 field value 有符号的64位整数(从-9223372036854775808到9223372036854775807)。在数字后面加上i来指定整数。例如:1i
字符串 measurement,tag key,tag value,field key,field value 长度限制为64KB。
布尔值 field value 存储TRUE或FALSE的值。
TRUE写入语法:[t, T, true, True, TRUE]
FALSE写入语法:[f, F, false, False, FALSE]
时间戳 时间戳 Unix纳秒级时间戳。使用HTTP API指定除纳秒之外其它精度的时间戳。最小的有效时间戳是-92233720368547758061677-09-21T00:12:43.145224194Z,最大的有效时间戳是92233720368547758062262-04-11T23:47:16.854775806Z

写入和查询布尔值的语法

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

field type差异

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

示例

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

  1. > INSERT mymeas value=1.0

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

  1. > INSERT mymeas value=1

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

  1. > INSERT mymeas value=-1.234456e+78

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

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

  1. > INSERT mymeas value=1i

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

  1. > INSERT mymeas value="stringing along"

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

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

  1. > INSERT mymeas value=true

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

  1. > INSERT mymeas value="true"

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

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

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

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

  1. > INSERT mymeas value=3 1465934559000000000
  2. > INSERT mymeas value="stringing along" 1466625759000000000
  3. >

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

引号

元素(element) 双引号 单引号
时间戳 不使用 不使用
measurement, tag key, tag value, field key 不使用* 不使用*
field value 字符串类型的field value需要用双引号括起来。不要用双引号将浮点数、整数或布尔值括起来。 不使用
  • 行协议允许用户使用双引号和单引号将measurement的名字、tag key、tag value和field key括起来。然而,它会把双引号和单引号当作是名字、key或value的一部分。这会使查询语法复杂化(请看下面的示例)。

示例

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

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

用双引号(或单引号)将时间戳括起来,会产生bad timestamp错误。

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

  1. > INSERT mymeas value="true"
  2. > SHOW FIELD KEYS FROM "mymeas"
  3. name: mymeas
  4. ------------
  5. fieldKey fieldType
  6. value string

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

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

  1. > INSERT "mymeas" value=200
  2. > SHOW MEASUREMENTS
  3. name: measurements
  4. ------------------
  5. name
  6. "mymeas"
  7. > SELECT * FROM mymeas
  8. > SELECT * FROM "mymeas"
  9. > SELECT * FROM "\"mymeas\""
  10. name: "mymeas"
  11. --------------
  12. time value
  13. 2016-06-14T20:36:21.836131014Z 200

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

特殊字符

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

  • 逗号 ,
  • 等号 =
  • 空格

对于measurement,始终使用反斜杠\来转义:

  • 逗号 ,
  • 空格

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

  • 双引号 "

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

示例

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

  1. > 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®.