InfluxDB 3 Java Client

The Java client that provides an easy and convenient way to interact with InfluxDB 3. This package supports both writing data to InfluxDB and querying data using the FlightSQL client, which allows you to execute SQL queries against InfluxDB IOx.

We offer this Getting Started: InfluxDB 3.0 Java Client Library video for learning more about the library.

⚠️ This client requires Java 11 and is compatible up to and including Java 25.

Installation

⚠️ Some JDK internals must be exposed by adding --add-opens=java.base/java.nio=ALL-UNNAMED to your JVM arguments.

If you are using JDK 25 or later, you also need to add --sun-misc-unsafe-memory-access=allow.

Add the latest version of the client to your project:

Maven dependency

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

Or when using Gradle

dependencies {
    implementation "com.influxdb:influxdb3-java:1.9.0"
}

Usage

Create client

To start with the client, import the com.influxdb.v3.client package and create a InfluxDBClient by:

package com.influxdb.v3;

import java.time.Instant;
import java.util.List;
import java.util.stream.Stream;

import com.influxdb.v3.client.InfluxDBClient;
import com.influxdb.v3.client.InfluxDBPartialWriteException;
import com.influxdb.v3.client.query.QueryOptions;
import com.influxdb.v3.client.Point;
import com.influxdb.v3.client.write.WriteOptions;

public class IOxExample {
    public static void main(String[] args) throws Exception {
        String host = "https://us-east-1-1.aws.cloud2.influxdata.com";
        char[] token = "my-token".toCharArray();
        String database = "database";

        try (InfluxDBClient client = InfluxDBClient.getInstance(host, token, database)) {
            // ...
        }
    }
}

Write

To insert data, you can use code like this:

//
// Write by Point
//
Point point = Point.measurement("temperature")
        .setTag("location", "west")
        .setField("value", 55.15)
        .setTimestamp(Instant.now().minusSeconds(-10));
client.writePoint(point);

WriteOptions orderedTagWrite = new WriteOptions.Builder()
        .tagOrder(List.of("region", "host"))
        .build();
client.writePoint(
        Point.measurement("temperature")
                .setTag("host", "server-1")
                .setTag("region", "eu-west")
                .setField("value", 60.25),
        orderedTagWrite
);

//
// Write with partial acceptance (default behavior)
//
WriteOptions partialWrite = new WriteOptions.Builder().build();
try {
    client.writeRecords(List.of(
            "temperature,region=west value=20.0",
            "temperature,region=west value=\"bad\""
    ), partialWrite);
} catch (InfluxDBPartialWriteException e) {
    // Inspect failed line details.
    e.lineErrors().forEach(line ->
            System.out.printf("line=%s msg=%s lp=%s%n", line.lineNumber(), line.errorMessage(), line.originalLine()));
}

//
// Write via v2 compatibility endpoint (InfluxDB Clustered)
//
WriteOptions useV2 = new WriteOptions.Builder()
        .useV2Api(true)
        .build();
client.writeRecord("temperature,location=north value=60.0", useV2);

//
// Write by LineProtocol
//
String record = "temperature,location=north value=60.0";
client.writeRecord(record);

Accept partial writes and inspect failed lines

Partial writes are enabled by default. acceptPartial can be configured in three ways: client defaults via WriteOptions, connection string / environment variable / system property (writeAcceptPartial / INFLUX_WRITE_ACCEPT_PARTIAL / influx.writeAcceptPartial), or per-write WriteOptions.

Set acceptPartial(false) to disable partial writes. With InfluxDB Core/Enterprise, when a write request fails due to one or more invalid lines, the error message starts with:

• partial write of line protocol occurred when partial writes are enabled.
• parsing failed for write_lp endpoint when partial writes are disabled.

When partial writes are disabled, any rejected line causes all lines to be rejected. InfluxDB Clustered does not return this structured partial-write error format.

Compatibility with InfluxDB Clustered

For InfluxDB Clustered, enable useV2Api for writes. Like other write options, this can be configured in client code, connection string / environment variable / system property (writeUseV2Api / INFLUX_WRITE_USE_V2_API / influx.writeUseV2Api), or per-write WriteOptions.

If useV2Api is set, acceptPartial is ignored because this compatibility mode does not support partial-write controls. Any rejected line causes all lines to be rejected.

Query

To query your data, you can use code like this:

//
// Query by SQL
//
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]));
}

System.out.printf("--------------------------------------------------------%n%n");

//
// Query by parametrized SQL
//
System.out.printf("--------------------Parametrized SQL--------------------%n");
System.out.printf("| %-8s | %-8s | %-30s |%n", "location", "value", "time");
System.out.printf("--------------------------------------------------------%n");

String sqlParams = "select time,location,value from temperature where location=$location order by time desc limit 10";
try (Stream<Object[]> stream = client.query(sqlParams, Map.of("location", "north"))) {
    stream.forEach(row -> System.out.printf("| %-8s | %-8s | %-30s |%n", row[1], row[2], row[0]));
}

System.out.printf("--------------------------------------------------------%n%n");

//
// Query by InfluxQL
//
System.out.printf("-----------------------------------------%n");
System.out.printf("| %-16s | %-18s |%n", "time", "mean");
System.out.printf("-----------------------------------------%n");

String influxQL = "select MEAN(value) from temperature group by time(1d) fill(none) order by time desc limit 10";
try (Stream<Object[]> stream = client.query(influxQL, QueryOptions.INFLUX_QL)) {
    stream.forEach(row -> System.out.printf("| %-16s | %-18s |%n", row[1], row[2]));
}

System.out.printf("-----------------------------------------%n");

or use PointValues structure with client.queryPoints:

System.out.printf("--------------------------------------------------------%n");
System.out.printf("| %-8s | %-8s | %-30s |%n", "location", "value", "time");
System.out.printf("--------------------------------------------------------%n");

//
// Query by SQL into Points
//
String sql1 = "select time,location,value from temperature order by time desc limit 10";
try (Stream<PointValues> stream = client.queryPoints(sql1, QueryOptions.DEFAULTS)) {
    stream.forEach(
        (PointValues p) -> {
            var time = p.getTimestamp();
            var location = p.getTag("location");
            var value = p.getField("value", Double.class);

            System.out.printf("| %-8s | %-8s | %-30s |%n", location, value, time);
    });
}

System.out.printf("--------------------------------------------------------%n%n");

gRPC Compression

The Java client supports gRPC response compression.

If the server chooses to compress query responses (e.g., with gzip), the client will automatically decompress them — no extra configuration is required.

Feedback

If you need help, please use our Community Slack or Community Page.

New features and bugs can be reported on GitHub: https://github.com/InfluxCommunity/influxdb3-java

Contribution

If you would like to contribute code you can do through GitHub by forking the repository and sending a pull request into the main branch.

License

The InfluxDB 3 Java Client is released under the MIT License.