InfluxDB line protocol tutorial

The InfluxDB line protocol is a text based format for writing points to thedatabase.Points must be in line protocol format for InfluxDB to successfully parse andwrite points (unless you’re using a service plugin).

Using fictional temperature data, this page introduces InfluxDB line protocol.It covers:

SyntaxData TypesQuotingSpecial Characters and Keywords

The final section, Writing data to InfluxDB,describes how to get data into InfluxDB and how InfluxDB handles LineProtocol duplicates.

Syntax

A single line of text in line protocol format represents one data point in InfluxDB.It informs InfluxDB of the point’s measurement, tag set, field set, andtimestamp.The following code block shows a sample of line protocol and breaks it into itsindividual components:

  1. weather,location=us-midwest temperature=82 1465839830100400200
  2.   |    -------------------- --------------  |
  3.   |             |             |             |
  4.   |             |             |             |
  5. +-----------+--------+-+---------+-+---------+
  6. |measurement|,tag_set| |field_set| |timestamp|
  7. +-----------+--------+-+---------+-+---------+

Moving across each element in the diagram:

Measurement

The name of the measurementthat you want to write your data to.The measurement is required in line protocol.

In the example, the measurement name is weather.

Tag set

The tag(s) that you want to includewith your data point.Tags are optional in line protocol.Notice that the measurement and tag set are separated by a comma and no spaces.

Separate tag key-value pairs with an equals sign = and no spaces:

  1. <tag_key>=<tag_value>

Separate multiple tag-value pairs with a comma and no spaces:

  1. <tag_key>=<tag_value>,<tag_key>=<tag_value>

In the example, the tag set consists of one tag: location=us-midwest.Adding another tag (season=summer) to the example looks like this:

  1. weather,location=us-midwest,season=summer temperature=82 1465839830100400200

For best performance you should sort tags by key before sending them to thedatabase.The sort should match the results from theGo bytes.Compare function.

Whitespace I

Separate the measurement and the field set or, if you’re including a tag setwith your data point, separate the tag set and the field set with a whitespace.The whitespace is required in line protocol.

Valid line protocol with no tag set:

  1. weather temperature=82 1465839830100400200

Field set

The field(s) for your data point.Every data point requires at least one field in line protocol.

Separate field key-value pairs with an equals sign = and no spaces:

  1. <field_key>=<field_value>

Separate multiple field-value pairs with a comma and no spaces:

  1. <field_key>=<field_value>,<field_key>=<field_value>

In the example, the field set consists of one field: temperature=82.Adding another field (humidity=71) to the example looks like this:

  1. weather,location=us-midwest temperature=82,humidity=71 1465839830100400200

Whitespace II

Separate the field set and the optional timestamp with a whitespace.The whitespace is required in line protocol if you’re including a timestamp.

Timestamp

The timestamp for your datapoint in nanosecond-precision Unix time.The timestamp is optional in line protocol.If you do not specify a timestamp for your data point InfluxDB uses the server’slocal nanosecond timestamp in UTC.

In the example, the timestamp is 1465839830100400200 (that’s2016-06-13T17:43:50.1004002Z in RFC3339 format).The line protocol below is the same data point but without the timestamp.When InfluxDB writes it to the database it uses your server’slocal timestamp instead of 2016-06-13T17:43:50.1004002Z.

  1. weather,location=us-midwest temperature=82

Use the InfluxDB API to specify timestamps with a precision other than nanoseconds,such as microseconds, milliseconds, or seconds.We recommend using the coarsest precision possible as this can result insignificant improvements in compression.See the API Reference for more information.

Setup Tip:

Use the Network Time Protocol (NTP) to synchronize time between hosts.InfluxDB uses a host’s local time in UTC to assign timestamps to data; ifhosts’ clocks aren’t synchronized with NTP, the timestamps on the data writtento InfluxDB can be inaccurate.

Data types

This section covers the data types of line protocol’s major components:measurements,tag keys,tag values,field keys,field values, andtimestamps.

Measurements, tag keys, tag values, and field keys are always strings.

Note:Because InfluxDB stores tag values as strings, InfluxDB cannot perform math ontag values.In addition, InfluxQL functionsdo not accept a tag value as a primary argument.It’s a good idea to take into account that information when designing yourschema.

