Get started writing data
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:
- Influx user interface (UI)
- InfluxDB HTTP API
influx
CLI- Telegraf
- 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: 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. 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
. The resulting line protocol would look something like the following:Write line protocol to InfluxDB
The following examples show how to write the sample data, already in line protocol format, to an InfluxDB Cloud Serverless bucket.
To learn more about available tools and options, see Write data.
All API, cURL, and client library examples in this getting started tutorial assume your InfluxDB host, organization, url, and token are provided by environment variables.
Go to cloud2.influxdata.com in a browser to log in and access the InfluxDB UI.
Navigate to Load Data > Buckets using the left navigation bar.
Click Add Data on the bucket you want to write the data to and select Line Protocol.
Select Enter Manually.
Important In the Precision drop-down menu above the line protocol text field, select Seconds (to match to precision of the timestamps in the line protocol).
Copy the line protocol above and paste it into the line protocol text field.
Click Write Data.
The UI will confirm that the data has been written successfully.
If you haven’t already, download, install, and configure the
influx
CLI.Use the
influx write
command to write the line protocol above to InfluxDB.Provide the following:
-b, --bucket
or--bucket-id
flag with the bucket name or ID to write do.-p, --precision
flag with the timestamp precision (s
).- String-encoded line protocol.
- Connection and authentication credentials
Use Telegraf to consume line protocol, and then write it to InfluxDB Cloud Serverless.
If you haven’t already, follow the instructions to download and install Telegraf.
Copy and save the home sensor data sample to a file on your local system–for example,
home.lp
.Run the following command to generate a Telegraf configuration file (
./telegraf.conf
) that enables theinputs.file
andoutputs.influxdb_v2
plugins:telegraf --sample-config \ --input-filter file \ --output-filter influxdb_v2 \ > telegraf.conf
In your editor, open
./telegraf.conf
and configure the following:file
input plugin: In the[[inputs.file]].files
list, replace"/tmp/metrics.out"
with your sample data filename. If Telegraf can’t find a file when started, it stops processing and exits.[[inputs.file]] ## Files to parse each interval. Accept standard unix glob matching rules, ## as well as ** to match recursive files and directories. files = ["home.lp"]
output-influxdb_v2
output plugin: In the[[outputs.influxdb_v2]]
section, replace the default values with the following configuration for your InfluxDB Cloud Dedicated cluster:[[outputs.influxdb_v2]] # InfluxDB Cloud Serverless region URL urls = ["${INFLUX_URL}"] # INFLUX_TOKEN is an environment variable you assigned to your API token token = "${INFLUX_TOKEN}" # An empty string (InfluxDB ignores this parameter) organization = "" # Bucket name bucket = "get-started"
The example configuration uses the following InfluxDB credentials:
urls
: an array containing yourINFLUX_URL
environment variabletoken
: yourINFLUX_TOKEN
environment variableorganization
: an empty string (InfluxDB ignores this parameter)bucket
: the name of the bucket to write to
To write the data, start the
telegraf
daemon with the following options:--config
: Specifies the filepath of the configuration file.--once
: Runs a single Telegraf collection cycle for the configured inputs and outputs, and then exits.
Enter the following command in your terminal:
telegraf --once --config ./telegraf.conf
If the write is successful, the output is similar to the following:
2023-05-31T20:09:08Z D! [agent] Starting service inputs 2023-05-31T20:09:19Z D! [outputs.influxdb_v2] Wrote batch of 52 metrics in 348.008167ms 2023-05-31T20:09:19Z D! [outputs.influxdb_v2] Buffer fullness: 0 / 10000 metrics
Telegraf and its plugins provide many options for reading and writing data. To learn more, see how to use Telegraf to write data.
To write data to InfluxDB using the InfluxDB HTTP API, send a request to
the InfluxDB API /api/v2/write
endpoint using the POST
request method.
POST http://localhost:8086/api/v2/write
Include the following with your request:
- Headers:
- Authorization: Token <INFLUX_TOKEN>
- Content-Type: text/plain; charset=utf-8
- Accept: application/json
- Query parameters:
- bucket: InfluxDB bucket name
- precision: timestamp precision (default is
ns
)
- Request body: Line protocol as plain text
The following example uses cURL and the InfluxDB v2 API to write line protocol to InfluxDB:
If successful, the output is the success message; otherwise, error details and the failure message.
Congratulations! You have written data to InfluxDB. With data now stored in InfluxDB, let’s query it.
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:
InfluxDB Cloud and InfluxDB Enterprise customers can contact InfluxData Support.