fix(influxdb3): Client library write guide: Refactor, reorganize, and cleanup
Jason Stirnaman
parent
6041afb396
commit
57d73b141e
|
|
@ -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.
|
||||
|
||||
<!-- 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
|
||||
|
||||
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
|
||||
|
||||
<!-- 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 %}}
|
||||
[Go](#)
|
||||
|
|
|
|||
Loading…
Reference in New Issue