Timestamps are UNIX timestamps.The minimum valid timestamp is -9223372036854775806 or 1677-09-21T00:12:43.145224194Z.The maximum valid timestamp is 9223372036854775806 or 2262-04-11T23:47:16.854775806Z.As mentioned above, by default, InfluxDB assumes that timestamps havenanosecond precision.See the API Reference for how to specifyalternative precisions.

Field values can be floats, integers, strings, or Booleans:

  • Floats - by default, InfluxDB assumes all numerical field values are floats.

Store the field value 82 as a float:

  1. weather,location=us-midwest temperature=82 1465839830100400200
  • Integers - append an i to the field value to tell InfluxDB to store thenumber as an integer.

Store the field value 82 as an integer:

  1. weather,location=us-midwest temperature=82i 1465839830100400200
  • Strings - double quote string field values (more on quoting in line protocolbelow).

Store the field value too warm as a string:

  1. weather,location=us-midwest temperature="too warm" 1465839830100400200
  • Booleans - specify TRUE with t, T, true, True, or TRUE. SpecifyFALSE with f, F, false, False, or FALSE.

Store the field value true as a Boolean:

  1. weather,location=us-midwest too_hot=true 1465839830100400200

Note: Acceptable Boolean syntax differs for data writes and dataqueries. SeeFrequently Asked Questionsfor more information.

Within a measurement, a field’s type cannot differ within ashard, but it can differ acrossshards. For example, writing an integer to a field that previously acceptedfloats fails if InfluxDB attempts to store the integer in the same shard as thefloats:

  1. > INSERT weather,location=us-midwest temperature=82 1465839830100400200
  2. > INSERT weather,location=us-midwest temperature=81i 1465839830100400300
  3. ERR: {"error":"field type conflict: input field \"temperature\" on measurement \"weather\" is type int64, already exists as type float"}

But, writing an integer to a field that previously accepted floats succeeds ifInfluxDB stores the integer in a new shard:

  1. > INSERT weather,location=us-midwest temperature=82 1465839830100400200
  2. > INSERT weather,location=us-midwest temperature=81i 1467154750000000000
  3. >

SeeFrequently Asked Questionsfor how field value type discrepancies can affect SELECT * queries.

Quoting

