Time Series Database:Line protocol reference

Syntax

<measurement>[,<tag_key>=<tag_value>[,<tag_key>=<tag_value>]] <field_key>=<field_value>[,<field_key>=<field_value>] [<timestamp>]

Each line represents one data point. Lines are separated by a line feed (\n). The line protocol is whitespace-sensitive.

Example

myMeasurement,tag1=val1,tag2=val2 field1="v1",field2=1i 1465839830100400200

In this example:

• myMeasurement is the measurement name

• tag1=val1,tag2=val2 is the tag set

• field1="v1",field2=1i is the field set

• 1465839830100400200 is the timestamp in nanoseconds

Elements

Data types

The syntax for writing Boolean values differs from the syntax for querying them. For more information, see FAQ.

Field value types must be consistent within a shard but can differ across shards. For how type conflicts affect SELECT * queries, see FAQ.

Data type examples

Write 1.0 as a float

> INSERT mymeas value=1.0

Write 1 as a float

> INSERT mymeas value=1

Numeric literals without an i suffix are floats by default.

Write -1.234456e+78 as a float

> INSERT mymeas value=-1.234456e+78

Write 1 as an integer

> INSERT mymeas value=1i

Write a string field value

> INSERT mymeas value="stringing along"

Enclose string field values in double quotation marks.

Write a Boolean field value

> INSERT mymeas value=true

Do not enclose Boolean field values in quotation marks. The following statement writes true as a string, not a Boolean:

> INSERT mymeas value="true"

Type conflict within the same shard

> INSERT mymeas value=3 1465934559000000000
> INSERT mymeas value="stringing along" 1465934559000000001
ERR: {"error":"field type conflict: input field \"value\" on measurement \"mymeas\" is type string, already exists as type float"}

Type conflict across shards (succeeds)

> INSERT mymeas value=3 1465934559000000000
> INSERT mymeas value="stringing along" 1466625759000000000
>

When the two timestamps fall in different shards, the type conflict does not produce an error.

Quotation marks, special characters, and additional naming guidelines

> INSERT mymeas value=9 "1466625759000000000"
ERR: {"error":"unable to parse 'mymeas value=9 \"1466625759000000000\"': bad timestamp"}

> INSERT mymeas value="true"
> SHOW FIELD KEYS FROM "mymeas"
name: mymeas
------------
fieldKey         fieldType
value            string

> INSERT "mymeas" value=200
> SHOW MEASUREMENTS
name: measurements
------------------
name
"mymeas"
> SELECT * FROM mymeas
> SELECT * FROM "mymeas"
> SELECT * FROM "\"mymeas\""
name: "mymeas"
--------------
time                              value
2016-06-14T20:36:21.836131014Z   200

> INSERT "measurement\ with\ quo⚡️es\ and\ emoji",tag\ key\ with\ sp⚡️ces=tag\,value\,with"commas" field_k\ey="string field value, only \" need be esc⚡️ped"

Write line protocol data

For instructions on writing line protocol data to a database, see the Tools chapter.

Duplicate data points

A data point is uniquely identified by its measurement name, tag set, and timestamp. If you write a data point with the same measurement, tag set, and timestamp as an existing point:

• If the new point has a different field set than the existing point, the field set becomes the union of the old and new field sets.

• If a field key conflicts, the new value takes precedence.

For an example and guidance on avoiding duplicates, see FAQ.

Usage notes

• Sort tags before writing: Sort tags by tag key using the same ordering as the Go bytes.Compare function. Consistent tag ordering improves write performance.

• Use coarser timestamp precision: We recommend using coarse-grained timestamps to improve data compression performance.

• Synchronize clocks with NTP: TSDB for InfluxDB® uses the local UTC time of the host to assign timestamps. If the host clock is not synchronized with a Network Time Protocol (NTP) server, written data may have inaccurate timestamps.

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