すべてのプロダクト
Search

このプロダクト

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

    ドキュメントセンター

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

    最終更新日:Jan 14, 2025

    TSDB for InfluxDB® のラインプロトコルは、テキストベースの形式です。このプロトコルは、データベースにポイントを書き込むために使用されます。 TSDB for InfluxDB® は、ポイントがラインプロトコル形式である場合にのみ、ポイントを解析および書き込むことができます。

    構文

    ラインプロトコル形式の1行のテキストは、TSDB for InfluxDB® の1つのポイントを表します。このポイントは、TSDB for InfluxDB® にポイントの測定値、タグセット、フィールドセット、およびタイムスタンプを通知します。次のコードブロックは、ラインプロトコルの例を示しています。この例のデータは、複数の要素に分割されています。

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

    以下のセクションでは、上記のコードブロックの要素について説明します。

    測定値

    データを書き込む測定値の名前です。ラインプロトコルでは、測定値は必須です。上記の例では、測定値の名前は weather です。

    タグセット

    ポイントに含めるタグです。ラインプロトコルでは、タグはオプションです。測定値とタグセットはカンマ（,）で区切られていることに注意してください。測定値とタグセットの間にスペースはありません。

    タグキーとタグ値は等号（=）で区切ります。タグキーとタグ値の間にスペースはありません。

    <tag_key>=<tag_value>

    タグのキーと値のペアはカンマで区切ります。タグのキーと値のペアの間にスペースはありません。

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

    この例では、タグセットは1つのタグ location=us-midwest で構成されています。例に別のタグ season=summer を追加します。次のコードブロックは、この操作の結果を示しています。

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

    ポイントはデータベースに送信される前に、キーでタグをソートできます。このようにして、最高のパフォーマンスを達成できます。Go bytes.Compare 関数 の結果とソート結果が一致する必要があります。

    スペース I

    測定値とフィールドセットはスペースで区切ります。ポイントにタグセットが含まれている場合は、タグセットとフィールドセットもスペースで区切る必要があります。ラインプロトコルでは、スペースは必須です。

    タグセットを含まない次のポイントは、有効なラインプロトコル形式です。

    weather temperature=82 1465839830100400200

    フィールドセット

    ポイントのフィールドです。ラインプロトコルでは、各ポイントに少なくとも1つのフィールドが必要です。

    フィールドキーとフィールド値は等号（=）で区切ります。フィールドキーとフィールド値の間にスペースはありません。

    <field_key>=<field_value>

    フィールドのキーと値のペアはカンマで区切ります。フィールドのキーと値のペアの間にスペースはありません。

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

    この例では、フィールドセットは1つのフィールド temperature=82 のみで構成されています。例に別のフィールド humidity=71 を追加します。次のコードブロックは、この操作の結果を示しています。

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

    スペース II

    フィールドセットとオプションのタイムスタンプはスペースで区切ります。ポイントにタイムスタンプが指定されている場合、ラインプロトコルではスペースが必要です。

    タイムスタンプ

    ポイントのナノ秒単位の精度のUNIXタイムスタンプです。ラインプロトコルでは、タイムスタンプはオプションです。ポイントのタイムスタンプを指定しない場合、TSDB for InfluxDB® はサーバー上のローカルタイムスタンプ（ナノ秒単位）をポイントのタイムスタンプとして使用します。タイムスタンプはUTCです。

    この例では、タイムスタンプはRFC 3339 形式の 1465839830100400200 です。このタイムスタンプは 2016-06-13T17:43:50.1004002Z を示します。ラインプロトコル形式の次のポイントと前の例のポイントとの唯一の違いは、次のポイントにタイムスタンプが含まれていないことです。TSDB for InfluxDB® がポイントをデータベースに書き込むとき、ポイントは 2016-06-13T17:43:50.1004002Z ではなく、サーバーのローカルタイムスタンプを使用します。

    weather,location=us-midwest temperature=82

    タイムスタンプがナノ秒ではなく、マイクロ秒、ミリ秒、秒などの別の時間粒度を使用する場合は、HTTP API を使用してタイムスタンプを指定します。可能な場合は、最も粗い時間粒度を使用することをお勧めします。このようにして、データ圧縮結果を大幅に改善できます。

    説明

    注: ホスト間で時刻を同期するには、Network Time Protocol（NTP）を使用します。TSDB for InfluxDB® は、ホストのローカルUTC時刻を使用してデータにタイムスタンプを割り当てます。ホストクロックがNTPサーバーと同期されていない場合、TSDB for InfluxDB® に書き込まれたデータのタイムスタンプが不正確になる可能性があります。

    データ型

    このセクションでは、ラインプロトコルの次の主要要素のデータ型について説明します。測定値、タグキー、タグ値、フィールドキー、フィールド値、およびタイムスタンプ。

    測定値名、タグキー、タグ値、およびフィールドキーは常に文字列として格納されます。

    説明

    注: TSDB for InfluxDB® はタグ値を文字列として格納するため、タグ値に対して数学演算を実行できません。また、InfluxQL関数はタグ値を主要な引数として使用しません。上記の情報を基にスキーマを設計することをお勧めします。

    タイムスタンプはUNIXタイムスタンプです。有効な最小タイムスタンプは -9223372036854775806 または 1677-09-21T00:12:43.145224194Z です。有効な最大タイムスタンプは 9223372036854775806 または 2262-04-11T23:47:16.854775806Z です。デフォルトでは、TSDB for InfluxDB® はタイムスタンプにナノ秒の粒度を使用します。他の時間粒度を指定する方法の詳細については、HTTP API のドキュメントをご参照ください。

    フィールド値のデータ型は、FLOAT、INTEGER、STRING、またはBOOLEANです。

    • FLOAT: デフォルトでは、TSDB for InfluxDB® は数値データ型のすべてのフィールド値を浮動小数点数と見なします。

      次のコードブロックでは、フィールド値 82 は浮動小数点数として格納されます。

      weather,location=us-midwest temperature=82 1465839830100400200

    • INTEGER: フィールド値に i を追加して、TSDB for InfluxDB® に値を整数として格納するように指示します。

      次の例では、フィールド値 82 は整数として格納されます。

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

    • STRING: 二重引用符（"）を使用して、STRING型のフィールド値を囲みます。ラインプロトコルの引用符の詳細については、「引用符」セクションをご参照ください。

      次の例では、フィールド値 too warm は文字列として格納されます。

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

    • BOOLEAN: t、T、true、True、または TRUE を指定してTRUE値を示すことができます。 f、F、false、False、または FALSE を指定してFALSE値を示すことができます。

      次の例では、フィールド値 true はBOOLEAN値として格納されます。

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

      注: BOOLEAN値を書き込むために使用される構文は、BOOLEAN値をクエリするために使用される構文とは異なります。詳細については、「FAQ」をご参照ください。

    測定値では、フィールドのデータ型は同じシャード内で一貫しています。フィールドのデータ型は、シャード間で異なる場合があります。たとえば、TSDB for InfluxDB® が整数を浮動小数点数と同じシャードに格納しようとすると、整数は以前に浮動小数点数を格納していたフィールドに書き込むことができません。

    > 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® が新しいシャードに整数を格納しようとすると、整数は以前に浮動小数点数を格納していたフィールドに書き込むことができます。

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

    フィールド値のデータ型の違いが SELECT * クエリにどのように影響するかについての詳細は、FAQ の対応するセクションをご参照ください。

    引用符

    このセクションでは、ラインプロトコルで二重引用符（"）または単一引用符（'）を使用できるシナリオと使用できないシナリオについて説明します。引用符を使用できるシナリオについては、セクションの最初に説明します。次に、引用符を使用できないシナリオについて説明します。

    • タイムスタンプを二重引用符（"）または単一引用符（'）で囲まないでください。タイムスタンプが二重引用符（"）または単一引用符（'）で囲まれている場合、対応するラインプロトコルは無効です。

      例:

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

    • フィールド値がSTRING型であっても、単一引用符（'）で囲まないでください。フィールド値が単一引用符（'）で囲まれている場合、対応するラインプロトコルは無効です。

      例:

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

    • 測定値の名前、タグキー、タグ値、またはフィールドキーを二重引用符（"）または単一引用符（'）で囲まないでください。測定値名が引用符で囲まれている場合、対応するラインプロトコルは有効ですが、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" 測定値のデータをクエリするには、測定値の名前を二重引用符（"）で囲み、測定値の二重引用符（"）をエスケープする必要があります。

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

    • STRING、INTEGER、またはBOOLEAN型のフィールド値を二重引用符（"）で囲まないでください。これらの値を二重引用符（"）で囲むと、TSDB for InfluxDB® はこれらの値を文字列として処理します。

      例:

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

    • STRING型のフィールド値を囲むには、二重引用符（"）を使用する必要があります。

      例:

      > 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

    特殊文字とキーワード

    特殊文字

    バックスラッシュ \ は常にタグキー、タグ値、およびフィールドキーをエスケープするために使用されます。

    • カンマ（,）

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

    • 等号（=）

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

    • スペース

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

      バックスラッシュ（\）は常に測定値名をエスケープするために使用されます。

    • カンマ（,）

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

    • スペース

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

      バックスラッシュ（\）は常にSTRING型のフィールド値をエスケープするために使用されます。

    • 二重引用符（"）

      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

    次のコードブロックは、weather測定値からデータをクエリした結果を示しています。バックスラッシュ（\）を単一引用符または二重引用符で囲んでも、クエリ結果は同じであることに注意してください。

    > 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

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

    > 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キーワードを識別子名として使用します。ほとんどの場合、スキーマでInfluxQLキーワードを使用しないことをお勧めします。これは、データクエリでキーワードが誤って処理される可能性があるためです。

    time キーワードは、他のInfluxQLキーワードと同じ方法では処理されません。time キーワードは、連続クエリ名、データベース名、測定値名、保存ポリシー名、サブスクリプション名、またはユーザー名にすることができます。これらの場合、time キーワードを二重引用符（"）で囲む必要はありません。time キーワードをフィールドキーまたはタグキーとして使用することはできません。TSDB for InfluxDB® は、time キーワードがフィールドキーまたはタグキーであるデータ書き込みを拒否し、このシナリオのエラーを返します。詳細については、FAQ をご参照ください。

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

    データベースへのデータの書き込み

    このセクションでは、ラインプロトコルを使用してTSDB for InfluxDB® にデータを書き込む方法について説明します。このセクションでは、2つの例を使用します。詳細については、ツール をご参照ください。

    HTTP API

    HTTP API を使用して TSDB for InfluxDB® にデータを書き込むには、/write エンドポイントに POST リクエストを送信し、リクエスト本文にラインプロトコル形式のデータを含めます。

    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® の CLI を使用して TSDB for InfluxDB® にデータを書き込むには、CLI を起動し、データベースにデータを書き込み、ラインプロトコル形式のデータの前に INSERT を追加します。

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

    CLI を使用してファイルからデータをインポートすることもできます。

    TSDB for InfluxDB® にデータを書き込むには、複数の方法を使用できます。詳細については、ツール をご参照ください。

    重複ポイント

    ポイントは、測定値名、タグセット、およびタイムスタンプによって一意に識別されます。たとえば、測定値名、タグセット、およびタイムスタンプが既存のポイントと同じで、送信されたポイントのフィールドセットが既存のポイントのフィールドセットと異なるポイントを送信します。この場合、送信されたポイントのフィールドセットは、以前のフィールドセットと新しいフィールドセットの和集合になります。競合が発生した場合、新しいフィールドセットが優先されます。

    このシナリオの完全な例と重複ポイントの処理方法の詳細については、FAQ の対応するセクションをご参照ください。

    InfluxDB® は InfluxData によって登録された商標であり、TSDB for InfluxDB® とは提携しておらず、TSDB for InfluxDB® を推奨していません。