全部產品
Search

搜尋本產品

    Time Series Database：行協議教程

    文件中心

    Time Series Database：行協議教程

    更新時間：Jul 06, 2024

    TSDB For InfluxDB®的行協議（Line Protocol）是一種基於文本的格式，用於將資料點寫入資料庫。資料點必須符合行協議格式，TSDB For InfluxDB®才能成功解析和寫入資料點。

    文法

    行協議中，一行資料表示TSDB For InfluxDB®中的一個資料點，它告訴TSDB For InfluxDB®該資料點的measurement、tag set、field set和時間戳記。以下代碼塊展示了行協議的一個樣本，並將其分解成多個組成部分：

    weather,location=us-midwest temperature=82 1465839830100400200
  |    -------------------- --------------  |
  |             |             |             |
  |             |             |             |
+-----------+--------+-+---------+-+---------+
|measurement|,tag_set| |field_set| |timestamp|
+-----------+--------+-+---------+-+---------+

    下面，我們將逐個分析上圖中的元素。

    Measurement

    您想要寫入資料的measurement的名字。在行協議中，measurement是必須要有的。在上面的樣本中，measurement的名字是weather。

    Tag set

    您想要在資料點中包含的tag。在行協議中，tag是可選的。請注意，measurement和tag set被逗號隔開並且它們之間沒有空格。

    使用等號=分隔tag key和tag value，並且它們之間不能有空格：

    <tag_key>=<tag_value>

    使用逗號分隔多個tag key-value pairs，並且它們之間不能有空格：

    <tag_key>=<tag_value>,<tag_key>=<tag_value>

    在樣本中，tag set由一個tag組成：location=us-midwest。在樣本中添加另一個tag（season=summer），如下所示：

    weather,location=us-midwest,season=summer temperature=82 1465839830100400200

    為了獲得最佳效能，您應該在將資料點發送到資料庫之前，將tag按tag key進行排序。排序結果應該與Go bytes.Compare function的結果匹配。

    空格 I

    使用空格分隔measurement和field set，如果資料點中包含了tag set，也需要使用空格分隔tag set和field set。在行協議中，這裡必須使用空格。

    沒有tag set的有效行協議：

    weather temperature=82 1465839830100400200

    Field set

    資料點中的field。在行協議中，每個資料點至少需要有一個field。

    使用等號=分隔field key和field value，並且它們之間不能有空格：

    <field_key>=<field_value>

    使用逗號分隔多個field key-value pairs，並且它們之間不能有空格：

    <field_key>=<field_value>,<field_key>=<field_value>

    在樣本中，field set由一個field組成：temperature=82。在樣本中添加另一個field（humidity=71），如下所示：

    weather,location=us-midwest temperature=82,humidity=71 1465839830100400200

    空格 II

    使用空格分隔field set和時間戳記（如果有的話）。如果為資料點指定了時間戳記，那麼在行協議中，這裡必須使用空格。

    時間戳記

    資料點中的時間戳記是精確到納米的Unix時間。在行協議中，時間戳記是可選的。如果您沒有指定資料點的時間戳記，那麼TSDB For InfluxDB®使用伺服器本地的納秒級時間戳記（UTC格式）作為資料點的時間戳記。

    在樣本中，時間戳記是1465839830100400200（也就是2016-06-13T17:43:50.1004002Z，按照RFC3339格式）。下面的行協議表示相同的資料點，但是不帶時間戳記。當TSDB For InfluxDB®將該資料點寫入資料庫，它使用伺服器的本地時間戳記，而不是2016-06-13T17:43:50.1004002Z。

    weather,location=us-midwest temperature=82

    使用HTTP API來指定除納秒之外其它精度的時間戳記，例如微秒、毫秒或者秒。我們建議盡量使用最粗糙的精度，因為這可以顯著提高壓縮效果。

    說明

    請使用網路時間協議（Network Time Protocol，NTP）來同步主機（host）之間的時間。TSDB For InfluxDB®使用主機的本地UTC時間為資料分配時間戳記；如果主機的時鐘與NTP不同步，寫入TSDB For InfluxDB®的資料的時間戳記可能會不準確。

    資料類型

    本節將介紹行協議中主要組成部分的資料類型：measurement、tag key、tag value、field key、field value和時間戳記。

    measurement、tag key、tag value和field key始終是字串。

    說明

    注釋：因為TSDB For InfluxDB®將tag value儲存為字串，所以TSDB For InfluxDB®不能對tag value執行數學運算。此外，InfluxQL函數不接受將tag value作為主要參數。當您在設計schema時，最好考慮一下這些細節。

    時間戳記是UNIX時間戳記。最小的有效時間戳記是-9223372036854775806或1677-09-21T00:12:43.145224194Z，最大的有效時間戳記是9223372036854775806或2262-04-11T23:47:16.854775806Z。如上所述，預設情況下，TSDB For InfluxDB®假設時間戳記精確到納秒。關於如何指定其它精度，請查看文檔HTTP API。

    field value可以是浮點數、整數、字串或者布爾值：

    • 浮點數 - 預設情況下，TSDB For InfluxDB®假設所有數實值型別的field value是浮點數。

      將field value 82儲存為浮點數：

      weather,location=us-midwest temperature=82 1465839830100400200

    • 整數 - 在field value後面加上i，告訴TSDB For InfluxDB®將該數字儲存為整數。

      將field value 82儲存為整數：

      weather,location=us-midwest temperature=82i 1465839830100400200

    • 字串 - 用雙引號把字串類型的field value括起來（更多關於行協議中引號的介紹，請參見“引號”內容）。

      將field value too warm儲存為字串：

      weather,location=us-midwest temperature="too warm" 1465839830100400200

    • 布爾值 - 可以使用t、T、true、True或TRUE指定TRUE，使用f、F、false、False或FALSE指定FALSE。

      將field value true儲存為布爾值：

      weather,location=us-midwest too_hot=true 1465839830100400200
      說明

      注釋：寫入和查詢布爾值的文法不一樣。請查看FAQ獲得更多相關資訊。

    在measurement中，一個field的資料類型在一個shard內不會不一致，但是在不同的shard，它的資料類型可以不同。例如，如果TSDB For InfluxDB®嘗試將整數儲存在與浮點數相同的shard中，那麼將整數寫入一個之前接受浮點數的field會失敗：

    > INSERT weather,location=us-midwest temperature=82 1465839830100400200
