Java client library for InfluxDB 3

The InfluxDB 3 influxdb3-java Java client library integrates with Java application code to write and query data stored in InfluxDB Cloud Serverless.

InfluxDB client libraries provide configurable batch writing of data to InfluxDB Cloud Serverless. Use client libraries to construct line protocol data, transform data from other formats to line protocol, and batch write line protocol data to InfluxDB HTTP APIs.

InfluxDB 3 client libraries can query InfluxDB Cloud Serverless using SQL or InfluxQL. The influxdb3-java Java client library wraps the Apache Arrow org.apache.arrow.flight.FlightClient in a convenient InfluxDB 3 interface for executing SQL and InfluxQL queries, requesting server metadata, and retrieving data from InfluxDB Cloud Serverless using the Flight protocol with gRPC.

Installation
- Using Maven
- Using Gradle
Importing the client
API reference
Classes
InfluxDBClient interface

Example: write and query data

The following example shows how to use influxdb3-java to write and query data stored in InfluxDB Cloud Serverless.

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://cloud2.influxdata.com"; // your Cloud Serverless region URL
  private static final String DATABASE = "DATABASE_NAME"; // your InfluxDB bucket
  private static final char[] TOKEN = System.getenv("API_TOKEN"); // a 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, TOKEN, DATABASE)) {
      writeData(client);
      queryData(client);
    }
    catch (Exception e) {
      System.err.println("An error occurred while connecting to InfluxDB!");
      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();
    }
  }
}

  
   Copy
 Fill window

Source: suyashcjoshi/SimpleJavaInfluxDB on GitHub

Replace the following:

DATABASE_NAME: the name of your InfluxDB Cloud Serverless bucket to read and write data to
API_TOKEN: a local environment variable that stores your token–the token must have read and write permissions on the specified bucket.

Run the example to write and query data

Build an executable JAR for the project–for example, using Maven:
```
mvn package
```
- Copy
- Fill window
In your terminal, run the java command to write and query data in your bucket:
```
java \
--add-opens=java.base/java.nio=org.apache.arrow.memory.core,ALL-UNNAMED \
-jar target/PROJECT_NAME.jar
```
- Copy
- Fill window
Include the following in your command:
- --add-opens=java.base/java.nio=org.apache.arrow.memory.core,ALL-UNNAMED: 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.
- -jar target/PROJECT_NAME.jar: your .jar file to run.

The output is the newly written data from your InfluxDB Cloud Serverless bucket.

Installation

Include com.influxdb.influxdb3-java in your project dependencies.

Maven pom.xml Gradle dependency script

<dependency>
  <groupId>com.influxdb</groupId>
  <artifactId>influxdb3-java</artifactId>
  <version>RELEASE</version>
</dependency>

  
   Copy
 Fill window

dependencies {

   implementation group: 'com.influxdb', name: 'influxdb3-java', version: 'latest.release'

}

   Copy
 Fill window

Importing the client

The influxdb3-java client library package provides com.influxdb.v3.client classes for constructing, writing, and querying data stored in InfluxDB Cloud Serverless.

API reference

Interface InfluxDBClient

InfluxDBClient 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 bucket.
An Arrow Flight client configured for querying the bucket.

To initialize a client, call getInstance and pass your credentials as one of the following types:

parameters
a ClientConfig
a database connection string

Initialize with credential parameters

static InfluxDBClient getInstance(@Nonnull final String host,
                           @Nullable final char[] token,
                           @Nullable final String database)

  
   Copy
 Fill window

host (string): The host URL of the InfluxDB instance.
database (string): The bucket to use for writing and querying.
token (char array): A token with read/write permissions.

Example: initialize with credential parameters

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://cloud2.influxdata.com";
  private static final String DATABASE = "DATABASE_NAME";
  private static final char[] API_TOKEN = System.getenv("API_TOKEN");

  // Create a client instance, and then write and query data in InfluxDB.
  public static void main(String[] args) {
    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 with the serverless InfluxDB!");
      e.printStackTrace();
    }
  }
}

  
   Copy
 Fill window

Replace the following:

DATABASE_NAME: your InfluxDB Cloud Serverless bucket
API_TOKEN: a local environment variable that stores your token–the token must have the necessary permissions on the specified bucket.

Default tags

To include default tags in all written data, pass a Map of tag keys and values.

InfluxDBClient getInstance(@Nonnull final String host,
                                      @Nullable final char[] token,
                                      @Nullable final String database,
                                      @Nullable Map<String, String> defaultTags)

  
   Copy
 Fill window

Initialize using a database connection string

"https://cloud2.influxdata.com"
+ "?token=API_TOKEN&amp;database=DATABASE_NAME"

  
   Copy
 Fill window

Replace the following:

DATABASE_NAME: your InfluxDB Cloud Serverless bucket
API_TOKEN: a token that has the necessary permissions on the specified bucket.

InfluxDBClient instance methods

InfluxDBClient.writePoint

To write points as line protocol to a bucket:

Initialize the client–your token must have write permission on the specified bucket.
Use the com.influxdb.v3.client.Point class to create time series data.
Call the client.writePoint() method to write points as line protocol in your bucket.

  // Use the Point class to construct time series data.
  // Call client.writePoint to write the point in your bucket.
  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 written to the bucket.");
    }
    catch (Exception e) {
      System.err.println("Failed to write data to the bucket.");
      e.printStackTrace();
    }
  }

  
   Copy
 Fill window

InfluxDBClient.query

To query data and process the results:

Initialize the client–your token must have read permission on the bucket you want to query.
Call client.query() and provide your SQL query as a string.
Use the result stream’s built-in iterator to process row data.

  // Query the latest 10 measurements using SQL
  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();
    }
  }

  
   Copy
 Fill window

View the InfluxDB 3 Java client library

Was this page helpful?

Thank you for your feedback!

Support and feedback

Thank you for being part of our community! We welcome and encourage your feedback and bug reports for InfluxDB Cloud Serverless and this documentation. To find support, use the following resources:

Customers with an annual or support contract can contact InfluxData Support.

Edit this page Submit docs issue Submit InfluxDB Cloud Serverless issue

Java client library for InfluxDB 3

Example: write and query data

Run the example to write and query data

Installation

Importing the client

API reference

InfluxDBClient interface

Initialize with credential parameters

Example: initialize with credential parameters

Default tags

Initialize using a database connection string

InfluxDBClient instance methods

InfluxDBClient.writePoint

InfluxDBClient.query

Support and feedback

The future of Flux

InfluxDB 3 Core and Enterprise are now in Beta

Java client library for InfluxDB 3

Select your InfluxDB Cloud Serverless region

AWS

Thank you for your feedback!

The future of Flux

InfluxDB 3 Core and Enterprise are now in Beta

InfluxDB Cloud Serverless