Documentation

Use InfluxDB client libraries to write line protocol data

Use InfluxDB client libraries to construct data as time series points, and then write them as line protocol to an InfluxDB Clustered database.

Construct line protocol

With a basic understanding of line protocol, you can construct line protocol data and write it to InfluxDB.

All InfluxDB client libraries write data in line protocol format to InfluxDB. Client library write methods let you provide data as raw line protocol or as Point objects that the client library converts to line protocol. If your program creates the data you write to InfluxDB, use the client library Point interface to take advantage of type safety in your program.

Example home schema

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 example shows how to construct and write points that follow the home schema.

Set up your project

The examples in this guide assume you followed Set up InfluxDB and Write data set up instructions in Get started.

After setting up InfluxDB and your project, you should have the following:

  • InfluxDB Clustered credentials:

  • A directory for your project.

  • Credentials stored as environment variables or in a project configuration file–for example, a .env (“dotenv”) file.

  • Client libraries installed for writing data to InfluxDB.

The following examples show how to construct Point objects that follow the example home schema, and then write the data as line protocol to an InfluxDB Clustered database.

The examples use InfluxDB v3 client libraries. For examples using InfluxDB v2 client libraries to write data to InfluxDB v3, see InfluxDB v2 clients.

The following steps set up a Go project using the InfluxDB v3 Go client:

  1. Install Go 1.13 or later.

  2. Create a directory for your Go module and change to the directory–for example:

    mkdir iot-starter-go && cd $_
    
  3. Initialize a Go module–for example:

    go mod init iot-starter
    
  4. Install influxdb3-go, which provides the InfluxDB influxdb3 Go client library module.

    go get github.com/InfluxCommunity/influxdb3-go
    

The following steps set up a JavaScript project using the InfluxDB v3 JavaScript client.

  1. Install Node.js.

  2. Create a directory for your JavaScript project and change to the directory–for example:

    mkdir -p iot-starter-js && cd $_
    
  3. Initialize a project–for example, using npm:

    npm init
    
  4. Install the @influxdata/influxdb3-client InfluxDB v3 JavaScript client library.

    npm install @influxdata/influxdb3-client
    

The following steps set up a Python project using the InfluxDB v3 Python client:

  1. Install Python

  2. Inside of your project directory, create a directory for your Python module and change to the module directory–for example:

    mkdir -p iot-starter-py && cd $_
    
  3. Optional, but recommended: Use venv or conda to activate a virtual environment for installing and executing code–for example, enter the following command using venv to create and activate a virtual environment for the project:

    python3 -m venv envs/iot-starter && source ./envs/iot-starter/bin/activate
    
  4. Install influxdb3-python, which provides the InfluxDB influxdb_client_3 Python client library module and also installs the pyarrow package for working with Arrow data.

    pip install influxdb3-python
    

Construct points and write line protocol

