All Products
Search
Document Center

Time Series Database:Line protocol tutorial

Last Updated:May 25, 2022

The line protocol of TSDB for InfluxDB® is a text-based format. This protocol is used to write points to databases. TSDB for InfluxDB® can parse and write points only if the points are in the line protocol format.

Syntax

A single line of text in the line protocol format represents one point in TSDB for InfluxDB®. The point informs TSDB for InfluxDB® of the measurement, tag set, field set, and timestamp of the point. The following code block provides an example on the line protocol. The data in this example is divided into multiple elements.

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

The following sections describe the elements in the preceding code block.

Measurement

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

Tag set

The tag that you want to include in the point. In the line protocol, tags are optional. Take note that the measurement and the tag set are separated by the comma (,). No spaces exist between the measurement and the tag set.

Separate the tag key and the tag value with an equal sign (=). No spaces exist between the tag key and the tag value.

<tag_key>=<tag_value>

Separate tag key-value pairs with commas. No spaces exist between tag key-value pairs.

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

In the example, the tag set consists of one tag: location=us-midwest. Add another tag season=summer to the example. The following code block shows the result of this operation.

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

You can sort tags by key before points are sent to databases. This way, the best performance can be achieved. The sorting result must match the result of the Go bytes.Compare function

Space I

Separate the measurement and the field set with a space. If a point contains a tag set, you must also separate the tag set and the field set with a space. In the line protocol, the space is required.

The following point that does not contain a tag set is in the valid line protocol format:

weather temperature=82 1465839830100400200

Field set

The field in the point. In the line protocol, each point must have at least one field.

Separate the field key and the field value with an equal sign (=). No spaces exist between the field key and the field value.

<field_key>=<field_value>

Separate field key-value pairs with commas. No spaces exist between field key-value pairs.

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

In this example, the field set consists of only one field: temperature=82. Add another field humidity=71 to the example. The following code block shows the result of this operation:

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

Space II

Separate the field set and the optional timestamp with a space. If a timestamp is specified in the point, the space is required in the line protocol.

Timestamp

The UNIX timestamp that is accurate to the nanosecond in the point. In the line protocol, the timestamp is optional. If you do not specify a timestamp for your point, TSDB for InfluxDB® uses the local timestamp in nanoseconds on the server as the timestamp of the point. The timestamp is in UTC.

In the example, the timestamp is 1465839830100400200 in RFC 3339 format. This timestamp indicates 2016-06-13T17:43:50.1004002Z. The only difference between the following point in the line protocol format and the point in the preceding example is that the following point does not contain a timestamp: When TSDB for InfluxDB® writes the point to the database, the point uses the local timestamp of the server instead of 2016-06-13T17:43:50.1004002Z.

weather,location=us-midwest temperature=82

If a timestamp uses another time granularity rather than the nanosecond granularity, such as the microsecond, millisecond, or second granularity, use the HTTP API to specify the timestamp. We recommend that you use the most coarse-grained time granularity if possible. This way, the data compression result can be greatly improved.

Note

Note: Use the Network Time Protocol (NTP) to synchronize the time between hosts. TSDB for InfluxDB® uses the local UTC time of your host to assign a timestamp to data. If the host clock is not synchronized with the NTP server, the timestamp of data written into TSDB for InfluxDB® may be inaccurate.

Data types

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

Measurement names, tag keys, tag values, and field keys are always stored as strings.

Note

Note: TSDB for InfluxDB® cannot perform mathematical operations on tag values because TSDB for InfluxDB® stores tag values as strings. In addition, InfluxQL functions do not use a tag value as a primary argument. We recommend that you design your schema based on the preceding information.

Timestamps are UNIX timestamps. The minimum valid timestamp is -9223372036854775806 or 1677-09-21T00:12:43.145224194Z. The maximum valid timestamp is 9223372036854775806 or 2262-04-11T23:47:16.854775806Z. By default, TSDB for InfluxDB® uses the nanosecond granularity for timestamps. For more information about how to specify other time granularities, see the documentation HTTP API.

