带注释的CSV

InfluxDB /api/v2/query API 以注释的 CSV 格式返回查询结果。 您还可以使用注释的 CSV 和 influx write 命令向 InfluxDB 写入数据， 或在 InfluxDB UI 中 上传 CSV 文件。

CSV 表格必须使用 UTF-8 编码，并按照 UAX15 中定义的 Unicode 正规化形式 C 编码。InfluxDB 在换行符之前会移除回车符。

CSV 响应格式

InfluxDB 注释的 CSV 支持以下列出的编码。

表格

一个表可能有以下行和列。

行

• 注释行: 描述列属性。
• 标题行: 定义列标签（每个表一个标题行）。
• 记录行: 描述表中的数据（每行一个记录）。

示例

#group,false,false,true,true,false,false,true,true,true,true
#datatype,string,long,dateTime:RFC3339,dateTime:RFC3339,dateTime:RFC3339,double,string,string,string,string
#default,mean,,,,,,,,,
,result,table,_start,_stop,_time,_value,_field,_measurement,host,region
,,0,2022-12-31T05:41:24Z,2023-01-31T05:41:24.001Z,2023-01-01T00:52:00Z,15.43,mem,m,A,east
,,1,2022-12-31T05:41:24Z,2023-01-31T05:41:24.001Z,2023-01-01T00:52:00Z,59.25,mem,m,B,east
,,2,2022-12-31T05:41:24Z,2023-01-31T05:41:24.001Z,2023-01-01T00:52:00Z,52.62,mem,m,C,east

列

除了数据列，表格可能还包括以下列：

• 注释列: 显示注释的名称。 仅在注释行中使用，并始终是第一列。 值可以为空或是一个支持的 annotation。 响应格式使用逗号 (,) 来分隔注释名称与行中的值。 为此，表中的行以一个前导逗号开始；您会注意到整张表的长度都有一个空列。
• 结果列: 包含查询指定的结果名称。
• 表列: 包含结果中每个表的唯一ID。

多个表和结果

如果一个文件或数据流包含多个表或结果，则必须满足以下要求：

• 表格列指示一行属于哪个表。
• 表中的所有行都是连续的。
• 空行在以下情况下划定新的表边界：
  • 在结果中不共享公共表模式的表之间。
  • 在连接的CSV文件之间。
• 每个新表的边界都以新的注释和标题行开始。

示例

#group,false,false,true,true,false,false,true,true,true,true
#datatype,string,long,dateTime:RFC3339,dateTime:RFC3339,dateTime:RFC3339,double,string,string,string,string
#default,_result,,,,,,,,,
,result,table,_start,_stop,_time,_value,_field,_measurement,host,region
,,0,2022-12-31T05:41:24Z,2023-01-31T05:41:24.001Z,2023-01-01T00:00:00Z,15.43,mem,m,A,east
,,1,2022-12-31T05:41:24Z,2023-01-31T05:41:24.001Z,2023-01-01T00:00:00Z,59.25,mem,m,B,east
,,2,2022-12-31T05:41:24Z,2023-01-31T05:41:24.001Z,2023-01-01T00:00:00Z,52.62,mem,m,C,east

#group,false,false,true,true,true,true,false,false,true,true
#datatype,string,long,string,string,dateTime:RFC3339,dateTime:RFC3339,dateTime:RFC3339,string,string,string
#default,_result,,,,,,,,,
,result,table,_field,_measurement,_start,_stop,_time,_value,host,region
,,3,mem_level,m,2022-12-31T05:41:24Z,2023-01-31T05:41:24.001Z,2023-01-01T00:00:00Z,ok,A,east
,,4,mem_level,m,2022-12-31T05:41:24Z,2023-01-31T05:41:24.001Z,2023-01-01T00:00:00Z,info,B,east
,,5,mem_level,m,2022-12-31T05:41:24Z,2023-01-31T05:41:24.001Z,2023-01-01T00:00:00Z,info,C,east

方言选项

Flux支持以下方言选项用于 text/csv 格式。

注释

注释行描述列属性，且以 #（或 commentPrefix 值）开头。 注释行中的第一列始终包含注释名称。 后续列包含注释值，如下表所示。

某些工具可能使用或需要逗号 (,) 来分隔注释名称和注释行中的值。

数据类型

行协议元素

datatype 注释接受 数据类型 和 线协议元素。 线协议元素标识在使用 influx write 命令 将注释的 CSV 写入 InfluxDB 时，列是如何转换为线协议的。

混合数据类型和行协议元素

带有 数据类型 （除了 dateTime）的列在 #datatype 注释中被视为 字段，当转换为行协议时。没有指定数据类型的列在转换为行协议时默认为 field，并且 列值在行协议中保持不变。请参见下面的示例 和 行协议数据类型和格式。

时间列

带有 time 或 dateTime #datatype 注释的列被用作行协议中的时间戳。 如果有多个 time 或 dateTime 列，则最后一列（右侧）被用作行协议中的时间戳。 其他时间列将被忽略，influx write 命令会输出警告。

时间列的值应该是 Unix 纳秒时间戳、 RFC3339 或 RFC3339Nano。

数据类型注解中的示例行协议元素

#group false,false,false,false,false,false,false
#datatype measurement,tag,tag,field,field,ignored,time
#default ,,,,,,
m,cpu,host,time_steal,usage_user,nothing,time
cpu,cpu1,host1,0,2.7,a,1482669077000000000
cpu,cpu1,host2,0,2.2,b,1482669087000000000

结果行协议：

cpu,cpu=cpu1,host=host1 time_steal=0,usage_user=2.7 1482669077000000000
cpu,cpu=cpu1,host=host2 time_steal=0,usage_user=2.2 1482669087000000000

混合数据类型和行协议元素的示例

#group,false,false,false,false,false,false,false,false,false
#datatype,measurement,tag,string,double,boolean,long,unsignedLong,duration,dateTime
#default,test,annotatedDatatypes,,,,,,
,m,name,s,d,b,l,ul,dur,time
,,,str1,1.0,true,1,1,1ms,1
,,,str2,2.0,false,2,2,2us,2020-01-11T10:10:10Z

结果行协议：

test,name=annotatedDatatypes s="str1",d=1,b=true,l=1i,ul=1u,dur=1000000i 1
test,name=annotatedDatatypes s="str2",d=2,b=false,l=2i,ul=2u,dur=2000i 1578737410000000000

错误

如果在执行过程中发生错误，将返回一个表格，内容包括：

• 包含错误信息的错误列。
• 一个具有唯一引用代码的参考列，用于识别错误的更多信息。
• 第二行包含错误属性。

如果发生错误：

• 在InfluxDB响应数据之前，HTTP状态代码指示一个错误。输出表包含错误详情。
• 在InfluxDB将部分结果发送给客户端后，错误编码为下一个表格，剩余结果将被丢弃。在这种情况下，HTTP状态码仍然是200 OK。

示例

带有数据类型注释的错误的编码：

#datatype,string,long
,error,reference
,Failed to parse query,897