多值數據寫入
本文介紹多值數據寫入的寫入模式及其響應內容。
時序多值模型
多值的模型是針對數據源建模,我們每一行數據針對的是一個數據源,它的被測量的多個指標在同一行上,所以每一個數據源,數據的來源在每一個時間點上都有一行,這就是多值的模型。比如某個機器的cpu,mem和load指標。每次是數據操作可以使用多個指標數據。
多值模型數據寫入
請求路徑和方法
請求路徑 | 請求方法 | 描述 |
---|---|---|
/api/mput | POST | 一次寫入多個數據點。 |
多值模型數據和單值模型數據不兼容。單值模型數據需要通過原有的/api/put
接口進行寫入。同時多值寫入數據需要通過/api/mquery
接口進行查詢,單值寫入的數據需要通過/api/query
進行查詢。
請求參數
名稱 | 類型 | 是否必需 | 描述 | 默認值 | 舉例 |
---|---|---|---|---|---|
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
就是真實失敗的數據點數。該模式適用于業務監控數據上報時對于上報數據的完整性存在需求,對于失敗數據希望進行修復重試時的場景。