Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 39 ยท Writing Data

Line Protocol Types and Escaping

Learn the five InfluxDB field types, how type conflicts are rejected, which characters to escape in line protocol, and how to write a safe serializer.

Line protocol looks simple until real data arrives: a city called "New York", a message containing a quote, a field that was an integer yesterday and a float today. This lesson covers the two rules that decide whether such writes succeed: each field has a fixed type, and special characters must be escaped.

Field types

Type Syntax Example Notes
Float plain number temp=21.5, ratio=3 64-bit; the default for numbers
Integer number + i count=42i Signed 64-bit
Unsigned integer number + u bytes=1048576u Supported in 2.x and 3.x
String double quotes msg="disk full" UTF-8; limited length per value
Boolean t, true, f, false (also upper-case variants) ok=true Unquoted

Tag values have no type: they are always strings, written without quotes.

Notice that ratio=3 is a float, not an integer. Only the trailing i makes an integer. This surprises many people when count=42 is later written as count=42i.

Types are fixed per field

The first write to a field decides its type for that measurement (in 1.x and 2.x, per shard group in practice; in 3.x, the table column type). Writing a different type later fails.

TEXT
room,name=kitchen humidity=48i     # humidity becomes an integer field
room,name=kitchen humidity=48.5    # rejected: field type conflict

InfluxDB responds with an error such as field type conflict and, depending on version, drops the conflicting points while accepting the rest of the batch (a "partial write"). This is one of the most common production surprises, usually caused by a client that sends 1 for a whole number and 1.5 for a fraction. Pick a type per field and always serialise it the same way: either always floats (write 1.0 or use a float formatter) or always integers.

This stand-in simulates the rule with a schema map. It is JavaScript, not InfluxDB, but the behaviour matches the documented rule.

JS Field type conflicts (stand-in)

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

No output.

Characters you must escape

Escape a character by putting a backslash in front of it. What needs escaping depends on where it appears.

Where Escape these
Measurement name comma , and space
Tag keys, tag values, field keys comma , equals = and space
String field values double quote " and backslash \
Timestamp, numbers, booleans nothing
TEXT
my\ measurement,city=New\ York,note\=tag=a\,b msg="She said \"hi\" at C:\\temp" 1772359200

Newlines are not allowed inside a point (they separate points); a string value containing a newline is permitted in a quoted field in some versions, but sending the line break as the two characters \n inside your own encoding and decoding it later is safer.

Two points of confusion:

  • Spaces in tag values need the backslash, but spaces in string field values do not, because the double quotes already protect them.
  • A backslash before a character that doesn't need escaping is kept literally, so \d stays two characters. Only escape what the table lists.

A safe serializer

Never build lines by joining raw strings with user data: a value with a comma or a space will corrupt the point (and attackers can inject whole extra points). Use a library, or at least a function like this one.

JS Serialize with correct escaping (stand-in)

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

No output.

Look at the output: my\ measurement, city=New\ York, note\==a\,b. Every special character is protected.

Strings are not for numbers

Putting numbers in string fields (temp="21.5") prevents mean(), max() and arithmetic. Reserve strings for text such as messages and states. Booleans are good for flags (online=true), but a small integer or a tag (state=ok) is often easier to aggregate: counting ok versus failed is natural with a tag, while a boolean needs a conversion.

Checking it in SQL

In InfluxDB 3 field types become column types. SQLite is more flexible than InfluxDB, but it still shows why a numeric column is useful for aggregation and a text column is not (SQLite stand-in):

SQL Numbers stored as text do not aggregate well (SQLite stand-in)

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

The text column returns '9.5' as the "maximum" because strings compare alphabetically. Typed fields avoid that bug entirely.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What type is the field value count=42?

    Without a trailing i or u a number is always a float.
  2. 2. You earlier wrote humidity=48i. What happens to a later write of humidity=48.5?

    The first write fixes the field type; a different type is rejected.
  3. 3. Which value needs a backslash escape in a TAG value?

    Commas, equals signs and spaces must be escaped in tag values; double quotes are escaped only in string field values.
  4. 4. Why should you use a client library to build lines instead of string concatenation?

    Unescaped user data can break lines or inject extra points.

Summary

  • Fields are float, integer (i), unsigned (u), string (double quotes) or boolean; tags are always strings.
  • The first write fixes a field's type; later mismatches are rejected, often as partial writes.
  • Escape commas, equals signs and spaces in tags, field keys and measurements as listed; escape quotes and backslashes in string fields.
  • Use typed numeric fields for anything you aggregate, and a serializer from a library for all external data.

Next: Writing with the HTTP API