Extended annotated CSV （扩展的带注解的 CSV）

Extended annotated 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 注解来指定列代表的 行协议元素。 要显式地将列定义为特定数据类型的 field（字段），请在注解中使用字段类型（例如：string，double，long 等）。

measurement （测量名称）

Indicates the column is the measurement（表示该列是测量名称）。

tag （标签）

Indicates the column is a tag（表示该列是一个标签）. The column label（列标签） is the tag key（标签键）. The column value（列值） is the tag value（标签值）.

dateTime （日期时间）

Indicates the column is the timestamp（表示该列是时间戳）. time is an alias for dateTime（time 是 dateTime 的别名）. If the timestamp format（时间戳格式） includes a time zone, the parsed timestamp includes the time zone offset（如果时间戳格式包含时区，则解析后的时间戳包含时区偏移量）. By default, all timestamps are UTC（默认情况下，所有时间戳都是 UTC）. You can also use the #timezone annotation（#timezone 注解） to adjust timestamps to a specific time zone（来将时间戳调整为特定的时区）.

The influx write command converts timestamps to Unix timestamps（Unix 时间戳）. Append the timestamp format to the dateTime datatype with (:)（使用 (:) 将时间戳格式附加到 dateTime 数据类型）.

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

Supported timestamp formats（支持的时间戳格式）

Custom timestamp formats（自定义时间戳格式）

To specify a custom timestamp format, use timestamp formats as described in the Go time package（Go time 包）. For example: 2020-01-02.

field （字段）

Indicates the column is a field（表示该列是一个字段）. The column label（列标签） is the field key（字段键）. The column value（列值） is the field value（字段值）.

ignored （忽略）

The column is ignored and not written to InfluxDB（该列被忽略，不会写入 InfluxDB）.

Field types（字段类型）

The column is a field（表示该列是一个字段） of a specified type. The column label（列标签） is the field key（字段键）. The column value（列值） is the field value（字段值）.

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

string （字符串）

Column is a string field（字符串字段）.

double （双精度浮点数）

Column is a float field（浮点数字段）. By default, InfluxDB expects float values that use a period (.) to separate the fraction from the whole number（默认情况下，InfluxDB 期望浮点数值使用句点 (.) 来分隔小数部分和整数部分）. If column values include or use other separators, such as commas (,) to visually separate large numbers into groups, specify the following float separators（浮点数分隔符）

• fraction separator（小数分隔符）: Separates the fraction from the whole number（将小数部分与整数部分分隔开）.
• ignored separator（忽略分隔符）: Visually separates the whole number into groups but ignores the separator when parsing the float value（在视觉上将整数部分分成组，但在解析浮点值时忽略该分隔符）.

Use the following syntax to specify float separators（浮点数分隔符）

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

# Example
.,

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

Append float separators（浮点数分隔符） to the double datatype annotation with a colon (:)（使用冒号 (:) 将 float separators（浮点数分隔符） 附加到 double 数据类型注解）. For example

#datatype "double:.,"

long （长整型）

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

• 小数分隔符：将小数部分与整数部分分隔开。当转换为行协议时，整数值会在小数分隔符处被截断。
• 忽略分隔符：在视觉上将整数分成组，但在解析整数值时忽略该分隔符。

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

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

# Example
.,

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

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

#datatype "long:.,"

unsignedLong （无符号长整型）

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

• 小数分隔符：将小数部分与整数部分分隔开。当转换为行协议时，无符号整数值会在小数分隔符处被截断。
• 忽略分隔符：在视觉上将整数分成组，但在解析无符号整数值时忽略该分隔符。

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

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

# Example
.,

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

将无符号整数分隔符附加到带有冒号 (:) 的 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 注释为每一行定义一个常量列标签和值。 #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 列表示measurement，没有默认值。
• 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