Get started writing data

  • 2 / 5

InfluxDB provides many different options for ingesting or writing data, including the following:

This tutorial walks you through the fundamental of using line protocol to write data to InfluxDB. If using tools like Telegraf or InfluxDB client libraries, they will build the line protocol for you, but it’s good to understand how line protocol works.

Line protocol

All data written to InfluxDB is written using line protocol, a text-based format that lets you provide the necessary information to write a data point to InfluxDB. This tutorial covers the basics of line protocol, but for detailed information, see the Line protocol reference.

Line protocol elements

Each line of line protocol contains the following elements:

* Required

  • * measurement: String that identifies the measurement to store the data in.
  • tag set: Comma-delimited list of key value pairs, each representing a tag. Tag keys and values are unquoted strings. Spaces, commas, and equal characters must be escaped.
  • * field set: Comma-delimited list key value pairs, each representing a field. Field keys are unquoted strings. Spaces and commas must be escaped. Field values can be strings (quoted), floats, integers, unsigned integers, or booleans.
  • timestamp: Unix timestamp associated with the data. InfluxDB supports up to nanosecond precision. If the precision of the timestamp is not in nanoseconds, you must specify the precision when writing the data to InfluxDB.

Line protocol element parsing

  • measurement: Everything before the first unescaped comma before the first whitespace.
  • tag set: Key-value pairs between the first unescaped comma and the first unescaped whitespace.
  • field set: Key-value pairs between the first and second unescaped whitespaces.
  • timestamp: Integer value after the second unescaped whitespace.
  • Lines are separated by the newline character (\n). Line protocol is whitespace sensitive.

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

For schema design recommendations, see InfluxDB schema design.

Construct line protocol

With a basic understanding of line protocol, you can now construct line protocol and write data to InfluxDB. Consider a use case where you collect data from sensors in your home. Each sensor collects temperature, humidity, and carbon monoxide readings. To collect this data, use the following schema:

  • measurement: home
    • tags
      • room: Living Room or Kitchen
    • fields
      • temp: temperature in °C (float)
      • hum: percent humidity (float)
      • co: carbon monoxide in parts per million (integer)
    • timestamp: Unix timestamp in second precision

Data is collected hourly beginning at 2022-01-01T08:00:00Z (UTC) until 2022-01-01T20:00:00Z (UTC). The resulting line protocol would look something like the following:

Home sensor data line protocol
  1. home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000
  2. home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000
  3. home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1641027600
  4. home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641027600
  5. home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1641031200
  6. home,room=Kitchen temp=22.7,hum=36.1,co=0i 1641031200
  7. home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1641034800
  8. home,room=Kitchen temp=22.4,hum=36.0,co=0i 1641034800
  9. home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1641038400
  10. home,room=Kitchen temp=22.5,hum=36.0,co=0i 1641038400
  11. home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1641042000
  12. home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641042000
  13. home,room=Living\ Room temp=22.3,hum=36.1,co=0i 1641045600
  14. home,room=Kitchen temp=22.8,hum=36.3,co=1i 1641045600
  15. home,room=Living\ Room temp=22.3,hum=36.1,co=1i 1641049200
  16. home,room=Kitchen temp=22.7,hum=36.2,co=3i 1641049200
  17. home,room=Living\ Room temp=22.4,hum=36.0,co=4i 1641052800
  18. home,room=Kitchen temp=22.4,hum=36.0,co=7i 1641052800
  19. home,room=Living\ Room temp=22.6,hum=35.9,co=5i 1641056400
  20. home,room=Kitchen temp=22.7,hum=36.0,co=9i 1641056400
  21. home,room=Living\ Room temp=22.8,hum=36.2,co=9i 1641060000
  22. home,room=Kitchen temp=23.3,hum=36.9,co=18i 1641060000
  23. home,room=Living\ Room temp=22.5,hum=36.3,co=14i 1641063600
  24. home,room=Kitchen temp=23.1,hum=36.6,co=22i 1641063600
  25. home,room=Living\ Room temp=22.2,hum=36.4,co=17i 1641067200
  26. home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200

Write line protocol to InfluxDB

Use the InfluxDB UI, influx CLI, or InfluxDB API to write the line protocol above to InfluxDB.

InfluxDB UI influx CLI InfluxDB API

  1. Visit localhost:8086 in a browser to log in and access the InfluxDB UI.

  2. Navigate to Load Data > Buckets using the left navigation bar.

Load Data

  1. Click Add Data on the bucket you want to write the data to and select Line Protocol.
  2. Select Enter Manually.
  3. Important In the Precision drop-down menu above the line protocol text field, select Seconds (to match to precision of the timestamps in the line protocol).
  4. Copy the line protocol above and paste it into the line protocol text field.
  5. Click Write Data.