> INSERT weather,location=us-midwest temperature=81i 1465839830100400300
ERR: {"error":"field type conflict: input field \"temperature\" on measurement \"weather\" is type int64, already exists as type float"}

    但是，如果TSDB For InfluxDB®嘗試將整數儲存在一個新的shard中，那麼將整數寫入一個之前接受浮點數的field會成功：

    > INSERT weather,location=us-midwest temperature=82 1465839830100400200
> INSERT weather,location=us-midwest temperature=81i 1467154750000000000
>

    若想瞭解field value的資料類型差異如何影響SELECT *查詢，請查看FAQ的相關章節。

    引號

    本節將介紹在行協議中，什麼時候不能使用雙引號（"）或單引號（'），什麼時候應該使用它們。我們先介紹不使用引號的情形，然後再介紹使用引號的情形：

    • 不能用雙引號或單引號將時間戳記括起來。這是無效的行協議。

      樣本：

      > INSERT weather,location=us-midwest temperature=82 "1465839830100400200"
ERR: {"error":"unable to parse 'weather,location=us-midwest temperature=82 \"1465839830100400200\"': bad timestamp"}

    • 不能用單引號將field value括起來（即使它們是字串）。這也是無效的行協議。

      樣本：

      > INSERT weather,location=us-midwest temperature='too warm'
ERR: {"error":"unable to parse 'weather,location=us-midwest temperature='too warm'': invalid boolean"}

    • 不能用雙引號或單引號將measurement的名字、tag key、tag value和field key括起來。雖然這是有效行協議，但是TSDB For InfluxDB®會把引號當作是名字的一部分。

      樣本：

      > INSERT weather,location=us-midwest temperature=82 1465839830100400200
> INSERT "weather",location=us-midwest temperature=87 1465839830100400200
> SHOW MEASUREMENTS
name: measurements
------------------
name
"weather"
weather

      查詢在"weather"中的資料，您需要用引號將measurement的名字括起來，並且將measurement中的雙引號轉義：

      > SELECT * FROM "\"weather\""
name: "weather"
---------------
time                            location     temperature
2016-06-13T17:43:50.1004002Z    us-midwest   87

    • 不能用雙引號將字串類型、整型或布爾類型的field value括起來。否則，TSDB For InfluxDB®會把這些值當作字串。

      樣本：

      > INSERT weather,location=us-midwest temperature="82"
> SELECT * FROM weather WHERE temperature >= 70
>

    • 需要用雙引號將字串類型的field value括起來。

      樣本：

      > INSERT weather,location=us-midwest temperature="too warm"
