Line protocol reference

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

• Elements of line protocol
• Data types and format
• Quotes
• Special characters
• Comments
• Naming restrictions
• Duplicate points

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

// Example
myTable,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.

Elements of line protocol

Table

(Required) The table name. InfluxDB accepts one table per point. Table 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

tableName 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

Whitespace

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

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

myTable fieldKey=1.0
myTable fieldKey=1
myTable fieldKey=-1.234456e+78

Integer

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

Integer field value examples

myTable fieldKey=1i
myTable fieldKey=12485903i
myTable fieldKey=-12485903i

UInteger

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

UInteger field value examples

myTable fieldKey=1u
myTable fieldKey=12485903u

String

Plain text string. Length limit 64KB.

String example

# String table name, field key, and field value
myTable fieldKey="this is a string"

Boolean

Stores true or false values.

Boolean field value examples

myTable fieldKey=true
myTable fieldKey=false
myTable fieldKey=t
myTable fieldKey=f
myTable fieldKey=TRUE
myTable fieldKey=FALSE

Unix timestamp

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

Unix timestamp example

myTableName fieldKey="fieldValue" 1556813561098000000

Quotes

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

^* Line protocol accepts double and single quotes in table 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 (\):

You do not need to escape other special characters.

Examples of special characters in line protocol

# Table name with spaces
my\ Table fieldKey="string value"

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

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

# Emojis
myTable,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:

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
myTable fieldKey="string value" 1556813561098000000

Naming restrictions

Table names, tag keys, and field keys are alphanumeric and must begin with a letter or a number. They can contain dashes (-) and underscores (_).

Duplicate points

A point is uniquely identified by the table name, tag set, and timestamp. If you submit line protocol with the same table, 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.