Write line protocol data to InfluxDB Cloud Serverless
Learn the fundamentals of constructing and writing line protocol data. Use tools like Telegraf and InfluxDB client libraries to build line protocol, and then write it to an InfluxDB bucket.
You can use these tools to build line protocol from scratch or transform your data to line protocol. However, if you already have CSV data, you might want to use tools that consume CSV and write it to InfluxDB as line protocol.
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.
Line protocol elements
In InfluxDB, a point contains a measurement name, one or more fields, a timestamp, and optional tags that provide metadata about the observation.
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.
measurement, field1="v1",field2=1i
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.
Example home schema
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
Data is collected hourly beginning at
.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 Serverless 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 example shows how to construct Point
objects that follow the example home
schema, and then write the points as line protocol to an
InfluxDB Cloud Serverless bucket.
Construct points and write line protocol
Create a file for your module–for example:
write-point.go
.In
write-point.go
, enter the following sample code:
package main
import (
"os"
"time"
"fmt"
"github.com/influxdata/influxdb-client-go/v2"
)
func main() {
// Set a log level constant
const debugLevel uint = 4
/**
* Instantiate a client with a configuration object
* that contains your InfluxDB URL and token.
**/
clientOptions := influxdb2.DefaultOptions().
SetBatchSize(20).
SetLogLevel(debugLevel).
SetPrecision(time.Second)
client := influxdb2.NewClientWithOptions(os.Getenv("INFLUX_URL"),
os.Getenv("INFLUX_TOKEN"),
clientOptions)
/**
* Create an asynchronous, non-blocking write client.
* Provide your InfluxDB org and bucket as arguments
**/
writeAPI := client.WriteAPI(os.Getenv("INFLUX_ORG"), "get-started")
// Get the errors channel for the asynchronous write client.
errorsCh := writeAPI.Errors()
/** Create a point.
* Provide measurement, tags, and fields as arguments.
**/
p := influxdb2.NewPointWithMeasurement("home").
AddTag("room", "Kitchen").
AddField("temp", 72.0).
AddField("hum", 20.2).
AddField("co", 9).
SetTime(time.Now())
// Define a proc for handling errors.
go func() {
for err := range errorsCh {
fmt.Printf("write error: %s\n", err.Error())
}
}()
// Write the point asynchronously
writeAPI.WritePoint(p)
// Send pending writes from the buffer to the bucket.
writeAPI.Flush()
// Ensure background processes finish and release resources.
client.Close()
}
Create a file for your module–for example:
write-point.js
.In
write-point.js
, enter the following sample code:'use strict' /** @module write * Use the JavaScript client library for Node.js. to create a point and write it to InfluxDB **/ import {InfluxDB, Point} from '@influxdata/influxdb-client' /** Get credentials from the environment **/ const url = process.env.INFLUX_URL const token = process.env.INFLUX_TOKEN const org = process.env.INFLUX_ORG /** * Instantiate a client with a configuration object * that contains your InfluxDB URL and token. **/ const influxDB = new InfluxDB({url, token}) /** * Create a write client configured to write to the bucket. * Provide your InfluxDB org and bucket. **/ const writeApi = influxDB.getWriteApi(org, 'get-started') /** * Create a point and add tags and fields. * To add a field, call the field method for your data type. **/ const point1 = new Point('home') .tag('room', 'Kitchen') .floatField('temp', 72.0) .floatField('hum', 20.2) .intField('co', 9) console.log(` ${point1}`) /** * Add the point to the batch. **/ writeApi.writePoint(point1) /** * Flush pending writes in the batch from the buffer and close the write client. **/ writeApi.close().then(() => { console.log('WRITE FINISHED') })
Create a file for your module–for example:
write-point.py
.In
write-point.py
, enter the following sample code:import os from influxdb_client import InfluxDBClient, Point # Instantiate a client with a configuration object # that contains your InfluxDB URL and token. # InfluxDB ignores the org argument, but the client requires it. client = InfluxDBClient(url=os.getenv('INFLUX_URL'), token=os.getenv('INFLUX_TOKEN'), org='ignored') # 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)] # Execute code after a successful write request. # Callback methods receive the configuration and data sent in the request. def success_callback(self, data): print(f"{data}") print(f"WRITE FINISHED") # Create a write client. # Optionally, provide callback methods to execute on request success, error, and completion. with client.write_api(success_callback=success_callback) as write_api: # Write the data to the bucket. write_api.write(bucket='get-started', record=points, content_encoding="identity", content_type="text/plain; charset=utf-8",) # Flush the write buffer and release resources. write_api.close()
The sample code does the following:
Instantiates a client configured with the InfluxDB URL and API token.
Uses the client to instantiate a write client with credentials.
Constructs a
Point
object with the measurement name ("home"
).Adds a tag and fields to the point.
Adds the point to a batch to be written to the bucket.
Sends the batch to InfluxDB and waits for the response.
Executes callbacks for the response, flushes the write buffer, and releases resources.
Run the example
To run the sample and write the data to your InfluxDB Cloud Serverless bucket, enter the following command in your terminal:
The example logs the point as line protocol to stdout, and then writes the point to the bucket. The line protocol is similar to the following:
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.