All Products
Search
Document Center

Line Portocol Reference

Last Updated: Aug 11, 2020

The line protocol is a text-based format that you use to write points to TSDB for InfluxDB®.

Line protocol

Syntax

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

Use the line feed \n to separate lines. Each line describes a point in TSDB for InfluxDB®. The line protocol is space sensitive.

Syntax description

The line protocol of TSDB for InfluxDB® specifies the measurement, tag set, field set, and timestamp of each point.

Element Optional or required Description Data type (For more information, see the “Data types” section.)
measurement Required. The name of the measurement. In TSDB for InfluxDB®, only one measurement can be specified for a point. Measurement names must be strings.
tag set Optional. The tag key-value pairs for the point. Tag keys and tag values must be strings.
field set Required. At least one field must be specified for a point. The field key-value pairs for the point. Field keys must be strings. Field values can be floating-point numbers, integers, or Boolean values.
Timestamp Optional. If you do not specify a timestamp for your point, TSDB for InfluxDB® uses the local timestamp of the server as the timestamp of the point. The local timestamp is in UTC and is measured in nanoseconds. The timestamp of the point. In TSDB for InfluxDB®, a point can be attached with only one timestamp. Timestamps of points are Unix timestamps that are measured in nanoseconds. You can use the HTTP API to specify a non-nanosecond timestamp granularity.

Considerations about performance and settings:

  • We recommend that you sort tags by tag key before you send points to your database. The expected sorting result is the same as the result of the Compare(a, b []byte) function of Go. For more information, see Compare(a, b []byte) function of Go.
  • We recommend that you use coarse-grained timestamps for your points to improve the performance of data compression.
  • Use the Network Time Protocol (NTP) to synchronize time among 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 timestamps of the data that the host writes to TSDB for InfluxDB® may be inaccurate.

Data types

Data type Element Description
FLOAT field value Stores IEEE-754 64-bit floating-point numbers. FLOAT is the default numeric data type. The examples include 1, 1.0, 1.e+ 78, and 1.E+ 78.
INT 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. For example, you can use 1i to specify the integer 1.
STRING Measurements, tag keys, tag values, field keys, and field values Stores strings. The maximum length of a string is 64 KB.
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 Timestamps Stores Unix timestamps that are measured in nanoseconds. You can use the HTTP API to specify a non-nanosecond timestamp granularity. The valid timestamp range is -9223372036854775806 to 9223372036854775806, or 1677-09-21T00:12:43.145224194Z to 2262-04-11T23:47:16.854775806Z.

Syntax for writing and querying Boolean values

The syntax for writing Boolean values is different from that for querying 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®

  1. > INSERT mymeas value=1.0

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

  1. > INSERT mymeas value=1

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

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

  1. > INSERT mymeas value=1i

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

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

  1. > INSERT mymeas value=true

Do not use quotation marks in the INSERT statement to enclose Boolean field values if you need to write the field values as Boolean values. The following statement writes true as a string to TSDB for InfluxDB®:

  1. > INSERT mymeas value="true"

Example 7: Attempt to write a string to a field that previously stored floating-point numbers

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

  1. > INSERT mymeas value=3 1465934559000000000
  2. > INSERT mymeas value="stringing along" 1465934559000000001
  3. 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 not stored in the same shard, the following result is returned:

  1. > INSERT mymeas value=3 1465934559000000000
  2. > INSERT mymeas value="stringing along" 1466625759000000000
  3. >

Quotation marks, special characters, and other naming guidelines

Quotation marks

Element Double quotation marks Single quotation marks
Timestamps Not used. Not used
measurement, tag key, tag value, field key Not used*. Not used*
field value Double quotation marks (“) must be used to enclose string field values. Double quotation marks (“) are not used to enclose floating-point numbers, integers, or Boolean values. Not used

The line protocol allows you to use double quotation marks (“) and single quotation marks (‘) to enclose measurement names, tag keys, tag values, or field keys. However, the line protocol considers the double quotation marks (“) and single quotation marks (‘) as part of the measurement names, tag keys, tag values, or field keys. This makes the query syntax complex. The following examples show how double quotation marks (“) and single quotation marks (‘) affect the query syntax.

Examples

Example 1: Invalid line protocol - Use double quotation marks (“) to enclose a timestamp

  1. > INSERT mymeas value=9 "1466625759000000000"
  2. 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 - Use double quotation marks (“) to enclose a Boolean field value

  1. > INSERT mymeas value="true"
  2. > SHOW FIELD KEYS FROM "mymeas"
  3. name: mymeas
  4. ------------
  5. fieldKey fieldType
  6. value string

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

Example 3: Semantic error - Use double quotation marks (“) to enclose a measurement name

  1. > INSERT "mymeas" value=200
  2. > SHOW MEASUREMENTS
  3. name: measurements
  4. ------------------
  5. name
  6. "mymeas"
  7. > SELECT * FROM mymeas
  8. > SELECT * FROM "mymeas"
  9. > SELECT * FROM "\"mymeas\""
  10. name: "mymeas"
  11. --------------
  12. time value
  13. 2016-06-14T20:36:21.836131014Z 200

A semantic error may occur if you use double quotation marks (“) to enclose a measurement name in your data that complies with the line protocol. To avoid the error when you query the measurement, you must use the FROM clause. In the FROM clause, you must use double quotation marks (“) to enclose the measurement name and use a backslash (\) to escape each double quotation mark (“).

Special characters

For tag keys, tag values, and field keys, you must use a backslash \ to escape each of the following special characters:

  • Commas (,)
  • Equal signs (=)
  • Spaces

For measurement names, you must use a backslash \ to escape each of the following special characters:

  • Commas (,)
  • Spaces

For string field values, you must use a backslash \ to escape each of the following special characters:

  • 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 a point that includes special characters to TSDB for InfluxDB®

  1. > 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 the specified point to TSDB for InfluxDB®. In the specified point, the measurement is "measurement with quo⚡es and emoji, the tag key is tag key with sp⚡️ces, and 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.

Other naming guidelines

The 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 the 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. We recommend that you avoid using 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. The time keyword can be 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 time in queries. You cannot use time as a field key or a tag key. TSDB for InfluxDB® rejects data writes where time is used as a field key or a tag key, and reports errors. For more information, see FAQ.

Use the line protocol to write data

For more information about how to write data that complies with the line protocol to databases, see the “Tools” topic.

Duplicate points

A point is uniquely identified by a measurement name, a tag set, and a timestamp. If two points have the same measurement name, tag set, and timestamp, they are considered as duplicate points. If you submit a duplicate point that has a different field set from an existing point, the field set of the point becomes the sum of the previous and new field sets. If a conflict occurs, the new field set prevails.

For more information about an example and how to avoid the issues, see FAQ.


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