Time Series Database:Line protocol reference

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

Data types

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

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