Documentation

Line protocol

InfluxDB 使用 Line Protocol 写入数据点。它是一种基于文本的格式,提供数据点的 measurement、tag set、field set 和 timestamp。

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

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

以换行符 \n 分隔的行表示 InfluxDB 中的单个点。Line Protocol 对空格敏感。

Line Protocol 不支持标签或字段值中的换行符 \n

Line Protocol 的元素

myMeasurement,tag1=val1,tag2=val2 field1="v1",field2=1i 0000000000000000000

Measurement

(必需) measurement 名称。InfluxDB 每个点接受一个 measurement。Measurement 名称区分大小写,并受命名限制约束。

数据类型: String

Tag set

可选 – 点的所有标签键值对。键值关系用 = 运算符表示。多个标签键值对用逗号分隔。标签键和标签值区分大小写。标签键受命名限制约束。标签值不能为空;相反,请从标签集中省略该标签。

键数据类型: String
值数据类型: String

Field set

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

键数据类型: String
值数据类型: Float | Integer | UInteger | String | Boolean

始终使用双引号引用字符串字段值。有关引号的更多信息,请参见下方

measurementName fieldKey="field string value" 1556813561098000000

Timestamp

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

数据类型: Unix 时间戳

关于时间戳的重要说明

  • 为确保数据点包含观察到指标的时间(而不是 InfluxDB 接收到的时间),请包含时间戳。
  • 如果您的时间戳不是纳秒,请在将数据写入 InfluxDB 时指定时间戳的精度。

空格

Line Protocol 中的空格决定了 InfluxDB 如何解释数据点。第一个未转义的空格分隔 measurement 和 tag set 与 field set。第二个未转义的空格分隔 field set 与 timestamp。

myMeasurement,tag1=val1,tag2=val2 field1="v1",field2=1i 0000000000000000000

数据类型和格式

Float

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

浮点字段值示例
myMeasurement fieldKey=1.0
myMeasurement fieldKey=1
myMeasurement fieldKey=-1.234456e+78

Integer

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

最小整数最大整数
-9223372036854775808i9223372036854775807i
整数字段值示例
myMeasurement fieldKey=1i
myMeasurement fieldKey=12485903i
myMeasurement fieldKey=-12485903i

UInteger

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

最小无符号整数最大无符号整数
0u18446744073709551615u
无符号整数字段值示例
myMeasurement fieldKey=1u
myMeasurement fieldKey=12485903u

String

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

字符串示例
# String measurement name, field key, and field value
myMeasurement fieldKey="this is a string"

Boolean

存储 truefalse 值。

布尔值接受的语法
TruetTtrueTrueTRUE
FalsefFfalseFalseFALSE
布尔字段值示例
myMeasurement fieldKey=true
myMeasurement fieldKey=false
myMeasurement fieldKey=t
myMeasurement fieldKey=f
myMeasurement fieldKey=TRUE
myMeasurement fieldKey=FALSE

不要引用布尔字段值。带引号的字段值被解释为字符串。

Unix 时间戳

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

最小时间戳最大时间戳
-92233720368547758069223372036854775806
Unix 时间戳示例
myMeasurementName fieldKey="fieldValue" 1556813561098000000

引号

Line Protocol 支持单引号和双引号,如下表所述

元素双引号单引号
Measurement有限 *有限 *
标签键有限 *有限 *
标签值有限 *有限 *
字段键有限 *有限 *
字段值仅限字符串从不
Timestamp从不从不

* Line Protocol 接受 measurement 名称、标签键、标签值和字段键中的双引号和单引号,但将其解释为名称、键或值的一部分。

特殊字符

Line Protocol 支持字符串元素中的特殊字符。在以下上下文中,它需要使用反斜杠 (\) 转义某些字符

元素转义字符
Measurement逗号、空格
标签键逗号、等号、空格
标签值逗号、等号、空格
字段键逗号、等号、空格
字段值双引号、反斜杠

您不需要转义其他特殊字符。

Line Protocol 中特殊字符的示例
# Measurement name with spaces
my\ Measurement fieldKey="string value"

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

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

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

转义反斜杠

Line Protocol 同时支持文字反斜杠和作为转义字符的反斜杠。对于两个连续的反斜杠,第一个被解释为转义字符。例如

反斜杠解释为
\\
\\\
\\\\\
\\\\\\
\\\\\\\\
\\\\\\\\\

注释

Line Protocol 将行首的 # 解释为注释字符,并忽略直到下一个换行符 \n 的所有后续字符。

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

命名限制

Measurement 名称、标签键和字段键不能以下划线 _ 开头。_ 命名空间保留供 InfluxDB 系统使用。

重复点

一个点由 measurement 名称、tag set 和 timestamp 唯一标识。如果您提交具有相同 measurement、tag set 和 timestamp 但具有不同 field set 的 Line Protocol,则 field set 将变为旧 field set 和新 field set 的并集,其中任何冲突都偏向于新 field set。


此页面是否对您有帮助?

感谢您的反馈!


Flux 的未来

Flux 即将进入维护模式。您可以继续像当前一样使用它,而无需对代码进行任何更改。

阅读更多

现已全面上市

InfluxDB 3 Core 和 Enterprise

快速启动。更快扩展。

获取更新

InfluxDB 3 Core 是一个开源、高速、最近数据引擎,可实时收集和处理数据,并将其持久化到本地磁盘或对象存储。InfluxDB 3 Enterprise 构建在 Core 的基础上,增加了高可用性、读取副本、增强的安全性以及数据压缩,从而实现更快的查询和优化的存储。InfluxDB 3 Enterprise 的免费层可供非商业家庭或业余爱好者使用。

有关更多信息,请查看