InfluxDB原理与实战最新章节_韩健著

3.2　写入

InfluxDB写操作支持简明的行协议（Line Protocol），行协议是一种基于文本格式的协议。

注意基于兼容开放和生态的考虑，除了行协议，InfluxDB还支持CollectD、Graphite、OpenTSDB、Prometheus、UDP等第三方协议，第三方协议将会在第8章详细介绍。

3.2.1　行协议

1.行协议语法

行协议的单行文本表示一条时序数据，由表、标签集、指标集和时间戳4部分组成，行协议的基本语法如代码清单3-10所示。

代码清单3-10　行协议基本语法

<measurement>[,<tag-key>=<tag-value>...] <field-key>=<field-value>[,<field2-key>=<field2-value>...] [timestamp]

标签对“tag-key=tag-value”分别是标签键和标签值，用于创建索引，提高查询性能。标签键和标签值都要求是字符串，该数据保存在META节点中。

指标对“field-key=field-value”分别是指标键和指标值，不会被索引，一般存放的是具体的时序数据，即随着时间戳的变化而变化的数据。指标键要求是字符串，而指标值可以为字符串类型、浮点型、整型或布尔型数据。

timestamp，可选参数，纳秒级精度的时间戳，如果没有该参数，InfluxDB将采用数据写入时间为时间戳。

行协议各参数的填写要求和支持的数据类型如表3-4所示。

表3-4　行协议参数清单

2.数据类型

行协议中不同的字段支持不同的数据类型，具体的数据类型和字段关系如表3-5所示。

表3-5　数据类型与字段

3.特殊符号

行协议中一些字段对某些特殊符号较敏感，当需要使用这些敏感符号作为字段的一部分时，需要在这些特殊符号前加反斜杠（\）进行转义处理，具体的特殊符号如表3-6所示。

表3-6　特殊符号

注意

·行协议对空格敏感，标签集和指标集中间必须有空格。

·时间戳参数不可以加引号，否则会报错。

·指标值支持字符串类型，要使用双引号将字符串类型的指标值括起来；但对于非字符串类型的指标值，要注意不能加引号，否则会被当成字符串类型来处理。

4.保留字和命名规范

须避免在表名或字段名中使用InfluxDB的保留字，具体的保留字信息如表3-7所示。

表3-7　保留字

另外，关键字“time”是一个特殊的保留字，“time”不可以用作标签键和指标键的命名，但可以用作其他命名，如表的命名、保留策略的命名等。

另外，除了时间戳字段，其他字段如表、标签键、标签值、指标键、指标值，是大小写敏感的。

3.2.2　写入数据

在写入数据前，首先要指定写入哪个数据库，可通过use命令指定相应的写入数据库，如代码清单3-11所示。

代码清单3-11　通过use命令指定写入数据库

use <database>

与MySQL等传统数据库不同的是，InfluxDB不需要显式地创建新表，当使用insert语句插入数据时，InfluxDB会自动根据insert数据的格式和指定的表名自动创建新表。

1.写入数据

在实际应用中，往往通过InfluxDB API写入时序数据。我们可以通过InfluxDB API写入一条时序数据，也可以同时写入多条时序数据，InfluxDB API的写入语法如代码清单3-12所示。

代码清单3-12　InfluxDB API写入语法

curl -ig http://HOST:PORT/write?db=<database> -d "<line_protocol_expression>
<line_protocol_expression>
<line_protocol_expression>
……
"

其中，line_protocol_expression表示行协议格式的时序数据，每条时序数据之间使用换行符分隔。

例3.16 同时向monitor数据库写入两条时序数据，server1机器的CPU使用率和内存使用率如下。

$ curl -g http://localhost:8086/write?db=monitor -d "cpu_usage,hostname=server1 percent=26.9,core=4 1566870620000000000
> mem_usage,hostname=server1 percent=38.733,value=298867542 1566870620000000000"
$

注意如果写入数据时没带上时间戳，InfluxDB会默认使用本地UTC纳秒时间作为写入数据的时间，当需要同时向同一个数据库同一个时间序列线写入多条数据时，每条数据都需要带时间戳，否则后写的数据会覆盖前面的数据。

2.文件数据导入

InfluxDB支持以文件的形式导入时序数据，支持两种写入方式：InfluxDB API导入和influx-import导入。

（1）InfluxDB API导入

InfluxDB API支持导入内容为行协议格式时序数据的文本文件，导入语法如代码清单3-13所示。

代码清单3-13　InfluxDB API导入基本语法

curl -ig http://HOST:PORT/write?db=<database> --data-binary @<file>

其中“<file>”参数表示导入文件的存储路径。

例3.17 将server1和server2某一天的内存监控数据（1分钟粒度）通过InfluxDB API导入monitor数据库。

$ cat mem_usage.txt
mem_usage,hostname=server1,region=us-west percent=26.79,value=2151672 1566846060000000000
mem_usage,hostname=server1,region=us-west percent=38.21,value=3068883 1566846120000000000
mem_usage,hostname=server1,region=us-west percent=42.66,value=3426290 1566846180000000000
mem_usage,hostname=server2,region=cn-sz percent=6.9,value=554182 1566846060000000000
mem_usage,hostname=server2,region=cn-sz percent=8.1,value=650561 1566846120000000000
mem_usage,hostname=server2,region=cn-sz percent=4.6,value=369454 1566846180000000000
$ curl -g http://localhost:8086/write?db=monitor --data-binary @./mem_usage.txt

注意

·默认情况下，InfluxDB API的超时时间为5秒，超时之后InfluxDB仍然会继续将数据写完，但请求方由于已经超时无法知道数据最终是否写入成功。

·当写入数据超过5000个的时候，应使用多次HTTP请求分批写入数据。

（2）influx-import导入

influx-import命令在导入功能上比InfluxDB API更加丰富强大，导入文件的内容包含两个部分：

·DDL（数据定义语言）：包含用于管理数据库和保留策略的InfluxQL命令，如果不需要可以跳过此部分。

·DML（数据操作语言）：指定写入数据的数据库及保留策略，使用行协议写入数据。在DDL部分，除了可以执行一些数据库管理的InfluxQL之外，还可以做一些保留策略的操作，如创建一个新的保留策略，并在DML指定引用。

例3.18 将server1和server2某一天的CPU监控数据（1分钟粒度）通过influx-import命令导入monitor数据库。

$ cat cpu_usage.txt
# DDL

CREATE DATABASE monitor



# DML

# CONTEXT-DATABASE: monitor

# CONTEXT-RETENTION-POLICY: autogen

cpu_usage,hostname=server1,region=us-west percent=25.65,core=4 1566846060000000000
cpu_usage,hostname=server1,region=us-west percent=26.91,core=4 1566846120000000000
cpu_usage,hostname=server1,region=us-west percent=35.49,core=4 1566846180000000000
cpu_usage,hostname=server2,region=cn-sz percent=5.65,core=4 1566846060000000000
cpu_usage,hostname=server2,region=cn-sz percent=6.91,core=4 1566846120000000000
cpu_usage,hostname=server2,region=cn-sz percent=5.49,core=4 1566846180000000000

$ influx -import -path=./cpu_usage.txt
2019/08/27 10:22:57 Processed 1 commands
2019/08/27 10:22:57 Processed 6 inserts
2019/08/27 10:22:57 Failed 0 inserts

注意

·当数据量比较大时，influx-import每插入100000条数据会输出一次执行状态日志。

·使用“-compressed”参数可以导入gz压缩文件中的时序数据。

3.2 写入

3.2.1 行协议