多值数据写入

时序多值模型

多值的模型是针对数据源建模，我们每一行数据针对的是一个数据源，它的被测量的多个指标在同一行上，所以每一个数据源，数据的来源在每一个时间点上都有一行，这就是多值的模型。比如某个机器的cpu，mem和load指标。每次是数据操作可以使用多个指标数据。

多值模型数据写入

• 请求路径和方法

  请求路径	请求方法	描述
  /api/mput	POST	一次写入多个数据点。

  重要

  多值模型数据和单值模型数据不兼容。单值模型数据需要通过原有的/api/put接口进行写入。同时多值写入数据需要通过/api/mquery接口进行查询，单值写入的数据需要通过/api/query 进行查询。

• 请求参数

  名称	类型	是否必需	描述	默认值	举例
  db	String	否	指定写入的database。	default	/api/mput?db=test
  summary	无类型	否	是否返回摘要信息。	false	/api/mput?summary
  details	无类型	否	是否返回详细信息。	false	/api/mput?details
  sync_timeout	Integer	否	超时时间，单位毫秒，0为永不超时。	0	/api/mput/?sync&sync_timeout=60000
  ignoreErrors	无类型	否	是否忽略部分数据点的写入异常。	false	/api/mput/?ignoreErrors

  说明

  • 所有“无类型”的参数只要提供，都被视为true。比如summary=false以及summary=true都被当作summary=true。

  • 如果details和summary都设置，API将返回details信息。

• 请求内容

  数据点格式为JSON格式，各参数说明如下：

  名称	类型	是否必需	是否有使用限制	描述	举例
  metric	String	是	只可包含大小写英文字母、中文、数字，以及特殊字符 -_./():,[]=‘#。	存储的指标名。	sys.cpu。 说明 高可用版本支持的metric长度最多为255字节。
  timestamp	Long	是	无	时间戳。单位为秒或者毫秒，判断规则详见下面的“时间戳说明”。	1499158925
  fields	Map	是	field 名字限制和 metric 限制一样，field 值只支持 String，Number，Boolean	域数据值。	“fields” : {“speed” : 20.8, “level” : 4, “direction” : “East”, “description” : “Fresh breeze”}
  tags	Map	是	可以包含大小写英文字母、中文、数字，以及特殊字符 -_./():,[]=‘#。	Tagk 和 Tagv 是字符串键值对，至少一个键值对。	{“host”:”web01”}，非字符串类型的tagk，tagv会强制转换为字符串类型。

时间戳说明

本说明适用于读写数据（/api/put & /api/mput）和查询数据（/api/query & /api/mquery）两个接口。时间戳的单位可以是秒或者毫秒。TSDB 会通过数值大小来判断时间戳的单位，规则如下：

• 时间戳区间为 [4294968,4294967295]：判断为秒，表示的时间区间为：[1970-02-20 01:02:48, 2106-02-07 14:28:15]。

• 时间戳区间为 [4294967296,9999999999999]：判断为毫秒，表示的时间区间为：[1970-02-20 01:02:47.296, 2286-11-21 01:46:39.999]。

• 时间戳区间为（-∞,4294968）和（9999999999999,+∞）：判断为非法时间戳区间。

数据点值说明

• String数值类型的数据值可以为任意字符，支持JSON字符串存储，最大为20 KB。

  写入数据示例：

  请求：POST/api/mput请求体：

  [
  {
  "metric":"wind",
  "fields":{
  "speed":20.8,
  "level":4,
  "direction":"East",
  "description":"Fresh breeze"
  },
  "tags":{
  "sensor":"IOTE_8859_0001",
  "city":"hangzhou",
  "province":"zhejiang",
  "country":"china"
  },
  "timestamp":1346846400
  },
  {
  "metric":"wind",
  "fields":{
  "speed":40.2,
  "level":6,
  "direction":"South",
  "description":"Fresh breeze"
  },
  "tags":{
  "sensor":"IOTE_8859_0002",
  "city":"hangzhou",
  "province":"zhejiang",
  "country":"china"
  },
  "timestamp":1346846401
  }
  ]

写入模式及其响应内容

根据写入时指定请求参数，TSDB支持四种模式的写入，分别如下所示：

• 极简模式

  写入时在api/mput后不带任何参数。TSDB写入成功会返回204表示成功，写入失败时会返回错误码以及对应的错误消息，但不会带更多信息。

  适用于一般性的业务监控数据上报的场景。

• 统计模式

  写入时在api/mput后带上summary。TSDB写入成功或失败时会按下述响应内容返回成功的数据点数和失败的数据点数方便业务端进行统计。

  名称	数据类型	描述
  success	Integer	写入成功的数据点数。
  failed	Integer	未能成功写入的数据点数。

  示例如下：

  {
      "failed":0,
      "success": 20
  }

  重要

  • 在统计模式下。对于一个api/mput请求中写入的一批数据，要么全部成功，要么全部失败。失败时返回的failed本质就是该批次的全部数据点数。

  • 在多值写入时，返回的success或failed统计的数据点数是基于单值模型统计的点数。即一个多值数据点在统计时会乘以其field个数。

  该模式适用于一般性业务监控数据上报时对于上报数据存在统计需求时的场景。

• 详细模式

  详细模式是上述统计模式的扩展模式。写入时在api/mput后带上details。此时TSDB写入或失败时，会按下述响应内容返回成功的数据点数以及导致失败的直接原因。

  名称	数据类型	描述
  success	Integer	写入成功的数据点数。
  failed	Integer	未写入的数据点数。
  errors	Array	描述引起写入失败直接原因的数组。其中只会包含第一个引发失败的数据点及其失败原因。

  重要

  在详细模式下，对于一个api/mput请求中写入的一批数据，要么全部成功，要么全部失败。而且返回的errors中只会返回第一个引发失败的数据点及其失败原因（直接原因），该批次的其他数据点不会包含在errors中，只会体现在统计信息failed中。

  该模式适用于业务监控数据上报时对于上报数据存在统计需求且需要失败定位时的场景。

• 容错模式

  写入时在api/mput后带上ignoreErrors。TSDB写入时，会保证一个请求的一批数据中尽量写入。即使这个批次中存在一些非法数据时，对于其他合法数据尽力写入成功。返回时，会将该批次数据中写入失败的数据全部返回，返回的响应内容和指定details时相同，只是此时通过errors字段返回的将是该批次数据中所有的失败数据，未被返回的数据可以认为写入成功。

  名称	数据类型	描述
  success	Integer	写入成功的数据点数。
  failed	Integer	未写入的数据点数。
  errors	Array	描述该批次数据中所有未能成功写入的数据点数组及其各自的失败原因。

  重要

  在容错模式下，一个批次中存在部分数据写入失败时，TSDB响应的返回码仍然是200。除非发生因底层存储异常等严重错误导致全量数据失败时，才会返回200以外的返回码。该模式下返回的failed就是真实失败的数据点数。

  该模式适用于业务监控数据上报时对于上报数据的完整性存在需求，对于失败数据希望进行修复重试时的场景。