chore(v3): Add Java client library interface and API

- Fix Python client library reference. - Removed `list_code_example` from both due to render problems.
2024-07-24 18:30:10 -05:00 · 2024-07-24 18:30:10 -05:00 · 421f48416f
parent dacf289531
commit 421f48416f
2 changed files with 253 additions and 76 deletions
--- a/content/influxdb/cloud-serverless/reference/client-libraries/v3/java.md
+++ b/content/influxdb/cloud-serverless/reference/client-libraries/v3/java.md
@ -3,7 +3,6 @@ title: Java client library for InfluxDB v3
 list_title: Java
 description: >
  The InfluxDB v3 `influxdb3-java` Java client library integrates with application code to write and query data stored in an InfluxDB Cloud Serverless bucket.
-external_url: https://github.com/InfluxCommunity/influxdb3-java
 menu:
  influxdb_cloud_serverless:
    name: Java
@ -15,22 +14,144 @@ aliases:
  - /cloud-serverless/query-data/sql/execute-queries/java/
 ---

-The InfluxDB v3 [`influxdb3-java` Java client library](https://github.com/InfluxCommunity/influxdb3-java) integrates with Java application code
-to write and query data stored in an {{% product-name %}} bucket.
+The InfluxDB v3 [`influxdb3-java` Java client library](https://github.com/InfluxCommunity/influxdb3-java) integrates
+with Java application code to write and query data stored in an {{% product-name %}}
+bucket.

-The documentation for this client library is available on GitHub.
+InfluxDB client libraries provide configurable batch writing of data to {{% product-name %}}.
+Client libraries can be used to construct line protocol data, transform data from other formats
+to line protocol, and batch write line protocol data to InfluxDB HTTP APIs.

-<a href="https://github.com/InfluxCommunity/influxdb3-java" target="_blank" class="btn github">InfluxDB v3 Java client library</a>
+InfluxDB v3 client libraries can query {{% product-name %}} using SQL or InfluxQL.
+The `influxdb3-java` Java client library wraps the Apache Arrow `org.apache.arrow.flight.FlightClient`
+in a convenient InfluxDB v3 interface for executing SQL and InfluxQL queries, requesting
+server metadata, and retrieving data from {{% product-name %}} using the Flight protocol with gRPC.

-## Setup & Installation
-
-Create a command line java application using Maven or Gradle.
-
-### Maven
-
-To use Maven to install the client library in your project, add the following to your `pom.xml`:
+- [Installation](#installation)
+  - [Using Maven](#using-maven)
+  - [Using Gradle](#using-gradle)
+- [Importing the client](#importing-the-client)
+- [API reference](#api-reference)
+- [Classes](#classes)
+- [Interface InfluxDBClient](#interface-influxdbclient)
+  - [Initialize with credential parameters](#initialize-with-credential-parameters)
+  - [InfluxDBClient instance methods](#influxdbclient-instance-methods)
+  - [InfluxDBClient.writePoint](#influxdbclientwritepoint)
+  - [InfluxDBClient.query](#influxdbclientquery)


+#### Example: write and query data
+
+The following example shows how to use `influxdb3-java` to write and query data stored in {{% product-name %}}.
+
+```java
+package com.influxdata.demo;
+
+import com.influxdb.v3.client.InfluxDBClient;
+import com.influxdb.v3.client.Point;
+import com.influxdb.v3.client.query.QueryOptions;
+import com.influxdb.v3.client.query.QueryType;
+
+import java.time.Instant;
+import java.util.stream.Stream;
+
+public class HelloInfluxDB {
+  private static final String HOST_URL = "https://{{< influxdb/host >}}"; // your Cloud Serverless region URL
+  private static final String DATABASE = "java"; // your Cloud Serverless bucket
+  private static final char[] API_TOKEN = System.getenv("API_TOKEN"); // your local environment variable that stores your API Token
+
+  // Create a client instance that writes and queries data in your bucket.
+  public static void main(String[] args) {
+    // Instantiate the client with your InfluxDB credentials
+    try (InfluxDBClient client = InfluxDBClient.getInstance(HOST_URL, API_TOKEN, DATABASE)) {
+      writeData(client);
+      queryData(client);
+    }
+    catch (Exception e) {
+      System.err.println("An error occurred while connecting to InfluxDB Cloud Serverless!");
+      e.printStackTrace();
+    }
+  }
+
+  // Use the Point class to construct time series data.
+  private static void writeData(InfluxDBClient client) {
+    Point point = Point.measurement("temperature")
+                       .setTag("location", "London")
+                       .setField("value", 30.01)
+                       .setTimestamp(Instant.now().minusSeconds(10));
+    try {
+      client.writePoint(point);
+      System.out.println("Data is written to the bucket.");
+    }
+    catch (Exception e) {
+      System.err.println("Failed to write data to the bucket.");
+      e.printStackTrace();
+    }
+  }
+
+  // Use SQL to query the most recent 10 measurements
+  private static void queryData(InfluxDBClient client) {
+    System.out.printf("--------------------------------------------------------%n");
+    System.out.printf("| %-8s | %-8s | %-30s |%n", "location", "value", "time");
+    System.out.printf("--------------------------------------------------------%n");
+
+    String sql = "select time,location,value from temperature order by time desc limit 10";
+    try (Stream<Object[]> stream = client.query(sql)) {
+      stream.forEach(row -> System.out.printf("| %-8s | %-8s | %-30s |%n", row[1], row[2], row[0]));
+    }
+    catch (Exception e) {
+      System.err.println("Failed to query data from the bucket.");
+      e.printStackTrace();
+    }
+  }
+}
+```
+
+{{% cite %}}Source: [suyashcjoshi/SimpleJavaInfluxDB](https://github.com/suyashcjoshi/SimpleJavaInfluxDB/) on GitHub{{% /cite %}}
+
+Replace the following:
+
+- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: your {{% product-name %}} [bucket](/influxdb/cloud-serverless/admin/buckets/)
+- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: a local environment variable that stores your [token](/influxdb/cloud-serverless/admin/tokens/)--the token must have read and write permission to the specified bucket.
+
+### Run the example to write and query data
+
+1. Build an executable JAR for the project--for example, using Maven:
+   
+   <!--pytest.mark.skip-->
+
+   ```bash
+   mvn package
+   ```
+   
+2. In your terminal, run the `java` command to write and query data in your bucket:
+
+   <!--pytest.mark.skip-->
+
+   ```bash
+   java \
+   --add-opens=java.base/java.nio=org.apache.arrow.memory.core,ALL-UNNAMED \
+   -jar target/PROJECT_NAME.jar
+   ```
+
+   Include the following in your command:
+
+   - [`--add-opens=java.base/java.nio=org.apache.arrow.memory.core,ALL-UNNAMED`](https://arrow.apache.org/docs/java/install.html#id3): with Java version 9 or later and Apache Arrow version 16 or later, exposes JDK internals for Arrow.
+   For more options, see the [Apache Arrow Java install documentation](https://arrow.apache.org/docs/java/install.html).
+   - `-jar target/PROJECT_NAME.jar`: your `.jar` file to run.
+
+The output is the newly written data from your {{< product-name >}} bucket.
+
+## Installation
+
+Include `com.influxdb.influxdb3-java` in your project dependencies.
+
+{{< code-tabs-wrapper >}}
+{{% code-tabs %}}
+[Maven pom.xml](#)
+[Gradle dependency script](#)
+{{% /code-tabs %}}
+{{% code-tab-content %}}
 ```xml
 <dependency>
  <groupId>com.influxdb</groupId>
@ -38,28 +159,84 @@ To use Maven to install the client library in your project, add the following to
  <version>RELEASE</version>
 </dependency>
 ```
-
-### Gradle
-
-To use Gradle to install the client library in your project, add the following to your `build.gradle` dependencies:
-
+{{% /code-tab-content %}}
+{{% code-tab-content %}}
+<!--pytest.mark.skip-->
 ```groovy
-implementation group: 'com.influxdb', name: 'influxdb3-java', version: 'latest.release'
+dependencies {
+
+   implementation group: 'com.influxdb', name: 'influxdb3-java', version: 'latest.release'
+
+}
 ```
+{{% /code-tab-content %}}
+{{< /code-tabs-wrapper >}}

-## Example: write and query data
+## Importing the client

-The following example, also available on [GitHub](https://github.com/suyashcjoshi/SimpleJavaInfluxDB/tree/main) shows how to use `influxdb3-java` to write and query data stored in {{% product-name %}}:
+The `influxdb3-java` client library package provides
+`com.influxdb.v3.client` classes for constructing, writing, and querying data
+stored in {{< product-name >}}.

-### Initialize the application
+## API reference

-Create a `HelloInfluxDB.java` class with the following information:
+- [Interface InfluxDBClient](#interface-influxdbclient)
+  - [Initialize with credential parameters](#initialize-with-credential-parameters)
+  - [InfluxDBClient instance methods](#influxdbclient-instance-methods)
+  - [InfluxDBClient.writePoint](#influxdbclientwritepoint)
+  - [InfluxDBClient.query](#influxdbclientquery)
+
+
+## Interface InfluxDBClient
+
+Provides an interface for interacting with InfluxDB APIs for writing and querying data.
+
+The `InfluxDBClient.getInstance` constructor initializes and returns a client instance with the following:
+
+- A _write client_ configured for writing to the database.
+- An Arrow _Flight client_ configured for querying the database.
+
+To initialize a client, call `getInstance` and pass your credentials as one of
+the following types:
+
+- [parameters](#initialize-with-credential-parameters)
+- a [`ClientConfig`](https://github.com/InfluxCommunity/influxdb3-java/blob/main/src/main/java/com/influxdb/v3/client/config/ClientConfig.java)
+- a database connection string--for example:
+  
+  ```java
+  "https://{{< influxdb/host >}}"
+  + "?token=API_TOKEN&amp;database=DATABASE_NAME"
+  ```
+
+### Initialize with credential parameters

 ```java
+static InfluxDBClient getInstance(@Nonnull final String host,
+                           @Nullable final char[] token,
+                           @Nullable final String database)
+```
+
+- **`host`** (string): The host URL of the InfluxDB instance.
+- **`database`** (string): The bucket to use for writing and querying.
+- **`token`** (string): An API token with read/write permissions.
+
+#### Example: initialize with credential parameters
+
+```java
+package com.influxdata.demo;
+
+import com.influxdb.v3.client.InfluxDBClient;
+import com.influxdb.v3.client.Point;
+import com.influxdb.v3.client.query.QueryOptions;
+import com.influxdb.v3.client.query.QueryType;
+
+import java.time.Instant;
+import java.util.stream.Stream;
+
 public class HelloInfluxDB {
  private static final String HOST_URL = "https://{{< influxdb/host >}}";
-  private static final String DATABASE = "java"; // your bucket in InfluxDB Cloud Serverless
-  private static final char[] API_TOKEN = System.getenv("API_TOKEN"); // your API Token found in InfluxDB Cloud Serverless stored locally
+  private static final String DATABASE = "DATABASE_NAME"; // your Cloud Serverless bucket
+  private static final char[] API_TOKEN = System.getenv("API_TOKEN"); // an environment variable for your Cloud Serverless API Token
  // Create a client instance, and then write and query data in InfluxDB Cloud Serverless.
  public static void main(String[] args) {
    try (InfluxDBClient client = InfluxDBClient.getInstance(HOST_URL, API_TOKEN, DATABASE)) {
@ -73,11 +250,30 @@ public class HelloInfluxDB {
  }
 ```

-### Write the data
+#### Default tags
+
+- _Optional_: To include default
+  [tags](/influxdb/cloud-serverless/reference/glossary/#tag) in all written data,
+  pass a `Map` of tag keys and values.
+
+  ```java
+  InfluxDBClient getInstance(@Nonnull final String host,
+                                        @Nullable final char[] token,
+                                        @Nullable final String database,
+                                        @Nullable Map<String, String> defaultTags)
+  ```
+
+### InfluxDBClient instance methods
+
+#### InfluxDBClient.writePoint
+
+1. Use the `com.influxdb.v3.client.Point` class to create time series data.
+2. Call the `client.writePoint()` method to write points as line protocol in your
+   bucket.

 ```java
  // Use the Point class to construct time series data.
-  // Call client.writePoint to write the point as line protocol to your bucket.
+  // Call client.writePoint to write the point in your bucket.
  private static void writeData(InfluxDBClient client) {
    Point point = Point.measurement("temperature")
                       .setTag("location", "London")
@ -94,7 +290,12 @@ public class HelloInfluxDB {
  }
 ```

-### Query the data
+#### InfluxDBClient.query
+
+To query data and process the results:
+
+1. Call `client.query()` and provide your SQL query as a string.
+2. Use the result stream's built-in iterator to process row data. 

 ```java
  // Query the latest 10 measurements using SQL
@ -115,10 +316,4 @@ public class HelloInfluxDB {
 }
 ```

-## Run the program to write and query data
-
-Build the project and then run the executable .jar file with this [JVM Flag](https://arrow.apache.org/docs/java/install.html). 
-```sh
-  java --add-opens=java.base/java.nio=org.apache.arrow.memory.core,ALL-UNNAMED -jar target/PROJECT_NAME.jar
-```
-You should be able to also confirm the newly written data in your InfluxDB Cloud Serverless.
+<a class="btn" href="https://github.com/InfluxCommunity/influxdb3-java/" target="\_blank">View the InfluxDB v3 Java client library</a>
--- a/content/influxdb/cloud-serverless/reference/client-libraries/v3/python.md
+++ b/content/influxdb/cloud-serverless/reference/client-libraries/v3/python.md
@ -15,45 +15,9 @@ aliases:
  - /influxdb/cloud-serverless/reference/client-libraries/v3/pyinflux3/
 related:
  - /influxdb/cloud-serverless/query-data/execute-queries/troubleshoot/
-list_code_example: >
-  <!-- Import for tests and hide from users.
-  ```python
-  import os
-  ```
-  -->
-  <!--pytest-codeblocks:cont-->
-  ```python
-  from influxdb_client_3 import(InfluxDBClient3,
-                                WriteOptions,
-                                write_client_options)
-
-  # Instantiate batch writing options for the client
-
-  write_options = WriteOptions()
-  wco = write_client_options(write_options=write_options)
-
-  # Instantiate an InfluxDB v3 client
-
-  with InfluxDBClient3(host=f"{{< influxdb/host >}}",
-                        database=f"BUCKET_NAME",
-                        token=f"API_TOKEN",
-                        write_client_options=wco) as client:
-
-    # Write data in batches
-    client.write_file(file='./data/home-sensor-data.csv', timestamp_column='time',
-                      tag_columns=["room"])
-
-    # Execute a query and retrieve data formatted as a PyArrow Table
-
-    table = client.query(
-      '''SELECT *
-         FROM home
-         WHERE time >= now() - INTERVAL '90 days'
-         ORDER BY time''')
-    ```
 ---

-The InfluxDB v3 [`influxdb3-python` Python client library](https://github.com/InfluxCommunity/influxdb3-python)
+The InfluxDB v3 [`influxdb3-python` Python client library](https://github.com/InfluxCommunity/influxdb3-python/)
 integrates {{% product-name %}} write and query operations with Python scripts and applications.

 InfluxDB client libraries provide configurable batch writing of data to {{% product-name %}}.
@ -85,8 +49,8 @@ Code samples in this page use the [Get started home sensor sample data](/influxd
 - [Class WriteOptions](#class-writeoptions)
  - [Parameters](#parameters-4)
 - [Functions](#functions)
-  - [Function write_client_options(\*\*kwargs)](#function-write_client_optionskwargs)
-  - [Function flight_client_options(\*\*kwargs)](#function-flight_client_optionskwargs)
+  - [Function write_client_options(**kwargs)](#function-write_client_optionskwargs)
+  - [Function flight_client_options(**kwargs)](#function-flight_client_optionskwargs)
 - [Constants](#constants)
 - [Exceptions](#exceptions)

@ -137,12 +101,17 @@ The `influxdb_client_3` module includes the following classes and functions.
  - [Writing modes](#writing-modes)
  - [InfluxDBClient3 instance methods](#influxdbclient3-instance-methods)
  - [InfluxDBClient3.write](#influxdbclient3write)
-  - [InfluxDBClient3.write_file](#influxdbclient3write_file)
+  - [InfluxDBClient3.write\_file](#influxdbclient3write_file)
  - [InfluxDBClient3.query](#influxdbclient3query)
  - [InfluxDBClient3.close](#influxdbclient3close)
 - [Class Point](#class-point)
 - [Class WriteOptions](#class-writeoptions)
  - [Parameters](#parameters-4)
+- [Functions](#functions)
+  - [Function write\_client\_options(\*\*kwargs)](#function-write_client_optionskwargs)
+  - [Function flight\_client\_options(\*\*kwargs)](#function-flight_client_optionskwargs)
+- [Constants](#constants)
+- [Exceptions](#exceptions)

 ## Class InfluxDBClient3

@ -186,10 +155,10 @@ Given that `write_client_options` isn't specified, the client uses the default [
 ```python
 import os
 ```
-<!--pytest-codeblocks:cont-->
-
 -->

+<!--pytest-codeblocks:cont-->
+
 ```python
 from influxdb_client_3 import InfluxDBClient3

@ -216,6 +185,7 @@ To explicitly specify synchronous mode, create a client with `write_options=SYNC
 import os
 ```
 -->
+
 <!--pytest-codeblocks:cont-->

 ```python
@ -270,6 +240,7 @@ specify callback functions for the response status (success, error, or retryable
 import os
 ```
 -->
+
 <!--pytest-codeblocks:cont-->

 ```python
@ -348,6 +319,7 @@ Writes a record or a list of records to InfluxDB.
 import os
 ```
 -->
+
 <!--pytest-codeblocks:cont-->

 ```python
@ -401,6 +373,7 @@ data to InfluxDB.
 import os
 ```
 -->
+
 <!--pytest-codeblocks:cont-->

 ```python
@ -534,6 +507,7 @@ and how to write data from CSV and JSON files to InfluxDB:
 import os
 ```
 -->
+
 <!--pytest-codeblocks:cont-->

 ```python
@ -636,6 +610,7 @@ Returns all data in the query result as an Arrow table ([`pyarrow.Table`](https:
 import os
 ```
 -->
+
 <!--pytest-codeblocks:cont-->

 ```python
@ -672,6 +647,7 @@ In the examples, replace the following:
 import os
 ```
 -->
+
 <!--pytest-codeblocks:cont-->

 ```python
@ -698,6 +674,7 @@ print(table.select(['room', 'temp']))
 import os
 ```
 -->
+
 <!--pytest-codeblocks:cont-->

 ```python
@ -723,6 +700,7 @@ print(pd.to_markdown())
 import os
 ```
 -->
+
 <!--pytest-codeblocks:cont-->

 ```python
@ -750,6 +728,7 @@ print(table.schema)
 import os
 ```
 -->
+
 <!--pytest-codeblocks:cont-->

 ```python
@ -776,6 +755,7 @@ Pass `timeout=<number of seconds>` for [`FlightCallOptions`](https://arrow.apach
 import os
 ```
 -->
+
 <!--pytest-codeblocks:cont-->

 ```python
@ -980,3 +960,5 @@ Replace the following:
 ## Exceptions

 - `influxdb_client_3.InfluxDBError`: Exception class raised for InfluxDB-related errors
+
+<a class="btn" href="https://github.com/InfluxCommunity/influxdb3-python/" target="\_blank">View the InfluxDB v3 Python client library</a>