全部产品
云市场

行协议教程

更新时间:2019-08-13 12:52:54

TSDB For InfluxDB®的行协议(Line Protocol)是一种基于文本的格式,用于将数据点写入数据库。数据点必须符合行协议格式,TSDB For InfluxDB®才能成功解析和写入数据点。

本文档使用模拟的温度数据来介绍行协议,涵盖以下内容:

| 语法 | 数据类型 | 引号 | 特殊字符和关键字 |

本文档的最后一个章节:将数据写入TSDB For InfluxDB®,描述了如何将数据写入TSDB For InfluxDB®和TSDB For InfluxDB®如何处理重复数据点。

语法

行协议中,一行数据表示TSDB For InfluxDB®中的一个数据点,它告诉TSDB For InfluxDB®该数据点的measurement、tag set、field set和时间戳。以下代码块展示了行协议的一个示例,并将其分解成多个组成部分:

  1. weather,location=us-midwest temperature=82 1465839830100400200
  2. | -------------------- -------------- |
  3. | | | |
  4. | | | |
  5. +-----------+--------+-+---------+-+---------+
  6. |measurement|,tag_set| |field_set| |timestamp|
  7. +-----------+--------+-+---------+-+---------+

下面,我们将逐个分析上图中的元素。

Measurement

您想要写入数据的measurement的名字。在行协议中,measurement是必须要有的。在上面的示例中,measurement的名字是weather

Tag set

您想要在数据点中包含的tag。在行协议中,tag是可选的。请注意,measurement和tag set被逗号隔开并且它们之间没有空格。

使用等号=分隔tag key和tag value,并且它们之间不能有空格:

  1. <tag_key>=<tag_value>

使用逗号分隔多个tag key-value pairs,并且它们之间不能有空格:

  1. <tag_key>=<tag_value>,<tag_key>=<tag_value>

在示例中,tag set由一个tag组成:location=us-midwest。在示例中添加另一个tag(season=summer),如下所示:

  1. weather,location=us-midwest,season=summer temperature=82 1465839830100400200

为了获得最佳性能,您应该在将数据点发送到数据库之前,将tag按tag key进行排序。排序结果应该与Go bytes.Compare function的结果匹配。

空格 I

使用空格分隔measurement和field set,如果数据点中包含了tag set,也需要使用空格分隔tag set和field set。在行协议中,这里必须使用空格。

没有tag set的有效行协议:

  1. weather temperature=82 1465839830100400200

Field set

数据点中的field。在行协议中,每个数据点至少需要有一个field。

使用等号=分隔field key和field value,并且它们之间不能有空格:

  1. <field_key>=<field_value>

使用逗号分隔多个field key-value pairs,并且它们之间不能有空格:

  1. <field_key>=<field_value>,<field_key>=<field_value>

在示例中,field set由一个field组成:temperature=82。在示例中添加另一个field(humidity=71),如下所示:

  1. weather,location=us-midwest temperature=82,humidity=71 1465839830100400200

空格 II

使用空格分隔field set和时间戳(如果有的话)。如果为数据点指定了时间戳,那么在行协议中,这里必须使用空格。

时间戳

数据点中的时间戳是精确到纳米的Unix时间。在行协议中,时间戳是可选的。如果您没有指定数据点的时间戳,那么TSDB For InfluxDB®使用服务器本地的纳秒级时间戳(UTC格式)作为数据点的时间戳。

在示例中,时间戳是1465839830100400200(也就是2016-06-13T17:43:50.1004002Z,按照RFC3339格式)。下面的行协议表示相同的数据点,但是不带时间戳。当TSDB For InfluxDB®将该数据点写入数据库,它使用服务器的本地时间戳,而不是2016-06-13T17:43:50.1004002Z

  1. weather,location=us-midwest temperature=82

使用HTTP API来指定除纳秒之外其它精度的时间戳,例如微秒、毫秒或者秒。我们建议尽量使用最粗糙的精度,因为这可以显著提高压缩效果。

设置提示:请使用网络时间协议(Network Time Protocol,NTP)来同步主机(host)之间的时间。TSDB For InfluxDB®使用主机的本地UTC时间为数据分配时间戳;如果主机的时钟与NTP不同步,写入TSDB For InfluxDB®的数据的时间戳可能会不准确。