> SELECT * FROM weather
name: weather
-------------
time                            location     temperature
2016-06-13T19:10:09.995766248Z  us-midwest   too warm

    特殊字元和關鍵字

    特殊字元

    對於tag key、tag value和field key，始終使用反斜線\來轉義：

    • 逗號 ,

      weather,location=us\,midwest temperature=82 1465839830100400200

    • 等號 =

      weather,location=us-midwest temp\=rature=82 1465839830100400200

    • 空格

      weather,location\ place=us-midwest temperature=82 1465839830100400200

      對於measurement，始終使用反斜線\來轉義：

    • 逗號 ,

      wea\,ther,location=us-midwest temperature=82 1465839830100400200

    • 空格

      wea\ ther,location=us-midwest temperature=82 1465839830100400200

      對於字串類型的field value，使用反斜線\來轉義：

    • 雙引號 "

      weather,location=us-midwest temperature="too\"hot\"" 1465839830100400200

    行協議不需要使用者將反斜線\轉義，但是如果您這樣做也沒有問題。例如，寫入以下資料：

    weather,location=us-midwest temperature_str="too hot/cold" 1465839830100400201
weather,location=us-midwest temperature_str="too hot\cold" 1465839830100400202
weather,location=us-midwest temperature_str="too hot\\cold" 1465839830100400203
weather,location=us-midwest temperature_str="too hot\\\cold" 1465839830100400204
weather,location=us-midwest temperature_str="too hot\\\\cold" 1465839830100400205
weather,location=us-midwest temperature_str="too hot\\\\\cold" 1465839830100400206

    將會理解為（請注意，用單引號或雙引號將反斜線括起來會產生相同的結果）：

    > SELECT * FROM "weather"
name: weather
time                location   temperature_str
----                --------   ---------------
1465839830100400201 us-midwest too hot/cold
1465839830100400202 us-midwest too hot\cold
1465839830100400203 us-midwest too hot\cold
1465839830100400204 us-midwest too hot\\cold
1465839830100400205 us-midwest too hot\\cold
1465839830100400206 us-midwest too hot\\\cold

    所有其它的特殊字元也不需要轉義。例如，行協議處理Emoji（emojis）沒有問題：

    > INSERT we⛅️ther,location=us-midwest t⛅️emperture=82 1465839830100400200
> SELECT * FROM "we⛅️ther"
name: we⛅️ther
------------------
time                                  location     t⛅️emperture
1465839830100400200      us-midwest      82

    關鍵字

    行協議將InfluxQL關鍵字作為標識符名字。通常，我們建議避免在schema中使用InfluxQL關鍵字，因為它可能會在查詢資料時引起混淆。

    關鍵字time是一個特例。time可以是一個連續查詢名字、資料庫名字、measurement的名字、保留原則名字、subscription的名字和使用者名稱。在這些情況下，不需要在查詢中用雙引號將time括起來。time不能是field key或tag key；TSDB For InfluxDB®拒絕寫入將time作為field key或tag key的資料，對於這種資料寫入，TSDB For InfluxDB®會返回錯誤。請查閱FAQ獲得更多相關資訊。

    將資料寫入TSDB For InfluxDB®

    將資料寫入資料庫

    現在您已經知道了關於行協議的所有內容，那麼如何使用行協議將資料寫入TSDB For InfluxDB®呢？在本節，我們將給出兩個簡單樣本，請參見工具章節擷取更多相關資訊。

    HTTP API

    使用HTTP API將資料寫入TSDB For InfluxDB®。向/write路徑發送POST請求，並在request body中給出行協議資料：

    curl -i -XPOST "https://<網路地址>:3242/write?db=science_is_cool&u=<帳號名稱>&p=<密碼>" --data-binary 'weather,location=us-midwest temperature=82 1465839830100400200'

    有關查詢參數、狀態代碼、響應和更多樣本的深入講解，請查看文檔HTTP API。

    CLI

    使用TSDB For InfluxDB®的命令列介面（Command Line Interface，CLI）將資料寫入TSDB For InfluxDB®。啟動CLI，使用相關的資料庫，並且將INSERT放在行協議語句前面：

    INSERT weather,location=us-midwest temperature=82 1465839830100400200

    您還可以使用CLI匯入檔案中的資料。

    將資料寫入TSDB For InfluxDB®的方法有幾種，請參見工具章節擷取更多相關資訊。

    重複資料點

    measurement的名字、tag set和時間戳記唯一標識一個資料點。如果您提交的資料具有相同measurement、tag set和時間戳記但具有不同field set，那麼資料的field set會變為舊field set和新field set的並集，如果有任何衝突以新field set為準。

    有關此行為的完整樣本和如何避免這種情況，請查看FAQ相關章節。