Use InfluxDB client libraries to write data
InfluxDB 3 Enterprise is in Public Alpha
InfluxDB 3 Enterprise is in public alpha and available for testing and feedback, but is not meant for production use. Both the product and this documentation are works in progress. We welcome and encourage your input about your experience with the alpha and invite you to join our public channels for updates and to share feedback.
Use InfluxDB 3 client libraries to construct data as time series points, and then write them as line protocol to an InfluxDB 3 Enterprise database.
Construct line protocol
With a basic understanding of line protocol, you can construct line protocol data and write it to InfluxDB 3 Enterprise.
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:
- table:
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
After setting up InfluxDB 3 Enterprise and your project, you should have the following:
InfluxDB 3 Enterprise credentials:
Authorization token
While in alpha, InfluxDB 3 Enterprise does not require an authorization token.
InfluxDB 3 Enterprise URL
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 3 Enterprise.
The following examples use InfluxDB 3 client libraries to show how to construct
Point
objects that follow the example home
schema,
and then write the data as line protocol to an InfluxDB 3 Enterprise database.
The following steps set up a Go project using the InfluxDB 3 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/v2
The following steps set up a JavaScript project using the InfluxDB 3 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 3 JavaScript client library.npm install @influxdata/influxdb3-client
The following steps set up a Python project using the InfluxDB 3 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/v2/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 3 Enterprise 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 3 Enterprise 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
tablePoint
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 3 Enterprise and this documentation. To find support, use the following resources:
Customers with an annual or support contract can contact InfluxData Support.