Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Add influxctl documentation to the "Write data" section (#5283) 

* reorg write line protocol docs

* port line protocol write changes to clustered
pull/5286/head
Scott Anderson 2023-12-19 13:07:43 -07:00 committed by GitHub
parent d61107a3d3
commit 15395a9da6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 817 additions and 442 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

81
content/influxdb/cloud-dedicated/write-data/line-protocol/_index.md Normal file
View File

@ -0,0 +1,81 @@
---
title: Write line protocol data to InfluxDB Cloud Dedicated
description: >
Use Telegraf and API clients to write line protocol data
to InfluxDB Cloud Dedicated.
menu:
influxdb_cloud_dedicated:
name: Write line protocol
parent: Write data
weight: 101
related:
- /influxdb/cloud-dedicated/reference/syntax/line-protocol/
- /influxdb/cloud-dedicated/get-started/write/
---
Learn the fundamentals of constructing and writing line protocol data.
Use tools like the `influxctl` CLI and InfluxDB client libraries to
build line protocol and then write it to an InfluxDB database.
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](/influxdb/cloud-dedicated/write-data/csv/).
<!-- TOC -->
- [Line protocol](#line-protocol)
- [Line protocol elements](#line-protocol-elements)
- [Line protocol element parsing](#line-protocol-element-parsing)
- [Write line protocol to InfluxDB](#write-line-protocol-to-influxdb)
<!-- /TOC -->
## Line protocol
All data written to InfluxDB is written using [line protocol](/influxdb/cloud-dedicated/reference/syntax/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:
{{< req type="key" >}}
- {{< req "\*" >}} **measurement**: String that identifies the [measurement](/influxdb/cloud-dedicated/reference/glossary/#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._
- {{< req "\*" >}} **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](/influxdb/cloud-dedicated/reference/syntax/line-protocol/#string) (quoted),
[floats](/influxdb/cloud-dedicated/reference/syntax/line-protocol/#float),
[integers](/influxdb/cloud-dedicated/reference/syntax/line-protocol/#integer),
[unsigned integers](/influxdb/cloud-dedicated/reference/syntax/line-protocol/#uinteger),
or [booleans](/influxdb/cloud-dedicated/reference/syntax/line-protocol/#boolean).
- **timestamp**: [Unix timestamp](/influxdb/cloud-dedicated/reference/syntax/line-protocol/#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.
---
{{< influxdb/line-protocol >}}
---
_For schema design recommendations, see [InfluxDB schema design](/influxdb/cloud-dedicated/write-data/best-practices/schema-design/)._
## Write line protocol to InfluxDB
{{< children >}}

105
content/influxdb/cloud-dedicated/write-data/line protocol/_index.md → content/influxdb/cloud-dedicated/write-data/line-protocol/client-libraries.md
View File

@ -1,89 +1,31 @@
--- ---
title: Write line protocol data to InfluxDB Cloud Dedicated title: Use InfluxDB client libraries to write line protocol data
description: > description: >
Use Telegraf and API clients to write line protocol data Use InfluxDB API clients to write line protocol data to InfluxDB Cloud Dedicated.
to InfluxDB Cloud Dedicated.
menu: menu:
influxdb_cloud_dedicated: influxdb_cloud_dedicated:
name: Write line protocol data name: Use client libraries
parent: Write data parent: Write line protocol
identifier: write-client-libs
weight: 103 weight: 103
related: related:
- /influxdb/cloud-dedicated/reference/syntax/line-protocol/ - /influxdb/cloud-dedicated/reference/syntax/line-protocol/
- /influxdb/cloud-dedicated/get-started/write/ - /influxdb/cloud-dedicated/get-started/write/
--- ---
Learn the fundamentals of constructing and writing line protocol data. Use InfluxDB client libraries to build line protocol, and then write it to an
Use tools like Telegraf and InfluxDB client libraries to InfluxDB database.
build line protocol, and then write it to an InfluxDB database.
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](/influxdb/cloud-dedicated/write-data/csv).
<!-- TOC -->
- [Line protocol](#line-protocol)
- [Line protocol elements](#line-protocol-elements)
- [Line protocol element parsing](#line-protocol-element-parsing)
- [Construct line protocol](#construct-line-protocol) - [Construct line protocol](#construct-line-protocol)
- [Set up your project](#set-up-your-project) - [Set up your project](#set-up-your-project)
- [Construct points and write line protocol](#construct-points-and-write-line-protocol) - [Construct points and write line protocol](#construct-points-and-write-line-protocol)
- [Run the example](#run-the-example) - [Run the example](#run-the-example)
- [Home sensor data line protocol](#home-sensor-data-line-protocol) - [Home sensor data line protocol](#home-sensor-data-line-protocol)
<!-- /TOC -->
## Line protocol
All data written to InfluxDB is written using [line protocol](/influxdb/cloud-dedicated/reference/syntax/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:
{{< req type="key" >}}
- {{< req "\*" >}} **measurement**: String that identifies the [measurement](/influxdb/cloud-dedicated/reference/glossary/#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._
- {{< req "\*" >}} **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](/influxdb/cloud-dedicated/reference/syntax/line-protocol/#string) (quoted),
[floats](/influxdb/cloud-dedicated/reference/syntax/line-protocol/#float),
[integers](/influxdb/cloud-dedicated/reference/syntax/line-protocol/#integer),
[unsigned integers](/influxdb/cloud-dedicated/reference/syntax/line-protocol/#uinteger),
or [booleans](/influxdb/cloud-dedicated/reference/syntax/line-protocol/#boolean).
- **timestamp**: [Unix timestamp](/influxdb/cloud-dedicated/reference/syntax/line-protocol/#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.
---
{{< influxdb/line-protocol >}}
---
_For schema design recommendations, see [InfluxDB schema design](/influxdb/cloud-dedicated/write-data/best-practices/schema-design/)._
## Construct line protocol ## Construct line protocol
With a basic understanding of line protocol, you can now construct line protocol With a [basic understanding of line protocol](/influxdb/cloud-dedicated/write-data/line-protocol/),
and write data to InfluxDB. you can now construct line protocol and write data to InfluxDB.
Consider a use case where you collect data from sensors in your home. Consider a use case where you collect data from sensors in your home.
Each sensor collects temperature, humidity, and carbon monoxide readings. Each sensor collects temperature, humidity, and carbon monoxide readings.
To collect this data, use the following schema: To collect this data, use the following schema:
@ -97,18 +39,17 @@ To collect this data, use the following schema:
- `co`: carbon monoxide in parts per million (integer) - `co`: carbon monoxide in parts per million (integer)
- **timestamp**: Unix timestamp in _second_ precision - **timestamp**: Unix timestamp in _second_ precision
Data is collected hourly beginning at
{{% influxdb/custom-timestamps-span %}}**2022-01-01T08:00:00Z (UTC)** until **2022-01-01T20:00:00Z (UTC)**{{% /influxdb/custom-timestamps-span %}}.
The following example shows how to construct and write points that follow this schema. The following example shows how to construct and write points that follow this schema.
### Set up your project ## Set up your project
The examples in this guide assume you followed [Set up InfluxDB](/influxdb/cloud-dedicated/get-started/setup/) and [Write data set up](/influxdb/cloud-dedicated/get-started/write/#set-up-your-project-and-credentials) instructions in [Get started](/influxdb/cloud-dedicated/get-started/). The examples in this guide assume you followed [Set up InfluxDB](/influxdb/cloud-dedicated/get-started/setup/)
and [Write data set up](/influxdb/cloud-dedicated/get-started/write/#set-up-your-project-and-credentials)
instructions in [Get started](/influxdb/cloud-dedicated/get-started/).
After setting up InfluxDB and your project, you should have the following: After setting up InfluxDB and your project, you should have the following:
- InfluxDB Cloud Dedicated credentials: - {{< product-name >}} credentials:
- [Database](/influxdb/cloud-dedicated/admin/databases/) - [Database](/influxdb/cloud-dedicated/admin/databases/)
- [Token](/influxdb/cloud-dedicated/admin/tokens/) - [Token](/influxdb/cloud-dedicated/admin/tokens/)
@ -174,7 +115,7 @@ npm install --save @influxdata/influxdb-client
{{% /tab-content %}} {{% /tab-content %}}
{{< /tabs-wrapper >}} {{< /tabs-wrapper >}}
### Construct points and write line protocol ## Construct points and write line protocol
{{< tabs-wrapper >}} {{< tabs-wrapper >}}
{{% tabs %}} {{% tabs %}}
@ -386,7 +327,7 @@ The sample code does the following:
7. Executes callbacks for the response, flushes the write buffer, and releases resources. 7. Executes callbacks for the response, flushes the write buffer, and releases resources.
### Run the example ## Run the example
To run the sample and write the data to your InfluxDB Cloud Dedicated database, enter the following command in your terminal: To run the sample and write the data to your InfluxDB Cloud Dedicated database, enter the following command in your terminal:
@ -427,12 +368,8 @@ go run write-point.go
The example logs the point as line protocol to stdout, and then writes the point to the database. The example logs the point as line protocol to stdout, and then writes the point to the database.
The line protocol is similar to the following: The line protocol is similar to the following:
{{% influxdb/custom-timestamps %}} ### Home sensor data line protocol
#### Home sensor data line protocol
```sh ```sh
home,room=Kitchen co=9i,hum=20.2,temp=72 1641024000 home,room=Kitchen co=9i,hum=20.2,temp=72 1641024000
``` ```
{{% /influxdb/custom-timestamps %}}

165
content/influxdb/cloud-dedicated/write-data/line-protocol/influxctl-cli.md Normal file
View File

@ -0,0 +1,165 @@
---
title: Use the influxctl CLI to write line protocol data
description: >
Use the [`influxctl` CLI](/influxdb/cloud-dedicated/reference/cli/influxctl/)
to write line protocol data to InfluxDB Cloud Dedicated.
menu:
influxdb_cloud_dedicated:
name: Use the influxctl CLI
parent: Write line protocol
identifier: write-influxctl
weight: 101
related:
- /influxdb/cloud-dedicated/reference/cli/influxctl/write/
- /influxdb/cloud-dedicated/reference/syntax/line-protocol/
- /influxdb/cloud-dedicated/get-started/write/
---
Use the [`influxctl` CLI](/influxdb/cloud-dedicated/reference/cli/influxctl/)
to write line protocol data to {{< product-name >}}.
- [Construct line protocol](#construct-line-protocol)
- [Write the line protocol to InfluxDB](#write-the-line-protocol-to-influxdb)
## Construct line protocol
With a [basic understanding of line protocol](/influxdb/cloud-dedicated/write-data/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
The following line protocol represent the schema described above:
```
home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000
home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000
home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1641027600
home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641027600
home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1641031200
home,room=Kitchen temp=22.7,hum=36.1,co=0i 1641031200
home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1641034800
home,room=Kitchen temp=22.4,hum=36.0,co=0i 1641034800
home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1641038400
home,room=Kitchen temp=22.5,hum=36.0,co=0i 1641038400
home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1641042000
home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641042000
```
For this tutorial, you can either pass this line protocol directly to the
`influxctl write` command as a string, via `stdin`, or you can save it to and read
it from a file.
## Write the line protocol to InfluxDB
Use the [`influxctl write` command](/influxdb/cloud-dedicated/reference/cli/influxctl/write/)
to write the [home sensor sample data](#home-sensor-data-line-protocol) to your
{{< product-name omit=" Clustered" >}} cluster.
Provide the following:
- Database name using the `--database` flag
- [Database token](/influxdb/cloud-dedicated/admin/tokens/) (with write permissions
on the target database) using the `--token` flag
- Timestamp precision as seconds (`s`) using the `--precision` flag
- [Line protocol](#construct-line-protocol).
Pass the line protocol in one of the following ways:
- a string on the command line
- a path to a file that contains the query
- a single dash (`-`) to read the query from stdin
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
[string](#)
[file](#)
[stdin](#)
{{% /code-tabs %}}
{{% code-tab-content %}}
{{% influxdb/custom-timestamps %}}
{{% code-placeholders "DATABASE_(NAME|TOKEN)|(LINE_PROTOCOL_FILEPATH)" %}}
```sh
influxctl write \
--database DATABASE_NAME \
--token DATABASE_TOKEN \
--precision s \
'home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000
home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000
home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1641027600
home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641027600
home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1641031200
home,room=Kitchen temp=22.7,hum=36.1,co=0i 1641031200
home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1641034800
home,room=Kitchen temp=22.4,hum=36.0,co=0i 1641034800
home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1641038400
home,room=Kitchen temp=22.5,hum=36.0,co=0i 1641038400
home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1641042000
home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641042000'
```
{{% /code-placeholders %}}
{{% /influxdb/custom-timestamps %}}
Replace the following:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}:
Name of the database to write to.
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}:
Database token with write permissions on the target database.
{{% /code-tab-content %}}
{{% code-tab-content %}}
{{% code-placeholders "DATABASE_(NAME|TOKEN)|(LINE_PROTOCOL_FILEPATH)" %}}
```sh
influxctl write \
--database DATABASE_NAME \
--token DATABASE_TOKEN \
--precision s \
LINE_PROTOCOL_FILEPATH
```
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}:
Name of the database to write to.
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}:
Database token with write permissions on the target database.
- {{% code-placeholder-key %}}`LINE_PROTOCOL_FILEPATH`{{% /code-placeholder-key %}}:
File path to the file containing the line protocol. Can be an absolute file path
or relative to the current working directory.
{{% /code-tab-content %}}
{{% code-tab-content %}}
{{% code-placeholders "DATABASE_(NAME|TOKEN)|(LINE_PROTOCOL_FILEPATH)" %}}
```sh
cat LINE_PROTOCOL_FILEPATH | influxctl write \
--database DATABASE_NAME \
--token DATABASE_TOKEN \
--precision s \
-
```
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}:
Name of the database to write to.
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}:
Database token with write permissions on the target database.
- {{% code-placeholder-key %}}`LINE_PROTOCOL_FILEPATH`{{% /code-placeholder-key %}}:
File path to the file containing the line protocol. Can be an absolute file path
or relative to the current working directory.
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}

368
content/influxdb/clustered/write-data/line protocol/_index.md
View File

@ -1,37 +1,32 @@
--- ---
title: Write line protocol data to InfluxDB Clustered title: Write line protocol data to InfluxDB Clustered
description: > description: >
Use Telegraf and API clients to write line protocol data Use Telegraf and API clients to write line protocol data to InfluxDB Clustered.
to InfluxDB Clustered.
menu: menu:
influxdb_clustered: influxdb_clustered:
name: Write line protocol data name: Write line protocol
parent: Write data parent: Write data
weight: 103 weight: 101
related: related:
- /influxdb/clustered/reference/syntax/line-protocol/ - /influxdb/clustered/reference/syntax/line-protocol/
- /influxdb/clustered/get-started/write/ - /influxdb/clustered/get-started/write/
--- ---
Learn the fundamentals of constructing and writing line protocol data. Learn the fundamentals of constructing and writing line protocol data.
Use tools like Telegraf and InfluxDB client libraries to Use tools like the `influxctl` CLI and InfluxDB client libraries to
build line protocol, and then write it to an InfluxDB database. build line protocol and then write it to an InfluxDB database.
You can use these tools to build line protocol from scratch or transform You can use these tools to build line protocol from scratch or transform
your data to line protocol. your data to line protocol.
However, if you already have CSV data, you might want to use tools that [consume CSV However, if you already have CSV data, you might want to use tools that
and write it to InfluxDB as line protocol](/influxdb/clustered/write-data/csv). [consume CSV and write it to InfluxDB as line protocol](/influxdb/clustered/write-data/csv/).
<!-- TOC --> <!-- TOC -->
- [Line protocol](#line-protocol) - [Line protocol](#line-protocol)
- [Line protocol elements](#line-protocol-elements) - [Line protocol elements](#line-protocol-elements)
- [Line protocol element parsing](#line-protocol-element-parsing) - [Line protocol element parsing](#line-protocol-element-parsing)
- [Construct line protocol](#construct-line-protocol) - [Write line protocol to InfluxDB](#write-line-protocol-to-influxdb)
- [Set up your project](#set-up-your-project)
- [Construct points and write line protocol](#construct-points-and-write-line-protocol)
- [Run the example](#run-the-example)
- [Home sensor data line protocol](#home-sensor-data-line-protocol)
<!-- /TOC --> <!-- /TOC -->
@ -80,349 +75,6 @@ Each line of line protocol contains the following elements:
_For schema design recommendations, see [InfluxDB schema design](/influxdb/clustered/write-data/best-practices/schema-design/)._ _For schema design recommendations, see [InfluxDB schema design](/influxdb/clustered/write-data/best-practices/schema-design/)._
## Construct line protocol ## Write line protocol to InfluxDB
With a basic understanding of line protocol, you can now construct line protocol {{< children >}}
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
Data is collected hourly beginning at
{{% influxdb/custom-timestamps-span %}}**2022-01-01T08:00:00Z (UTC)** until **2022-01-01T20:00:00Z (UTC)**{{% /influxdb/custom-timestamps-span %}}.
The following example shows how to construct and write points that follow this schema.
### Set up your project
The examples in this guide assume you followed [Set up InfluxDB](/influxdb/clustered/get-started/setup/) and [Write data set up](/influxdb/clustered/get-started/write/#set-up-your-project-and-credentials) instructions in [Get started](/influxdb/clustered/get-started/).
After setting up InfluxDB and your project, you should have the following:
- InfluxDB Clustered credentials:
- [Database](/influxdb/clustered/admin/databases/)
- [Token](/influxdb/clustered/admin/tokens/)
- 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](#example-home-schema), and then write the points as line protocol to an
InfluxDB Clustered database.
{{< tabs-wrapper >}}
{{% tabs %}}
[Go](#)
[Node.js](#)
[Python](#)
{{% /tabs %}}
{{% tab-content %}}
<!-- BEGIN GO PROJECT SETUP -->
1. Install [Go 1.13 or later](https://golang.org/doc/install).
2. Inside of your project directory, install the client package to your project dependencies.
```sh
go get github.com/influxdata/influxdb-client-go/v2
```
<!-- END GO SETUP PROJECT -->
{{% /tab-content %}}
{{% tab-content %}}
<!-- BEGIN NODE.JS PROJECT SETUP -->
Inside of your project directory, install the `@influxdata/influxdb-client` InfluxDB v2 JavaScript client library.
```sh
npm install --save @influxdata/influxdb-client
```
<!-- END NODE.JS SETUP PROJECT -->
{{% /tab-content %}}
{{% tab-content %}}
<!-- BEGIN PYTHON SETUP PROJECT -->
1. **Optional, but recommended**: Use `venv` or `conda` to activate a virtual environment for installing and executing code--for example:
Inside of your project directory, enter the following command to create and activate a virtual environment for the project:
```sh
python3 -m venv envs/env1 && source ./envs/env1/bin/activate
```
2. Install the `influxdb-client` InfluxDB v2 Python library.
```sh
pip install influxdb-client
```
<!-- END PYTHON SETUP PROJECT -->
{{% /tab-content %}}
{{< /tabs-wrapper >}}
### Construct points and write line protocol
{{< tabs-wrapper >}}
{{% tabs %}}
[Go](#)
[Node.js](#)
[Python](#)
{{% /tabs %}}
{{% tab-content %}}
<!-- BEGIN GO SETUP SAMPLE -->
1. Create a file for your module--for example: `write-point.go`.
2. In `write-point.go`, enter the following sample code:
```go
package main
import (
"os"
"time"
"fmt"
"github.com/influxdata/influxdb-client-go/v2"
)
func main() {
// Set a log level constant
const debugLevel uint = 4
/**
* Define options for the client.
* Instantiate the client with the following arguments:
* - An object containing InfluxDB URL and token credentials.
* - Write options for batch size and timestamp precision.
**/
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 database 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 database.
writeAPI.Flush()
// Ensure background processes finish and release resources.
client.Close()
}
```
<!-- END GO SETUP SAMPLE -->
{{% /tab-content %}}
{{% tab-content %}}
<!-- BEGIN NODE.JS SETUP SAMPLE -->
1. Create a file for your module--for example: `write-point.js`.
2. In `write-point.js`, enter the following sample code:
```js
'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 database.
* Provide your InfluxDB org and database.
**/
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')
})
```
<!-- END NODE.JS SETUP SAMPLE -->
{{% /tab-content %}}
{{% tab-content %}}
<!-- BEGIN PYTHON SETUP SAMPLE -->
1. Create a file for your module--for example: `write-point.py`.
2. In `write-point.py`, enter the following sample code:
```python
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 database.
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()
```
<!-- END PYTHON SETUP PROJECT -->
{{% /tab-content %}}
{{< /tabs-wrapper >}}
The sample code does the following:
1. Instantiates a client configured with the InfluxDB URL and API token.
2. Uses the client to instantiate a **write client** with credentials.
3. Constructs a `Point` object with the [measurement](/influxdb/clustered/reference/glossary/#measurement) name (`"home"`).
4. Adds a tag and fields to the point.
5. Adds the point to a batch to be written to the database.
6. Sends the batch to InfluxDB and waits for the response.
7. 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 Clustered database, enter the following command in your terminal:
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
[Go](#)
[Node.js](#)
[Python](#)
{{% /code-tabs %}}
{{% code-tab-content %}}
<!-- BEGIN GO RUN EXAMPLE -->
```sh
go run write-point.go
```
<!-- END GO RUN EXAMPLE -->
{{% /code-tab-content %}}
{{% code-tab-content %}}
<!-- BEGIN NODE.JS RUN EXAMPLE -->
```sh
node write-point.js
```
<!-- END NODE.JS RUN EXAMPLE -->
{{% /code-tab-content %}}
{{% code-tab-content %}}
<!-- BEGIN PYTHON RUN EXAMPLE -->
```sh
python write-point.py
```
<!-- END PYTHON RUN EXAMPLE -->
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
The example logs the point as line protocol to stdout, and then writes the point to the database.
The line protocol is similar to the following:
{{% influxdb/custom-timestamps %}}
#### Home sensor data line protocol
```sh
home,room=Kitchen co=9i,hum=20.2,temp=72 1641024000
```
{{% /influxdb/custom-timestamps %}}

375
content/influxdb/clustered/write-data/line protocol/client-libraries.md Normal file
View File

@ -0,0 +1,375 @@
---
title: Use InfluxDB client libraries to write line protocol data
description: >
Use InfluxDB API clients to write line protocol data to InfluxDB Clustered.
menu:
influxdb_clustered:
name: Use client libraries
parent: Write line protocol
identifier: write-client-libs
weight: 103
related:
- /influxdb/clustered/reference/syntax/line-protocol/
- /influxdb/clustered/get-started/write/
---
Use InfluxDB client libraries to build line protocol, and then write it to an
InfluxDB database.
- [Construct line protocol](#construct-line-protocol)
- [Set up your project](#set-up-your-project)
- [Construct points and write line protocol](#construct-points-and-write-line-protocol)
- [Run the example](#run-the-example)
- [Home sensor data line protocol](#home-sensor-data-line-protocol)
## Construct line protocol
With a [basic understanding of line protocol](/influxdb/clustered/write-data/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
The following example shows how to construct and write points that follow this schema.
## Set up your project
The examples in this guide assume you followed [Set up InfluxDB](/influxdb/clustered/get-started/setup/)
and [Write data set up](/influxdb/clustered/get-started/write/#set-up-your-project-and-credentials)
instructions in [Get started](/influxdb/clustered/get-started/).
After setting up InfluxDB and your project, you should have the following:
- {{< product-name >}} credentials:
- [Database](/influxdb/clustered/admin/databases/)
- [Token](/influxdb/clustered/admin/tokens/)
- 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](#example-home-schema), and then write the points as line protocol to an
{{% product-name %}} database.
{{< tabs-wrapper >}}
{{% tabs %}}
[Go](#)
[Node.js](#)
[Python](#)
{{% /tabs %}}
{{% tab-content %}}
<!-- BEGIN GO PROJECT SETUP -->
1. Install [Go 1.13 or later](https://golang.org/doc/install).
2. Inside of your project directory, install the client package to your project dependencies.
```sh
go get github.com/influxdata/influxdb-client-go/v2
```
<!-- END GO SETUP PROJECT -->
{{% /tab-content %}}
{{% tab-content %}}
<!-- BEGIN NODE.JS PROJECT SETUP -->
Inside of your project directory, install the `@influxdata/influxdb-client` InfluxDB v2 JavaScript client library.
```sh
npm install --save @influxdata/influxdb-client
```
<!-- END NODE.JS SETUP PROJECT -->
{{% /tab-content %}}
{{% tab-content %}}
<!-- BEGIN PYTHON SETUP PROJECT -->
1. **Optional, but recommended**: Use [`venv`](https://docs.python.org/3/library/venv.html)) or [`conda`](https://docs.continuum.io/anaconda/install/) to activate a virtual environment for installing and executing code--for example:
Inside of your project directory, enter the following command using `venv` to create and activate a virtual environment for the project:
```sh
python3 -m venv envs/env1 && source ./envs/env1/bin/activate
```
2. Install the [`influxdb3-python`](https://github.com/InfluxCommunity/influxdb3-python), which provides the InfluxDB `influxdb_client_3` Python client library module and also installs the [`pyarrow` package](https://arrow.apache.org/docs/python/index.html) for working with Arrow data.
```sh
pip install influxdb3-python
```
<!-- END PYTHON SETUP PROJECT -->
{{% /tab-content %}}
{{< /tabs-wrapper >}}
## Construct points and write line protocol
{{< tabs-wrapper >}}
{{% tabs %}}
[Go](#)
[Node.js](#)
[Python](#)
{{% /tabs %}}
{{% tab-content %}}
<!-- BEGIN GO SETUP SAMPLE -->
1. Create a file for your module--for example: `write-point.go`.
2. In `write-point.go`, enter the following sample code:
```go
package main
import (
"os"
"time"
"fmt"
"github.com/influxdata/influxdb-client-go/v2"
)
func main() {
// Set a log level constant
const debugLevel uint = 4
/**
* Define options for the client.
* Instantiate the client with the following arguments:
* - An object containing InfluxDB URL and token credentials.
* - Write options for batch size and timestamp precision.
**/
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 database 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 database.
writeAPI.Flush()
// Ensure background processes finish and release resources.
client.Close()
}
```
<!-- END GO SETUP SAMPLE -->
{{% /tab-content %}}
{{% tab-content %}}
<!-- BEGIN NODE.JS SETUP SAMPLE -->
1. Create a file for your module--for example: `write-point.js`.
2. In `write-point.js`, enter the following sample code:
```js
'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 database.
* Provide your InfluxDB org and database.
**/
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')
})
```
<!-- END NODE.JS SETUP SAMPLE -->
{{% /tab-content %}}
{{% tab-content %}}
<!-- BEGIN PYTHON SETUP SAMPLE -->
1. Create a file for your module--for example: `write-point.py`.
2. In `write-point.py`, enter the following sample code to write data in batching mode:
```python
import os
from influxdb_client_3 import Point, write_client_options, WritePrecision, WriteOptions, InfluxDBError
# 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,
WriteOptions=write_options)
# Instantiate a synchronous instance of the client with your
# InfluxDB credentials and write options.
with InfluxDBClient3(host=config['INFLUX_HOST'],
token=config['INFLUX_TOKEN'],
database=config['INFLUX_DATABASE'],
write_client_options=wco) as client:
client.write(points, write_precision='s')
```
<!-- END PYTHON SETUP PROJECT -->
{{% /tab-content %}}
{{< /tabs-wrapper >}}
The sample code does the following:
1. Instantiates a client configured with the InfluxDB URL and API token.
2. Uses the client to instantiate a **write client** with credentials.
3. Constructs a `Point` object with the [measurement](/influxdb/clustered/reference/glossary/#measurement) name (`"home"`).
4. Adds a tag and fields to the point.
5. Adds the point to a batch to be written to the database.
6. Sends the batch to InfluxDB and waits for the response.
7. 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 Clustered database, enter the following command in your terminal:
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
[Go](#)
[Node.js](#)
[Python](#)
{{% /code-tabs %}}
{{% code-tab-content %}}
<!-- BEGIN GO RUN EXAMPLE -->
```sh
go run write-point.go
```
<!-- END GO RUN EXAMPLE -->
{{% /code-tab-content %}}
{{% code-tab-content %}}
<!-- BEGIN NODE.JS RUN EXAMPLE -->
```sh
node write-point.js
```
<!-- END NODE.JS RUN EXAMPLE -->
{{% /code-tab-content %}}
{{% code-tab-content %}}
<!-- BEGIN PYTHON RUN EXAMPLE -->
```sh
python write-point.py
```
<!-- END PYTHON RUN EXAMPLE -->
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
The example logs the point as line protocol to stdout, and then writes the point to the database.
The line protocol is similar to the following:
### Home sensor data line protocol
```sh
home,room=Kitchen co=9i,hum=20.2,temp=72 1641024000
```

165
content/influxdb/clustered/write-data/line protocol/influxctl-cli.md Normal file
View File

@ -0,0 +1,165 @@
---
title: Use the influxctl CLI to write line protocol data
description: >
Use the [`influxctl` CLI](/influxdb/clustered/reference/cli/influxctl/)
to write line protocol data to InfluxDB Clustered.
menu:
influxdb_clustered:
name: Use the influxctl CLI
parent: Write line protocol
identifier: write-influxctl
weight: 101
related:
- /influxdb/clustered/reference/cli/influxctl/write/
- /influxdb/clustered/reference/syntax/line-protocol/
- /influxdb/clustered/get-started/write/
---
Use the [`influxctl` CLI](/influxdb/clustered/reference/cli/influxctl/)
to write line protocol data to {{< product-name >}}.
- [Construct line protocol](#construct-line-protocol)
- [Write the line protocol to InfluxDB](#write-the-line-protocol-to-influxdb)
## Construct line protocol
With a [basic understanding of line protocol](/influxdb/clustered/write-data/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
The following line protocol represent the schema described above:
```
home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000
home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000
home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1641027600
home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641027600
home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1641031200
home,room=Kitchen temp=22.7,hum=36.1,co=0i 1641031200
home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1641034800
home,room=Kitchen temp=22.4,hum=36.0,co=0i 1641034800
home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1641038400
home,room=Kitchen temp=22.5,hum=36.0,co=0i 1641038400
home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1641042000
home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641042000
```
For this tutorial, you can either pass this line protocol directly to the
`influxctl write` command as a string, via `stdin`, or you can save it to and read
it from a file.
## Write the line protocol to InfluxDB
Use the [`influxctl write` command](/influxdb/clustered/reference/cli/influxctl/write/)
to write the [home sensor sample data](#home-sensor-data-line-protocol) to your
{{< product-name omit=" Clustered" >}} cluster.
Provide the following:
- Database name using the `--database` flag
- [Database token](/influxdb/clustered/admin/tokens/) (with write permissions
on the target database) using the `--token` flag
- Timestamp precision as seconds (`s`) using the `--precision` flag
- [Line protocol](#construct-line-protocol).
Pass the line protocol in one of the following ways:
- a string on the command line
- a path to a file that contains the query
- a single dash (`-`) to read the query from stdin
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
[string](#)
[file](#)
[stdin](#)
{{% /code-tabs %}}
{{% code-tab-content %}}
{{% influxdb/custom-timestamps %}}
{{% code-placeholders "DATABASE_(NAME|TOKEN)|(LINE_PROTOCOL_FILEPATH)" %}}
```sh
influxctl write \
--database DATABASE_NAME \
--token DATABASE_TOKEN \
--precision s \
'home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000
home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000
home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1641027600
home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641027600
home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1641031200
home,room=Kitchen temp=22.7,hum=36.1,co=0i 1641031200
home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1641034800
home,room=Kitchen temp=22.4,hum=36.0,co=0i 1641034800
home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1641038400
home,room=Kitchen temp=22.5,hum=36.0,co=0i 1641038400
home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1641042000
home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641042000'
```
{{% /code-placeholders %}}
{{% /influxdb/custom-timestamps %}}
Replace the following:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}:
Name of the database to write to.
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}:
Database token with write permissions on the target database.
{{% /code-tab-content %}}
{{% code-tab-content %}}
{{% code-placeholders "DATABASE_(NAME|TOKEN)|(LINE_PROTOCOL_FILEPATH)" %}}
```sh
influxctl write \
--database DATABASE_NAME \
--token DATABASE_TOKEN \
--precision s \
LINE_PROTOCOL_FILEPATH
```
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}:
Name of the database to write to.
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}:
Database token with write permissions on the target database.
- {{% code-placeholder-key %}}`LINE_PROTOCOL_FILEPATH`{{% /code-placeholder-key %}}:
File path to the file containing the line protocol. Can be an absolute file path
or relative to the current working directory.
{{% /code-tab-content %}}
{{% code-tab-content %}}
{{% code-placeholders "DATABASE_(NAME|TOKEN)|(LINE_PROTOCOL_FILEPATH)" %}}
```sh
cat LINE_PROTOCOL_FILEPATH | influxctl write \
--database DATABASE_NAME \
--token DATABASE_TOKEN \
--precision s \
-
```
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}:
Name of the database to write to.
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}:
Database token with write permissions on the target database.
- {{% code-placeholder-key %}}`LINE_PROTOCOL_FILEPATH`{{% /code-placeholder-key %}}:
File path to the file containing the line protocol. Can be an absolute file path
or relative to the current working directory.
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}