ラインプロトコルのチュートリアル - Time Series Database

ラインプロトコルは、TSDB for InfluxDB® がデータベースにデータポイントを書き込むために使用するテキストベースのフォーマットです。各行は 1 つのデータポイントを表します。

構文

ラインプロトコルのデータポイントは、次の構造に従います：

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

メジャメント、タグセット、フィールドセット、タイムスタンプの 4 つの要素は、特定の文字で区切られます。データポイント内に他の空白文字を入れることはできません。

weather,location=us-midwest temperature=82

要素の概要

要素	必須	区切り文字	データの型
メジャメント	はい	タグセットの前はカンマ (`,`)、フィールドセットの前はスペース	文字列
タグセット	いいえ	ペア間はカンマ (`,`)、キーと値の間は `=`	文字列 (キーと値)
フィールドセット	はい — 少なくとも 1 つのフィールドが必要	ペア間はカンマ (`,`)、キーと値の間は `=`	文字列 (キー)、浮動小数点数、整数、文字列、またはブール値 (値)
タイムスタンプ	いいえ	タイムスタンプの前にスペース	UNIX タイムスタンプ (デフォルトはナノ秒)

測定

データを書き込むメジャメントの名前です。この例では、メジャメントは weather です。

タグセット

タグは、データポイントを記述するオプションのキーと値のペアです。メジャメントとタグセットは、スペースを入れずにカンマで結合されます。

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

この例では、location=us-midwest という 1 つのタグを使用しています。2 つ目のタグ season=summer を追加します：

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

書き込みパフォーマンスを最適化するために、書き込む前にタグをキーでソートします。ソート順は、Go の bytes.Compare 関数と一致している必要があります。

フィールドセット

フィールドは、実際の測定データを保存する必須のキーと値のペアです。各ポイントには、少なくとも 1 つのフィールドが必要です。

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

例に 2 つ目のフィールド humidity=71 を追加します：

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

タイムスタンプ

データポイントの UNIX タイムスタンプで、デフォルトではナノ秒単位の精度です。タイムスタンプは協定世界時 (UTC) です。

省略した場合、TSDB for InfluxDB® は書き込み時点のローカルサーバーの時刻を使用します。

例のタイムスタンプ 1465839830100400200 は 2016-06-13T17:43:50.1004002Z に対応します。タイムスタンプのないポイントは次のようになります：

weather,location=us-midwest temperature=82

より粗い粒度（マイクロ秒、ミリ秒、または秒）でタイムスタンプを書き込むには、HTTP API を介して精度を指定します。データに適合する最も粗い粒度を使用すると、圧縮が向上します。

ホスト間のクロックを同期させるには、ネットワークタイムプロトコル (NTP) を使用してください。TSDB for InfluxDB® は、ホストのローカル UTC 時刻を使用してタイムスタンプを割り当てるため、クロックのドリフトが発生すると、取り込まれたデータのタイムスタンプが不正確になる可能性があります。

データの型

メジャメント名、タグキー、タグ値、フィールドキー

常に文字列として保存されます。

タグ値は文字列として保存されるため、算術演算や InfluxQL 関数の主要な引数として使用することはできません。これに応じてスキーマを設計してください。

タイムスタンプ

UNIX タイムスタンプです。有効値は -9223372036854775806 (1677-09-21T00:12:43.145224194Z) から 9223372036854775806 (2262-04-11T23:47:16.854775806Z) です。

デフォルトでは、タイムスタンプはナノ秒精度を使用します。その他の精度については、「HTTP API」をご参照ください。

フィールド値

フィールド値は 4 つのデータの型をサポートしています：

型	書き方	例
FLOAT	プレーンな数値 (デフォルト)	`temperature=82`
INTEGER	末尾に `i`	`temperature=82i`
STRING	二重引用符で囲む	`temperature="too warm"`
BOOLEAN	`t`、`T`、`true`、`True`、`TRUE` / `f`、`F`、`false`、`False`、`FALSE`	`too_hot=true`

ブール値を記述する構文は、それらをクエリする際に使用される構文とは異なります。詳細については、「よくある質問」をご参照ください。

シャード内での型の一貫性

フィールドの型は、同じシャード内で一貫している必要があります。同じシャード内の同じフィールドに異なる型の値を書き込もうとすると、型の競合エラーで失敗します：

> 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"}

以前のシャードと型が異なっていても、新しいシャードへの書き込みは成功します：

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

