全部产品
Search
文档中心

多值数据写入

更新时间: 2020-08-30

时序多值模型

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

时间序列数据模型.png

多值模型数据写入

请求路径和方法

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

注意

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

请求参数

名称 类型 是否必需 描述 默认值 举例
summary 无类型 是否返回摘要信息 false /api/put?summary
details 无类型 是否返回详细信息 false /api/put?details
sync_timeout Integer 超时时间,单位毫秒,0为永不超时 0 /api/put/?sync&sync_timeout=60000

注意

  • 所有“无类型”的参数,只要提供,都被视为 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 会通过数值大小来判断时间戳的单位,规则如下:

  • 时间戳区间为 [4284768,9999999999]: 判断为秒,表示的时间区间为: [1970-02-20 00:59:28, 2286-11-21 01:46:39]
  • 时间戳区间为 [10000000000,9999999999999]:判断为毫秒,表示的时间区间为: [1970-04-27 01:46:40.000, 2286-11-21 01:46:39.999]
  • 时间戳区间为 (-∞,4284768)和(9999999999999,+∞):判断为非法时间戳区间

数据点值说明

  • 在写入的数据类型的约束方面,集群版本与高可用版本存在以下差异:
    • 集群版本
      在数据类型约束上相对宽松,只要求每条时间线的数据类型必须一致。比如在集群版本中,下述两批次的写入是被允许的。 这是因为两批次数据虽然都包含相同的metric和相同的两个字段field1和field2, 但是由于tag的组合不同分属不同时间线, 因此对应相同的字段允许写入不同的数据类型。
      1. [{"metric":"fakemetric", "tags":{"tagk":"tagv1"},"timestamp":1514736000, "values":{"field1":"val", "field2": 111.11}, {"metric":"fakemetric", "tags":{"tagk":"tagv1"},"timestamp":1514736030, "values":{"field1":"val2", "field2": 222.22}}]
      2. [{"metric":"fakemetric", "tags":{"tagk":"tagv2"},"timestamp":1514736000, "values":{"field1":12.34, "field2": 333.33}}, {"metric":"fakemetric", "tags":{"tagk":"tagv2"},"timestamp":1514736030, "values":{"field1":43.21, "field2": 444.44}}}]
    • 高可用版本
      在数据类型约束上相对严格,不仅要求每条时间线的数据类型必须一致, 如果不同时间线拥有相同的metric,那么这些时间线的相同字段也必须保持数据类型的一致性。因此上述示例的第二批次数据在高可用版本上写入会失败。因为尽管第一批次和第二批次由于tag组合不同分属不同时间线,但是两批次的时间线拥有相同的metric,那么对应的相同字段的类型也必须完全一直。但实际上第二批次的字段 field1所对应的数据类型与第一批次的field1所对应类型不一致。
  • String数值类型的数据值可以为任意字符,支持JSON字符串存储,最大为20KB

    写入数据示例

    请求:POST/api/mput请求体:

    1. [
    2. {
    3. "metric" : "wind",
    4. "fields" : {
    5. "speed" : 20.8,
    6. "level" : 4,
    7. "direction" : "East",
    8. "description" : "Fresh breeze"
    9. },
    10. "tags" : {
    11. "sensor":"IOTE_8859_0001",
    12. "city":"hangzhou",
    13. "province":"zhejiang",
    14. "country":"china"
    15. },
    16. "timestamp" : 1346846400
    17. },
    18. {
    19. "metric" : "wind",
    20. "fields" : {
    21. "speed" : 40.2,
    22. "level" : 6,
    23. "direction" : "South",
    24. "description" : "Fresh breeze"
    25. },
    26. "tags" : {
    27. "sensor":"IOTE_8859_0002",
    28. "city":"hangzhou",
    29. "province":"zhejiang",
    30. "country":"china"
    31. },
    32. "timestamp" : 1346846401
    33. }
    34. ]

    响应说明

    如果所有数据点写入成功,返回码为204,如果有部分写入失败,返回码400,响应内容为具体错误信息。如果请求参数包含 summary 或者 details,返回信息包括如下属性:名称|数据类型|描述-|-|-success|Integer|写入成功的数据点数failed|Integer|未写入的数据点数errors|Array|一个描述哪些数据点未写入以及其原因的数组,仅在指定 details 有效。

    响应示例

    指定 summary 的响应示例:

    请求: POST/api/mput?summary请求体:

    1. ```json Invalid Timestamp
    2. [
    3. {
    4. "metric" : "wind",
    5. "fields" : {
    6. "speed" : 50.2,
    7. "level" : 7,
    8. "direction" : "North",
    9. "description" : "Fresh breeze"
    10. },
    11. "tags" : {
    12. "sensor":"IOTE_8859_0003",
    13. "city":"hangzhou",
    14. "province":"zhejiang",
    15. "country":"china"
    16. },
    17. "timestamp" : 401
    18. }
    19. ]
    20. ```

    响应内容:

    1. {
    2. "failed": 1,
    3. "success": 0
    4. }

    表示0个点写入成功,1个点写入失败。

    指定 details 的返回示例:

    请求:POST/api/mput?details请求体:

    1. [
    2. {
    3. "metric" : "wind",
    4. "fields" : {
    5. "speed" : 50.2_string,
    6. "level" : 7,
    7. "direction" : "North",
    8. "description" : "Fresh breeze"
    9. },
    10. "tags" : {
    11. "sensor":"IOTE_8859_0003",
    12. "city":"hangzhou",
    13. "province":"zhejiang",
    14. "country":"china"
    15. },
    16. "timestamp" : 400
    17. }
    18. ]

    响应内容:

    1. {
    2. "errors": [
    3. {
    4. "datapoint": {
    5. "metric" : "wind",
    6. "fields" : {
    7. "speed" : 50.2,
    8. "level" : 7,
    9. "direction" : "North",
    10. "description" : "Fresh breeze"
    11. },
    12. "tags" : {
    13. "sensor":"IOTE_8859_0003",
    14. "city":"hangzhou",
    15. "province":"zhejiang",
    16. "country":"china"
    17. },
    18. "timestamp" : 400
    19. },
    20. "error": "Invalid timestamp"
    21. }
    22. ],
    23. "failed": 1,
    24. "success": 0
    25. }

    表示0个点写入成功,1个点写入失败。失败的点由 datapoint 指定。该点写入失败的原因由 error 字段指定。