The UI will confirm that the data has been written successfully.

  1. If you haven’t already, download, install, and configure the influx CLI.

  2. Use the influx write command to write the line protocol above to InfluxDB.

    Provide the following:

    1. influx write \
    2.   --bucket get-started \
    3.   --precision s "
    4. home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000
    5. home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000
    6. home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1641027600
    7. home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641027600
    8. home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1641031200
    9. home,room=Kitchen temp=22.7,hum=36.1,co=0i 1641031200
    10. home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1641034800
    11. home,room=Kitchen temp=22.4,hum=36.0,co=0i 1641034800
    12. home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1641038400
    13. home,room=Kitchen temp=22.5,hum=36.0,co=0i 1641038400
    14. home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1641042000
    15. home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641042000
    16. home,room=Living\ Room temp=22.3,hum=36.1,co=0i 1641045600
    17. home,room=Kitchen temp=22.8,hum=36.3,co=1i 1641045600
    18. home,room=Living\ Room temp=22.3,hum=36.1,co=1i 1641049200
    19. home,room=Kitchen temp=22.7,hum=36.2,co=3i 1641049200
    20. home,room=Living\ Room temp=22.4,hum=36.0,co=4i 1641052800
    21. home,room=Kitchen temp=22.4,hum=36.0,co=7i 1641052800
    22. home,room=Living\ Room temp=22.6,hum=35.9,co=5i 1641056400
    23. home,room=Kitchen temp=22.7,hum=36.0,co=9i 1641056400
    24. home,room=Living\ Room temp=22.8,hum=36.2,co=9i 1641060000
    25. home,room=Kitchen temp=23.3,hum=36.9,co=18i 1641060000
    26. home,room=Living\ Room temp=22.5,hum=36.3,co=14i 1641063600
    27. home,room=Kitchen temp=23.1,hum=36.6,co=22i 1641063600
    28. home,room=Living\ Room temp=22.2,hum=36.4,co=17i 1641067200
    29. home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200
    30. "

To write data to InfluxDB using the InfluxDB HTTP API, send a request to the InfluxDB API /api/v2/write endpoint using the POST request method.

  1. POST http://localhost:8086/api/v2/write

Include the following with your request:

  • Headers:
    • Authorization: Token <INFLUX_TOKEN>
    • Content-Type: text/plain; charset=utf-8
    • Accept: application/json
  • Query parameters:
    • org: InfluxDB organization name
    • bucket: InfluxDB bucket name
    • precision: timestamp precision (default is ns)
  • Request body: Line protocol as plain text

The following example uses cURL and the InfluxDB API to write line protocol to InfluxDB:

  1. export INFLUX_HOST=http://localhost:8086
  2. export INFLUX_ORG=<YOUR_INFLUXDB_ORG>
  3. export INFLUX_TOKEN=<YOUR_INFLUXDB_API_TOKEN>
  5. curl --request POST \
  6. "$INFLUX_HOST/api/v2/write?org=$INFLUX_ORG&bucket=get-started&precision=s" \
  7.   --header "Authorization: Token $INFLUX_TOKEN" \
  8.   --header "Content-Type: text/plain; charset=utf-8" \
  9.   --header "Accept: application/json" \
  10.   --data-binary "
  11. home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000
  12. home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000
  13. home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1641027600
  14. home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641027600
  15. home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1641031200
  16. home,room=Kitchen temp=22.7,hum=36.1,co=0i 1641031200
  17. home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1641034800
  18. home,room=Kitchen temp=22.4,hum=36.0,co=0i 1641034800
  19. home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1641038400
  20. home,room=Kitchen temp=22.5,hum=36.0,co=0i 1641038400
  21. home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1641042000
  22. home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641042000
  23. home,room=Living\ Room temp=22.3,hum=36.1,co=0i 1641045600
  24. home,room=Kitchen temp=22.8,hum=36.3,co=1i 1641045600
  25. home,room=Living\ Room temp=22.3,hum=36.1,co=1i 1641049200
  26. home,room=Kitchen temp=22.7,hum=36.2,co=3i 1641049200
  27. home,room=Living\ Room temp=22.4,hum=36.0,co=4i 1641052800
  28. home,room=Kitchen temp=22.4,hum=36.0,co=7i 1641052800
  29. home,room=Living\ Room temp=22.6,hum=35.9,co=5i 1641056400
  30. home,room=Kitchen temp=22.7,hum=36.0,co=9i 1641056400
  31. home,room=Living\ Room temp=22.8,hum=36.2,co=9i 1641060000
  32. home,room=Kitchen temp=23.3,hum=36.9,co=18i 1641060000
  33. home,room=Living\ Room temp=22.5,hum=36.3,co=14i 1641063600
  34. home,room=Kitchen temp=23.1,hum=36.6,co=22i 1641063600
  35. home,room=Living\ Room temp=22.2,hum=36.4,co=17i 1641067200
  36. home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200
  37. "

View the written data

