All Products
Search
Document Center

Line Protocol Tutorial

Last Updated: Aug 18, 2020

The line protocol of TSDB for InfluxDB® is a text-based format that you use to write points to databases. TSDB for InfluxDB® can parse and write only points that comply with the line protocol.

A set of simulated temperature data is used in this topic to describe the line protocol:

|Syntax|Data types|Quotation marks|Special characters and keywords|

The last section “Write data to TSDB for InfluxDB®” in this topic describes how to write data to TSDB for InfluxDB® and how TSDB for InfluxDB® processes duplicate points.

Syntax

Each line of text in the line protocol format describes a point in TSDB for InfluxDB®. Each line specifies the measurement, tag set, field set, and timestamp of a point. The following code block shows a sample line. In the code block, the sample line is split based on the elements of the line protocol.

  1. weather,location=us-midwest temperature=82 1465839830100400200
  2. | -------------------- -------------- |
  3. | | | |
  4. | | | |
  5. +-----------+--------+-+---------+-+---------+
  6. |measurement|,tag_set| |field_set| |timestamp|
  7. +-----------+--------+-+---------+-+---------+

The following sections analyze each element of the line protocol.

Measurement

The name of the measurement to which you want to write the data. The measurement element is required in the line protocol. In the preceding example, the measurement name is weather.

Tag set

The tags that you want to include in the point. Tags are optional in the line protocol. To comply with the line protocol, you must separate measurement names and tag sets with commas (,) and you cannot use spaces before or after the commas (,).

Separate tag keys and tag values with equal signs (=). You cannot use spaces before or after the equal signs (=).

  1. <tag_key>=<tag_value>

Separate tag key-value pairs with commas (,). You cannot use spaces before or after the commas (,).

  1. <tag_key>=<tag_value>,<tag_key>=<tag_value>

In the preceding example, the tag set contains only one tag-value pair: location=us-midwest. If you add another tag-value pair (season=summer), use the following format:

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

To achieve optimal performance, we recommend you sort tags by tag key before you write points to your database. The expected sorting result is the same as the result of the Compare(a, b []byte) function of Go. For more information, see Compare(a, b []byte) function of Go.

Part 1: Space

Separate measurement names and field sets with spaces. If your points contain tag sets, separate tag sets and field sets with spaces. In these scenarios, the line protocol requires that you use spaces.

The following example shows a valid sample line where no tag sets are specified:

  1. weather temperature=82 1465839830100400200

Field set

The fields for your point. The line protocol requires that you specify at least one field for each point.

Separate field keys and field values with equal signs (=). You cannot use spaces before or after the equal signs (=).

  1. <field_key>=<field_value>

Separate field key-value pairs with commas (,). You cannot use spaces before or after the commas (,).

  1. <field_key>=<field_value>,<field_key>=<field_value>

In the preceding example, the field set contains only one field-value pair: temperature=82. If you add another field-value pair (humidity=71), use the following format:

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

Part 2: Space

Separate field sets and timestamps with spaces. Timestamps are optional in the line protocol. To comply with the line protocol, you must use spaces to separate field sets and timestamps if you specify timestamps for points.

Timestamps

By default, the timestamps of your points are represented by the Unix time that is measured in nanoseconds. Timestamps are optional in the line protocol. If you do not specify a timestamp for your point, TSDB for InfluxDB® uses the local timestamp of the server as the timestamp of the point. The local timestamp is in UTC and is measured in nanoseconds.

In the preceding example, the timestamp is 1465839830100400200. The timestamp indicates 2016-06-13T17:43:50.1004002Z that uses the RFC3339 format. The following sample line indicates the same point as the preceding example. The difference is that no timestamp is specified for the point in this sample line. When TSDB for InfluxDB® writes this point to the database, TSDB for InfluxDB® uses the local timestamp of the server instead of 2016-06-13T17:43:50.1004002Z as the timestamp for the point.

  1. weather,location=us-midwest temperature=82

You can use the HTTP API to specify a non-nanosecond timestamp granularity, such as microseconds, milliseconds, and seconds. We recommend that you use coarse-grained timestamps for your points to improve the performance of data compression.

Setting considerations:Use the Network Time Protocol (NTP) to synchronize time among hosts. TSDB for InfluxDB® uses the local time of a host to assign timestamps to data. The local time is in UTC. If the clock of the host is not synchronized with that of the NTP server, the timestamps of the data that the host writes to TSDB for InfluxDB® may be inaccurate.

Data types

This section describes the data types for the following elements of the line protocol: measurements, tag keys, tag values, field keys, field values, and timestamps.

The data types for measurements, tag keys, tag values, and field keys are STRING.

