https://github.com/influxcommunity/influxdb3-java
The Java Client that provides a simple and convenient way to interact with InfluxDB 3.
https://github.com/influxcommunity/influxdb3-java
Last synced: 17 days ago
JSON representation
The Java Client that provides a simple and convenient way to interact with InfluxDB 3.
- Host: GitHub
- URL: https://github.com/influxcommunity/influxdb3-java
- Owner: InfluxCommunity
- License: mit
- Created: 2023-05-18T08:22:03.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2026-06-02T15:30:31.000Z (25 days ago)
- Last Synced: 2026-06-02T17:12:50.781Z (25 days ago)
- Language: Java
- Homepage: https://InfluxCommunity.github.io/influxdb3-java/apidocs/com/influxdb/v3/client/package-summary.html
- Size: 4.95 MB
- Stars: 39
- Watchers: 5
- Forks: 9
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# 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](https://www.youtube.com/watch?v=EFnG7rUDvR4) video for learning more about the library.
> :warning: This client requires Java 11 and is compatible up to and including Java 25.
## Installation
> :warning: 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
```xml
com.influxdb
influxdb3-java
1.10.0
```
### Or when using Gradle
```groovy
dependencies {
implementation "com.influxdb:influxdb3-java:1.10.0"
}
```
## Usage
### Create client
To start with the client, import the `com.influxdb.v3.client` package and create a `InfluxDBClient` by:
```java
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:
```java
//
// 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 API endpoint (InfluxDB Clustered and InfluxDB Cloud Dedicated/Serverless)
//
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 when writing through the V3 API endpoint (`useV2Api=false`).
`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 and InfluxDB Cloud Dedicated/Serverless
Writes use the V2 API endpoint by default.
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`.
`noSync` requires the V3 API endpoint, which is available with InfluxDB 3 Core/Enterprise. `acceptPartial` applies only when writes are sent to the V3 API endpoint and is ignored when using the V2 API endpoint. To use `noSync`, set `useV2Api=false`.
Note: when writes use the V2 API endpoint, `noSync=true` returns a validation error (`invalid write options: noSync requires useV2Api=false`).
### Query
To query your data, you can use code like this:
```java
//
// 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 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 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 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`:
```java
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 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](https://app.slack.com/huddle/TH8RGQX5Z/C02UDUPLQKA)
or [Community Page](https://community.influxdata.com/).
New features and bugs can be reported on GitHub:
## 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](https://opensource.org/licenses/MIT).