The data type of field values can be FLOAT, INTEGER, STRING, or BOOLEAN.

  • FLOAT: By default, TSDB for InfluxDB® assumes that all field values of the numeric data type are floating-point numbers.

    In the following code block, the field value 82 is stored as a floating-point number.

    weather,location=us-midwest temperature=82 1465839830100400200
  • INTEGER: Append an i to a field value to instruct TSDB for InfluxDB® to store the value as an integer.

    In the following example, the field value 82 is stored as an integer:

    weather,location=us-midwest temperature=82i 1465839830100400200
  • STRING: Use double quotation marks (") to enclose field values of the STRING type. For more information about quotation marks in the line protocol, see Quotation marks.

    In the following example, the field value too warm is stored as a string:

    weather,location=us-midwest temperature="too warm" 1465839830100400200
  • BOOLEAN: You can specify t, T, true, True, or TRUE to indicate the TRUE value. You can specify f, F, false, False, or FALSE to indicate the FALSE value.

    In the following example, the field value true is stored as a BOOLEAN value:

    weather,location=us-midwest too_hot=true 1465839830100400200
    Note

    Note: The syntax used to write BOOLEAN values is different from the syntax used to query BOOLEAN values. For more information, see FAQ.

In a measurement, the data types of a field are consistent in the same shard. The data types of a field can be different across shards. For example, if TSDB for InfluxDB® attempts to store an integer in the same shard as floating-point numbers, the integer fails to be written to a field that previously stored the floating-point numbers.

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

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

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

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

Quotation marks

This section describes the scenarios in which double quotation marks (") or single quotation marks (') can be used and cannot be used in the line protocol. The scenarios in which quotation marks can be used are described at the start of the section. Then, the scenarios in which quotation marks cannot be used are described.

  • Do not enclose timestamps in double quotation marks (") or single quotation marks ('). If a timestamp is enclosed in double quotation marks (") or single quotation marks ('), the corresponding line protocol is invalid.

    Example:

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

    Example:

    > INSERT weather,location=us-midwest temperature='too warm'
    ERR: {"error":"unable to parse 'weather,location=us-midwest temperature='too warm'': invalid boolean"}
  • Do not enclose names, tag keys, tag values, or field keys of measurements in double quotation marks (") or single quotation marks ('). If measurement names are enclosed in quotations marks, the corresponding line protocol is valid, but TSDB for InfluxDB® considers quotation marks as part of the names.

    Example:

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

    To query the data in the "weather" measurement, you must enclose the name of the measurement in double quotation marks (") and escape the double quotation marks (") in the measurement.

    > SELECT * FROM "\"weather\""
    name: "weather"
    ---------------
    time                            location     temperature
    2016-06-13T17:43:50.1004002Z    us-midwest   87
  • Do not enclose field values of the STRING, INTEGER, or BOOLEAN type in double quotation marks ("). If you enclose these values in double quotation marks ("), TSDB for InfluxDB® processes these values as strings.

    Example:

    > INSERT weather,location=us-midwest temperature="82"
    > SELECT * FROM weather WHERE temperature >= 70
    >
  • You must use double quotation marks (") to enclose field values of the STRING type.

    Example:

    > 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

Special characters and keywords

Special characters

Backslashes \ are always used to escape tag keys, tag values, and field keys.

  • Commas (,)

    weather,location=us\,midwest temperature=82 1465839830100400200
  • Equal signs (=)

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

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

    Backslashes (\) are always used to escape measurement names.

  • Commas (,)

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

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

    Backslashes (\) are always used to escape field values of the STRING type.

  • Double quotation marks (")

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

You do not need to escape backslashes (\) in the line protocol. If you escape backslashes (\) in the line protocol, no errors occur. For example, the following data is written:

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

The following code block shows the result of querying data from the weather measurement. Take note that the query results are the same if you enclose backslashes (\) in single or double quotation marks.

> 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

All other special characters also do not need to be escaped. For example, the line protocol can process 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

Keywords

The line protocol uses InfluxQL keywords as identifier names. In most cases, we recommend that you do not use InfluxQL keywords in your schema. This is because the keywords may be incorrectly processed in data queries.

The time keyword is not processed in the same manner as other InfluxQL keywords. The time keyword can be a continuous query name, a database name, measurement name, retention policy name, subscription name, or a username. In these cases, you do not need to use double quotation marks (") to enclose the time keyword. You cannot use the time keyword as a field key or a tag key. TSDB for InfluxDB® rejects data writes in which the time keyword is a field key or a tag key, and returns an error for this scenario. For more information, see FAQ.

Write data to TSDB for InfluxDB®

Write data to databases

This section describes how to use the line protocol to write data to TSDB for InfluxDB®. Two examples are used in this section. For more information, see Tools.

HTTP API

To use the HTTP API to write data to TSDB for InfluxDB®, send a POST request to the /write endpoint and include the data in the line protocol format in the request body.

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'

For more information about the in-depth explanation on query parameters, status codes, responses, and examples, see the documentation HTTP API.

CLI

To use the CLI of TSDB for InfluxDB® to write data to TSDB for InfluxDB®, start the CLI, write data to your database, and add INSERT in front of the data in the line protocol format.

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

You can also use the CLI to import data from a file.

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

Duplicate points

A point is uniquely identified by a measurement name, a tag set, and a timestamp. For example, you submit a point for which the measurement name, tag set, and timestamp are the same as those of an existing point and the field set of the submitted point is different from the field set of the existing point. In this case, the field set of the submitted point becomes the union of the previous and new field sets. If a conflict occurs, the new field set takes precedence.

For more information about the complete example of this scenario and how to handle duplicate points, see the corresponding section in FAQ.

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