Documentation

Get started writing data

This tutorial walks you through the fundamental of creating line protocol data and writing it to InfluxDB.

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

  • Influx user interface (UI)
  • InfluxDB HTTP API (v1 and v2)
  • Telegraf
  • influx3 data CLI
  • InfluxDB client libraries
  • influx CLI

If using tools like Telegraf or InfluxDB client libraries, they can 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 of 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.

myMeasurement,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

The following line protocol sample represents data collected hourly beginning at 2025-06-16T08:00:00Z (UTC) until 2025-06-16T20:00:00Z (UTC).

Home sensor data line protocol
home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1719924000
home,room=Kitchen temp=21.0,hum=35.9,co=0i 1719924000
home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1719927600
home,room=Kitchen temp=23.0,hum=36.2,co=0i 1719927600
home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1719931200
home,room=Kitchen temp=22.7,hum=36.1,co=0i 1719931200
home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1719934800
home,room=Kitchen temp=22.4,hum=36.0,co=0i 1719934800
home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1719938400
home,room=Kitchen temp=22.5,hum=36.0,co=0i 1719938400
home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1719942000
home,room=Kitchen temp=22.8,hum=36.5,co=1i 1719942000
home,room=Living\ Room temp=22.3,hum=36.1,co=0i 1719945600
home,room=Kitchen temp=22.8,hum=36.3,co=1i 1719945600
home,room=Living\ Room temp=22.3,hum=36.1,co=1i 1719949200
home,room=Kitchen temp=22.7,hum=36.2,co=3i 1719949200
home,room=Living\ Room temp=22.4,hum=36.0,co=4i 1719952800
home,room=Kitchen temp=22.4,hum=36.0,co=7i 1719952800
home,room=Living\ Room temp=22.6,hum=35.9,co=5i 1719956400
home,room=Kitchen temp=22.7,hum=36.0,co=9i 1719956400
home,room=Living\ Room temp=22.8,hum=36.2,co=9i 1719960000
home,room=Kitchen temp=23.3,hum=36.9,co=18i 1719960000
home,room=Living\ Room temp=22.5,hum=36.3,co=14i 1719963600
home,room=Kitchen temp=23.1,hum=36.6,co=22i 1719963600
home,room=Living\ Room temp=22.2,hum=36.4,co=17i 1719967200
home,room=Kitchen temp=22.7,hum=36.5,co=26i 1719967200
  • Copy
  • Fill window

Write line protocol to InfluxDB

The following examples show how to write the preceding sample data, already in line protocol format, to an InfluxDB Cloud Serverless bucket.

To learn more about available tools and options, see Write data.

Some examples in this getting started tutorial assume your InfluxDB credentials (URL, organization, and token) are provided by environment variables.

