From 57d73b141e1721017ebe2df1d251937f5a6487bb Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Fri, 20 Jun 2025 15:49:59 -0500 Subject: [PATCH] fix(influxdb3): Client library write guide: Refactor, reorganize, and cleanup --- .../client-libraries.md | 357 ++++++++++-------- 1 file changed, 204 insertions(+), 153 deletions(-) diff --git a/content/shared/influxdb3-write-guides/client-libraries.md b/content/shared/influxdb3-write-guides/client-libraries.md index bfd690f5b..66559b108 100644 --- a/content/shared/influxdb3-write-guides/client-libraries.md +++ b/content/shared/influxdb3-write-guides/client-libraries.md @@ -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) - [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. + + + +{{< tabs-wrapper >}} +{{% tabs %}} +[Go](#) +[Node.js](#) +[Python](#) +{{% /tabs %}} +{{% tab-content %}} + + +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 + ``` + + + +{{% /tab-content %}} +{{% tab-content %}} + + +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`: + + + + ```sh + npm init + ``` + + +{{% /tab-content %}} +{{% tab-content %}} + + +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 + ``` + + +{{% /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 %}} + +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 %}} + +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 %}} + +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 + + com.influxdb + influxdb3-java + 1.1.0 + +``` + +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 %}} + +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 %}} + +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 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 %}}. -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` +Use client library write methods to 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, the `Point` 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 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) - **timestamp**: Unix timestamp in _second_ precision - - -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/): - - - -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 - ``` - - - -{{% /tab-content %}} {{% tab-content %}} - - - -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`: - - - - ```sh - npm init - ``` - -1. Install the `@influxdata/influxdb3-client` InfluxDB 3 JavaScript client - library. - - ```sh - npm install @influxdata/influxdb3-client - ``` - - - -{{% /tab-content %}} {{% tab-content %}} - - - -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 - ``` - - - -{{% /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](#)