Notes: TSDB for InfluxDB® stores tag values as strings. Therefore, TSDB for InfluxDB® cannot perform mathematical operations on tag values. In addition, InfluxQL functions do not use tag values as main arguments. We recommend you pay attention to these details when you design your schema.

In TSDB for InfluxDB®, your points use Unix timestamps. The valid timestamp range is -9223372036854775806 to 9223372036854775806, or 1677-09-21T00:12:43.145224194Z to 2262-04-11T23:47:16.854775806Z. By default, TSDB for InfluxDB® assumes that timestamps use the nanosecond granularity. For more information about how to specify other time granularities, see HTTP API.

Field values can be floating-point numbers, integers, strings, or Boolean values.

  • Floating-point numbers: By default, TSDB for InfluxDB® assumes that numerical field values are floating-point numbers. Store the 82 field value as a floating-point number:
    1. weather,location=us-midwest temperature=82i 1465839830100400200
  • Integers: Add i to the end of the field value to store the field value as an integer in TSDB for InfluxDB®. Store the field value 82 as an integer:
    1. weather,location=us-midwest temperature=82i 1465839830100400200
  • Strings: Enclose string field values in double quotation marks (“). For more information about the quotation marks in the line protocol, see the Quotation marks section. Store the too warm field value as a string:
    1. weather,location=us-midwest temperature="too warm" 1465839830100400200
  • Boolean values: You can use t, T, true, True, or TRUE to indicate TRUE, and use f, F, false, False, or FALSE to indicate FALSE. Store the true field value as a Boolean value:
    1. weather,location=us-midwest too_hot=true 1465839830100400200

    Notes: The syntax for writing Boolean values is different from that for querying Boolean values. For more information, see FAQ.

The data types of the values for each field in a measurement must be the same in a shard, but can be different across shards. For example, if TSDB for InfluxDB® attempts to store an integer in a shard that stores floating-point numbers, the integer failed to be written to a field that previously stored floating-point numbers.

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

If TSDB for InfluxDB® attempts to store an integer in a different shard, the integer can be written to a field that previously stored floating-point numbers.

  1. > INSERT weather,location=us-midwest temperature=82 1465839830100400200
  2. > INSERT weather,location=us-midwest temperature=81i 1467154750000000000
  3. >

For more information about how data type differences of field values affect SELECT * queries, see FAQ.

Quotation marks

