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

fix(influxdb3): Client library write guide: Refactor, reorganize, and cleanup

pull/6148/head
Jason Stirnaman 2025-06-20 15:49:59 -05:00
parent 6041afb396
commit 57d73b141e
1 changed files with 204 additions and 153 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

357
content/shared/influxdb3-write-guides/client-libraries.md
View File

@ -7,17 +7,217 @@ as time series points, and then write them as line protocol to an
- [Set up your project](#set-up-your-project) - [Set up your project](#set-up-your-project)
- [Construct points and write line protocol](#construct-points-and-write-line-protocol) - [Construct points and write line protocol](#construct-points-and-write-line-protocol)
## Set up your project
Set up your {{< product-name >}} project and credentials
to write data using the InfluxDB 3 client library for your programming language
of choice.
1. [Install {{< product-name >}}](/influxdb3/version/get-started/install/)
2. [Set up {{< product-name >}}](/influxdb3/version/get-started/setup/)
3. Create a project directory and store your
{{< product-name >}} credentials as environment variables or in a project
configuration file, such as a `.env` ("dotenv") file.
After setting up {{< product-name >}} and your project, you should have the following:
- {{< product-name >}} credentials:
- [Database](/influxdb3/version/admin/databases/)
- [Authorization token](/influxdb3/version/admin/tokens/)
- {{% product-name %}} URL
- A directory for your project.
- Credentials stored as environment variables or in a project configuration
file--for example, a `.env` ("dotenv") file.
### Initialize a project directory
Create a project directory and initialize it for your programming language.
<!-- vale InfluxDataDocs.v3Schema = YES -->
{{< tabs-wrapper >}}
{{% tabs %}}
[Go](#)
[Node.js](#)
[Python](#)
{{% /tabs %}}
{{% tab-content %}}
<!-- BEGIN GO PROJECT SETUP -->
1. Install [Go 1.13 or later](https://golang.org/doc/install).
2. Create a directory for your Go module and change to the directory--for
example:
```sh
mkdir iot-starter-go && cd $_
```
3. Initialize a Go module--for example:
```sh
go mod init iot-starter
```
<!-- END GO SETUP PROJECT -->
{{% /tab-content %}}
{{% tab-content %}}
<!-- BEGIN JAVASCRIPT PROJECT SETUP -->
1. Install [Node.js](https://nodejs.org/en/download/).
2. Create a directory for your JavaScript project and change to the
directory--for example:
```sh
mkdir -p iot-starter-js && cd $_
```
3. Initialize a project--for example, using `npm`:
<!-- pytest.mark.skip -->
```sh
npm init
```
<!-- END JAVASCRIPT SETUP PROJECT -->
{{% /tab-content %}}
{{% tab-content %}}
<!-- BEGIN PYTHON SETUP PROJECT -->
1. Install [Python](https://www.python.org/downloads/)
2. 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 $_
```
3. **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
```
<!-- END PYTHON SETUP PROJECT -->
{{% /tab-content %}}
{{< /tabs-wrapper >}}
### Install the client library
Install the InfluxDB 3 client library for your programming language of choice.
{{< tabs-wrapper >}}
{{% tabs %}}
[C#](#)
[Go](#)
[Java](#)
[Node.js](#)
[Python](#)
{{% /tabs %}}
{{% tab-content %}}
<!-- BEGIN C# INSTALL CLIENT LIBRARY -->
Add the [InfluxDB 3 C# client library](https://github.com/InfluxCommunity/influxdb3-csharp) to your project using the
[`dotnet` CLI](https://docs.microsoft.com/dotnet/core/tools/dotnet) or
by adding the package to your project file--for example:
```bash
dotnet add package InfluxDB3.Client
```
{{% /tab-content %}}
{{% tab-content %}}
<!-- BEGIN GO INSTALL CLIENT LIBRARY -->
Add the
[InfluxDB 3 Go client library](https://github.com/InfluxCommunity/influxdb3-go)
to your project using the
[`go get` command](https://golang.org/cmd/go/#hdr-Add_dependencies_to_current_module_and_install_them)--for example:
```bash
go mod init path/to/project/dir && cd $_
go get github.com/InfluxCommunity/influxdb3-go/v2/influxdb3
```
{{% /tab-content %}}
{{% tab-content %}}
<!-- BEGIN JAVA INSTALL CLIENT LIBRARY -->
Add the [InfluxDB 3 Java client library](https://github.com/InfluxCommunity/influxdb3-java) to your project dependencies using
the [Maven](https://maven.apache.org/)
[Gradle](https://gradle.org/) build tools.
For example, to add the library to a Maven project, add the following dependency
to your `pom.xml` file:
```xml
<dependency>
<groupId>com.influxdb</groupId>
<artifactId>influxdb3-java</artifactId>
<version>1.1.0</version>
</dependency>
```
To add the library to a Gradle project, add the following dependency to your `build.gradle` file:
```groovy
dependencies {
implementation 'com.influxdb:influxdb3-java:1.1.0'
}
```
{{% /tab-content %}}
{{% tab-content %}}
<!-- BEGIN NODE.JS INSTALL CLIENT LIBRARY -->
For a Node.js project, use `@influxdata/influxdb3-client`, which provides main (CommonJS),
module (ESM), and browser (UMD) exports.
Add the [InfluxDB 3 JavaScript client library](https://github.com/InfluxCommunity/influxdb3-js) using your preferred package manager--for example, using [`npm`](https://www.npmjs.com/):
```bash
npm install --save @influxdata/influxdb3-client
```
{{% /tab-content %}}
{{% tab-content %}}
<!-- BEGIN PYTHON INSTALL CLIENT LIBRARY -->
Install the [InfluxDB 3 Python client library](https://github.com/InfluxCommunity/influxdb3-python) using
[`pip`](https://pypi.org/project/pip/).
To use Pandas features, such as `to_pandas()`, provided by the Python
client library, you must also install the
[`pandas` package](https://pandas.pydata.org/).
```bash
pip install influxdb3-python pandas
```
{{% /tab-content %}}
{{< /tabs-wrapper >}}
### Construct line protocol ### Construct line protocol
With a [basic understanding of line protocol](/influxdb3/version/write-data/#line-protocol), With a [basic understanding of line protocol](/influxdb3/version/write-data/#line-protocol),
you can construct line protocol data and write it to {{% product-name %}}. you can construct line protocol data and write it to {{% product-name %}}.
All InfluxDB client libraries write data in line protocol format to InfluxDB. Use client library write methods to provide data as raw line protocol
Client library `write` methods let you provide data as raw line protocol or as or as `Point` objects that the client library converts to line protocol.
`Point` objects that the client library converts to line protocol. If your If your program creates the data you write to InfluxDB, the `Point`
program creates the data you write to InfluxDB, use the client library `Point`
interface to take advantage of type safety in your program. interface to take advantage of type safety in your program.
Client libraries provide one or more `Point` constructor methods. Some libraries
support language-native data structures, such as Go's `struct`, for creating
points.
Examples in this guide show how to construct `Point` objects that follow the [example `home` schema](#example-home-schema),
and then write the points as line protocol data to an {{% product-name %}} database.
#### Example home schema #### Example home schema
Consider a use case where you collect data from sensors in your home. Each Consider a use case where you collect data from sensors in your home. Each
@ -36,155 +236,6 @@ To collect this data, use the following schema:
- `co`: carbon monoxide in parts per million (integer) - `co`: carbon monoxide in parts per million (integer)
- **timestamp**: Unix timestamp in _second_ precision - **timestamp**: Unix timestamp in _second_ precision
<!-- vale InfluxDataDocs.v3Schema = YES -->
The following example shows how to construct and write points that follow the
`home` schema.
### Set up your project
After setting up {{< product-name >}} and your project, you should have the following:
- {{< product-name >}} credentials:
- [Database](/influxdb3/version/admin/databases/)
- Authorization token
> [!Note]
> While in beta, {{< product-name >}} does not require an authorization token.
- {{% product-name %}} URL
- A directory for your project.
- Credentials stored as environment variables or in a project configuration
file--for example, a `.env` ("dotenv") file.
- Client libraries installed for writing data to {{< product-name >}}.
The following examples use InfluxDB 3 client libraries to 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 %}} database.
{{< tabs-wrapper >}}
{{% tabs %}}
[Go](#)
[Node.js](#)
[Python](#)
{{% /tabs %}}
{{% tab-content %}}
The following steps set up a Go project using the
[InfluxDB 3 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/v2
```
<!-- END GO SETUP PROJECT -->
{{% /tab-content %}} {{% tab-content %}}
<!-- BEGIN NODE.JS PROJECT SETUP -->
The following steps set up a JavaScript project using the
[InfluxDB 3 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 3 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 3 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-wrapper >}}
{{% tabs %}} {{% tabs %}}
[Go](#) [Go](#)