扩展注解 CSV

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

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

• 测量
• 字段集
• 时间戳 （可选但推荐）
• 标签集 （可选）

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

CSV 注释

扩展带注释的 CSV 增加了以下注释

• 数据类型
• 常量
• 时区
• 连接

数据类型

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

测量

表示该列是 测量。

标签

表示该列是 标签。 列标签 是 标签键。 列值 是 标签值。

dateTime

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

influx write 命令将时间戳转换为 Unix 时间戳。将时间戳格式附加到 dateTime 数据类型后跟 (:)。

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

支持的日期时间格式

自定义日期时间格式

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

字段

表示该列是 字段。 列标签 是 字段键。 列值 是 字段值。

忽略

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

字段类型

列是特定类型的 字段。列 标签 是字段 键。列 值 是字段 值。

• string
• double
• long
• unsignedLong
• boolean

string

列是 字符串 字段。

double

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

• 小数分隔符：分隔小数和整数。
• 忽略的分隔符：视觉上分隔整数成组，但在解析浮点值时忽略分隔符。

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

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

# Example
.,

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

将 浮点分隔符 添加到 double 数据类型注解中，后面跟一个冒号 (:)。例如

#datatype "double:.,"

long

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

• 小数分隔符：分隔小数和整数。整数值在转换为行协议时在小数分隔符处截断。
• 忽略的分隔符：视觉上分隔整数成组，但在解析整数值时忽略分隔符。

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

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

# Example
.,

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

将 整数分隔符 添加到 long 数据类型注解中，后面跟一个冒号 (:)。例如

#datatype "long:.,"

unsignedLong

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

• 小数分隔符：分隔小数和整数。Uinteger 值在转换为行协议时在小数分隔符处截断。
• 忽略的分隔符：视觉上分隔整数成组，但在解析 uinteger 值时忽略分隔符。

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

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

# Example
.,

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

将 uinteger 分隔符 添加到 long 数据类型注解中，后面跟一个冒号 (:)。例如

#datatype "unsignedLong:.,"

boolean

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

# 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注释提供了一种提供CSV数据中不存在的行协议元素的方法。

使用以下语法定义常量

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

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

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

时区

使用#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注释通过使用引用现有列标签的变量进行bash-like字符串插值文本添加新列。

例如

#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

定义自定义列分隔符

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

sep=;

注释简写

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

<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列代表measurement，没有默认值。
• location列是一个tag，默认值为Hong Kong。
• temp列是一个field，具有float（double）值，没有默认值。
• pm列是一个field，具有integer（long）值，默认为0。
• time列代表timestamp，使用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