Documentation

InfluxDB Clustered

Java client library for InfluxDB v3

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

InfluxDB client libraries provide configurable batch writing of data to InfluxDB Clustered. 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 v3 client libraries can query InfluxDB Clustered 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 InfluxDB Clustered using the Flight protocol with gRPC.

Example: write and query data

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

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://cluster-host.com"; // your cluster URL
  private static final String DATABASE = "DATABASE_NAME"; // your InfluxDB database name 
  private static final char[] TOKEN = System.getenv("DATABASE_TOKEN"); // a local environment variable that stores your database token

  // Create a client instance that writes and queries data in your database.
  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 database.");
    }
    catch (Exception e) {
      System.err.println("Failed to write data to the database.");
      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 database.");
      e.printStackTrace();
    }
  }
}

Source: suyashcjoshi/SimpleJavaInfluxDB on GitHub

Replace the following:

  • DATABASE_NAME: the name of your InfluxDB Clustered database to read and write data to
  • DATABASE_TOKEN: a local environment variable that stores your token–the token must have read and write permissions on the specified database.

Run the example to write and query data

  1. Build an executable JAR for the project–for example, using Maven:

    mvn package

  2. In your terminal, run the java command to write and query data in your database:

    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:

The output is the newly written data from your InfluxDB Clustered database.

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>

dependencies {

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

}

Importing the client

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

API reference

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 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:

Initialize with credential parameters

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 database to use for writing and querying.
  • token (char array): A database 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://cluster-host.com";
  private static final String DATABASE = "DATABASE_NAME";
  private static final char[] TOKEN = System.getenv("DATABASE_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, DATABASE_TOKEN, DATABASE)) {
      writeData(client);
      queryData(client);
    }
    catch (Exception e) {
      System.err.println("An error occurred while connecting to InfluxDB!");
      e.printStackTrace();
    }
  }
}

Replace the following:

  • DATABASE_NAME: your InfluxDB Clustered database
  • DATABASE_TOKEN: a database token that has the necessary permissions on the specified database.

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)

Initialize using a database connection string

"https://cluster-host.com"
+ "?token=DATABASE_TOKEN&amp;database=DATABASE_NAME"

Replace the following:

  • DATABASE_NAME: your InfluxDB Clustered database
  • DATABASE_TOKEN: a database token that has the necessary permissions on the specified database.

InfluxDBClient instance methods

InfluxDBClient.writePoint

To write points as line protocol to a database:

  1. Initialize the client–your token must have write permission on the specified database.
  2. Use the com.influxdb.v3.client.Point class to create time series data.
  3. Call the client.writePoint() method to write points as line protocol in your database.
  // Use the Point class to construct time series data.
  // Call client.writePoint to write the point in your database.
  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 database.");
    }
    catch (Exception e) {
      System.err.println("Failed to write data to the database.");
      e.printStackTrace();
    }
  }

InfluxDBClient.query

To query data and process the results:

  1. Initialize the client–the token must have read permission on the database you want to query.
  2. Call client.query() and provide your SQL query as a string.
  3. 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 database.");
      e.printStackTrace();
    }
  }

View the InfluxDB v3 Java client library

Flight client Java gRPC SQL Flight SQL client libraries

Was this page helpful?

Thank you for your feedback!

© 2024 InfluxData, Inc.

What is your InfluxDB cluster URL?

Enter your InfluxDB cluster URL and we’ll update code examples for you.

Enter cluster URL

Thank you for your feedback!

Let us know what we can do better:

Thank you!

No thanks

The future of Flux

Flux is going into maintenance mode. You can continue using it as you currently are without any changes to your code.

Read more

InfluxDB v3 enhancements and InfluxDB Clustered is now generally available

New capabilities, including faster query performance and management tooling advance the InfluxDB v3 product line. InfluxDB Clustered is now generally available.

InfluxDB v3 performance and features

The InfluxDB v3 product line has seen significant enhancements in query performance and has made new management tooling available. These enhancements include an operational dashboard to monitor the health of your InfluxDB cluster, single sign-on (SSO) support in InfluxDB Cloud Dedicated, and new management APIs for tokens and databases.

Learn about the new v3 enhancements

InfluxDB Clustered general availability

InfluxDB Clustered is now generally available and gives you the power of InfluxDB v3 in your self-managed stack.

Talk to us about InfluxDB Clustered