扩展的带注释 CSV

扩展的带注释 CSV 提供了额外的注释和选项，用于指定如何将 CSV 数据转换为行协议并写入 InfluxDB。 InfluxDB 使用 csv2lp 库 将 CSV 转换为行协议。扩展的带注释 CSV 支持所有 带注释的 CSV 注释。

要将数据写入 InfluxDB，行协议必须包含以下内容

• measurement（测量）
• field set（字段集）
• timestamp（时间戳） （可选但推荐）
• tag set（标签集） （可选）

扩展的 CSV 注释标识列所代表的行协议元素。

CSV 注释

扩展的带注释 CSV 扩展并添加了以下注释

• datatype（数据类型）
• constant（常量）
• timezone（时区）
• concat（连接）

datatype（数据类型）

使用 #datatype 注释来指定列所代表的 行协议元素。要将列显式定义为特定数据类型的字段，请在注释中使用字段类型（例如：string、double、long 等）。

measurement（测量）

指示列是 measurement（测量）。

tag（标签）

指示列是 tag（标签）。列标签是 tag key（标签键）。列值是 tag value（标签值）。

dateTime（日期时间）

指示列是 timestamp（时间戳）。time 是 dateTime 的别名。如果 时间戳格式 包含时区，则解析的时间戳包含时区偏移量。默认情况下，所有时间戳均为 UTC。您还可以使用 #timezone 注释 将时间戳调整为特定时区。

influx write 命令将时间戳转换为 Unix 时间戳。将时间戳格式附加到带有冒号 (:) 的 dateTime 数据类型。

#datatype dateTime:RFC3339
#datatype dateTime:RFC3339Nano
#datatype dateTime:number
#datatype dateTime:2006-01-02

支持的时间戳格式

自定义时间戳格式

要指定自定义时间戳格式，请使用 Go time 包 中描述的时间戳格式。例如：2020-01-02。

field（字段）

指示列是 field（字段）。列标签是 field key（字段键）。列值是 field value（字段值）。

ignored（忽略）

该列将被忽略，不会写入 InfluxDB。

字段类型

列是指定类型的 field（字段）。列标签是 field key（字段键）。列值是 field value（字段值）。

• string（字符串）
• double（双精度浮点数）
• long（长整型）
• unsignedLong（无符号长整型）
• boolean（布尔型）

string（字符串）

列是 string field（字符串字段）。

double（双精度浮点数）

列是 float field（浮点数字段）。默认情况下，InfluxDB 期望浮点数值使用句点 (.) 来分隔小数部分和整数部分。如果列值包含或使用其他分隔符，例如逗号 (,) 以在视觉上将大数字分成组，请指定以下浮点数分隔符

• fraction separator（小数分隔符）：分隔小数部分和整数部分。
• ignored separator（忽略的分隔符）：在视觉上将整数部分分成组，但在解析浮点数值时忽略该分隔符。

使用以下语法来指定浮点数分隔符

# Syntax
<fraction-separator><ignored-separator>

# Example
.,

# With the float separators above
# 1,200,000.15 => 1200000.15

使用冒号 (:) 将浮点数分隔符附加到 double 数据类型注释。例如

#datatype "double:.,"

long（长整型）

列是 integer field（整数字段）。如果列值包含分隔符，例如句点 (.) 或逗号 (,)，请指定以下整数分隔符

• fraction separator（小数分隔符）：分隔小数部分和整数部分。转换为行协议时，整数值会在小数分隔符处被截断。
• ignored separator（忽略的分隔符）：在视觉上将整数部分分成组，但在解析整数值时忽略该分隔符。

使用以下语法来指定整数分隔符

# Syntax
<fraction-separator><ignored-separator>

# Example
.,

# With the integer separators above
# 1,200,000.00 => 1200000i

使用冒号 (:) 将整数分隔符附加到 long 数据类型注释。例如

#datatype "long:.,"

unsignedLong（无符号长整型）

列是 unsigned integer (uinteger) field（无符号整数字段）。如果列值包含分隔符，例如句点 (.) 或逗号 (,)，请指定以下无符号整数分隔符