数据类型

本节将介绍行协议中主要组成部分的数据类型:measurement、tag key、tag value、field key、field value和时间戳。

measurement、tag key、tag value和field key始终是字符串。

注释:因为TSDB For InfluxDB®将tag value存储为字符串,所以TSDB For InfluxDB®不能对tag value执行数学运算。此外,InfluxQL函数不接受将tag value作为主要参数。当您在设计schema时,最好考虑一下这些细节。

时间戳是UNIX时间戳。最小的有效时间戳是-92233720368547758061677-09-21T00:12:43.145224194Z,最大的有效时间戳是92233720368547758062262-04-11T23:47:16.854775806Z。如上所述,默认情况下,TSDB For InfluxDB®假设时间戳精确到纳秒。关于如何指定其它精度,请查看文档HTTP API

field value可以是浮点数、整数、字符串或者布尔值:

  • 浮点数 - 默认情况下,TSDB For InfluxDB®假设所有数值类型的field value是浮点数。

    将field value 82存储为浮点数:

    1. weather,location=us-midwest temperature=82 1465839830100400200
  • 整数 - 在field value后面加上i,告诉TSDB For InfluxDB®将该数字存储为整数。

    将field value 82存储为整数:

    1. weather,location=us-midwest temperature=82i 1465839830100400200
  • 字符串 - 用双引号把字符串类型的field value括起来(更多关于行协议中引号的介绍,请查看引号的章节)。

    将field value too warm存储为字符串:

    1. weather,location=us-midwest temperature="too warm" 1465839830100400200
  • 布尔值 - 可以使用tTtrueTrueTRUE指定TRUE,使用fFfalseFalseFALSE指定FALSE。

    将field value true存储为布尔值:

    1. weather,location=us-midwest too_hot=true 1465839830100400200

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

在measurement中,一个field的数据类型在一个shard内不会不一致,但是在不同的shard,它的数据类型可以不同。例如,如果TSDB For InfluxDB®尝试将整数存储在与浮点数相同的shard中,那么将整数写入一个之前接受浮点数的field会失败:

  1. > INSERT weather,location=us-midwest temperature=82 1465839830100400200
  2. > INSERT weather,location=us-midwest temperature=81i 1465839830100400300
  3. ERR: {"error":"field type conflict: input field \"temperature\" on measurement \"weather\" is type int64, already exists as type float"}

但是,如果TSDB For InfluxDB®尝试将整数存储在一个新的shard中,那么将整数写入一个之前接受浮点数的field会成功:

  1. > INSERT weather,location=us-midwest temperature=82 1465839830100400200
  2. > INSERT weather,location=us-midwest temperature=81i 1467154750000000000
  3. >

若想了解field value的数据类型差异如何影响SELECT *查询,请查看FAQ的相关章节。

引号

