Line Protocol Tutorial

InfluxDB’s Line Protocol is a text based format for writing points to the database. Points must be in Line Protocol format for InfluxDB to successfully parse and write points (unless you’re using a service plugin).

Using fictional temperature data, this page introduces Line Protocol. It covers:

The final section, Writing data to InfluxDB, describes how to get data into InfluxDB and how InfluxDB handles Line Protocol duplicates.

Syntax

A single line of Line Protocol represents one data point in InfluxDB. It informs InfluxDB of the point’s measurement, tag set, field set, and timestamp. The following code block shows a sample of Line Protocol and breaks it into its individual components:

For best performance you should sort tags by key before sending them to the database. The sort should match the results from the Go bytes.Compare function.

Whitespace I

Separate the measurement and the field set or, if you’re including a tag set with your data point, separate the tag set and the field set with a whitespace. The whitespace is required in Line Protocol.

Valid Line Protocol with no tag set:

weather temperature=82 1465839830100400200

Field set

The field(s) for your data point. Every data point requires at least one field in Line Protocol.

Separate field key-value pairs with an equals sign = and no spaces:

<field_key>=<field_value>

Separate multiple field-value pairs with a comma and no spaces:

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

In the example, the field set consists of one field: temperature=82. Adding another field (bug_concentration=98) to the example looks like this:

Whitespace II

Separate the field set and the optional timestamp with a whitespace. The whitespace is required in Line Protocol if you’re including a timestamp.

Timestamp

The timestamp for your data point in nanosecond-precision Unix time. The timestamp is optional in Line Protocol. If you do not specify a timestamp for your data point InfluxDB uses the server’s local nanosecond timestamp in UTC.

In the example, the timestamp is 1465839830100400200 (that’s 2016-06-13T17:43:50.1004002Z in RFC3339 format). The Line Protocol below is the same data point but without the timestamp. When InfluxDB writes it to the database it uses your server’s local timestamp instead of 2016-06-13T17:43:50.1004002Z.

weather,location=us-midwest temperature=82

Use the HTTP API to specify timestamps with a precision other than nanoseconds, such as microseconds, milliseconds, or seconds. We recommend using the coarsest precision possible as this can result in significant improvements in compression. See the API Reference for more information.

Setup Tip:

Use the Network Time Protocol (NTP) to synchronize time between hosts. InfluxDB uses a host’s local time in UTC to assign timestamps to data; if hosts’ clocks aren’t synchronized with NTP, the timestamps on the data written to InfluxDB can be inaccurate.

Note: Because InfluxDB stores tag values as strings, InfluxDB cannot perform math on tag values. In addition, InfluxQL functions do not accept a tag value as a primary argument. It’s a good idea to take into account that information when designing your schema.

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. As mentioned above, by default, InfluxDB assumes that timestamps have nanosecond precision. See the API Reference for how to specify alternative precisions.

Field values can be floats, integers, strings, or booleans:

Floats - by default, InfluxDB assumes all numerical field values are floats.

Store the field value 82 as a float:

weather,location=us-midwest temperature=82 1465839830100400200

Integers - append an i to the field value to tell InfluxDB to store the number as an integer.

Within a measurement, a field’s type cannot differ within a shard, but it can differ across shards. For example, writing an integer to a field that previously accepted floats fails if InfluxDB attempts to store the integer in the same shard as the floats:

Duplicate points

A point is uniquely identified by the measurement name, tag set, and timestamp. If you submit Line Protocol with the same measurement, tag set, and timestamp, but with a different field set, the field set becomes the union of the old field set and the new field set, where any conflicts favor the new field set.