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

chore: Write data improvements 

-  Format and structure serverless write-data
- Structure cloud-serverless write-data/line-protocol the same as clustered and dedicated to allow for adding more tool-specific pages.
- Make influxctl examples pass tests
pull/5503/head
Jason Stirnaman 2024-06-24 15:42:10 -05:00
parent 3274742abe
commit 17c4315569
11 changed files with 1130 additions and 244 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
.prettierrc.yaml
View File

@ -7,8 +7,11 @@ trailingComma: "es5"
useTabs: false useTabs: false
overrides: overrides:
- files: - files:
- "*.md" - "*.md"
- "*.markdown" - "*.markdown"
options: options:
proseWrap: "preserve" proseWrap: "preserve"
plugins:
- "prettier-plugin-sql"
# Prettier also uses settings, such as indent, specified in .editorconfig # Prettier also uses settings, such as indent, specified in .editorconfig

98
content/influxdb/cloud-dedicated/get-started/write.md
View File

@ -69,13 +69,16 @@ Each line of line protocol contains the following elements:
or or
[booleans](/influxdb/cloud-dedicated/reference/syntax/line-protocol/#boolean). [booleans](/influxdb/cloud-dedicated/reference/syntax/line-protocol/#boolean).
- **timestamp**: - **timestamp**:
[Unix timestamp](/influxdb/cloud-dedicated/reference/syntax/line-protocol/#unix-timestamp) [Unix timestamp](/influxdb/cloud-dedicated/reference/syntax/line-protocol/#unix-timestamp)
associated with the data. InfluxDB supports up to nanosecond precision. _If associated with the data. InfluxDB supports up to nanosecond precision. _If
the precision of the timestamp is not in nanoseconds, you must specify the the precision of the timestamp is not in nanoseconds, you must specify the
precision when writing the data to InfluxDB._ precision when writing the data to InfluxDB._
<!-- vale InfluxDataDocs.v3Schema = YES -->
#### Line protocol element parsing #### Line protocol element parsing
<!-- vale InfluxDataDocs.v3Schema = NO -->
- **measurement**: Everything before the _first unescaped comma before the first - **measurement**: Everything before the _first unescaped comma before the first
whitespace_. whitespace_.
- **tag set**: Key-value pairs between the _first unescaped comma_ and the - **tag set**: Key-value pairs between the _first unescaped comma_ and the
@ -98,6 +101,8 @@ _For schema design recommendations, see
## Construct line protocol ## Construct line protocol
<!-- vale InfluxDataDocs.v3Schema = NO -->
With a basic understanding of line protocol, you can now construct line protocol With a basic understanding of line protocol, you can now construct line protocol
and write data to InfluxDB. 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.
@ -154,7 +159,7 @@ home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200
## Write line protocol to InfluxDB ## Write line protocol to InfluxDB
The following examples show how to write the The following examples show how to write the preceding
[sample data](#home-sensor-data-line-protocol), already in line protocol format, [sample data](#home-sensor-data-line-protocol), already in line protocol format,
to an {{% product-name %}} database. to an {{% product-name %}} database.
@ -235,6 +240,9 @@ home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200'
{{% /code-placeholders %}} {{% /code-placeholders %}}
{{% /influxdb/custom-timestamps %}} {{% /influxdb/custom-timestamps %}}
If successful, the output is the success message; otherwise, error details and
the failure message.
<!----------------------------- END INFLUXCTL CLI CONTENT -----------------------------> <!----------------------------- END INFLUXCTL CLI CONTENT ----------------------------->
{{% /tab-content %}} {{% /tab-content %}}
@ -492,7 +500,8 @@ Replace the following:
a [database token](/influxdb/cloud-dedicated/admin/tokens/#database-token) with a [database token](/influxdb/cloud-dedicated/admin/tokens/#database-token) with
sufficient permissions to the specified database sufficient permissions to the specified database
If successful, the output is an HTTP `204 No Content` status code. If successful, the output is an HTTP `204 No Content` status code; otherwise,
the error status code and failure message.
<!--pytest-codeblocks:expected-output--> <!--pytest-codeblocks:expected-output-->
@ -603,7 +612,8 @@ Replace the following:
[database token](/influxdb/cloud-dedicated/admin/tokens/#database-tokens) with [database token](/influxdb/cloud-dedicated/admin/tokens/#database-tokens) with
sufficient permissions to the specified database sufficient permissions to the specified database
If successful, the output is an HTTP `204 No Content` status code. If successful, the output is an HTTP `204 No Content` status code; otherwise,
the error status code and failure message.
<!--pytest-codeblocks:expected-output--> <!--pytest-codeblocks:expected-output-->
@ -629,17 +639,12 @@ dependencies to your current project.
1. Create a module directory and navigate into it--for example: 1. Create a module directory and navigate into it--for example:
<!--
Using bash here is required when running with pytest.
I don't know why, but sh evaluates $_ to /usr/bin/pytest.
-->
```bash ```bash
mkdir -p influxdb_py_client && cd influxdb_py_client mkdir -p influxdb_py_client && cd influxdb_py_client
``` ```
2. Setup your Python virtual environment. 2. Setup your Python virtual environment.
Inside of your module directory: Inside of your module directory, enter the following command:
<!--pytest-codeblocks:cont--> <!--pytest-codeblocks:cont-->
@ -765,6 +770,9 @@ dependencies to your current project.
{{% /influxdb/custom-timestamps %}} {{% /influxdb/custom-timestamps %}}
If successful, the output is the success message; otherwise, error details and
the failure message.
<!----------------------------- END PYTHON CONTENT ----------------------------> <!----------------------------- END PYTHON CONTENT ---------------------------->
{{% /tab-content %}} {{% /tab-content %}}
@ -940,17 +948,17 @@ To write data to {{% product-name %}} using Go, use the InfluxDB v3
} }
``` ```
6. In your terminal, enter the following command to install the packages listed 6. To install dependencies and write the data to your {{% product-name %}}
in `imports`, build the `influxdb_go_client` module, and execute the database, enter the following command into your terminal:
`main()` function:
<!--pytest.mark.skip--> <!--pytest.mark.skip-->
```sh ```sh
go mod tidy && go build && go run influxdb_go_client go mod tidy && go run influxdb_go_client
``` ```
The program writes the line protocol to your {{% product-name %}} database. If successful, the output is the success message; otherwise, error details and
the failure message.
{{% /influxdb/custom-timestamps %}} {{% /influxdb/custom-timestamps %}}
@ -1146,6 +1154,9 @@ To write data to {{% product-name %}} using Go, use the InfluxDB v3
{{% /influxdb/custom-timestamps %}} {{% /influxdb/custom-timestamps %}}
If successful, the output is the success message; otherwise, error details and
the failure message.
<!---------------------------- END NODE.JS CONTENT ---------------------------> <!---------------------------- END NODE.JS CONTENT --------------------------->
{{% /tab-content %}} {{% /tab-content %}}
@ -1281,8 +1292,8 @@ To write data to {{% product-name %}} using Go, use the InfluxDB v3
with _write_ access to the specified database. _Store this in a secret with _write_ access to the specified database. _Store this in a secret
store or environment variable to avoid exposing the raw token string._ store or environment variable to avoid exposing the raw token string._
_Instantiating the client with the `using` statement ensures that the _The `using` statement ensures that the program disposes of the
client is disposed of when it's no longer needed._ client when it's no longer needed._
2. Defines an array of line protocol strings where each string represents a 2. Defines an array of line protocol strings where each string represents a
data record. data record.
@ -1324,19 +1335,23 @@ To write data to {{% product-name %}} using Go, use the InfluxDB v3
7. To build and execute the program and write the line protocol to your 7. To build and execute the program and write the line protocol to your
{{% product-name %}} database, enter the following command in your terminal: {{% product-name %}} database, enter the following command in your terminal:
<!--pytest.mark.skip--> <!--pytest.mark.skip-->
```sh ```sh
dotnet run dotnet run
``` ```
<!---------------------------- END C# CONTENT ---------------------------> If successful, the output is the success message; otherwise, error details and
the failure message.
{{% /influxdb/custom-timestamps %}} <!---------------------------- END C# CONTENT --------------------------->
{{% /tab-content %}}
{{% tab-content %}} {{% /influxdb/custom-timestamps %}}
{{% influxdb/custom-timestamps %}} {{% /tab-content %}}
<!---------------------------- BEGIN JAVA CONTENT ---------------------------> {{% tab-content %}}
{{% influxdb/custom-timestamps %}}
<!-------------------------- BEGIN JAVA CONTENT --------------------------->
_The tutorial assumes using Maven version 3.9 and Java version >= 15._ _The tutorial assumes using Maven version 3.9 and Java version >= 15._
@ -1555,21 +1570,21 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._
10. In your terminal or editor, execute `App.main()` to write to InfluxDB--for 10. In your terminal or editor, execute `App.main()` to write to InfluxDB--for
example, using Maven: example, using Maven:
<!--pytest.mark.skip--> <!--pytest.mark.skip-->
```sh ```sh
mvn exec:java -Dexec.mainClass="com.influxdbv3.App" mvn exec:java -Dexec.mainClass="com.influxdbv3.App"
``` ```
<!---------------------------- END JAVA CONTENT --------------------------->
{{% /influxdb/custom-timestamps %}}
{{% /tab-content %}}
{{< /tabs-wrapper >}}
If successful, the output is the success message; otherwise, error details and If successful, the output is the success message; otherwise, error details and
the failure message. the failure message.
<!---------------------------- END JAVA CONTENT --------------------------->
{{% /influxdb/custom-timestamps %}}
{{% /tab-content %}}
{{< /tabs-wrapper >}}
{{< expand-wrapper >}} {{< expand-wrapper >}}
{{% expand "View the written data" %}} {{% expand "View the written data" %}}
@ -1610,4 +1625,5 @@ the failure message.
**Congratulations!** You've written data to InfluxDB. **Congratulations!** You've written data to InfluxDB.
Next, learn how to query your data. Next, learn how to query your data.
{{< page-nav prev="/influxdb/cloud-dedicated/get-started/setup/" next="/influxdb/cloud-dedicated/get-started/query/" keepTab=true >}} {{< page-nav prev="/influxdb/cloud-dedicated/get-started/setup/"
next="/influxdb/cloud-dedicated/get-started/query/" keepTab=true >}}

7
content/influxdb/cloud-dedicated/write-data/line-protocol/_index.md
View File

@ -22,15 +22,10 @@ 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 [consume CSV
and write it to InfluxDB as line protocol](/influxdb/cloud-dedicated/write-data/csv/). and write it to InfluxDB as line protocol](/influxdb/cloud-dedicated/write-data/csv/).
<!-- 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)
- [Write line protocol to InfluxDB](#write-line-protocol-to-influxdb) - [Write line protocol to InfluxDB](#write-line-protocol-to-influxdb)
<!-- /TOC -->
## Line protocol ## Line protocol
All data written to InfluxDB is written using [line protocol](/influxdb/cloud-dedicated/reference/syntax/line-protocol/), a text-based All data written to InfluxDB is written using [line protocol](/influxdb/cloud-dedicated/reference/syntax/line-protocol/), a text-based
@ -44,7 +39,7 @@ Each line of line protocol contains the following elements:
{{< req type="key" >}} {{< req type="key" >}}
- {{< req "\*" >}} **measurement**: String that identifies the [measurement](/influxdb/cloud-dedicated/reference/glossary/#measurement) to store the data in. - {{< 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 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._ 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. - {{< req "\*" >}} **field set**: Comma-delimited list of key value pairs, each representing a field.

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

@ -89,8 +89,6 @@ client libraries to write data to InfluxDB v3, see
{{< tabs-wrapper >}} {{< tabs-wrapper >}}
{{% tabs %}} {{% tabs %}}
<!-- prettier-ignore -->
[Go](#) [Go](#)
[Node.js](#) [Node.js](#)
[Python](#) [Python](#)
@ -210,8 +208,6 @@ points.
{{< tabs-wrapper >}} {{< tabs-wrapper >}}
{{% tabs %}} {{% tabs %}}
<!-- prettier-ignore -->
[Go](#) [Go](#)
[Node.js](#) [Node.js](#)
[Python](#) [Python](#)

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

@ -29,7 +29,7 @@ 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:
- **measurement**: `home` - **measurement**: `home`
- **tags** - **tags**
- `room`: Living Room or Kitchen - `room`: Living Room or Kitchen
- **fields** - **fields**
@ -40,7 +40,7 @@ To collect this data, use the following schema:
The following line protocol represent the schema described above: The following line protocol represent the schema described above:
``` ```text
home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000 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=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=Living\ Room temp=21.4,hum=35.9,co=0i 1641027600
@ -66,10 +66,10 @@ to write the [home sensor sample data](#home-sensor-data-line-protocol) to your
{{< product-name omit=" Clustered" >}} cluster. {{< product-name omit=" Clustered" >}} cluster.
Provide the following: Provide the following:
- Database name using the `--database` flag - The [database](/influxdb/clustered/admin/databases/) name using the `--database` flag
- [Database token](/influxdb/cloud-dedicated/admin/tokens/#database-tokens) - A [database token](/influxdb/cloud-dedicated/admin/tokens/#database-tokens)
(with write permissions on the target database) using the `--token` flag (with write permissions on the target database) using the `--token` flag
- Timestamp precision as seconds (`s`) using the `--precision` flag - The timestamp precision as seconds (`s`) using the `--precision` flag
- [Line protocol](#construct-line-protocol). - [Line protocol](#construct-line-protocol).
Pass the line protocol in one of the following ways: Pass the line protocol in one of the following ways:
@ -77,16 +77,17 @@ Provide the following:
- a path to a file that contains the query - a path to a file that contains the query
- a single dash (`-`) to read the query from stdin - a single dash (`-`) to read the query from stdin
{{< code-tabs-wrapper >}} {{< tabs-wrapper >}}
{{% code-tabs %}} {{% tabs %}}
[string](#) [string](#)
[file](#) [file](#)
[stdin](#) [stdin](#)
{{% /code-tabs %}} {{% /tabs %}}
{{% code-tab-content %}} {{% tab-content %}}
{{% influxdb/custom-timestamps %}} {{% influxdb/custom-timestamps %}}
{{% code-placeholders "DATABASE_(NAME|TOKEN)|(LINE_PROTOCOL_FILEPATH)" %}} {{% code-placeholders "DATABASE_(NAME|TOKEN)|(LINE_PROTOCOL_FILEPATH)" %}}
```sh ```sh
influxctl write \ influxctl write \
--database DATABASE_NAME \ --database DATABASE_NAME \
@ -105,6 +106,7 @@ 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=Living\ Room temp=22.4,hum=36.0,co=0i 1641042000
home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641042000' home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641042000'
``` ```
{{% /code-placeholders %}} {{% /code-placeholders %}}
{{% /influxdb/custom-timestamps %}} {{% /influxdb/custom-timestamps %}}
@ -115,17 +117,43 @@ Replace the following:
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: - {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}:
Database token with write permissions on the target database. Database token with write permissions on the target database.
{{% /code-tab-content %}} {{% /tab-content %}}
{{% code-tab-content %}} {{% tab-content %}}
{{% code-placeholders "DATABASE_(NAME|TOKEN)|(LINE_PROTOCOL_FILEPATH)" %}} {{% code-placeholders "DATABASE_(NAME|TOKEN)|(LINE_PROTOCOL_FILEPATH)" %}}
```sh
influxctl write \ 1. In your terminal, enter the following command to create the sample data file:
--database DATABASE_NAME \
--token DATABASE_TOKEN \ ```sh
--precision s \ cat <<EOF > ./home.lp && LINE_PROTOCOL_FILEPATH=./home.lp
LINE_PROTOCOL_FILEPATH 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
EOF
```
<!--pytest-codeblocks:cont-->
2. Enter the following CLI command to write the data from the sample file:
```sh
influxctl write \
--database DATABASE_NAME \
--token DATABASE_TOKEN \
--precision s \
$LINE_PROTOCOL_FILEPATH
```
{{% /code-placeholders %}} {{% /code-placeholders %}}
Replace the following: Replace the following:
@ -134,21 +162,25 @@ Replace the following:
Name of the database to write to. Name of the database to write to.
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: - {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}:
Database token with write permissions on the target database. Database token with write permissions on the target database.
- {{% code-placeholder-key %}}`LINE_PROTOCOL_FILEPATH`{{% /code-placeholder-key %}}: - {{% code-placeholder-key %}}`$LINE_PROTOCOL_FILEPATH`{{% /code-placeholder-key %}}:
File path to the file containing the line protocol. Can be an absolute file path File path to the file containing the line protocol. Can be an absolute file path
or relative to the current working directory. or relative to the current working directory.
{{% /code-tab-content %}} {{% /tab-content %}}
{{% code-tab-content %}} {{% tab-content %}}
{{% code-placeholders "DATABASE_(NAME|TOKEN)|(LINE_PROTOCOL_FILEPATH)" %}} {{% code-placeholders "DATABASE_(NAME|TOKEN)|(LINE_PROTOCOL_FILEPATH)" %}}
<!--pytest-codeblocks:cont-->
```sh ```sh
cat LINE_PROTOCOL_FILEPATH | influxctl write \ cat $LINE_PROTOCOL_FILEPATH | influxctl write \
--database DATABASE_NAME \ --database DATABASE_NAME \
--token DATABASE_TOKEN \ --token DATABASE_TOKEN \
--precision s \ --precision s \
- -
``` ```
{{% /code-placeholders %}} {{% /code-placeholders %}}
Replace the following: Replace the following:
@ -157,9 +189,9 @@ Replace the following:
Name of the database to write to. Name of the database to write to.
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: - {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}:
Database token with write permissions on the target database. Database token with write permissions on the target database.
- {{% code-placeholder-key %}}`LINE_PROTOCOL_FILEPATH`{{% /code-placeholder-key %}}: - {{% code-placeholder-key %}}`$LINE_PROTOCOL_FILEPATH`{{% /code-placeholder-key %}}:
File path to the file containing the line protocol. Can be an absolute file path File path to the file containing the line protocol. Can be an absolute file path
or relative to the current working directory. or relative to the current working directory.
{{% /code-tab-content %}} {{% /tab-content %}}
{{< /code-tabs-wrapper >}} {{< /tabs-wrapper >}}

157
content/influxdb/cloud-serverless/get-started/write.md
View File

@ -44,8 +44,6 @@ see the [Line protocol reference](/influxdb/cloud-serverless/reference/syntax/li
Each line of line protocol contains the following elements: Each line of line protocol contains the following elements:
<!-- vale InfluxDataDocs.v3Schema = NO -->
{{< req type="key" >}} {{< req type="key" >}}
- {{< req "\*" >}} **measurement**: String that identifies the [measurement](/influxdb/cloud-serverless/reference/glossary/#measurement) to store the data in. - {{< req "\*" >}} **measurement**: String that identifies the [measurement](/influxdb/cloud-serverless/reference/glossary/#measurement) to store the data in.
@ -65,14 +63,16 @@ Each line of line protocol contains the following elements:
#### Line protocol element parsing #### Line protocol element parsing
<!-- vale InfluxDataDocs.v3Schema = NO -->
- **measurement**: Everything before the _first unescaped comma before the first - **measurement**: Everything before the _first unescaped comma before the first
whitespace_. whitespace_.
- **tag set**: Key-value pairs between the _first unescaped comma_ and the _first - **tag set**: Key-value pairs between the _first unescaped comma_ and the _first
unescaped whitespace_. unescaped whitespace_.
- **field set**: Key-value pairs between the _first and second unescaped whitespaces_. - **field set**: Key-value pairs between the _first and second unescaped whitespaces_.
- **timestamp**: Integer value after the _second unescaped whitespace_. - **timestamp**: Integer value after the _second unescaped whitespace_.
- Lines are separated by the newline character (`\n`). - Lines are separated by the newline character (`\n`). Line protocol is
Line protocol is whitespace sensitive. whitespace sensitive.
<!-- vale InfluxDataDocs.v3Schema = YES -->
--- ---
@ -84,6 +84,7 @@ _For schema design recommendations, see [InfluxDB schema design](/influxdb/cloud
## Construct line protocol ## Construct line protocol
<!-- vale InfluxDataDocs.v3Schema = NO -->
With a basic understanding of line protocol, you can now construct line protocol With a basic understanding of line protocol, you can now construct line protocol
and write data to InfluxDB. 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.
@ -140,7 +141,7 @@ home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200
## Write line protocol to InfluxDB ## Write line protocol to InfluxDB
The following examples show how to write the The following examples show how to write the preceding
[sample data](#home-sensor-data-line-protocol), already in line protocol format, [sample data](#home-sensor-data-line-protocol), already in line protocol format,
to an {{% product-name %}} bucket. to an {{% product-name %}} bucket.
@ -239,6 +240,8 @@ home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200
``` ```
{{< /influxdb/custom-timestamps >}} {{< /influxdb/custom-timestamps >}}
If successful, the output is the success message; otherwise, error details and
the failure message.
<!------------------------------ END CLI CONTENT ------------------------------> <!------------------------------ END CLI CONTENT ------------------------------>
{{% /tab-content %}} {{% /tab-content %}}
@ -247,11 +250,14 @@ home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200
{{< influxdb/custom-timestamps >}} {{< influxdb/custom-timestamps >}}
Use [Telegraf](/telegraf/v1/) to consume line protocol, and then write it to {{< product-name >}}. Use [Telegraf](/telegraf/v1/) to consume line protocol, and then write it to
{{< product-name >}}.
1. If you haven't already, follow the instructions to [download and install Telegraf](/telegraf/v1/install/). 11. If you haven't already, follow the instructions to
[download and install Telegraf](/telegraf/v1/install/).
2. Copy and save the [home sensor data sample](#home-sensor-data-line-protocol) to a file on your local system--for example, `home.lp`. 2. Copy and save the [home sensor data sample](#home-sensor-data-line-protocol)
to a file on your local system--for example, `home.lp`.
```sh ```sh
cat <<- EOF > home.lp cat <<- EOF > home.lp
@ -398,12 +404,13 @@ guide.
{{% /note %}} {{% /note %}}
To write data to InfluxDB using the To write data to InfluxDB using the
[InfluxDB v1 HTTP API](/influxdb/cloud-serverless/reference/api/), send a [InfluxDB v1 HTTP API](/influxdb/cloud-serverless/reference/api/), send a request
request to the to the
[InfluxDB API `/write` endpoint](/influxdb/cloud-serverless/api/#operation/PostLegacyWrite) [InfluxDB API `/write` endpoint](/influxdb/cloud-serverless/api/#operation/PostLegacyWrite)
using the `POST` request method. using the `POST` request method.
{{% api-endpoint endpoint="https://{{< influxdb/host >}}/write" method="post" api-ref="/influxdb/cloud-serverless/api/#operation/PostLegacyWrite" %}} {{% api-endpoint endpoint="https://{{< influxdb/host >}}/write" method="post"
api-ref="/influxdb/cloud-serverless/api/#operation/PostLegacyWrite"%}}
Include the following with your request: Include the following with your request:
@ -485,7 +492,8 @@ _For InfluxDB to [auto-generate the DBRP mapping](/influxdb/cloud-serverless/gui
[All-Access API token](/influxdb/cloud-serverless/admin/tokens/#all-access-api-token) [All-Access API token](/influxdb/cloud-serverless/admin/tokens/#all-access-api-token)
in the write request_. in the write request_.
If successful, the output is an HTTP `204 No Content` status code. If successful, the output is an HTTP `204 No Content` status code; otherwise,
the error status code and failure message.
<!--pytest-codeblocks:expected-output--> <!--pytest-codeblocks:expected-output-->
@ -584,7 +592,7 @@ Replace the following:
to the specified bucket to the specified bucket
If successful, the output is an HTTP `204 No Content` status code; otherwise, If successful, the output is an HTTP `204 No Content` status code; otherwise,
the status code and error message. the error status code and failure message.
<!--pytest-codeblocks:expected-output--> <!--pytest-codeblocks:expected-output-->
@ -715,7 +723,7 @@ dependencies to your current project.
- **`host`**: {{% product-name %}} region hostname (URL without protocol - **`host`**: {{% product-name %}} region hostname (URL without protocol
or trailing slash) or trailing slash)
- **`token`**: a [token](/influxdb/cloud-serverless/admin/tokens/) with - **`token`**: a [token](/influxdb/cloud-serverless/admin/tokens/) with
`write_ access to the specified bucket. write access to the specified bucket.
_Store this in a secret store or environment variable to avoid exposing _Store this in a secret store or environment variable to avoid exposing
the raw token string._ the raw token string._
- **`database`**: the name of the {{% product-name %}} bucket to write to - **`database`**: the name of the {{% product-name %}} bucket to write to
@ -729,7 +737,7 @@ dependencies to your current project.
[timestamp precision](/influxdb/cloud-serverless/reference/glossary/#timestamp-precision) [timestamp precision](/influxdb/cloud-serverless/reference/glossary/#timestamp-precision)
to seconds.** to seconds.**
1. To execute the module and write line protocol to your {{% product-name %}} 7. To execute the module and write line protocol to your {{% product-name %}}
bucket, enter the following command in your terminal: bucket, enter the following command in your terminal:
<!--pytest.mark.skip--> <!--pytest.mark.skip-->
@ -739,6 +747,9 @@ dependencies to your current project.
``` ```
{{% /influxdb/custom-timestamps %}} {{% /influxdb/custom-timestamps %}}
If successful, the output is the success message; otherwise, error details and
the failure message.
<!----------------------------- END PYTHON CONTENT ----------------------------> <!----------------------------- END PYTHON CONTENT ---------------------------->
{{% /tab-content %}} {{% /tab-content %}}
{{% tab-content %}} {{% tab-content %}}
@ -875,7 +886,7 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
`influxdb3.New(influxdb3.ClientConfig)` function and passes the following: `influxdb3.New(influxdb3.ClientConfig)` function and passes the following:
- **`Host`**: your {{% product-name %}} region URL - **`Host`**: your {{% product-name %}} region URL
- **`Token`**: a [token](/influxdb/cloud-serverless/admin/tokens/) - **`Token`**: a [token](/influxdb/cloud-serverless/admin/tokens/)
with _write_ access to the specified bucket. _Store this in a with write access to the specified bucket. _Store this in a
secret store or environment variable to avoid exposing the raw secret store or environment variable to avoid exposing the raw
token string._ token string._
- **`WriteOptions`**: `influxdb3.WriteOptions` options for writing - **`WriteOptions`**: `influxdb3.WriteOptions` options for writing
@ -883,7 +894,8 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
**Because the timestamps in the sample line protocol are in second **Because the timestamps in the sample line protocol are in second
precision, the example passes the `Precision: lineprotocol.Second` precision, the example passes the `Precision: lineprotocol.Second`
option to set the [timestamp precision](/influxdb/cloud-serverless/reference/glossary/#timestamp-precision) option to set the
[timestamp precision](/influxdb/cloud-serverless/reference/glossary/#timestamp-precision)
to seconds.** to seconds.**
2. Defines a deferred function that closes the client when the function 2. Defines a deferred function that closes the client when the function
@ -906,23 +918,26 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
} }
``` ```
6. In your terminal, enter the following command to install the packages listed 6. To install dependencies and write the data to your {{% product-name %}} bucket,
in `imports`, build the `influxdb_go_client` module, and execute the enter the following command into your terminal:
`main()` function:
<!--pytest.mark.skip--> <!--pytest.mark.skip-->
```sh ```sh
go mod tidy && go build && go run influxdb_go_client go mod tidy && go run influxdb_go_client
``` ```
The program writes the line protocol to your {{% product-name %}} bucket. If successful, the output is the success message; otherwise, error details and
the failure message.
{{% /influxdb/custom-timestamps %}} {{% /influxdb/custom-timestamps %}}
<!------------------------------- END GO CONTENT ------------------------------> <!------------------------------- END GO CONTENT ------------------------------>
{{% /tab-content %}} {{% /tab-content %}}
{{% tab-content %}} {{% tab-content %}}
{{% influxdb/custom-timestamps %}} {{% influxdb/custom-timestamps %}}
<!---------------------------- BEGIN NODE.JS CONTENT ---------------------------> <!---------------------------- BEGIN NODE.JS CONTENT --------------------------->
1. If you haven't already, follow the instructions for 1. If you haven't already, follow the instructions for
@ -1050,8 +1065,9 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
- **`host`**: your {{% product-name %}} region URL - **`host`**: your {{% product-name %}} region URL
- **`token`**: a [token](/influxdb/cloud-serverless/admin/tokens/) - **`token`**: a [token](/influxdb/cloud-serverless/admin/tokens/)
with _write_ access to the specified bucket. with write access to the specified bucket.
_Store this in a secret store or environment variable to avoid exposing the raw token string._ _Store this in a secret store or environment variable to avoid exposing
the raw token string._
3. Defines a list of line protocol strings where each string represents a 3. Defines a list of line protocol strings where each string represents a
data record. data record.
@ -1075,6 +1091,7 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
success and failure messages to a `writeResults` constant. success and failure messages to a `writeResults` constant.
6. Iterates over and prints the messages in `writeResults`. 6. Iterates over and prints the messages in `writeResults`.
7. Closes the client to release resources. 7. Closes the client to release resources.
7. In your terminal or editor, create an `index.js` file. 7. In your terminal or editor, create an `index.js` file.
8. Inside of `index.js`, enter the following sample code to import and call 8. Inside of `index.js`, enter the following sample code to import and call
`writeLineProtocol()`: `writeLineProtocol()`:
@ -1104,6 +1121,9 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
{{% /influxdb/custom-timestamps %}} {{% /influxdb/custom-timestamps %}}
If successful, the output is the success message; otherwise, error details and
the failure message.
<!---------------------------- END NODE.JS CONTENT ---------------------------> <!---------------------------- END NODE.JS CONTENT --------------------------->
{{% /tab-content %}} {{% /tab-content %}}
@ -1126,14 +1146,15 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
``` ```
3. Change into the generated `influxdb_csharp_client` directory. 3. Change into the generated `influxdb_csharp_client` directory.
<!--pytest.mark.skip--> <!--pytest.mark.skip-->
```sh ```sh
cd influxdb_csharp_client cd influxdb_csharp_client
``` ```
4. Run the following command to install the latest version of the InfluxDB v3 C# client library. 4. Run the following command to install the latest version of the InfluxDB v3 C#
client library.
<!--pytest.mark.skip--> <!--pytest.mark.skip-->
@ -1158,7 +1179,7 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
/** /**
* Writes line protocol to InfluxDB using the C# .NET client * Writes line protocol to InfluxDB using the C# .NET client
* library. * library.
*/ */
public static async Task WriteLines() public static async Task WriteLines()
{ {
// Set InfluxDB credentials // Set InfluxDB credentials
@ -1231,10 +1252,11 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
- **host**: your {{% product-name %}} region URL - **host**: your {{% product-name %}} region URL
- **database**: the name of the {{% product-name %}} bucket to write to - **database**: the name of the {{% product-name %}} bucket to write to
- **token**: a [token](/influxdb/cloud-serverless/admin/tokens/) with _write_ access to the specified bucket. - **token**: a [token](/influxdb/cloud-serverless/admin/tokens/) with write access to the specified bucket.
_Store this in a secret store or environment variable to avoid exposing the raw token string._ _Store this in a secret store or environment variable to avoid exposing the raw token string._
_Instantiating the client with the `using` statement ensures that the client is disposed of when it's no longer needed._ _The `using` statement ensures that the program disposes of the
client when it's no longer needed._
2. Defines an array of line protocol strings where each string represents a data record. 2. Defines an array of line protocol strings where each string represents a data record.
3. Calls the client's `WriteRecordAsync()` method to write each line protocol record to InfluxDB. 3. Calls the client's `WriteRecordAsync()` method to write each line protocol record to InfluxDB.
@ -1262,11 +1284,13 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
} }
``` ```
The `Program` class shares the same `InfluxDBv3` namespace as the `Write` class you defined in the preceding step The `Program` class shares the same `InfluxDBv3` namespace as the `Write`
and defines a `Main()` function that calls `Write.WriteLineProtocol()`. class you defined in the preceding step and defines a `Main()` function that
The `dotnet` CLI recognizes `Program.Main()` as the entry point for your program. calls `Write.WriteLineProtocol()`. The `dotnet` CLI recognizes
`Program.Main()` as the entry point for your program.
7. To build and execute the program and write the line protocol to your {{% product-name %}} bucket, enter the following command in your terminal: 7. To build and execute the program and write the line protocol to your
{{% product-name %}} bucket, enter the following command in your terminal:
<!--pytest.mark.skip--> <!--pytest.mark.skip-->
@ -1274,6 +1298,9 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
dotnet run dotnet run
``` ```
If successful, the output is the success message; otherwise, error details and
the failure message.
<!---------------------------- END C# CONTENT ---------------------------> <!---------------------------- END C# CONTENT --------------------------->
{{% /influxdb/custom-timestamps %}} {{% /influxdb/custom-timestamps %}}
{{% /tab-content %}} {{% /tab-content %}}
@ -1283,7 +1310,9 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
_The tutorial assumes using Maven version 3.9 and Java version >= 15._ _The tutorial assumes using Maven version 3.9 and Java version >= 15._
1. If you haven't already, follow the instructions to download and install the [Java JDK](https://www.oracle.com/java/technologies/downloads/) and [Maven](https://maven.apache.org/download.cgi) for your system. 1. If you haven't already, follow the instructions to download and install the
[Java JDK](https://www.oracle.com/java/technologies/downloads/) and
[Maven](https://maven.apache.org/download.cgi) for your system.
2. In your terminal or editor, use Maven to generate a project--for example: 2. In your terminal or editor, use Maven to generate a project--for example:
```bash ```bash
@ -1295,9 +1324,11 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._
``` ```
Maven creates the `<artifactId>` directory (`./influxdb_java_client`) that Maven creates the `<artifactId>` directory (`./influxdb_java_client`) that
contains a `pom.xml` and scaffolding for your `com.influxdbv3.influxdb_java_client` Java application. contains a `pom.xml` and scaffolding for your
`com.influxdbv3.influxdb_java_client` Java application.
3. In your terminal or editor, change into the `./influxdb_java_client` directory--for example: 3. In your terminal or editor, change into the `./influxdb_java_client`
directory--for example:
<!--pytest-codeblocks:cont--> <!--pytest-codeblocks:cont-->
@ -1305,7 +1336,8 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._
cd ./influxdb_java_client cd ./influxdb_java_client
``` ```
4. In your editor, open the `pom.xml` Maven configuration file and add the `com.influxdb.influxdb3-java` client library into `dependencies`. 4. In your editor, open the `pom.xml` Maven configuration file and add the
`com.influxdb.influxdb3-java` client library into `dependencies`.
```pom ```pom
... ...
@ -1329,7 +1361,9 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._
mvn validate mvn validate
``` ```
6. In your editor, navigate to the `./influxdb_java_client/src/main/java/com/influxdbv3` directory and create a `Write.java` file. 6. In your editor, navigate to the
`./influxdb_java_client/src/main/java/com/influxdbv3` directory and create a
`Write.java` file.
7. In `Write.java`, enter the following sample code: 7. In `Write.java`, enter the following sample code:
```java ```java
@ -1344,7 +1378,7 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._
/** /**
* Writes line protocol to InfluxDB using the Java client * Writes line protocol to InfluxDB using the Java client
* library. * library.
*/ */
public final class Write { public final class Write {
/** /**
* Write data to InfluxDB v3. * Write data to InfluxDB v3.
@ -1357,7 +1391,7 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._
* @throws Exception * @throws Exception
*/ */
public static void writeLineProtocol() throws Exception { public static void writeLineProtocol() throws Exception {
// Set InfluxDB credentials // Set InfluxDB credentials
final String host = "https://{{< influxdb/host >}}"; final String host = "https://{{< influxdb/host >}}";
final String database = "get-started"; final String database = "get-started";
@ -1421,7 +1455,7 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._
The sample code does the following: The sample code does the following:
1. Imports the following classes: 1. Imports the following classes:
- `java.util.List`; - `java.util.List`;
- `com.influxdb.v3.client.InfluxDBClient` - `com.influxdb.v3.client.InfluxDBClient`
- `com.influxdb.v3.client.write.WriteParameters` - `com.influxdb.v3.client.write.WriteParameters`
@ -1432,17 +1466,26 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._
- **`host`**: your {{% product-name %}} region URL - **`host`**: your {{% product-name %}} region URL
- **`database`**: the name of the {{% product-name %}} bucket to write to - **`database`**: the name of the {{% product-name %}} bucket to write to
- **`token`**: a [token](/influxdb/cloud-serverless/admin/tokens/) with _write_ access to the specified bucket. - **`token`**: a
_Store this in a secret store or environment variable to avoid exposing the raw token string._ [token](/influxdb/cloud-serverless/admin/tokens/) with write access
to the specified bucket.
_Store this in a secret store or environment variable to avoid exposing
the raw token string._
2. Defines a list of line protocol strings where each string represents a data record. 3. Defines a list of line protocol strings where each string represents a
3. Calls the client's `writeRecord()` method to write each record separately to InfluxDB. data record.
4. Calls the client's `writeRecord()` method to write each record
separately to InfluxDB.
**Because the timestamps in the sample line protocol are in second **Because the timestamps in the sample line protocol are in second
precision, the example passes the [`WritePrecision.S` enum value](https://github.com/InfluxCommunity/influxdb3-java/blob/main/src/main/java/com/influxdb/v3/client/write/WritePrecision.java) precision, the example passes the
as the `precision` argument to set the write [timestamp precision](/influxdb/cloud-serverless/reference/glossary/#timestamp-precision) to seconds.** [`WritePrecision.S` enum value](https://github.com/InfluxCommunity/influxdb3-java/blob/main/src/main/java/com/influxdb/v3/client/write/WritePrecision.java)
as the `precision` argument to set the write
[timestamp precision](/influxdb/cloud-serverless/reference/glossary/#timestamp-precision)
to seconds.**
8. In your editor, open the `App.java` file (created by Maven) and replace its contents with the following sample code: 8. In your editor, open the `App.java` file (created by Maven) and replace its
contents with the following sample code:
```java ```java
// App.java // App.java
@ -1465,10 +1508,13 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._
} }
} }
``` ```
- The `App` class and `Write` class are part of the same `com.influxdbv3` package (your project **groupId**). - The `App` class and `Write` class are part of the same `com.influxdbv3`
package (your project **groupId**).
- `App` defines a `main()` function that calls `Write.writeLineProtocol()`. - `App` defines a `main()` function that calls `Write.writeLineProtocol()`.
9. In your terminal or editor, use Maven to to install dependencies and compile the project code--for example:
9. In your terminal or editor, use Maven to install dependencies and compile
the project code--for example:
<!--pytest.mark.skip--> <!--pytest.mark.skip-->
@ -1476,20 +1522,23 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._
mvn compile mvn compile
``` ```
10. In your terminal or editor, execute `App.main()` to write to InfluxDB--for example, using Maven: 10. In your terminal or editor, execute `App.main()` to write to InfluxDB--for
example, using Maven:
<!--pytest.mark.skip--> <!--pytest.mark.skip-->
```sh ```sh
mvn exec:java -Dexec.mainClass="com.influxdbv3.App" mvn exec:java -Dexec.mainClass="com.influxdbv3.App"
``` ```
If successful, the output is the success message; otherwise, error details and
the failure message.
<!---------------------------- END JAVA CONTENT ---------------------------> <!---------------------------- END JAVA CONTENT --------------------------->
{{% /influxdb/custom-timestamps %}} {{% /influxdb/custom-timestamps %}}
{{% /tab-content %}} {{% /tab-content %}}
{{< /tabs-wrapper >}} {{< /tabs-wrapper >}}
If successful, the output is the success message; otherwise, error details and the failure message.
{{< expand-wrapper >}} {{< expand-wrapper >}}
{{% expand "View the written data" %}} {{% expand "View the written data" %}}

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

@ -0,0 +1,89 @@
---
title: Write line protocol data to InfluxDB Cloud Serverless
description: >
Use Telegraf and API clients to write line protocol data
to InfluxDB Cloud Serverless.
menu:
influxdb_cloud_serverless:
name: Write line protocol data
parent: Write data
weight: 103
related:
- /influxdb/cloud-serverless/reference/syntax/line-protocol/
- /influxdb/cloud-serverless/reference/syntax/annotated-csv/
- /influxdb/cloud-serverless/reference/cli/influx/write/
- /influxdb/cloud-serverless/get-started/write/
---
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](/influxdb/cloud-serverless/write-data/csv).
- [Line protocol](#line-protocol)
- [Line protocol elements](#line-protocol-elements)
- [Write line protocol to InfluxDB](#write-line-protocol-to-influxdb)
## Line protocol
All data written to InfluxDB is written using
[line protocol](/influxdb/cloud-serverless/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-serverless/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-serverless/reference/syntax/line-protocol/#string)
(quoted),
[floats](/influxdb/cloud-serverless/reference/syntax/line-protocol/#float),
[integers](/influxdb/cloud-serverless/reference/syntax/line-protocol/#integer),
[unsigned integers](/influxdb/cloud-serverless/reference/syntax/line-protocol/#uinteger),
or [booleans](/influxdb/cloud-serverless/reference/syntax/line-protocol/#boolean).
- **timestamp**: [Unix timestamp](/influxdb/cloud-serverless/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-serverless/write-data/best-practices/schema-design/)._
## Write line protocol to InfluxDB
{{< children >}}

475
content/influxdb/cloud-serverless/write-data/line-protocol/client-libraries.md Normal file
View File

@ -0,0 +1,475 @@
---
title: Use InfluxDB client libraries to write line protocol data
description: >
Use InfluxDB API clients to write points as line protocol data to InfluxDB
Cloud Serverless.
menu:
influxdb_cloud_serverless:
name: Use client libraries
parent: Write line protocol
identifier: write-client-libs
weight: 103
related:
- /influxdb/cloud-serverless/reference/syntax/line-protocol/
- /influxdb/cloud-serverless/get-started/write/
---
Use InfluxDB client libraries to construct data as time series points, and then
write them as line protocol to an {{% product-name %}} bucket.
- [Construct line protocol](#construct-line-protocol)
- [Example home schema](#example-home-schema)
- [Set up your project](#set-up-your-project)
- [Construct points and write line protocol](#construct-points-and-write-line-protocol)
## Construct line protocol
With a
[basic understanding of line protocol](/influxdb/cloud-serverless/write-data/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:
<!-- vale InfluxDataDocs.v3Schema = NO -->
- **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
<!-- vale InfluxDataDocs.v3Schema = YES -->
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](/influxdb/cloud-serverless/get-started/setup/) and
[Write data set up](/influxdb/cloud-serverless/get-started/write/#set-up-your-project-and-credentials)
instructions in [Get started](/influxdb/cloud-serverless/get-started/).
After setting up InfluxDB and your project, you should have the following:
- {{< product-name >}} credentials:
- [Bucket](/influxdb/cloud-serverless/admin/buckets/)
- [API token](/influxdb/cloud-serverless/admin/tokens/)
- InfluxDB region 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 examples show how to construct `Point` objects that follow the
[example `home` schema](#example-home-schema), and then write the data as line
protocol to an {{% product-name %}} bucket.
The examples use InfluxDB v3 client libraries.
For examples using InfluxDB v2
client libraries to write data to InfluxDB v3, see
[InfluxDB v2 clients](/influxdb/cloud-serverless/reference/client-libraries/v2/).
{{< tabs-wrapper >}}
{{% tabs %}}
[Go](#)
[Node.js](#)
[Python](#)
{{% /tabs %}}
{{% tab-content %}}
The following steps set up a Go project using the
[InfluxDB v3 Go client](https://github.com/InfluxCommunity/influxdb3-go/):
<!-- BEGIN GO PROJECT SETUP -->
1. Install [Go 1.13 or later](https://golang.org/doc/install).
1. Create a directory for your Go module and change to the directory--for
example:
```sh
mkdir iot-starter-go && cd $_
```
1. Initialize a Go module--for example:
```sh
go mod init iot-starter
```
1. Install [`influxdb3-go`](https://github.com/InfluxCommunity/influxdb3-go/),
which provides the InfluxDB `influxdb3` Go client library module.
```sh
go get github.com/InfluxCommunity/influxdb3-go
```
<!-- END GO SETUP PROJECT -->
{{% /tab-content %}} {{% tab-content %}}
<!-- BEGIN NODE.JS PROJECT SETUP -->
The following steps set up a JavaScript project using the
[InfluxDB v3 JavaScript client](https://github.com/InfluxCommunity/influxdb3-js/).
1. Install [Node.js](https://nodejs.org/en/download/).
1. Create a directory for your JavaScript project and change to the
directory--for example:
```sh
mkdir -p iot-starter-js && cd $_
```
1. Initialize a project--for example, using `npm`:
<!-- pytest.mark.skip -->
```sh
npm init
```
1. Install the `@influxdata/influxdb3-client` InfluxDB v3 JavaScript client
library.
```sh
npm install @influxdata/influxdb3-client
```
<!-- END NODE.JS SETUP PROJECT -->
{{% /tab-content %}} {{% tab-content %}}
<!-- BEGIN PYTHON SETUP PROJECT -->
The following steps set up a Python project using the
[InfluxDB v3 Python client](https://github.com/InfluxCommunity/influxdb3-python/):
1. Install [Python](https://www.python.org/downloads/)
1. Inside of your project directory, create a directory for your Python module
and change to the module directory--for example:
```sh
mkdir -p iot-starter-py && cd $_
```
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, enter the
following command using `venv` to create and activate a virtual environment
for the project:
```bash
python3 -m venv envs/iot-starter && source ./envs/iot-starter/bin/activate
```
1. Install
[`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
Client libraries provide one or more `Point` constructor methods. Some libraries
support language-native data structures, such as Go's `struct`, for creating
points.
{{< tabs-wrapper >}}
{{% tabs %}}
[Go](#)
[Node.js](#)
[Python](#)
{{% /tabs %}}
{{% tab-content %}}
<!-- BEGIN GO SETUP SAMPLE -->
1. Create a file for your module--for example: `main.go`.
1. In `main.go`, enter the following sample code:
```go
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_BUCKET")
// 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()
}
```
1. To run the module and write the data to your {{% product-name %}} bucket,
enter the following command in your terminal:
<!-- pytest.mark.skip -->
```sh
go run main.go
```
<!-- END GO SAMPLE -->
{{% /tab-content %}} {{% tab-content %}}
<!-- BEGIN NODE.JS SETUP SAMPLE -->
1. Create a file for your module--for example: `write-points.js`.
1. In `write-points.js`, enter the following sample code:
```js
// write-points.js
import { InfluxDBClient, Point } from '@influxdata/influxdb3-client';
/**
* Set InfluxDB credentials.
*/
const host = process.env.INFLUX_HOST ?? '';
const database = process.env.INFLUX_BUCKET;
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 (bucket),
* 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();
```
1. To run the module and write the data to your {{\< product-name >}} bucket,
enter the following command in your terminal:
<!-- pytest.mark.skip -->
```sh
node writePoints.js
```
<!-- END NODE.JS SAMPLE -->
{{% /tab-content %}} {{% tab-content %}}
<!-- BEGIN PYTHON SETUP SAMPLE -->
1. Create a file for your module--for example: `write-points.py`.
1. In `write-points.py`, enter the following sample code to write data in
batching mode:
```python
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_BUCKET')
# 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')
```
1. To run the module and write the data to your {{< product-name >}} bucket,
enter the following command in your terminal:
<!-- pytest.mark.skip -->
```sh
python write-points.py
```
<!-- END PYTHON SETUP PROJECT -->
{{% /tab-content %}} {{< /tabs-wrapper >}}
The sample code does the following:
<!-- vale InfluxDataDocs.v3Schema = NO -->
1. Instantiates a client configured with the InfluxDB URL and API token.
2. Constructs `home`
[measurement](/influxdb/cloud-serverless/reference/glossary/#measurement)
`Point` objects.
3. Sends data as line protocol format to InfluxDB and waits for the response.
4. If the write succeeds, logs the success message to stdout; otherwise, logs
the failure message and error details.
5. Closes the client to release resources.
<!-- vale InfluxDataDocs.v3Schema = YES -->

222
content/influxdb/clustered/get-started/write.md
View File

@ -55,29 +55,36 @@ Each line of line protocol contains the following elements:
- {{< req "\*" >}} **measurement**: A string that identifies the - {{< req "\*" >}} **measurement**: A string that identifies the
[table](/influxdb/clustered/reference/glossary/#table) to store the data in. [table](/influxdb/clustered/reference/glossary/#table) to store the data in.
- **tag set**: Comma-delimited list of key value pairs, each representing a tag. - **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._ Tag keys and values are unquoted strings. _Spaces, commas, and equal characters
- {{< req "\*" >}} **field set**: Comma-delimited list of key value pairs, each representing a field. 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 keys are unquoted strings. _Spaces and commas must be escaped._
Field values can be [strings](/influxdb/clustered/reference/syntax/line-protocol/#string) (quoted), Field values can be [strings](/influxdb/clustered/reference/syntax/line-protocol/#string)
(quoted),
[floats](/influxdb/clustered/reference/syntax/line-protocol/#float), [floats](/influxdb/clustered/reference/syntax/line-protocol/#float),
[integers](/influxdb/clustered/reference/syntax/line-protocol/#integer), [integers](/influxdb/clustered/reference/syntax/line-protocol/#integer),
[unsigned integers](/influxdb/clustered/reference/syntax/line-protocol/#uinteger), [unsigned integers](/influxdb/clustered/reference/syntax/line-protocol/#uinteger),
or [booleans](/influxdb/clustered/reference/syntax/line-protocol/#boolean). or [booleans](/influxdb/clustered/reference/syntax/line-protocol/#boolean).
- **timestamp**: [Unix timestamp](/influxdb/clustered/reference/syntax/line-protocol/#unix-timestamp) - **timestamp**: [Unix timestamp](/influxdb/clustered/reference/syntax/line-protocol/#unix-timestamp)
associated with the data. InfluxDB supports up to nanosecond precision. associated with the data. InfluxDB supports up to nanosecond precision.
_If the precision of the timestamp is not in nanoseconds, you must specify the _If the precision of the timestamp is not in nanoseconds, you must specify the
precision when writing the data to InfluxDB._ precision when writing the data to InfluxDB._
<!-- vale InfluxDataDocs.v3Schema = YES -->
#### Line protocol element parsing #### Line protocol element parsing
<!-- vale InfluxDataDocs.v3Schema = NO -->
- **measurement**: Everything before the _first unescaped comma before the first - **measurement**: Everything before the _first unescaped comma before the first
whitespace_. whitespace_.
- **tag set**: Key-value pairs between the _first unescaped comma_ and the _first - **tag set**: Key-value pairs between the _first unescaped comma_ and the _first
unescaped whitespace_. unescaped whitespace_.
- **field set**: Key-value pairs between the _first and second unescaped whitespaces_. - **field set**: Key-value pairs between the _first and second unescaped whitespaces_.
- **timestamp**: Integer value after the _second unescaped whitespace_. - **timestamp**: Integer value after the _second unescaped whitespace_.
- Lines are separated by the newline character (`\n`). - Lines are separated by the newline character (`\n`). Line protocol is
Line protocol is whitespace sensitive. whitespace sensitive.
<!-- vale InfluxDataDocs.v3Schema = YES -->
--- ---
@ -85,10 +92,13 @@ 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 ## Construct line protocol
<!-- vale InfluxDataDocs.v3Schema = NO -->
With a basic understanding of line protocol, you can now construct line protocol With a basic understanding of line protocol, you can now construct line protocol
and write data to InfluxDB. 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.
@ -145,7 +155,7 @@ home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200
## Write line protocol to InfluxDB ## Write line protocol to InfluxDB
The following examples show how to write the The following examples show how to write the preceding
[sample data](#home-sensor-data-line-protocol), already in line protocol format, [sample data](#home-sensor-data-line-protocol), already in line protocol format,
to an {{% product-name %}} database. to an {{% product-name %}} database.
@ -225,6 +235,9 @@ home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200'
{{% /code-placeholders %}} {{% /code-placeholders %}}
{{% /influxdb/custom-timestamps %}} {{% /influxdb/custom-timestamps %}}
If successful, the output is the success message; otherwise, error details and
the failure message.
<!----------------------------- END INFLUXCTL CLI CONTENT -----------------------------> <!----------------------------- END INFLUXCTL CLI CONTENT ----------------------------->
{{% /tab-content %}} {{% /tab-content %}}
@ -237,9 +250,11 @@ home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200'
Use [Telegraf](/telegraf/v1/) to consume line protocol, Use [Telegraf](/telegraf/v1/) to consume line protocol,
and then write it to {{< product-name >}}. and then write it to {{< product-name >}}.
1. If you haven't already, follow the instructions to [download and install Telegraf](/telegraf/v1/install/). 1. If you haven't already, follow the instructions to
[download and install Telegraf](/telegraf/v1/install/).
2. Copy and save the [home sensor data sample](#home-sensor-data-line-protocol) to a file on your local system--for example, `home.lp`. 2. Copy and save the [home sensor data sample](#home-sensor-data-line-protocol)
to a file on your local system--for example, `home.lp`.
```sh ```sh
cat <<- EOF > home.lp cat <<- EOF > home.lp
@ -285,64 +300,63 @@ and then write it to {{< product-name >}}.
4. In your editor, open `./telegraf.conf` and configure the following: 4. In your editor, open `./telegraf.conf` and configure the following:
- **`file` input plugin**: In the `[[inputs.file]].files` list, replace - **`file` input plugin**: In the `[[inputs.file]].files` list, replace
`"/tmp/metrics.out"` with your sample data filename. If Telegraf can't `"/tmp/metrics.out"` with your sample data filename. If Telegraf can't
find a file when started, it stops processing and exits. find a file when started, it stops processing and exits.
```toml ```toml
[[inputs.file]] [[inputs.file]]
## Files to parse each interval. Accept standard unix glob matching rules, ## Files to parse each interval. Accept standard unix glob matching rules,
## as well as ** to match recursive files and directories. ## as well as ** to match recursive files and directories.
files = ["home.lp"] files = ["home.lp"]
``` ```
<!--test <!--test
```bash ```bash
echo '[[inputs.file]]' > telegraf.conf echo '[[inputs.file]]' > telegraf.conf
echo ' files = ["home.lp"]' >> telegraf.conf echo ' files = ["home.lp"]' >> telegraf.conf
``` ```
--> -->
- **`output-influxdb_v2` output plugin**: In the `[[outputs.influxdb_v2]]` - **`output-influxdb_v2` output plugin**: In the `[[outputs.influxdb_v2]]`
section, replace the default values with the following configuration for
your {{% product-name %}} database:
section, replace the default values with the following configuration for your ```toml
{{% product-name %}} database: [[outputs.influxdb_v2]]
# InfluxDB cluster URL
urls = ["${INFLUX_HOST}"]
```toml # INFLUX_TOKEN is an environment variable you assigned to your database token
[[outputs.influxdb_v2]] token = "${INFLUX_TOKEN}"
# InfluxDB cluster URL
urls = ["${INFLUX_HOST}"]
# INFLUX_TOKEN is an environment variable you assigned to your database token # An empty string (InfluxDB ignores this parameter)
token = "${INFLUX_TOKEN}" organization = ""
# An empty string (InfluxDB ignores this parameter) # Database name
organization = "" bucket = "get-started"
```
# Database name <!--test
bucket = "get-started" ```bash
``` echo '[[outputs.influxdb_v2]]' >> telegraf.conf
echo ' urls = ["${INFLUX_HOST}"]' >> telegraf.conf
echo '' >> telegraf.conf
echo ' token = "${INFLUX_TOKEN}"' >> telegraf.conf
echo '' >> telegraf.conf
echo ' organization = ""' >> telegraf.conf
echo '' >> telegraf.conf
echo ' bucket = "get-started"' >> telegraf.conf
```
-->
<!--test The example configuration uses the following InfluxDB credentials:
```bash
echo '[[outputs.influxdb_v2]]' >> telegraf.conf
echo ' urls = ["${INFLUX_HOST}"]' >> telegraf.conf
echo '' >> telegraf.conf
echo ' token = "${INFLUX_TOKEN}"' >> telegraf.conf
echo '' >> telegraf.conf
echo ' organization = ""' >> telegraf.conf
echo '' >> telegraf.conf
echo ' bucket = "get-started"' >> telegraf.conf
```
-->
The example configuration uses the following InfluxDB credentials: - **`urls`**: an array containing your **`INFLUX_HOST`** environment
variable
- **`urls`**: an array containing your **`INFLUX_HOST`** environment - **`token`**: your **`INFLUX_TOKEN`** environment variable
variable - **`organization`**: an empty string (InfluxDB ignores this parameter)
- **`token`**: your **`INFLUX_TOKEN`** environment variable - **`bucket`**: the name of the database to write to
- **`organization`**: an empty string (InfluxDB ignores this parameter)
- **`bucket`**: the name of the database to write to
5. To write the data, start the `telegraf` daemon with the following options: 5. To write the data, start the `telegraf` daemon with the following options:
@ -364,8 +378,9 @@ and then write it to {{< product-name >}}.
2023-05-31T20:09:19Z D! [outputs.influxdb_v2] Buffer fullness: 0 / 10000 metrics 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. Telegraf and its plugins provide many options for reading and writing data. To
To learn more, see how to [use Telegraf to write data](/influxdb/clustered/write-data/use-telegraf/). learn more, see how to
[use Telegraf to write data](/influxdb/clustered/write-data/use-telegraf/).
{{% /influxdb/custom-timestamps %}} {{% /influxdb/custom-timestamps %}}
@ -411,11 +426,11 @@ Include the following with your request:
{{% note %}} {{% note %}}
With the {{% product-name %}} With the {{% product-name %}}
[v1 API `/write` endpoint](/influxdb/cloud-dedicated/api/#operation/PostLegacyWrite), [v1 API `/write` endpoint](/influxdb/clustered/api/#operation/PostLegacyWrite),
`Authorization: Bearer` and `Authorization: Token` are equivalent and you can `Authorization: Bearer` and `Authorization: Token` are equivalent and you can
use either scheme to pass a database token in your request. For more information use either scheme to pass a database token in your request. For more information
about HTTP API token schemes, see how to about HTTP API token schemes, see how to
[authenticate API requests](/influxdb/cloud-dedicated/guides/api-compatibility/v1/). [authenticate API requests](/influxdb/clustered/guides/api-compatibility/v1/).
{{% /note %}} {{% /note %}}
The following example uses cURL and the InfluxDB v1 API to write line protocol The following example uses cURL and the InfluxDB v1 API to write line protocol
@ -479,7 +494,8 @@ Replace the following:
a [database token](/influxdb/clustered/admin/tokens/#database-tokens) with a [database token](/influxdb/clustered/admin/tokens/#database-tokens) with
sufficient permissions to the specified database sufficient permissions to the specified database
If successful, the output is an HTTP `204 No Content` status code. If successful, the output is an HTTP `204 No Content` status code; otherwise,
the error status code and failure message.
<!--pytest-codeblocks:expected-output--> <!--pytest-codeblocks:expected-output-->
@ -590,7 +606,7 @@ Replace the following:
sufficient permissions to the specified database sufficient permissions to the specified database
If successful, the output is an HTTP `204 No Content` status code; otherwise, If successful, the output is an HTTP `204 No Content` status code; otherwise,
the status code and error message. the error status code and failure message.
<!--pytest-codeblocks:expected-output--> <!--pytest-codeblocks:expected-output-->
@ -616,17 +632,12 @@ dependencies to your current project.
1. Create a module directory and navigate into it--for example: 1. Create a module directory and navigate into it--for example:
<!--
Using bash here is required when running with pytest.
I don't know why, but sh evaluates $_ to /usr/bin/pytest.
-->
```bash ```bash
mkdir -p influxdb_py_client && cd influxdb_py_client mkdir -p influxdb_py_client && cd influxdb_py_client
``` ```
2. Setup your Python virtual environment. 2. Setup your Python virtual environment.
Inside of your module directory: Inside of your module directory, enter the following command:
<!--pytest-codeblocks:cont--> <!--pytest-codeblocks:cont-->
@ -752,6 +763,9 @@ dependencies to your current project.
{{% /influxdb/custom-timestamps %}} {{% /influxdb/custom-timestamps %}}
If successful, the output is the success message; otherwise, error details and
the failure message.
<!----------------------------- END PYTHON CONTENT ----------------------------> <!----------------------------- END PYTHON CONTENT ---------------------------->
{{% /tab-content %}} {{% /tab-content %}}
@ -927,17 +941,17 @@ To write data to {{% product-name %}} using Go, use the InfluxDB v3
} }
``` ```
6. In your terminal, enter the following command to install the packages listed 6. To install dependencies and write the data to your {{% product-name %}}
in `imports`, build the `influxdb_go_client` module, and execute the database, enter the following command into your terminal:
`main()` function:
<!--pytest.mark.skip--> <!--pytest.mark.skip-->
```sh ```sh
go mod tidy && go build && go run influxdb_go_client go mod tidy && go run influxdb_go_client
``` ```
The program writes the line protocol to your {{% product-name %}} database. If successful, the output is the success message; otherwise, error details and
the failure message.
{{% /influxdb/custom-timestamps %}} {{% /influxdb/custom-timestamps %}}
@ -1133,6 +1147,9 @@ To write data to {{% product-name %}} using Go, use the InfluxDB v3
{{% /influxdb/custom-timestamps %}} {{% /influxdb/custom-timestamps %}}
If successful, the output is the success message; otherwise, error details and
the failure message.
<!---------------------------- END NODE.JS CONTENT ---------------------------> <!---------------------------- END NODE.JS CONTENT --------------------------->
{{% /tab-content %}} {{% /tab-content %}}
@ -1268,8 +1285,8 @@ To write data to {{% product-name %}} using Go, use the InfluxDB v3
with _write_ access to the specified database. _Store this in a secret with _write_ access to the specified database. _Store this in a secret
store or environment variable to avoid exposing the raw token string._ store or environment variable to avoid exposing the raw token string._
_Instantiating the client with the `using` statement ensures that the _The `using` statement ensures that the program disposes of the
client is disposed of when it's no longer needed._ client when it's no longer needed._
2. Defines an array of line protocol strings where each string represents a 2. Defines an array of line protocol strings where each string represents a
data record. data record.
@ -1311,19 +1328,23 @@ To write data to {{% product-name %}} using Go, use the InfluxDB v3
7. To build and execute the program and write the line protocol to your 7. To build and execute the program and write the line protocol to your
{{% product-name %}} database, enter the following command in your terminal: {{% product-name %}} database, enter the following command in your terminal:
<!--pytest.mark.skip--> <!--pytest.mark.skip-->
```sh ```sh
dotnet run dotnet run
``` ```
<!---------------------------- END C# CONTENT ---------------------------> If successful, the output is the success message; otherwise, error details and
the failure message.
{{% /influxdb/custom-timestamps %}} <!---------------------------- END C# CONTENT --------------------------->
{{% /tab-content %}}
{{% tab-content %}} {{% /influxdb/custom-timestamps %}}
{{% influxdb/custom-timestamps %}} {{% /tab-content %}}
<!---------------------------- BEGIN JAVA CONTENT ---------------------------> {{% tab-content %}}
{{% influxdb/custom-timestamps %}}
<!-------------------------- BEGIN JAVA CONTENT --------------------------->
_The tutorial assumes using Maven version 3.9 and Java version >= 15._ _The tutorial assumes using Maven version 3.9 and Java version >= 15._
@ -1542,21 +1563,21 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._
10. In your terminal or editor, execute `App.main()` to write to InfluxDB--for 10. In your terminal or editor, execute `App.main()` to write to InfluxDB--for
example, using Maven: example, using Maven:
<!--pytest.mark.skip--> <!--pytest.mark.skip-->
```sh ```sh
mvn exec:java -Dexec.mainClass="com.influxdbv3.App" mvn exec:java -Dexec.mainClass="com.influxdbv3.App"
``` ```
<!---------------------------- END JAVA CONTENT --------------------------->
{{% /influxdb/custom-timestamps %}}
{{% /tab-content %}}
{{< /tabs-wrapper >}}
If successful, the output is the success message; otherwise, error details and If successful, the output is the success message; otherwise, error details and
the failure message. the failure message.
<!---------------------------- END JAVA CONTENT --------------------------->
{{% /influxdb/custom-timestamps %}}
{{% /tab-content %}}
{{< /tabs-wrapper >}}
{{< expand-wrapper >}} {{< expand-wrapper >}}
{{% expand "View the written data" %}} {{% expand "View the written data" %}}
@ -1597,4 +1618,5 @@ the failure message.
**Congratulations!** You've written data to InfluxDB. **Congratulations!** You've written data to InfluxDB.
Next, learn how to query your data. Next, learn how to query your data.
{{< page-nav prev="/influxdb/clustered/get-started/setup/" next="/influxdb/clustered/get-started/query/" keepTab=true >}} {{< page-nav prev="/influxdb/clustered/get-started/setup/"
next="/influxdb/clustered/get-started/query/" keepTab=true >}}

36
content/influxdb/clustered/write-data/line-protocol/client-libraries.md
View File

@ -6,7 +6,7 @@ description: >
menu: menu:
influxdb_clustered: influxdb_clustered:
name: Use client libraries name: Use client libraries
parent: Write line protocol parent: Write line protocol data
identifier: write-client-libs identifier: write-client-libs
weight: 103 weight: 103
related: related:
@ -14,8 +14,8 @@ related:
- /influxdb/clustered/get-started/write/ - /influxdb/clustered/get-started/write/
--- ---
Use InfluxDB client libraries to build time series points, and then write them Use InfluxDB client libraries to construct data as time series points, and then
line protocol to an {{% product-name %}} database. write them as line protocol to an {{% product-name %}} database.
- [Construct line protocol](#construct-line-protocol) - [Construct line protocol](#construct-line-protocol)
- [Example home schema](#example-home-schema) - [Example home schema](#example-home-schema)
@ -79,15 +79,21 @@ After setting up InfluxDB and your project, you should have the following:
- Client libraries installed for writing data to InfluxDB. - Client libraries installed for writing data to InfluxDB.
The following example shows how to construct `Point` objects that follow the The following examples show how to construct `Point` objects that follow the
[example `home` schema](#example-home-schema), and then write the data as line [example `home` schema](#example-home-schema), and then write the data as line
protocol to an {{% product-name %}} database. protocol to an {{% product-name %}} database.
The examples use InfluxDB v3 client libraries. For examples using InfluxDB v2 The examples use InfluxDB v3 client libraries.
For examples using InfluxDB v2
client libraries to write data to InfluxDB v3, see client libraries to write data to InfluxDB v3, see
[InfluxDB v2 clients](/influxdb/clustered/reference/client-libraries/v2/). [InfluxDB v2 clients](/influxdb/clustered/reference/client-libraries/v2/).
{{< tabs-wrapper >}} {{% tabs %}} [Go](#) [Node.js](#) [Python](#) {{% /tabs %}} {{< tabs-wrapper >}}
{{% tabs %}}
[Go](#)
[Node.js](#)
[Python](#)
{{% /tabs %}}
{{% tab-content %}} {{% tab-content %}}
The following steps set up a Go project using the The following steps set up a Go project using the
@ -192,7 +198,8 @@ The following steps set up a Python project using the
<!-- END PYTHON SETUP PROJECT --> <!-- END PYTHON SETUP PROJECT -->
{{% /tab-content %}} {{< /tabs-wrapper >}} {{% /tab-content %}}
{{< /tabs-wrapper >}}
## Construct points and write line protocol ## Construct points and write line protocol
@ -200,7 +207,12 @@ Client libraries provide one or more `Point` constructor methods. Some libraries
support language-native data structures, such as Go's `struct`, for creating support language-native data structures, such as Go's `struct`, for creating
points. points.
{{< tabs-wrapper >}} {{% tabs %}} [Go](#) [Node.js](#) [Python](#) {{% /tabs %}} {{< tabs-wrapper >}}
{{% tabs %}}
[Go](#)
[Node.js](#)
[Python](#)
{{% /tabs %}}
{{% tab-content %}} {{% tab-content %}}
<!-- BEGIN GO SETUP SAMPLE --> <!-- BEGIN GO SETUP SAMPLE -->
@ -452,12 +464,12 @@ The sample code does the following:
<!-- vale InfluxDataDocs.v3Schema = NO --> <!-- vale InfluxDataDocs.v3Schema = NO -->
1. Instantiates a client configured with the InfluxDB URL and API token. 1. Instantiates a client configured with the InfluxDB URL and API token.
1. Constructs `home` 2. Constructs `home`
[measurement](/influxdb/clustered/reference/glossary/#measurement) [measurement](/influxdb/clustered/reference/glossary/#measurement)
`Point` objects. `Point` objects.
1. Sends data as line protocol format to InfluxDB and waits for the response. 3. Sends data as line protocol format to InfluxDB and waits for the response.
1. If the write succeeds, logs the success message to stdout; otherwise, logs 4. If the write succeeds, logs the success message to stdout; otherwise, logs
the failure message and error details. the failure message and error details.
1. Closes the client to release resources. 5. Closes the client to release resources.
<!-- vale InfluxDataDocs.v3Schema = YES --> <!-- vale InfluxDataDocs.v3Schema = YES -->

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

@ -0,0 +1,197 @@
---
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 data
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:
```text
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:
- The [database](/influxdb/clustered/admin/databases/) name using the `--database` flag
- A [database token](/influxdb/clustered/admin/tokens/#database-tokens)
(with write permissions on the target database) using the `--token` flag
- The 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
{{< tabs-wrapper >}}
{{% tabs %}}
[string](#)
[file](#)
[stdin](#)
{{% /tabs %}}
{{% 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.
{{% /tab-content %}}
{{% tab-content %}}
{{% code-placeholders "DATABASE_(NAME|TOKEN)|(LINE_PROTOCOL_FILEPATH)" %}}
1. In your terminal, enter the following command to create the sample data file:
```sh
cat <<EOF > ./home.lp && LINE_PROTOCOL_FILEPATH=./home.lp
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
EOF
```
<!--pytest-codeblocks:cont-->
2. Enter the following CLI command to write the data from the sample file:
```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.
{{% /tab-content %}}
{{% tab-content %}}
{{% code-placeholders "DATABASE_(NAME|TOKEN)|(LINE_PROTOCOL_FILEPATH)" %}}
<!--pytest-codeblocks:cont-->
```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.
{{% /tab-content %}}
{{< /tabs-wrapper >}}