Client libraries provide one or more Point constructor methods. Some libraries support language-native data structures, such as Go’s struct, for creating points.

  1. Create a file for your module–for example: main.go.

  2. In main.go, enter the following sample code:

    package main
    
    import (
     "context"
     "os"
     "fmt"
     "time"
     "github.com/InfluxCommunity/influxdb3-go/influxdb3"
     "github.com/influxdata/line-protocol/v2/lineprotocol"
    )
    
    func Write() error {
      url := os.Getenv("INFLUX_HOST")
      token := os.Getenv("INFLUX_TOKEN")
      database := os.Getenv("INFLUX_DATABASE")
    
      // To instantiate a client, call New() with InfluxDB credentials.
      client, err := influxdb3.New(influxdb3.ClientConfig{
       Host: url,
       Token: token,
       Database: database,
      })
    
      /** Use a deferred function to ensure the client is closed when the
        * function returns.
       **/
      defer func (client *influxdb3.Client)  {
       err = client.Close()
       if err != nil {
         panic(err)
       }
      }(client)
    
      /** Use the NewPoint method to construct a point.
        * NewPoint(measurement, tags map, fields map, time)
       **/
      point := influxdb3.NewPoint("home",
         map[string]string{
           "room": "Living Room",
         },
         map[string]any{
           "temp": 24.5,
           "hum":  40.5,
           "co":   15i},
         time.Now(),
       )
    
      /** Use the NewPointWithMeasurement method to construct a point with
        * method chaining.
       **/
      point2 := influxdb3.NewPointWithMeasurement("home").
       SetTag("room", "Living Room").
       SetField("temp", 23.5).
       SetField("hum", 38.0).
       SetField("co",  16i).
       SetTimestamp(time.Now())
    
      fmt.Println("Writing points")
      points := []*influxdb3.Point{point, point2}
    
      /** Write points to InfluxDB.
        * You can specify WriteOptions, such as Gzip threshold,
        * default tags, and timestamp precision. Default precision is lineprotocol.Nanosecond
       **/
      err = client.WritePoints(context.Background(), points,
        influxdb3.WithPrecision(lineprotocol.Second))
      return nil
    }
    
    func main() {
      Write()
    }
    
  3. To run the module and write the data to your InfluxDB Clustered database, enter the following command in your terminal:

    go run main.go
    
  1. Create a file for your module–for example: write-points.js.

  2. In write-points.js, enter the following sample code:

    // write-points.js
    import { InfluxDBClient, Point } from '@influxdata/influxdb3-client';
    
    /**
     * Set InfluxDB credentials.
     */
    const host = process.env.INFLUX_HOST ?? '';
    const database = process.env.INFLUX_DATABASE;
    const token = process.env.INFLUX_TOKEN;
    
    /**
     * Write line protocol to InfluxDB using the JavaScript client library.
     */
    export async function writePoints() {
      /**
       * Instantiate an InfluxDBClient.
       * Provide the host URL and the database token.
       */
      const client = new InfluxDBClient({ host, token });
    
      /** Use the fluent interface with chained methods to construct Points. */
      const point = Point.measurement('home')
        .setTag('room', 'Living Room')
        .setFloatField('temp', 22.2)
        .setFloatField('hum', 35.5)
        .setIntegerField('co', 7)
        .setTimestamp(new Date().getTime() / 1000);
    
      const point2 = Point.measurement('home')
        .setTag('room', 'Kitchen')
        .setFloatField('temp', 21.0)
        .setFloatField('hum', 35.9)
        .setIntegerField('co', 0)
        .setTimestamp(new Date().getTime() / 1000);
    
      /** Write points to InfluxDB.
       * The write method accepts an array of points, the target database, and
       * an optional configuration object.
       * You can specify WriteOptions, such as Gzip threshold, default tags,
       * and timestamp precision. Default precision is lineprotocol.Nanosecond
       **/
    
      try {
        await client.write([point, point2], database, '', { precision: 's' });
        console.log('Data has been written successfully!');
      } catch (error) {
        console.error(`Error writing data to InfluxDB: ${error.body}`);
      }
    
      client.close();
    }
    
    writePoints();
    
  3. To run the module and write the data to your {{< product-name >}} database, enter the following command in your terminal:

    node writePoints.js
    
  1. Create a file for your module–for example: write-points.py.

  2. In write-points.py, enter the following sample code to write data in batching mode:

    import os
    from influxdb_client_3 import (
      InfluxDBClient3, InfluxDBError, Point, WritePrecision,
      WriteOptions, write_client_options)
    
    host = os.getenv('INFLUX_HOST')
    token = os.getenv('INFLUX_TOKEN')
    database = os.getenv('INFLUX_DATABASE')
    
    # Create an array of points with tags and fields.
    points = [Point("home")
                .tag("room", "Kitchen")
                .field("temp", 25.3)
                .field('hum', 20.2)
                .field('co', 9)]
    
    # With batching mode, define callbacks to execute after a successful or
    # failed write request.
    # Callback methods receive the configuration and data sent in the request.
    def success(self, data: str):
        print(f"Successfully wrote batch: data: {data}")
    
    def error(self, data: str, exception: InfluxDBError):
        print(f"Failed writing batch: config: {self}, data: {data} due: {exception}")
    
    def retry(self, data: str, exception: InfluxDBError):
        print(f"Failed retry writing batch: config: {self}, data: {data} retry: {exception}")
    
    # Configure options for batch writing.
    write_options = WriteOptions(batch_size=500,
                                        flush_interval=10_000,
                                        jitter_interval=2_000,
                                        retry_interval=5_000,
                                        max_retries=5,
                                        max_retry_delay=30_000,
                                        exponential_base=2)
    
    # Create an options dict that sets callbacks and WriteOptions.
    wco = write_client_options(success_callback=success,
                              error_callback=error,
                              retry_callback=retry,
                              write_options=write_options)
    
    # Instantiate a synchronous instance of the client with your
    # InfluxDB credentials and write options, such as Gzip threshold, default tags,
    # and timestamp precision. Default precision is nanosecond ('ns').
    with InfluxDBClient3(host=host,
                            token=token,
                            database=database,
                            write_client_options=wco) as client:
    
          client.write(points, write_precision='s')
    
  3. To run the module and write the data to your InfluxDB Clustered database, enter the following command in your terminal:

    python write-points.py
    

The sample code does the following:

  1. Instantiates a client configured with the InfluxDB URL and API token.
  2. Constructs home measurement Point objects.
  3. Sends data as line protocol format to InfluxDB and waits for the response.
  4. If the write succeeds, logs the success message to stdout; otherwise, logs the failure message and error details.
  5. Closes the client to release resources.

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

InfluxDB v3 enhancements and InfluxDB Clustered is now generally available

New capabilities, including faster query performance and management tooling advance the InfluxDB v3 product line. InfluxDB Clustered is now generally available.

InfluxDB v3 performance and features

The InfluxDB v3 product line has seen significant enhancements in query performance and has made new management tooling available. These enhancements include an operational dashboard to monitor the health of your InfluxDB cluster, single sign-on (SSO) support in InfluxDB Cloud Dedicated, and new management APIs for tokens and databases.

Learn about the new v3 enhancements


InfluxDB Clustered general availability

InfluxDB Clustered is now generally available and gives you the power of InfluxDB v3 in your self-managed stack.

Talk to us about InfluxDB Clustered