本节将介绍在行协议中,什么时候不能使用双引号(")或单引号('),什么时候应该使用它们。我们先介绍不使用引号的情形,然后再介绍使用引号的情形:

  • 不能用双引号或单引号将时间戳括起来。这是无效的行协议。

    示例:

    1. > INSERT weather,location=us-midwest temperature=82 "1465839830100400200"
    2. ERR: {"error":"unable to parse 'weather,location=us-midwest temperature=82 \"1465839830100400200\"': bad timestamp"}
  • 不能用单引号将field value括起来(即使它们是字符串)。这也是无效的行协议。

    示例:

    1. > INSERT weather,location=us-midwest temperature='too warm'
    2. ERR: {"error":"unable to parse 'weather,location=us-midwest temperature='too warm'': invalid boolean"}
  • 不能用双引号或单引号将measurement的名字、tag key、tag value和field key括起来。虽然这是有效的行协议,但是TSDB For InfluxDB®会把引号当作是名字的一部分。

    示例:

    1. > INSERT weather,location=us-midwest temperature=82 1465839830100400200
    2. > INSERT "weather",location=us-midwest temperature=87 1465839830100400200
    3. > SHOW MEASUREMENTS
    4. name: measurements
    5. ------------------
    6. name
    7. "weather"
    8. weather

    查询在"weather"中的数据,您需要用引号将measurement的名字括起来,并且将measurement中的双引号转义:

    1. > SELECT * FROM "\"weather\""
    2. name: "weather"
    3. ---------------
    4. time location temperature
    5. 2016-06-13T17:43:50.1004002Z us-midwest 87
  • 不能用双引号将字符串类型、整型或布尔类型的field value括起来。否则,TSDB For InfluxDB®会把这些值当作字符串。

    示例:

    1. > INSERT weather,location=us-midwest temperature="82"
    2. > SELECT * FROM weather WHERE temperature >= 70
    3. >
  • 需要用双引号将字符串类型的field value括起来。

    示例:

    1. > INSERT weather,location=us-midwest temperature="too warm"
    2. > SELECT * FROM weather
    3. name: weather
    4. -------------
    5. time location temperature
    6. 2016-06-13T19:10:09.995766248Z us-midwest too warm

特殊字符和关键字

特殊字符

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

  • 逗号 ,

    1. weather,location=us\,midwest temperature=82 1465839830100400200
  • 等号 =

    1. weather,location=us-midwest temp\=rature=82 1465839830100400200
  • 空格

    1. weather,location\ place=us-midwest temperature=82 1465839830100400200

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

  • 逗号 ,

    1. wea\,ther,location=us-midwest temperature=82 1465839830100400200
  • 空格

    1. wea\ ther,location=us-midwest temperature=82 1465839830100400200

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

  • 双引号 "

    1. weather,location=us-midwest temperature="too\"hot\"" 1465839830100400200

行协议不需要用户将反斜杠\转义,但是如果您这样做也没有问题。例如,写入以下数据:

  1. weather,location=us-midwest temperature_str="too hot/cold" 1465839830100400201
  2. weather,location=us-midwest temperature_str="too hot\cold" 1465839830100400202
  3. weather,location=us-midwest temperature_str="too hot\\cold" 1465839830100400203
  4. weather,location=us-midwest temperature_str="too hot\\\cold" 1465839830100400204
  5. weather,location=us-midwest temperature_str="too hot\\\\cold" 1465839830100400205
  6. weather,location=us-midwest temperature_str="too hot\\\\\cold" 1465839830100400206

将会理解为(请注意,用单引号或双引号将反斜杠括起来会产生相同的结果):

  1. > SELECT * FROM "weather"
  2. name: weather
  3. time location temperature_str
  4. ---- -------- ---------------
  5. 1465839830100400201 us-midwest too hot/cold
  6. 1465839830100400202 us-midwest too hot\cold
  7. 1465839830100400203 us-midwest too hot\cold
  8. 1465839830100400204 us-midwest too hot\\cold
  9. 1465839830100400205 us-midwest too hot\\cold
  10. 1465839830100400206 us-midwest too hot\\\cold

所有其它的特殊字符也不需要转义。例如,行协议处理表情符号(emojis)没有问题:

  1. > INSERT we⛅️ther,location=us-midwest temper⛅️ture=82 1465839830100400200
  2. > SELECT * FROM "we⛅️ther"
  3. name: we⛅️ther
  4. ------------------
  5. time location temper⛅️ture
  6. 1465839830100400200 us-midwest 82

关键字

行协议将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获得更多相关信息。

将数据写入TSDB For InfluxDB®

将数据写入数据库

现在您已经知道了关于行协议的所有内容,那么如何使用行协议将数据写入TSDB For InfluxDB®呢?在本节,我们将给出两个简单示例,您可以在工具章节中获取更多信息。

HTTP API

使用HTTP API将数据写入TSDB For InfluxDB®。向/write路径发送POST请求,并在request body中给出行协议数据:

  1. curl -i -XPOST "https://<网络地址>:3242/write?db=science_is_cool&u=<账号名称>&p=<密码>" --data-binary 'weather,location=us-midwest temperature=82 1465839830100400200'

有关查询参数、状态码、响应和更多示例的深入讲解,请查看文档HTTP API

CLI

使用TSDB For InfluxDB®的命令行界面(Command Line Interface,CLI)将数据写入TSDB For InfluxDB®。启动CLI,使用相关的数据库,并且将INSERT放在行协议语句前面:

  1. INSERT weather,location=us-midwest temperature=82 1465839830100400200

您还可以使用CLI导入文件中的数据。

将数据写入TSDB For InfluxDB®的方法有几种,请查看工具章节获取更多相关信息。

重复数据点

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