Java SDK
更新时间:2026-07-24
本文介绍如何使用 Java SDK 连接 TSDB 专享版,并完成数据写入和查询。
环境准备
使用 SDK 前,请安装 JDK 11 或更高版本,准备一个 Maven 或 Gradle 项目,并完成 SDK 使用说明中的连接准备工作。
安装 SDK
本文示例使用 influxdb3-java 1.10.0。
Maven:
XML
1<dependency>
2 <groupId>com.influxdb</groupId>
3 <artifactId>influxdb3-java</artifactId>
4 <version>1.10.0</version>
5</dependency>
Gradle:
Groovy
1implementation 'com.influxdb:influxdb3-java:1.10.0'
配置连接信息
示例通过以下环境变量读取连接信息:
| 环境变量 | 说明 |
|---|---|
TSDB_HOST_URL |
由集群详情页显示的访问地址和端口组成的完整 URL,例如 http://<访问地址>:<端口> |
TSDB_DATABASE_NAME |
目标 Database 名称 |
TSDB_AUTH_TOKEN |
具有目标 Database 读写权限的业务访问令牌 |
写入和查询数据
以下示例初始化客户端,写入一条 Line Protocol 数据,然后使用 SQL 查询刚写入的数据:
Java
1import com.influxdb.v3.client.InfluxDBClient;
2import com.influxdb.v3.client.config.ClientConfig;
3
4import java.util.Map;
5import java.util.stream.Stream;
6
7public final class TsdbExample {
8 private TsdbExample() {
9 }
10
11 public static void main(String[] args) throws Exception {
12 ClientConfig config = new ClientConfig.Builder()
13 .host(System.getenv("TSDB_HOST_URL"))
14 .token(System.getenv("TSDB_AUTH_TOKEN").toCharArray())
15 .authScheme("Bearer")
16 .database(System.getenv("TSDB_DATABASE_NAME"))
17 .writeUseV2Api(false)
18 .build();
19
20 try (InfluxDBClient client = InfluxDBClient.getInstance(config)) {
21 client.writeRecord("cpu,host=server01 usage=42.5");
22
23 // 首次写入创建 Table 后,等待新表可查询。
24 Thread.sleep(5_000);
25
26 String sql = "SELECT time, host, usage FROM cpu "
27 + "WHERE host = 'server01' ORDER BY time DESC LIMIT 1";
28 try (Stream<Map<String, Object>> rows = client.queryRows(sql)) {
29 rows.forEach(System.out::println);
30 }
31 }
32 }
33}
配置说明
writeUseV2Api(false)用于启用 V3 写入接口,复制示例时请保留该配置。- 写入和查询使用同一个
TSDB_HOST_URL,无需手动拼接 API 路径。 - 示例首次写入
cpu时会自动创建 Table,因此在写入后等待 5 秒。新表通常在约 5 秒后可以查询,实际时间可能受集群运行状态影响。该等待只适用于首次建表;向已有 Table 写入不受影响。 try-with-resources会在操作完成后关闭客户端,并释放 HTTP 和 Flight 连接。- SDK 只用于数据写入和查询。管理 Database、Table、Retention 或业务访问令牌时,请使用 CLI 工具或资源管理 API。
评价此篇文章
