多值資料寫入 - Time Series Database

本文介紹多值資料寫入的寫入模式及其響應內容。

時序多值模型

多值的模型是針對資料來源建模，我們每一行資料針對的是一個資料來源，它的被測量的多個指標在同一行上，所以每一個資料來源，資料的來源在每一個時間點上都有一行，這就是多值的模型。比如某個機器的cpu，mem和load指標。每次是資料操作可以使用多個指標資料。時間序列資料模型.png

多值模型資料寫入

請求路徑和方法

請求路徑	要求方法	描述
/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就是真實失敗的資料點數。

該模式適用於業務監控資料上報時對於上報資料的完整性存在需求，對於失敗資料希望進行修複重試時的情境。