diff --git a/content/influxdb/cloud-serverless/reference/client-libraries/v3/java.md b/content/influxdb/cloud-serverless/reference/client-libraries/v3/java.md index 3526a718e..0e1d18412 100644 --- 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. -InfluxDB v3 Java client library +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 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: + + + + ```bash + mvn package + ``` + +2. In your terminal, run the `java` command to write and query data in your bucket: + + + + ```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 com.influxdb @@ -38,28 +159,84 @@ To use Maven to install the client library in your project, add the following to RELEASE ``` - -### 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 %}} + ```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&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 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. +View the InfluxDB v3 Java client library \ No newline at end of file diff --git a/content/influxdb/cloud-serverless/reference/client-libraries/v3/python.md b/content/influxdb/cloud-serverless/reference/client-libraries/v3/python.md index f75a6d175..4e1781478 100644 --- 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: > - - - ```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 ``` - - --> + + ```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 ``` --> + ```python @@ -270,6 +240,7 @@ specify callback functions for the response status (success, error, or retryable import os ``` --> + ```python @@ -348,6 +319,7 @@ Writes a record or a list of records to InfluxDB. import os ``` --> + ```python @@ -401,6 +373,7 @@ data to InfluxDB. import os ``` --> + ```python @@ -534,6 +507,7 @@ and how to write data from CSV and JSON files to InfluxDB: import os ``` --> + ```python @@ -636,6 +610,7 @@ Returns all data in the query result as an Arrow table ([`pyarrow.Table`](https: import os ``` --> + ```python @@ -672,6 +647,7 @@ In the examples, replace the following: import os ``` --> + ```python @@ -698,6 +674,7 @@ print(table.select(['room', 'temp'])) import os ``` --> + ```python @@ -723,6 +700,7 @@ print(pd.to_markdown()) import os ``` --> + ```python @@ -750,6 +728,7 @@ print(table.schema) import os ``` --> + ```python @@ -776,6 +755,7 @@ Pass `timeout=` for [`FlightCallOptions`](https://arrow.apach import os ``` --> + ```python @@ -980,3 +960,5 @@ Replace the following: ## Exceptions - `influxdb_client_3.InfluxDBError`: Exception class raised for InfluxDB-related errors + +View the InfluxDB v3 Python client library