All Products
Search
Document Center

Line protocol reference

Last Updated: Nov 17, 2021

The line protocol is a text-based format that is used to write data points to Time Series Database (TSDB) for InfluxDB®.

Line protocol

Syntax

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

The line protocol uses the line feed \n to separate lines. Each line represents a data point in TSDB for InfluxDB®. The line protocol is whitespace-sensitive.

Syntax description

The line protocol is used to specify the measurement, tag set, field set, and timestamp of each data point in TSDB for InfluxDB®.

Element

Required

Description

Type (More information in the "Data types" section)

measurement

Yes.

The name of the measurement. In TSDB for InfluxDB®, only one measurement can be specified for a data point.

Measurement names must be strings.

tag set

No.

All tag key-value pairs for a data point.

Tag keys and tag values must be strings.

field set

Yes. At least one field must be specified for a data point.

All field key-value pairs for a data point.

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

Timestamp

No. If no timestamp is specified for a data point, TSDB for InfluxDB® uses the local timestamp of the server as the timestamp of the data point. The local timestamp is in UTC and is measured in nanoseconds.

The timestamp of a data point. In TSDB for InfluxDB®, a data point can be associated with only one timestamp.

A timestamp is a UNIX time in nanoseconds. You can use the HTTP API to specify timestamps of alternative precisions.

Note

Before you send a data point to a TSDB for InfluxDB® database, sort tags by tag key. The sorting result must match the results from the Go bytes.Compare function. We recommend that you use coarse-grained timestamps for data points to improve the performance of data compression. Use the Network Time Protocol (NTP) to synchronize time between 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 data that the host writes to TSDB for InfluxDB® may contain inaccurate timestamps.

Data types

Data type

Element

Description

FLOAT

field value

Stores IEEE-754 64-bit floating-point numbers. FLOAT is the default numeric data type.

Examples: 1, 1.0, 1.e+78, and 1.E+78.

INTEGER

field value

Stores signed 64-bit integers that range from -9223372036854775808 to 9223372036854775807. You can add i to the end of a number to specify the number as an integer.

Example: 1i.

STRING

Measurement, tag key, tag value, field key, and field value

Stores strings. A string cannot exceed 64 KB in length.

BOOLEAN

field value

Stores TRUE or FALSE values.

  • Use the following syntax to write TRUE values: [t, T, true, True, TRUE].

  • Use the following syntax to write FALSE values: [f, F, false, False, FALSE].

TIMESTAMP

Timestamp

Stores UNIX nanosecond timestamps. You can use the HTTP API to specify timestamps of alternative precisions.

  • 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.

Syntax to write and query Boolean values

The syntax to write Boolean values is different from the syntax to query Boolean values. For more information, see FAQ.

Data type differences of field values

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 more information about how data type differences of field values affect SELECT * queries, see FAQ.

Examples

Example 1: Write the 1.0 field value as a floating-point number to TSDB for InfluxDB®

> INSERT mymeas value=1.0

Example 2: Write the 1 field value as a floating-point number to TSDB for InfluxDB®

> INSERT mymeas value=1

Example 3: Write the -1.234456e+78 field value as a floating-point number to TSDB for InfluxDB®

> INSERT mymeas value=-1.234456e+78

In TSDB for InfluxDB®, you can use scientific notation to specify field values.

Example 4: Write the 1 field value as an integer to TSDB for InfluxDB®

> INSERT mymeas value=1i

Example 5: Write the "stringing along" field value as a string to TSDB for InfluxDB®

> INSERT mymeas value="stringing along"

You must use double quotation marks (") to enclose string field values. For more information about quotation marks, see the "Quotation marks" section.

Example 6: Write the true field value as a Boolean value to TSDB for InfluxDB®

> INSERT mymeas value=true

Do not enclose field values of the BOOLEAN type in quotation marks ("). The following statement writes the true value as a string to TSDB for InfluxDB®:

> INSERT mymeas value="true"

Example 7: Attempt to write a string to a field in which a floating-point number is stored

If the timestamps of the floating-point number and the string are stored in the same shard, the following result is returned:

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

If the timestamps of the floating-point number and the string are stored in different shards, the following result is returned:

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

Quotation marks, special characters, and additional naming guidelines

Quotation marks

Element

Double quotation mark

Single quotation mark

Timestamp

Not used.

Not used

measurement, tag key, tag value, field key

Not used.

Not used

field value

You must use double quotation marks (") to enclose field values of the STRING type. Do not enclose floating-point numbers, integers, or Boolean values in double quotation marks (").

Not used

  • The line protocol allows you to use double quotation marks (") or single quotation marks (') to enclose measurement names, tag keys, tag values, and field keys. However, the line protocol considers double quotation marks (") and single quotation marks (') as part of a name, key, or value. This can make the query syntax complex. The following examples show how double quotation marks (") and single quotation marks (') affect query syntax.

Examples

Example 1: Invalid line protocol - Enclose a timestamp in double quotation marks

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

If a timestamp is enclosed in double quotation marks (") or single quotation marks ('), a bad timestamp error occurs.

Example 2: Semantic error - Enclose a Boolean field value in double quotation marks

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

TSDB for InfluxDB® assumes that all field values that are enclosed in double quotation marks (") are strings.

Example 3: Semantic error - Enclose a measurement name in double quotation marks

> 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

If you use double quotation marks (") to enclose a measurement name in your line protocol data, a semantic error may occur. To avoid this semantic error when you use double quotation marks (") to enclose the measurement name in the FROM clause, you must use a backslash (\) to escape each of the double quotation marks (").

Special characters

Use a backslash (\) to escape each of the following special characters in tag keys, tag values, and field keys:

  • Commas (,)

  • Equal signs (=)

  • Spaces ()

Use a backslash (\) to escape each of the following special characters in measurement names:

  • Commas (,)

  • Spaces ()

Use a backslash (\) to escape each of the following special characters in field values of the STRING type:

  • Double quotation marks (")

The line protocol does not require that you escape backslashes (\). You do not need to escape the other special characters that are not listed in this topic.

Examples

Example 1: Write data points that contain special characters

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

The system writes a data point. In the data point, the measurement is "measurement with quo⚡️es and emoji", the tag key is tag key with sp⚡️ces, the tag value is tag,value,with"commas", the field key is field_k\ey, and the field value is string field value, only " need be esc⚡️ped.

Additional naming guidelines

A number sign (#) at the beginning of a line is a valid character that indicates the start of a comment in the line protocol. TSDB for InfluxDB® ignores all the characters that are located between a number sign (#) and the next line feed (\n).

Measurement names, tag keys, tag values, field keys, and field values are case-sensitive.

The line protocol uses InfluxQL keywords as identifier names. In most cases, we recommend that you do not use 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. You can use the time keyword as 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 the time keyword. However, you cannot use the time keyword as a field key or a tag key. TSDB for InfluxDB® rejects write requests in which the time keyword is used as a field key or a tag key, and reports an error. For more information, see FAQ.

Use the line protocol to write data

For information about how to write line protocol data to a database, see the "Tools" chapter.

Duplicate data points

A data point is uniquely identified by a measurement name, a tag set, and a timestamp. If the measurement name, tag set, and timestamp of a new data point are the same as those of an existing data point, the new data point is a duplicate data point. If you submit a duplicate data point that contains a different field set than an existing data point, the field set of the new data point becomes the union of the previous field set and the new field set. If a conflict occurs, the new field set takes precedence.

For more information about an example of duplicate data points and how to avoid this issue, see FAQ.

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