Use InfluxDB client libraries to write line protocol data
Use InfluxDB client libraries to build time series points, and then write them line protocol to an InfluxDB Cloud Dedicated 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
- tags
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 Cloud Dedicated credentials:
- Database
- Database token
- Cluster hostname
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 example shows how to construct Point
objects that follow the
example home
schema, and then write the data as line
protocol to an InfluxDB Cloud Dedicated 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:
Install Go 1.13 or later.
Create a directory for your Go module and change to the directory–for example:
mkdir iot-starter-go && cd $_
Initialize a Go module–for example:
go mod init iot-starter
Install
influxdb3-go
, which provides the InfluxDBinfluxdb3
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.
Install Node.js.
Create a directory for your JavaScript project and change to the directory–for example:
mkdir -p iot-starter-js && cd $_
Initialize a project–for example, using
npm
:npm init
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:
Install Python
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 $_
Optional, but recommended: Use
venv
orconda
to activate a virtual environment for installing and executing code–for example, enter the following command usingvenv
to create and activate a virtual environment for the project:python3 -m venv envs/iot-starter && source ./envs/iot-starter/bin/activate
Install
influxdb3-python
, which provides the InfluxDBinfluxdb_client_3
Python client library module and also installs thepyarrow
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.
Create a file for your module–for example:
main.go
.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() }
To run the module and write the data to your InfluxDB Cloud Dedicated database, enter the following command in your terminal:
go run main.go
Create a file for your module–for example:
write-points.js
.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();
To run the module and write the data to your {{< product-name >}} database, enter the following command in your terminal:
node writePoints.js
Create a file for your module–for example:
write-points.py
.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')
To run the module and write the data to your InfluxDB Cloud Dedicated database, enter the following command in your terminal:
python write-points.py
The sample code does the following:
- Instantiates a client configured with the InfluxDB URL and API token.
- Constructs
home
measurementPoint
objects. - Sends data as line protocol format to InfluxDB and waits for the response.
- If the write succeeds, logs the success message to stdout; otherwise, logs the failure message and error details.
- Closes the client to release resources.
Was this page helpful?
Thank you for your feedback!
Support and feedback
Thank you for being part of our community! We welcome and encourage your feedback and bug reports for InfluxDB and this documentation. To find support, use the following resources:
Customers with an annual or support contract can contact InfluxData Support.