型の違いが SELECT * クエリに与える影響については、「よくある質問」をご参照ください。

引用符

以下の表は、各要素に対して二重引用符と単一引用符が有効な場合をまとめたものです。

要素	二重引用符 (`"`)	単一引用符 (`'`)
メジャメント名	受け入れられますが、名前の一部として扱われます	受け入れられますが、名前の一部として扱われます
タグキー	非推奨 — 囲まないでください	非推奨 — 囲まないでください
タグ値	非推奨 — 囲まないでください	非推奨 — 囲まないでください
フィールドキー	非推奨 — 囲まないでください	非推奨 — 囲まないでください
フィールド値 (STRING)	必須	なし — 無効
フィールド値 (INTEGER/FLOAT/BOOLEAN)	使用不可 — STRING として扱われます	使用不可 — 無効
タイムスタンプ	使用不可 — 無効	使用不可 — 無効

例

タイムスタンプを引用符で囲むと、行が無効になります：

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

文字列のフィールド値を単一引用符で囲むと、行が無効になります：

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

メジャメント名を引用符で囲むと、引用符が名前の一部になります。以下の 2 つの挿入は、別々のメジャメントを作成します：

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

"weather" をクエリするには、埋め込まれた引用符をエスケープします：

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

INTEGER のフィールド値を引用符で囲むと、STRING として保存され、数値クエリから除外されます：

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

特殊文字とキーワード

特殊文字

特定の要素で構造的な意味を持つ文字をエスケープするには、バックスラッシュ (\) を使用します。

要素	エスケープが必要な文字
メジャメント名	カンマ (`,`)、スペース
タグキー	カンマ (`,`)、等号 (`=`)、スペース
タグ値	カンマ (`,`)、等号 (`=`)、スペース
フィールドキー	カンマ (`,`)、等号 (`=`)、スペース
フィールド値 (STRING)	二重引用符 (`"`)

エスケープの例

メジャメント名に含まれるカンマとスペース：

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

タグキー、タグ値、フィールドキーに含まれるカンマ、等号、スペース：

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

STRING フィールド値に含まれる二重引用符：

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

STRING フィールド値のバックスラッシュ

ラインプロトコルでは、バックスラッシュをエスケープする必要はありません。以下の書き込みはそのまま受け入れられます：

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

クエリ結果 — 1 つおよび 2 つのバックスラッシュシーケンスは同じように折りたたまれます：

> 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

他のすべての特殊文字もエスケープする必要はありません。例えば、ラインプロトコルは絵文字やその他の特殊文字をエスケープなしで処理できます。

キーワード

ラインプロトコルは InfluxQL のキーワードを識別子名として受け入れますが、それらを使用するとクエリで予期しない動作を引き起こす可能性があります。可能な限り、スキーマで InfluxQL のキーワードを避けてください。

time キーワードは、他の InfluxQL キーワードとは異なる扱いを受けます：

許可：メジャメント名、データベース名、保持ポリシー名、継続的クエリ名、サブスクリプション名、ユーザー名
不許可：フィールドキーまたはタグキー — TSDB for InfluxDB® は書き込みを拒否し、エラーを返します

詳細については、「よくある質問」をご参照ください。

TSDB for InfluxDB® へのデータの書き込み

HTTP API

/write エンドポイントに POST リクエストを送信し、リクエストボディにラインプロトコルデータを含めます：

curl -i -XPOST "https://<Network address>:3242/write?db=science_is_cool&u=<Account name>&p=<Password>" \
  --data-binary 'weather,location=us-midwest temperature=82 1465839830100400200'

クエリパラメーター、状態コード、およびその他の例については、「HTTP API」をご参照ください。

CLI

CLI を起動し、ラインプロトコルデータの前に INSERT を付けます：

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

CLI はファイルからのデータのインポートもサポートしています。

その他の書き込み方法については、「ツール」をご参照ください。

重複したポイント

ポイントは、メジャメント名、タグセット、およびタイムスタンプによって一意に識別されます。新しいポイントが既存のポイントとこれら 3 つすべてを共有しているが、フィールドセットが異なる場合、フィールドセットはマージされます。競合するフィールドキーについては、新しい値が既存の値を上書きします。

完全な例と対処法については、「よくある質問」をご参照ください。

InfluxDB® は InfluxData の登録商標です。InfluxData は TSDB for InfluxDB® とは提携しておらず、また推奨もしていません。