• fraction separator（小数分隔符）：分隔小数部分和整数部分。转换为行协议时，无符号整数值会在小数分隔符处被截断。
• ignored separator（忽略的分隔符）：在视觉上将整数部分分成组，但在解析无符号整数值时忽略该分隔符。

使用以下语法来指定无符号整数分隔符

# Syntax
<fraction-separator><ignored-separator>

# Example
.,

# With the uinteger separators above
# 1,200,000.00 => 1200000u

使用冒号 (:) 将无符号整数分隔符附加到 long 数据类型注释。例如

#datatype "unsignedLong:.,"

boolean（布尔型）

列是 boolean field（布尔字段）。如果列值不是 支持的布尔值，请使用以下语法指定布尔格式

# Syntax
<true-values>:<false-values>

# Example
y,Y,1:n,N,0

# With the boolean format above
# y => true, Y => true, 1 => true
# n => false, N => false, 0 => false

使用冒号 (:) 将布尔格式附加到 boolean 数据类型注释。例如

#datatype "boolean:y,Y:n,N"

constant（常量）

使用 #constant 注释为每一行定义常量列标签和值。#constant 注释提供了一种提供 行协议元素 的方法，这些元素在 CSV 数据中不存在。

使用以下语法来定义常量

#constant <datatype>,<column-label>,<column-value>

要提供多个常量，请在单独的行上包含每个 #constant 注释。

#constant measurement,m
#constant tag,dataSource,csv

timezone（时区）

使用 #timezone 注释将时间戳更新为特定时区。默认情况下，时间戳被解析为 UTC。使用 ±HHmm 格式来指定相对于 UTC 的时区偏移量。

严格模式

使用 :strict 关键字来指示在解析 long 或 unsignedLong 数据类型时精度会降低。通过使用以 strict 结尾的列数据类型来启用严格模式，例如 long:strict。当从带有小数位数的字符串值解析 long 或 unsignedLong 值时，如果处于严格模式，则整个 CSV 行将失败。如果未处于严格模式，则会打印警告，提示 line x: column y: '1.2' truncated to '1' to fit into long data type。有关严格解析的更多信息，请参阅 包文档。

时区示例

时区注释示例

#timezone -0600

concat（连接）

#concat 注释添加一个新列，该列根据类似 bash 的字符串插值文字，使用引用现有列标签的变量，从现有列连接而成。

例如

#concat,string,fullName,${firstName} ${lastName}

当从多列构建时间戳时，这尤其有用。例如，以下注释将把给定的 CSV 列组合成一个时间戳

#concat,dateTime:2006-01-02,${Year}-${Month}-${Day}

Year,Month,Day,Hour,Minute,Second,Tag,Value
2020,05,22,00,00,00,test,0
2020,05,22,00,05,00,test,1
2020,05,22,00,10,00,test,2

定义自定义列分隔符

如果列使用逗号以外的字符分隔，请使用 sep 关键字在 CSV 文件的第一行中定义自定义分隔符。

sep=;

注释速记

扩展的带注释 CSV 支持注释速记。使用以下语法在每个列标题行中包含列标签、数据类型和（可选）默认值

<column-label>|<column-datatype>|<column-default-value>

注释速记示例

m|measurement,location|tag|Hong Kong,temp|double,pm|long|0,time|dateTime:RFC3339
weather,San Francisco,51.9,38,2020-01-01T00:00:00Z
weather,New York,18.2,,2020-01-01T00:00:00Z
weather,,53.6,171,2020-01-01T00:00:00Z

速记解释

• m 列代表测量，没有默认值。
• location 列是一个 tag，默认值为 Hong Kong。
• temp 列是一个 field，具有 float (double) 值，没有默认值。
• pm 列是一个 field，具有 integer (long) 值，默认值为 0。
• time 列代表时间戳，使用 RFC3339 时间戳格式，没有默认值。

生成的行协议

weather,location=San\ Francisco temp=51.9,pm=38i 1577836800000000000
weather,location=New\ York temp=18.2,pm=0i 1577836800000000000
weather,location=Hong\ Kong temp=53.6,pm=171i 1577836800000000000