Documentation

Line protocol

InfluxDB uses line protocol to write data points. It is a text-based format that provides the measurement, tag set, field set, and timestamp of a data point.

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

// Example
myMeasurement,tag1=value1,tag2=value2 fieldKey="fieldValue" 1556813561098000000

Lines separated by the newline character \n represent a single point in InfluxDB. Line protocol is whitespace sensitive.

Line protocol does not support the newline character \n in tag or field values.

Elements of line protocol

measurement,tag1=val1,tag2=val2 field1="v1",field2=1i 0000000000000000000

Measurement

(Required) The measurement name. InfluxDB accepts one measurement per point. Measurement names are case-sensitive and subject to naming restrictions.

Data type: String

Tag set

Optional – All tag key-value pairs for the point. Key-value relationships are denoted with the = operand. Multiple tag key-value pairs are comma-delimited. Tag keys and tag values are case-sensitive. Tag keys are subject to naming restrictions. Tag values cannot be empty; instead, omit the tag from the tag set.

Key data type: String
Value data type: String

Field set

(Required) All field key-value pairs for the point. Points must have at least one field. Field keys and string values are case-sensitive. Field keys are subject to naming restrictions.

Key data type: String
Value data type: Float | Integer | UInteger | String | Boolean

Always double quote string field values. More on quotes below.

measurementName fieldKey="field string value" 1556813561098000000

Timestamp

Optional – The unix timestamp for the data point. InfluxDB accepts one timestamp per point. If no timestamp is provided, InfluxDB uses the system time (UTC) of its host machine.

Data type: Unix timestamp

Important notes about timestamps

  • To ensure a data point includes the time a metric is observed (not received by InfluxDB), include the timestamp.
  • If your timestamps are not in nanoseconds, specify the precision of your timestamps when writing the data to InfluxDB.

Whitespace

Whitespace in line protocol determines how InfluxDB interprets the data point. The first unescaped space delimits the measurement and the tag set from the field set. The second unescaped space delimits the field set from the timestamp.

measurement,tag1=val1,tag2=val2 field1="v1",field2=1i 0000000000000000000

Data types and format

Float

IEEE-754 64-bit floating-point numbers. Default numerical type. InfluxDB supports scientific notation in float field values.

Float field value examples
myMeasurement fieldKey=1.0
myMeasurement fieldKey=1
myMeasurement fieldKey=-1.234456e+78

Integer

Signed 64-bit integers. Trailing i on the number specifies an integer.

Minimum integerMaximum integer
-9223372036854775808i9223372036854775807i
Integer field value examples
myMeasurement fieldKey=1i
myMeasurement fieldKey=12485903i
myMeasurement fieldKey=-12485903i

UInteger

Unsigned 64-bit integers. Trailing u on the number specifies an unsigned integer.

Minimum uintegerMaximum uinteger
0u18446744073709551615u
UInteger field value examples
myMeasurement fieldKey=1u
myMeasurement fieldKey=12485903u

String

Plain text string. Length limit 64KB.

String example
# String measurement name, field key, and field value
myMeasurement fieldKey="this is a string"

Boolean

Stores true or false values.

Boolean valueAccepted syntax
Truet, T, true, True, TRUE
Falsef, F, false, False, FALSE
Boolean field value examples
myMeasurement fieldKey=true
myMeasurement fieldKey=false
myMeasurement fieldKey=t
myMeasurement fieldKey=f
myMeasurement fieldKey=TRUE
myMeasurement fieldKey=FALSE

Do not quote boolean field values. Quoted field values are interpreted as strings.

Unix timestamp

Unix timestamp in a specified precision. Default precision is nanoseconds (ns).

Minimum timestampMaximum timestamp
-92233720368547758069223372036854775806
Unix timestamp example
myMeasurementName fieldKey="fieldValue" 1556813561098000000

Quotes

Line protocol supports single and double quotes as described in the following table:

ElementDouble quotesSingle quotes
MeasurementLimited *Limited *
Tag keyLimited *Limited *
Tag valueLimited *Limited *
Field keyLimited *Limited *
Field valueStrings onlyNever
TimestampNeverNever

* Line protocol accepts double and single quotes in measurement names, tag keys, tag values, and field keys, but interprets them as part of the name, key, or value.

Special Characters

Line protocol supports special characters in string elements. In the following contexts, it requires escaping certain characters with a backslash (\):

ElementEscape characters
MeasurementComma, Space
Tag keyComma, Equals Sign, Space
Tag valueComma, Equals Sign, Space
Field keyComma, Equals Sign, Space
Field valueDouble quote, Backslash

You do not need to escape other special characters.

Examples of special characters in line protocol
# Measurement name with spaces
my\ Measurement fieldKey="string value"

# Double quotes in a string field value
myMeasurement fieldKey="\"string\" within a string"

# Tag keys and values with spaces
myMeasurement,tag\ Key1=tag\ Value1,tag\ Key2=tag\ Value2 fieldKey=100

# Emojis
myMeasurement,tagKey=🍭 fieldKey="Launch 🚀" 1556813561098000000

Escaping backslashes

Line protocol supports both literal backslashes and backslashes as an escape character. With two contiguous backslashes, the first is interpreted as an escape character. For example:

BackslashesInterpreted as
\\
\\\
\\\\\
\\\\\\
\\\\\\\\
\\\\\\\\\

Comments

Line protocol interprets # at the beginning of a line as a comment character and ignores all subsequent characters until the next newline \n.

# This is a comment
myMeasurement fieldKey="string value" 1556813561098000000

Naming restrictions

Measurement names, tag keys, and field keys cannot begin with an underscore _. The _ namespace is reserved for InfluxDB system use.

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.


Was this page helpful?

Thank you for your feedback!


The future of Flux

Flux is going into maintenance mode. You can continue using it as you currently are without any changes to your code.

Read more

InfluxDB v3 enhancements and InfluxDB Clustered is now generally available

New capabilities, including faster query performance and management tooling advance the InfluxDB v3 product line. InfluxDB Clustered is now generally available.

InfluxDB v3 performance and features

The InfluxDB v3 product line has seen significant enhancements in query performance and has made new management tooling available. These enhancements include an operational dashboard to monitor the health of your InfluxDB cluster, single sign-on (SSO) support in InfluxDB Cloud Dedicated, and new management APIs for tokens and databases.

Learn about the new v3 enhancements


InfluxDB Clustered general availability

InfluxDB Clustered is now generally available and gives you the power of InfluxDB v3 in your self-managed stack.

Talk to us about InfluxDB Clustered

InfluxDB Cloud powered by TSM