行协议参考

InfluxDB 3 Core 使用行协议写入数据点。这是一种基于文本的格式，可提供数据点的表、标签集、字段集和时间戳。

• 行协议的组成部分
• 数据类型和格式
• 引号
• 特殊字符
• 注释
• 命名限制
• 重复的点

// Syntax
<table>[,<tag_key>=<tag_value>[,<tag_key>=<tag_value>]] <field_key>=<field_value>[,<field_key>=<field_value>] [<timestamp>]

// Example
myTable,tag1=value1,tag2=value2 fieldKey="fieldValue" 1556813561098000000

以换行符 \n 分隔的行代表 InfluxDB 中的一个点。行协议对空格敏感。

行协议的组成部分

表

(必需) 表名。InfluxDB 每个点接受一个表。表名区分大小写，并受 命名限制 的约束。

数据类型： 字符串

标签集

(可选) 点的所有标签键值对。键值关系用 = 操作符表示。多个标签键值对用逗号分隔。标签键和标签值区分大小写。标签键受 命名限制 的约束。标签值不能为空；如果标签值为空，请从标签集中省略该标签。

键数据类型： 字符串
值数据类型： 字符串

字段集

(必需) 点的所有字段键值对。点必须至少有一个字段。字段键和字符串值区分大小写。字段键受 命名限制 的约束。

键数据类型： 字符串
值数据类型： 浮点数 | 整数 | 无符号整数 | 字符串 | 布尔值

tableName fieldKey="field string value" 1556813561098000000

Timestamp

(可选) 数据点的 Unix 时间戳。InfluxDB 每个点接受一个时间戳。如果未提供时间戳，InfluxDB 将使用其主机系统的当前时间（UTC）。

数据类型： Unix 时间戳

空格

行协议中的空格决定了 InfluxDB 如何解释数据点。第一个未转义的空格分隔表和标签集与字段集。第二个未转义的空格分隔字段集与时间戳。

数据类型和格式

浮点数

IEEE-754 64 位浮点数。默认数值类型。InfluxDB 支持浮点数字段值中的科学计数法。

浮点数字段值示例

myTable fieldKey=1.0
myTable fieldKey=1
myTable fieldKey=-1.234456e+78

整数

带符号 64 位整数。数字后面的 i 指定整数。

整数数字段值示例

myTable fieldKey=1i
myTable fieldKey=12485903i
myTable fieldKey=-12485903i

无符号整数

无符号 64 位整数。数字后面的 u 指定无符号整数。

无符号整数数字段值示例

myTable fieldKey=1u
myTable fieldKey=12485903u

字符串

纯文本字符串。长度限制为 64KB。

字符串示例

# String table name, field key, and field value
myTable fieldKey="this is a string"

布尔值

存储 true 或 false 值。

布尔数字段值示例

myTable fieldKey=true
myTable fieldKey=false
myTable fieldKey=t
myTable fieldKey=f
myTable fieldKey=TRUE
myTable fieldKey=FALSE

Unix 时间戳

以 指定精度表示的 Unix 时间戳。默认精度为纳秒 (ns)。

Unix 时间戳示例

myTableName fieldKey="fieldValue" 1556813561098000000

引号

行协议支持如下表所述的单引号和双引号。

^* 行协议接受表名、标签键、标签值和字段名中的双引号和单引号，但将其解释为名称、键或值的一部分。

特殊字符

行协议支持 字符串元素 中的特殊字符。在以下上下文中，它要求用反斜杠 (\) 转义某些字符

您无需转义其他特殊字符。

行协议中特殊字符的示例

# Table name with spaces
my\ Table fieldKey="string value"

# Double quotes in a string field value
myTable fieldKey="\"string\" within a string"

# Tag keys and values with spaces
myTable,tag\ Key1=tag\ Value1,tag\ Key2=tag\ Value2 fieldKey=100

# Emojis
myTable,tagKey=🍭 fieldKey="Launch 🚀" 1556813561098000000

转义反斜杠

行协议支持字面意义上的反斜杠和作为转义字符的反斜杠。使用两个连续的反斜杠时，第一个被解释为转义字符。例如

注释

行协议将行开头的 # 解释为注释字符，并忽略该行之后的所有字符，直到下一个换行符 \n。

# This is a comment
myTable fieldKey="string value" 1556813561098000000

命名限制

表名、标签键和字段键是字母数字的，并且必须以字母或数字开头。它们可以包含连字符 (-) 和下划线 (_)。

重复的点

一个点由表名、标签集和时间戳唯一标识。如果您提交的行协议具有相同的表、标签集和时间戳，但具有不同的字段集，则字段集将成为旧字段集和新字段集的并集，其中任何冲突都以新字段集为准。