Use Telegraf to consume line protocol, and then write it to InfluxDB Cloud Serverless.

  1. If you haven’t already, follow the instructions to download and install Telegraf.

  2. Copy and save the home sensor data sample to a file on your local system–for example, home.lp.

    cat <<- EOF > home.lp
    home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1719924000
    home,room=Kitchen temp=21.0,hum=35.9,co=0i 1719924000
    home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1719927600
    home,room=Kitchen temp=23.0,hum=36.2,co=0i 1719927600
    home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1719931200
    home,room=Kitchen temp=22.7,hum=36.1,co=0i 1719931200
    home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1719934800
    home,room=Kitchen temp=22.4,hum=36.0,co=0i 1719934800
    home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1719938400
    home,room=Kitchen temp=22.5,hum=36.0,co=0i 1719938400
    home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1719942000
    home,room=Kitchen temp=22.8,hum=36.5,co=1i 1719942000
    home,room=Living\ Room temp=22.3,hum=36.1,co=0i 1719945600
    home,room=Kitchen temp=22.8,hum=36.3,co=1i 1719945600
    home,room=Living\ Room temp=22.3,hum=36.1,co=1i 1719949200
    home,room=Kitchen temp=22.7,hum=36.2,co=3i 1719949200
    home,room=Living\ Room temp=22.4,hum=36.0,co=4i 1719952800
    home,room=Kitchen temp=22.4,hum=36.0,co=7i 1719952800
    home,room=Living\ Room temp=22.6,hum=35.9,co=5i 1719956400
    home,room=Kitchen temp=22.7,hum=36.0,co=9i 1719956400
    home,room=Living\ Room temp=22.8,hum=36.2,co=9i 1719960000
    home,room=Kitchen temp=23.3,hum=36.9,co=18i 1719960000
    home,room=Living\ Room temp=22.5,hum=36.3,co=14i 1719963600
    home,room=Kitchen temp=23.1,hum=36.6,co=22i 1719963600
    home,room=Living\ Room temp=22.2,hum=36.4,co=17i 1719967200
    home,room=Kitchen temp=22.7,hum=36.5,co=26i 1719967200
    EOF
    
    • Copy
    • Fill window
  3. Run the following command to generate a Telegraf configuration file (./telegraf.conf) that enables the inputs.file and outputs.influxdb_v2 plugins:

    telegraf --sample-config \
      --input-filter file \
      --output-filter influxdb_v2 \
      > telegraf.conf
    
    • Copy
    • Fill window
  4. In your editor, open ./telegraf.conf and configure the following:

    • file input plugin: In the [[inputs.file]].files list, replace "/tmp/metrics.out" with your sample data filename. If Telegraf can’t find a file when started, it stops processing and exits.

      [[inputs.file]]
        ## Files to parse each interval.  Accept standard unix glob matching rules,
        ## as well as ** to match recursive files and directories.
        files = ["home.lp"]
      
      • Copy
      • Fill window
    • output-influxdb_v2 output plugin: In the [[outputs.influxdb_v2]] section, replace the default values with the following configuration for your InfluxDB Cloud Serverless bucket:

      [[outputs.influxdb_v2]]
        # InfluxDB Cloud Serverless URL
        urls = ["${INFLUX_HOST}"]
      
        # INFLUX_TOKEN is an environment variable you assigned to your API token
        token = "${INFLUX_TOKEN}"
      
        # An empty string (InfluxDB ignores this parameter)
        organization = ""
      
        # Bucket name
        bucket = "get-started"
      
      • Copy
      • Fill window

      The example configuration uses the following InfluxDB credentials:

      • urls: an array containing your INFLUX_HOST environment variable
      • token: your INFLUX_TOKEN environment variable
      • organization: an empty string (InfluxDB ignores this parameter)
      • bucket: the name of the bucket to write to
  5. To write the data, start the telegraf daemon with the following options:

    • --config: Specifies the path of the configuration file.
    • --once: Runs a single Telegraf collection cycle for the configured inputs and outputs, and then exits.

    Enter the following command in your terminal:

    telegraf --once --config ./telegraf.conf
    
    • Copy
    • Fill window

    If the write is successful, the output is similar to the following:

    2023-05-31T20:09:08Z D! [agent] Starting service inputs
    2023-05-31T20:09:19Z D! [outputs.influxdb_v2] Wrote batch of 52 metrics in 348.008167ms
    2023-05-31T20:09:19Z D! [outputs.influxdb_v2] Buffer fullness: 0 / 10000 metrics
    
    • Copy
    • Fill window

Telegraf and its plugins provide many options for reading and writing data. To learn more, see how to use Telegraf to write data.

View the written data

Congratulations! You have written data to InfluxDB. With data now stored in InfluxDB, let’s query it.


Was this page helpful?

Thank you for your feedback!


The future of Flux

Flux is going into maintenance mode. You can continue using it as you currently are without any changes to your code.

Read more

Now Generally Available

InfluxDB 3 Core and Enterprise

Start fast. Scale faster.

Get the Updates

InfluxDB 3 Core is an open source, high-speed, recent-data engine that collects and processes data in real-time and persists it to local disk or object storage. InfluxDB 3 Enterprise builds on Core’s foundation, adding high availability, read replicas, enhanced security, and data compaction for faster queries and optimized storage. A free tier of InfluxDB 3 Enterprise is available for non-commercial at-home or hobbyist use.

For more information, check out:

InfluxDB Cloud Serverless