全部产品
Search
文档中心

时间序列数据库 TSDB:行协议参考

更新时间:Jul 04, 2022

行协议(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和时间戳。

元素(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

长度限制为64 KB。

布尔值

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®

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

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

引号

元素(element)

双引号

单引号

时间戳

不使用

不使用

measurement, tag key, tag value, field key

不使用

不使用

field value

字符串类型的field value需要用双引号括起来。不要用双引号将浮点数、整数或布尔值括起来。

不使用

  • 行协议允许用户使用双引号和单引号将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关键字作为标识符名字。通常,我们建议避免在schema中使用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®.