Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 39 ยท Writing Data

Line Protocol: The InfluxDB Write Format

Learn InfluxDB line protocol: the measurement, tag set, field set and timestamp syntax, how to write several points, comments, and common formatting mistakes.

Line protocol is the text format InfluxDB reads when you write data. One line is one point. It is compact, easy to generate from any language and identical across InfluxDB 1.x, 2.x and 3.x, so once you can read it you can read almost any InfluxDB example on the internet.

This lesson teaches the syntax, shows how to build lines in code and lists the mistakes that cause most write errors.

The syntax

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

There are exactly two spaces that matter:

  1. The first unescaped space separates the measurement and tags from the fields.
  2. The second separates the fields from the timestamp.
TEXT
weather,city=Lisbon,sensor=roof temp=18.4,humidity=62i 1772359200000000000
Segment Example Rules
Measurement weather Required
Tag set ,city=Lisbon,sensor=roof Optional; comma-separated key=value, no spaces
Field set temp=18.4,humidity=62i At least one; comma-separated key=value
Timestamp 1772359200000000000 Optional integer (default unit nanoseconds)

Points are separated by newlines. A write request can contain thousands of lines.

TEXT
# lines starting with # are comments
weather,city=Lisbon temp=18.4 1772359200000000000
weather,city=Porto temp=15.1 1772359200000000000
weather,city=Lisbon temp=18.9 1772359260000000000

Tag order and performance

For best write performance, sort tag keys alphabetically (in byte order). The server does not require it, but it normalises tag sets internally, so pre-sorted input saves work. Client libraries do this for you.

A serializer in code

You rarely hand-write lines in production; you build them from data. This is a plain JavaScript stand-in for what a client library does (escaping is left to the next lesson, so the sample values here contain no special characters).

JS Build line protocol from objects (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The output sorts the tag keys (city before sensor) and marks humidity as an integer with the trailing i.

Reading a line back

A parser is the other half. This stand-in splits a simple line into its parts so you can see how the two separator spaces work. Real parsers must also handle escapes, quoted strings with spaces and many edge cases.

JS Split a line into its four parts (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Writing it to a server

The same text goes over HTTP unchanged. The commands below are read-only here; they need a server and a token.

Terminal
# 2.x
curl --request POST "http://localhost:8086/api/v2/write?org=my-org&bucket=weather&precision=s" \
  --header "Authorization: Token $INFLUX_TOKEN" \
  --data-binary @points.lp

# 3.x
curl --request POST "http://localhost:8181/api/v3/write_lp?db=weather&precision=second" \
  --header "Authorization: Bearer $INFLUXDB3_AUTH_TOKEN" \
  --data-binary @points.lp

@points.lp reads the file. Use --data-binary rather than -d: plain -d strips newlines, which collapses many lines into one.

A SQL view of the same points

In InfluxDB 3 every measurement becomes a table. The lines above would turn into rows like these (SQLite stand-in):

SQL Lines as table rows (SQLite stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Common mistakes

Mistake Result Fix
Space inside a tag value (city=New York) Parse error or wrong split Escape: city=New\ York
No field set (weather,city=Lisbon 1772359200) Rejected: a point needs a field Add at least one field
Integer without i (humidity=62) Stored as float Add i
Quoted number as a tag Tags are strings, quotes are part of the value Remove quotes
String field without double quotes Parse error Wrap in "..."
Timestamp in seconds, no precision Date in 1970 Pass precision=s (Timestamps)
Windows line endings or missing final newline Usually fine; a stray \r inside a value is not Normalise newlines
Same tag and field key Type conflict errors Use different names

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In a line protocol line, what separates tags from fields?

    The first unescaped space ends the measurement and tag set; the second ends the field set.
  2. 2. Which line is valid?

    A point needs at least one field; the timestamp is optional.
  3. 3. Why use curl --data-binary for files?

    Plain -d strips newlines, merging all lines into one.
  4. 4. What does the trailing i in humidity=62i mean?

    Without i a number is a float; i marks a signed integer.

Summary

  • A line is measurement,tags fields timestamp; points are separated by newlines.
  • Tags are optional strings, fields are required and typed, the timestamp is optional.
  • Two unescaped spaces matter; sort tag keys and use exactly one space as the separator.
  • The same text works for every InfluxDB generation and every write path.

Next: Line Protocol Types and Escaping