_time_measurementroom_field_value
2022-01-01T08:00:00ZhomeKitchenco0
2022-01-01T09:00:00ZhomeKitchenco0
2022-01-01T10:00:00ZhomeKitchenco0
2022-01-01T11:00:00ZhomeKitchenco0
2022-01-01T12:00:00ZhomeKitchenco0
2022-01-01T13:00:00ZhomeKitchenco1
2022-01-01T14:00:00ZhomeKitchenco1
2022-01-01T15:00:00ZhomeKitchenco3
2022-01-01T16:00:00ZhomeKitchenco7
2022-01-01T17:00:00ZhomeKitchenco9
2022-01-01T18:00:00ZhomeKitchenco18
2022-01-01T19:00:00ZhomeKitchenco22
2022-01-01T20:00:00ZhomeKitchenco26
_time_measurementroom_field_value
2022-01-01T08:00:00ZhomeKitchenhum35.9
2022-01-01T09:00:00ZhomeKitchenhum36.2
2022-01-01T10:00:00ZhomeKitchenhum36.1
2022-01-01T11:00:00ZhomeKitchenhum36
2022-01-01T12:00:00ZhomeKitchenhum36
2022-01-01T13:00:00ZhomeKitchenhum36.5
2022-01-01T14:00:00ZhomeKitchenhum36.3
2022-01-01T15:00:00ZhomeKitchenhum36.2
2022-01-01T16:00:00ZhomeKitchenhum36
2022-01-01T17:00:00ZhomeKitchenhum36
2022-01-01T18:00:00ZhomeKitchenhum36.9
2022-01-01T19:00:00ZhomeKitchenhum36.6
2022-01-01T20:00:00ZhomeKitchenhum36.5
_time_measurementroom_field_value
2022-01-01T08:00:00ZhomeKitchentemp21
2022-01-01T09:00:00ZhomeKitchentemp23
2022-01-01T10:00:00ZhomeKitchentemp22.7
2022-01-01T11:00:00ZhomeKitchentemp22.4
2022-01-01T12:00:00ZhomeKitchentemp22.5
2022-01-01T13:00:00ZhomeKitchentemp22.8
2022-01-01T14:00:00ZhomeKitchentemp22.8
2022-01-01T15:00:00ZhomeKitchentemp22.7
2022-01-01T16:00:00ZhomeKitchentemp22.4
2022-01-01T17:00:00ZhomeKitchentemp22.7
2022-01-01T18:00:00ZhomeKitchentemp23.3
2022-01-01T19:00:00ZhomeKitchentemp23.1
2022-01-01T20:00:00ZhomeKitchentemp22.7
_time_measurementroom_field_value
2022-01-01T08:00:00ZhomeLiving Roomco0
2022-01-01T09:00:00ZhomeLiving Roomco0
2022-01-01T10:00:00ZhomeLiving Roomco0
2022-01-01T11:00:00ZhomeLiving Roomco0
2022-01-01T12:00:00ZhomeLiving Roomco0
2022-01-01T13:00:00ZhomeLiving Roomco0
2022-01-01T14:00:00ZhomeLiving Roomco0
2022-01-01T15:00:00ZhomeLiving Roomco1
2022-01-01T16:00:00ZhomeLiving Roomco4
2022-01-01T17:00:00ZhomeLiving Roomco5
2022-01-01T18:00:00ZhomeLiving Roomco9
2022-01-01T19:00:00ZhomeLiving Roomco14
2022-01-01T20:00:00ZhomeLiving Roomco17
_time_measurementroom_field_value
2022-01-01T08:00:00ZhomeLiving Roomhum35.9
2022-01-01T09:00:00ZhomeLiving Roomhum35.9
2022-01-01T10:00:00ZhomeLiving Roomhum36
2022-01-01T11:00:00ZhomeLiving Roomhum36
2022-01-01T12:00:00ZhomeLiving Roomhum35.9
2022-01-01T13:00:00ZhomeLiving Roomhum36
2022-01-01T14:00:00ZhomeLiving Roomhum36.1
2022-01-01T15:00:00ZhomeLiving Roomhum36.1
2022-01-01T16:00:00ZhomeLiving Roomhum36
2022-01-01T17:00:00ZhomeLiving Roomhum35.9
2022-01-01T18:00:00ZhomeLiving Roomhum36.2
2022-01-01T19:00:00ZhomeLiving Roomhum36.3
2022-01-01T20:00:00ZhomeLiving Roomhum36.4
_time_measurementroom_field_value
2022-01-01T08:00:00ZhomeLiving Roomtemp21.1
2022-01-01T09:00:00ZhomeLiving Roomtemp21.4
2022-01-01T10:00:00ZhomeLiving Roomtemp21.8
2022-01-01T11:00:00ZhomeLiving Roomtemp22.2
2022-01-01T12:00:00ZhomeLiving Roomtemp22.2
2022-01-01T13:00:00ZhomeLiving Roomtemp22.4
2022-01-01T14:00:00ZhomeLiving Roomtemp22.3
2022-01-01T15:00:00ZhomeLiving Roomtemp22.3
2022-01-01T16:00:00ZhomeLiving Roomtemp22.4
2022-01-01T17:00:00ZhomeLiving Roomtemp22.6
2022-01-01T18:00:00ZhomeLiving Roomtemp22.8
2022-01-01T19:00:00ZhomeLiving Roomtemp22.5
2022-01-01T20:00:00ZhomeLiving Roomtemp22.2

Congratulations! You have written data to InfluxDB. The method described above is the manual way of writing data, but there are other options available:

With data now stored in InfluxDB, let’s query it.

Set up InfluxDB Query data