文档文档

InfluxDB OSS v2

带注释的 CSV

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

CSV 表格必须以 UTF-8 和 Unicode Normal Form C 编码，如 UAX15 中定义的那样。 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

列

除了数据列之外，表格还可以包含以下列

  • 注释列：显示注释的名称。仅在注释行中使用，并且始终是第一列。值可以为空或受支持的注释。响应格式使用逗号 (,) 分隔注释名称和行中的值。为了解决这个问题，表格中的行以一个前导逗号开始；您会注意到表格的整个长度上都有一列为空。
  • 结果列：包含查询指定的结果的名称。
  • 表格列：包含结果中每个表格的唯一 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 格式的以下方言选项。

选项描述默认值
header如果为 true，则包含标题行。true
delimiter用于分隔列的字符。,
quoteChar用于引用包含分隔符的值的字符。"
annotations要编码的注释列表（datatype、group 或 default）。empty
commentPrefix用于标识注释的字符串前缀。始终添加到注释中。#

注释

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

注释名称值描述
datatype数据类型或行协议元素描述列代表的数据类型或行协议元素。
group布尔标志 true 或 false指示列是组键的一部分。
default列数据类型的值用于空值的行的值。

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

要编码带有其组键的表格，必须包含 datatype、group 和 default 注释。如果表格没有行，则 default 注释提供组键值。

数据类型

数据类型Flux 类型描述
booleanbool“true” 或 “false”
unsignedLonguint无符号 64 位整数
longint有符号 64 位整数
doublefloatIEEE-754 64 位浮点数
stringstringUTF-8 编码的字符串
base64Binarybytesbase64 编码的字节序列，如 RFC 4648 中定义
dateTimetime时间瞬间，可以后跟冒号 : 和格式描述（number、RFC3339、RFC3339Nano）
durationduration时间长度，表示为无符号 64 位整数纳秒数

行协议元素

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

行协议元素描述
measurement列值是 measurement
field （默认）列标题是字段键，列值是字段值
tag列标题是标签键，列值是标签值
time列值是时间戳（dateTime 的别名）
ignore 或ignored列被忽略，不包含在行协议中

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

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

时间列

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

时间列值应为 Unix 纳秒时间戳、RFC3339 或 RFC3339Nano。

datatype 注释中的行协议元素示例
#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 注释的错误的编码

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

此页是否对您有帮助？

感谢您的反馈！

© 2025 InfluxData, Inc.

您的 InfluxDB OSS URL 是什么？

自定义您的 InfluxDB OSS URL，我们将为您更新代码示例。

默认值
自定义

有关更多信息，请参阅InfluxDB OSS URL。

感谢您的反馈！

请告诉我们如何做得更好

谢谢！

不用了，谢谢

Flux 的未来

Flux 即将进入维护模式。您可以继续像现在一样使用它，而无需更改任何代码。

阅读更多

现已全面上市

InfluxDB 3 Core 和 Enterprise

快速启动。更快扩展。

获取更新

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

有关更多信息，请查看