This section covers when not to and when to double (") or single (')quote in line protocol.Moving from never quote to please do quote:

  • Never double or single quote the timestamp.It’s not valid line protocol.

Example:

  1. > INSERT weather,location=us-midwest temperature=82 "1465839830100400200"
  2. ERR: {"error":"unable to parse 'weather,location=us-midwest temperature=82 \"1465839830100400200\"': bad timestamp"}
  • Never single quote field values (even if they’re strings!).It’s also not valid line protocol.

Example:

  1. > INSERT weather,location=us-midwest temperature='too warm'
  2. ERR: {"error":"unable to parse 'weather,location=us-midwest temperature='too warm'': invalid boolean"}
  • Do not double or single quote measurement names, tag keys, tag values, and fieldkeys.It is valid line protocol but InfluxDB assumes that the quotes are part of thename.

Example:

  1. > INSERT weather,location=us-midwest temperature=82 1465839830100400200
  2. > INSERT "weather",location=us-midwest temperature=87 1465839830100400200
  3. > SHOW MEASUREMENTS
  4. name: measurements
  5. ------------------
  6. name
  7. "weather"
  8. weather

To query data in "weather" you need to double quote the measurement name andescape the measurement’s double quotes:

  1. > SELECT * FROM "\"weather\""
  2. name: "weather"
  3. ---------------
  4. time                            location     temperature
  5. 2016-06-13T17:43:50.1004002Z    us-midwest   87
  • Do not double quote field values that are floats, integers, or Booleans.InfluxDB will assume that those values are strings.

Example:

  1. > INSERT weather,location=us-midwest temperature="82"
  2. > SELECT * FROM weather WHERE temperature >= 70
  3. >
  • Do double quote field values that are strings.

Example:

  1. > INSERT weather,location=us-midwest temperature="too warm"
  2. > SELECT * FROM weather
  3. name: weather
  4. -------------
  5. time                            location     temperature
  6. 2016-06-13T19:10:09.995766248Z  us-midwest   too warm

Special characters and keywords

Special characters

For tag keys, tag values, and field keys always use a backslash character \to escape:

  • commas ,
  1. weather,location=us\,midwest temperature=82 1465839830100400200
  • equal signs =
  1. weather,location=us-midwest temp\=rature=82 1465839830100400200
  • spaces
  1. weather,location\ place=us-midwest temperature=82 1465839830100400200

For measurements always use a backslash character \ to escape:

  • commas ,
  1. wea\,ther,location=us-midwest temperature=82 1465839830100400200
  • spaces
  1. wea\ ther,location=us-midwest temperature=82 1465839830100400200

For string field values use a backslash character \ to escape:

  • double quotes "
  1. weather,location=us-midwest temperature="too\"hot\"" 1465839830100400200

line protocol does not require users to escape the backslash character \ butwill not complain if you do. For example, inserting the following:

  1. weather,location=us-midwest temperature_str="too hot/cold" 1465839830100400201
  2. weather,location=us-midwest temperature_str="too hot\cold" 1465839830100400202
  3. weather,location=us-midwest temperature_str="too hot\\cold" 1465839830100400203
  4. weather,location=us-midwest temperature_str="too hot\\\cold" 1465839830100400204
  5. weather,location=us-midwest temperature_str="too hot\\\\cold" 1465839830100400205
  6. weather,location=us-midwest temperature_str="too hot\\\\\cold" 1465839830100400206

Will be interpreted as follows (notice that a single and double backslash produce the same record):

  1. > SELECT * FROM "weather"
  2. name: weather
  3. time                location   temperature_str
  4. ----                --------   ---------------
  5. 1465839830100400201 us-midwest too hot/cold
  6. 1465839830100400202 us-midwest too hot\cold
  7. 1465839830100400203 us-midwest too hot\cold
  8. 1465839830100400204 us-midwest too hot\\cold
  9. 1465839830100400205 us-midwest too hot\\cold
  10. 1465839830100400206 us-midwest too hot\\\cold

All other special characters also do not require escaping.For example, line protocol handles emojis with no problem:

  1. > INSERT we⛅️ther,location=us-midwest temper🔥ture=82 1465839830100400200
  2. > SELECT * FROM "we⛅️ther"
  3. name: we⛅️ther
  4. ------------------
  5. time                          location       temper🔥ture
  6. 1465839830100400200     us-midwest     82

Keywords

Line protocol acceptsInfluxQL keywordsas identifier names.In general, we recommend avoiding using InfluxQL keywords in your schema asit can causeconfusion when querying the data.

The keyword time is a special case.time can be acontinuous query name,database name,measurement name,retention policy name,subscription name, anduser name.In those cases, time does not require double quotes in queries.time cannot be a field key ortag key;InfluxDB rejects writes with time as a field key or tag key and returns an error.See Frequently Asked Questions for more information.

Writing data to InfluxDB

Getting data in the database

Now that you know all about the InfluxDB line protocol, how do you actually get theline protocol to InfluxDB?Here, we’ll give two quick examples and then point you to theTools sections for furtherinformation.

InfluxDB API

Write data to InfluxDB using the InfluxDB API.Send a POST request to the /write endpoint and provide your line protocol inthe request body:

  1. curl -i -XPOST "http://localhost:8086/write?db=science_is_cool" --data-binary 'weather,location=us-midwest temperature=82 1465839830100400200'

For in-depth descriptions of query string parameters, status codes, responses,and more examples, see the API Reference.

CLI

Write data to InfluxDB using the InfluxDB command line interface (CLI).Launch the CLI, use the relevantdatabase, and put INSERT infront of your line protocol:

  1. INSERT weather,location=us-midwest temperature=82 1465839830100400200

You can also use the CLI toimport LineProtocol from a file.

There are several ways to write data to InfluxDB.See the Tools section for moreon the InfluxDB API, theCLI, and the available Service Plugins (UDP,Graphite,CollectD, andOpenTSDB).

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 oldfield set and the new field set, where any conflicts favor the new field set.

For a complete example of this behavior and how to avoid it, seeHow does InfluxDB handle duplicate point?