带注释的 CSV (Annotated CSV)
InfluxDB 的 /api/v2/query API 以带注释的 CSV 格式返回查询结果。 您还可以使用带注释的 CSV 和 influx write 命令将数据写入 InfluxDB，或在 InfluxDB UI 中上传 CSV 文件。
CSV 表格必须以 UTF-8 编码和 Unicode Normal Form C（如 UAX15 中定义）编码。 InfluxDB 会在换行符之前删除回车符。
CSV 响应格式 (CSV response format)
InfluxDB 带注释的 CSV 支持以下列出的编码。
表格 (Tables)
表格可以包含以下行和列。
行 (Rows)
- 注释行 (Annotation rows)：描述列属性。
- 标题行 (Header row)：定义列标签（每个表格一个标题行）。
- 记录行 (Record row)：描述表格中的数据（每行一条记录）。
示例 (Example)
#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
列 (Columns)
除了数据列之外，表格还可以包含以下列
- 注释列 (Annotation column)：显示注释的名称。 仅在注释行中使用，并且始终是第一列。 值可以为空或受支持的注释。 响应格式使用逗号 (
,) 将注释名称与行中的值分开。 为了解决这个问题，表格中的行以一个前导逗号开始； 您会注意到整个表格的长度都有一列为空。 - 结果列 (Result column)：包含查询指定的结果的名称。
- 表格列 (Table column)：包含结果中每个表格的唯一 ID。
多个表格和结果 (Multiple tables and results)
如果文件或数据流包含多个表格或结果，则必须满足以下要求
- 表格列指示行属于哪个表格。
- 表格中的所有行都是连续的。
- 在以下情况下，空行会分隔新的表格边界
- 同一结果中不共享公共表格模式的表格之间。
- 在连接的 CSV 文件之间。
- 每个新的表格边界都以新的注释行和标题行开始。
示例 (Example)
#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
方言选项 (Dialect options)
Flux 支持 text/csv 格式的以下方言选项。
| 选项 (Option) | 描述 (Description) | 默认值 (Default) |
|---|---|---|
| header | 如果为 true，则包含标题行。 | true |
| delimiter | 用于分隔列的字符。 | , |
| quoteChar | 用于引用包含分隔符的值的字符。 | " |
| annotations | 要编码的注释列表（datatype、group 或 default）。 | empty |
| commentPrefix | 用于标识注释的字符串前缀。 始终添加到注释。 | # |
注释 (Annotations)
注释行描述列属性，并以 #（或 commentPrefix 值）开头。 注释行中的第一列始终包含注释名称。 后续列包含如下表所示的注释值。
| 注释名称 (Annotation name) | 值 (Values) | 描述 (Description) |
|---|---|---|
| datatype | 数据类型或行协议元素 | 描述数据的类型或该列表示哪个行协议元素。 |
| group | 布尔标志 true 或 false | 指示该列是组键的一部分。 |
| default | 列数据类型的值 | 用于具有空值的行的值。 |
某些工具可能会使用或要求使用逗号 (,) 将注释名称与注释行中的值分开。
要使用其组键对表格进行编码，必须包含 datatype、group 和 default 注释。 如果表格没有行，则 default 注释提供组键值。
数据类型 (Data types)
| 数据类型 (Datatype) | Flux 类型 (Flux type) | 描述 (Description) |
|---|---|---|
| boolean | bool | “true” 或 “false” |
| unsignedLong | uint | 无符号 64 位整数 |
| long | int | 有符号 64 位整数 |
| double | float | IEEE-754 64 位浮点数 |
| string | string | UTF-8 编码字符串 |
| base64Binary | bytes | base64 编码的字节序列，如 RFC 4648 中定义 |
| dateTime | time | 时间上的瞬间，后面可能跟一个冒号 : 和格式的描述（number、RFC3339、RFC3339Nano） |
| duration | duration | 时间长度，表示为无符号 64 位整数的纳秒数 |
行协议元素 (Line protocol elements)
datatype 注释接受数据类型和 行协议元素。 行协议元素标识在使用influx write 命令将带注释的 CSV 写入 InfluxDB 时，如何将列转换为行协议。
| 行协议元素 (Line protocol element) | 描述 (Description) |
|---|---|
measurement | 列值为 measurement |
field (默认) | 列标题是 field key，列值是 field value |
tag | 列标题是 tag key，列值是 tag value |
time | 列值是时间戳 （dateTime 的别名） |
ignore orignored | 该列被忽略，不包含在行协议中 |
混合数据类型和行协议元素 (Mixing data types and line protocol elements)
#datatype 注释中具有数据类型（dateTime 除外）的列在转换为行协议时被视为 fields。 没有指定数据类型的列在转换为行协议时默认使用 field，并且 列值在行协议中保持不变。 请参阅下面的示例和行协议数据类型和格式。
时间列 (Time columns)
带有 time 或 dateTime #datatype 注释的列在转换为 Line Protocol 时用作时间戳。如果存在多个 time 或 dateTime 列，则最右侧的列将用作 Line Protocol 中的时间戳。其他时间列将被忽略，并且 influx write 命令会输出警告。
时间列的值应为 Unix 纳秒时间戳、RFC3339 或 RFC3339Nano。
数据类型注释中的 Line Protocol 元素示例
#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
生成的 Line Protocol
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
混合数据类型和 Line Protocol 元素的示例
#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
生成的 Line Protocol
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。
示例 (Example)
带有数据类型注释的错误的编码
#datatype,string,long
,error,reference
,Failed to parse query,897
此页是否对您有帮助？
感谢您的反馈！