Documentation

InfluxDB Clustered

Get started writing data

  • 2 / 3

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:

  • InfluxDB HTTP API (v1 and v2)
  • Telegraf
  • influxctl CLI
  • influx3 data CLI
  • InfluxDB client libraries

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: A string that identifies the table 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-05-28T08:00:00Z (UTC) until 2025-05-28T20:00:00Z (UTC).

Home sensor data line protocol
home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1748419200
home,room=Kitchen temp=21.0,hum=35.9,co=0i 1748419200
home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1748422800
home,room=Kitchen temp=23.0,hum=36.2,co=0i 1748422800
home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1748426400
home,room=Kitchen temp=22.7,hum=36.1,co=0i 1748426400
home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1748430000
home,room=Kitchen temp=22.4,hum=36.0,co=0i 1748430000
home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1748433600
home,room=Kitchen temp=22.5,hum=36.0,co=0i 1748433600
home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1748437200
home,room=Kitchen temp=22.8,hum=36.5,co=1i 1748437200
home,room=Living\ Room temp=22.3,hum=36.1,co=0i 1748440800
home,room=Kitchen temp=22.8,hum=36.3,co=1i 1748440800
home,room=Living\ Room temp=22.3,hum=36.1,co=1i 1748444400
home,room=Kitchen temp=22.7,hum=36.2,co=3i 1748444400
home,room=Living\ Room temp=22.4,hum=36.0,co=4i 1748448000
home,room=Kitchen temp=22.4,hum=36.0,co=7i 1748448000
home,room=Living\ Room temp=22.6,hum=35.9,co=5i 1748451600
home,room=Kitchen temp=22.7,hum=36.0,co=9i 1748451600
home,room=Living\ Room temp=22.8,hum=36.2,co=9i 1748455200
home,room=Kitchen temp=23.3,hum=36.9,co=18i 1748455200
home,room=Living\ Room temp=22.5,hum=36.3,co=14i 1748458800
home,room=Kitchen temp=23.1,hum=36.6,co=22i 1748458800
home,room=Living\ Room temp=22.2,hum=36.4,co=17i 1748462400
home,room=Kitchen temp=22.7,hum=36.5,co=26i 1748462400
  • 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 Clustered database.

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.

influxctl CLI Telegraf v1 API v2 API Python Go Node.js C# Java

To write data to InfluxDB Clustered using Python, use the influxdb_client_3 module. The following steps include setting up a Python virtual environment to scope dependencies to your current project.

  1. Create a module directory and navigate into it–for example:

    mkdir -p influxdb_py_client && cd influxdb_py_client
    • Copy
    • Fill window

  2. Setup your Python virtual environment. Inside of your module directory, enter the following command:

    python -m venv envs/virtual-env
    • Copy
    • Fill window

  3. Activate the virtual environment.

    source ./envs/virtual-env/bin/activate
    • Copy
    • Fill window

  4. Install the client library package:

    pip install influxdb3-python
    • Copy
    • Fill window

    The influxdb3-python package provides the influxdb_client_3 module and also installs the pyarrow package for working with Arrow data returned from queries.

  5. In your terminal or editor, create a new file for your code–for example: write.py.

    touch write.py
    • Copy
    • Fill window

  6. Inside of write.py, enter the following sample code:

    from influxdb_client_3 import InfluxDBClient3
import os

# INFLUX_TOKEN is an environment variable you assigned to your
# database WRITE token value.
token = os.getenv('INFLUX_TOKEN')

# host is the URL hostname without protocol or trailing slash
client = InfluxDBClient3(
    host='cluster-host.com',
    org='',
    token=token,
    database='get-started'
)

lines = [
    "home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1748419200",
    "home,room=Kitchen temp=21.0,hum=35.9,co=0i 1748419200",
    "home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1748422800",
    "home,room=Kitchen temp=23.0,hum=36.2,co=0i 1748422800",
    "home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1748426400",
    "home,room=Kitchen temp=22.7,hum=36.1,co=0i 1748426400",
    "home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1748430000",
    "home,room=Kitchen temp=22.4,hum=36.0,co=0i 1748430000",
    "home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1748433600",
    "home,room=Kitchen temp=22.5,hum=36.0,co=0i 1748433600",
    "home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1748437200",
    "home,room=Kitchen temp=22.8,hum=36.5,co=1i 1748437200",
    "home,room=Living\ Room temp=22.3,hum=36.1,co=0i 1748440800",
    "home,room=Kitchen temp=22.8,hum=36.3,co=1i 1748440800",
    "home,room=Living\ Room temp=22.3,hum=36.1,co=1i 1748444400",
    "home,room=Kitchen temp=22.7,hum=36.2,co=3i 1748444400",
    "home,room=Living\ Room temp=22.4,hum=36.0,co=4i 1748448000",
    "home,room=Kitchen temp=22.4,hum=36.0,co=7i 1748448000",
    "home,room=Living\ Room temp=22.6,hum=35.9,co=5i 1748451600",
    "home,room=Kitchen temp=22.7,hum=36.0,co=9i 1748451600",
    "home,room=Living\ Room temp=22.8,hum=36.2,co=9i 1748455200",
    "home,room=Kitchen temp=23.3,hum=36.9,co=18i 1748455200",
    "home,room=Living\ Room temp=22.5,hum=36.3,co=14i 1748458800",
    "home,room=Kitchen temp=23.1,hum=36.6,co=22i 1748458800",
    "home,room=Living\ Room temp=22.2,hum=36.4,co=17i 1748462400",
    "home,room=Kitchen temp=22.7,hum=36.5,co=26i 1748462400"
]

client.write(lines,write_precision='s')
    • Copy
    • Fill window

    The sample does the following:

    1. Imports the InfluxDBClient3 object from the influxdb_client_3 module.

    2. Calls the InfluxDBClient3() constructor to instantiate an InfluxDB client configured with the following credentials:

      • host: InfluxDB cluster hostname (URL without protocol or trailing slash)
      • org: an empty or arbitrary string (InfluxDB ignores this parameter)
      • token: a database token with write access to the specified database. Store this in a secret store or environment variable to avoid exposing the raw token string.
      • database: the name of the InfluxDB Clustered database to write to

    3. Defines a list of line protocol strings where each string represents a data record.

    4. Calls the client.write() method with the line protocol record list and write options.

      Because the timestamps in the sample line protocol are in second precision, the example passes the write_precision='s' option to set the timestamp precision to seconds.

  7. To execute the module and write line protocol to your InfluxDB Clustered database, enter the following command in your terminal:

    python write.py
    • Copy
    • Fill window

If successful, the output is the success message; otherwise, error details and the failure message.

View the written data

Congratulations! You’ve written data to InfluxDB. Next, learn how to query your data.

Was this page helpful?

Thank you for your feedback!

© 2025 InfluxData, Inc.

What is your InfluxDB cluster URL?

Enter your InfluxDB cluster URL and we’ll update code examples for you.

Enter cluster URL

Thank you for your feedback!

Let us know what we can do better:

Thank you!

No thanks

Select a new date

Select a date in your database's retention period.

SuMoTuWeThFrSa
27282930123456789101112131415161718192021222324252627282930311234567
Update

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:

Ask AI