This section describes how to use double quotation marks (") and single quotation marks (') in the line protocol. This section starts with the scenarios where quotation marks are not used and then describes the scenarios where quotation marks are used.

  • Do not use double quotation marks (“) or single quotation marks (‘) to enclose timestamps. If timestamps are enclosed in double quotation marks (“) or single quotation marks (‘), the syntax is invalid in the line protocol.

    Example

    1. > INSERT weather,location=us-midwest temperature=82 "1465839830100400200"
    2. ERR: {"error":"unable to parse 'weather,location=us-midwest temperature=82 \"1465839830100400200\"': bad timestamp"}
  • Do not use single quotation marks (‘) to enclose field values even if the field values are strings. If field values are enclosed in single quotation marks (‘), the syntax is invalid in the line protocol.

    Example

    1. > INSERT weather,location=us-midwest temperature='too warm'
    2. ERR: {"error":"unable to parse 'weather,location=us-midwest temperature='too warm'': invalid boolean"}
  • We recommend that you do not use quotation marks to enclose measurement names, tag keys, tag values, or field keys. If you use quotation marks to enclose these elements, the line protocol is valid. However, TSDB for InfluxDB® assumes that the quotation marks are part of the names or values.

    Example

    1. > INSERT weather,location=us-midwest temperature=82 1465839830100400200
    2. > INSERT "weather",location=us-midwest temperature=87 1465839830100400200
    3. > SHOW MEASUREMENTS
    4. name: measurements
    5. ------------------
    6. name
    7. "weather"
    8. weather

    In this scenario, to query the data that is stored in the "weather" measurement, you must use double quotation marks (“) to enclose the measurement name. You must also use backslashes () to escape the double quotation marks (“).

    1. > SELECT * FROM "\"weather\""
    2. name: "weather"
    3. ---------------
    4. time location temperature
    5. 2016-06-13T17:43:50.1004002Z us-midwest 87
  • Do not use double quotation marks (“) to enclose the field values of FLOAT, INT, or BOOLEAN data types. If the field values of these data types are enclosed in double quotation marks (“), TSDB for InfluxDB® considers the field values as strings.

    Example

    1. > INSERT weather,location=us-midwest temperature="82"
    2. > SELECT * FROM weather WHERE temperature >= 70
    3. >
  • Use double quotation marks (“) to enclose string field values.

    Example

    1. > INSERT weather,location=us-midwest temperature="too warm"
    2. > SELECT * FROM weather
    3. name: weather
    4. -------------
    5. time location temperature
    6. 2016-06-13T19:10:09.995766248Z us-midwest too warm

Special characters and keywords

Special characters

For tag keys, tag values, and field keys, you must use a backslash (\) to escape each of the following special characters:

  • Commas (,)
    1. weather,location=us\,midwest temperature=82 1465839830100400200
  • Equal signs (=)
    1. weather,location=us-midwest temp\=rature=82 1465839830100400200
  • Spaces

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

    For measurements, you must use a backslash (\) to escape each of the following special characters:

  • Commas (,)

    1. wea\,ther,location=us-midwest temperature=82 1465839830100400200
  • Spaces

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

    For string field values, you must use a backslash () to escape each of the following special characters:

  • Double quotation marks (“)

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

The line protocol does not require that you escape backslashes (). TSDB for InfluxDB® returns the same results regardless of whether you escape backslashes (). For example, you can write the following records to TSDB for InfluxDB®:

  1. weather,location=us-midwest temperature_str="too hot/cold" 1465839830100400201
  2. weather,location=us-midwest temperature_str="too hot\cold" 1465839830100400202
  3. weather,location=us-midwest temperature_str="too hot\\cold" 1465839830100400203
  4. weather,location=us-midwest temperature_str="too hot\\\cold" 1465839830100400204
  5. weather,location=us-midwest temperature_str="too hot\\\\cold" 1465839830100400205
  6. weather,location=us-midwest temperature_str="too hot\\\\\cold" 1465839830100400206

Note that the backslashes () enclosed in single quotation marks (‘) produce the same results as those enclosed in double quotation marks (“). Therefore, TSDB for InfluxDB® interprets the records as the following results:

  1. > SELECT * FROM "weather"
  2. name: weather
  3. time location temperature_str
  4. ---- -------- ---------------
  5. 1465839830100400201 us-midwest too hot/cold
  6. 1465839830100400202 us-midwest too hot\cold
  7. 1465839830100400203 us-midwest too hot\cold
  8. 1465839830100400204 us-midwest too hot\\cold
  9. 1465839830100400205 us-midwest too hot\\cold
  10. 1465839830100400206 us-midwest too hot\\\cold

You do not need to escape the other special characters that are not listed in this topic. For example, emojis can be processed as expected if you use the line protocol.

  1. > INSERT we⛅️ther,location=us-midwest temper⛅️ture=82 1465839830100400200
  2. > SELECT * FROM "we⛅️ther"
  3. name: we⛅️ther
  4. ------------------
  5. time location temper⛅️ture
  6. 1465839830100400200 us-midwest 82

Keywords

The line protocol uses InfluxQL keywords as identifier names. We recommend that you avoid using InfluxQL keywords in your schema. If you use InfluxQL keywords in your schema, the InfluxQL keywords may be considered as the keywords of query statements. This may cause errors for data queries.

The preceding rule does not apply to the time keyword. The time keyword can be a continuous query name, database name, measurement name, retention policy name, subscription name, or username. In these cases, you do not need to use double quotation marks (“) to enclose time in queries. You cannot use time as a field key or a tag key. TSDB for InfluxDB® rejects data writes where time is used as a field key or a tag key, and reports errors. For more information, see FAQ.

Write data to TSDB for InfluxDB®

Write data to databases

Now you have familiarized yourself with the line protocol. You can move on to the next step. This section describes how to use the line protocol to write data to TSDB for InfluxDB®. This section provides two simple examples. For more information, see the Tools topic.

HTTP API

You can use the HTTP API to write data to TSDB for InfluxDB®. To do this, send a POST request to the /write endpoint. You must use the line protocol to specify your data in the request body.

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

For more information about query parameters, HTTP status codes, responses, and examples, see HTTP API.

CLI

You can use the command line interface (CLI) of TSDB for InfluxDB® to write data to TSDB for InfluxDB®. To do this, open the CLI, specify a database, and then add INSERT to the beginning of the data that complies with the line protocol.

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

You can also use the CLI to import data that is stored in files.

You can use multiple methods to write data to TSDB for InfluxDB®. For more information, see the Tools topic.

Duplicate points

A point is uniquely identified by a measurement name, a tag set, and a timestamp. If two points have the same measurement name, tag set, and timestamp, they are considered as duplicate points. If you submit a duplicate point that has a different field set from an existing point, the field set of the point becomes the sum of the previous and new field sets. If a conflict occurs, the new field set prevails.

For more information about an example of this scenario and how to avoid this scenario, see FAQ.


InfluxDB® is a trademark registered by InfluxData, which is not affiliated with, and does not endorse, TSDB for InfluxDB®.