Java
- 写入数据
- 查询数据

Java

GreptimeDB 使用不同的客户端库来写入和查询数据。你根据需求可以选择合适的客户端库。

写入数据

GreptimeDB 提供了一个 ingester 库来帮助你写入数据。它使用 gRPC 协议，支持自动生成表结构，无需在写入数据前创建表。更多信息请参考自动生成表结构。

GreptimeDB 提供的 Java ingester SDK 是一个轻量级库，具有以下特点：

基于 SPI 的可扩展网络传输层，提供了使用 gRPC 框架的默认实现。
非阻塞、纯异步的易于使用的 API。
默认情况下自动收集各种性能指标，然后可以配置并将其写入本地文件。
能够对关键对象进行内存快照，配置并将其写入本地文件。这对于解决复杂问题很有帮助。

安装

安装 Java 开发工具包（JDK）

确保你的系统已安装 JDK 8 或更高版本。有关如何检查 Java 版本并安装 JDK 的更多信息，请参见 Oracle JDK 安装概述文档

将 GreptimeDB Java SDK 添加为依赖项

如果你使用的是 Maven，请将以下内容添加到 pom.xml 的依赖项列表中：

xml

<dependency>
    <groupId>io.greptime</groupId>
    <artifactId>ingester-all</artifactId>
    <version>${latest_version}</version>
</dependency>

最新版本可以在这里查看。

配置依赖项后，请确保它们对项目可用，这可能需要在 IDE 中刷新项目或运行依赖项管理器。

连接数据库

连接 GreptimeDB 时，通常需要用户名和密码。关于如何设置 GreptimeDB 的鉴权方式，请参考鉴权。这里我们在使用 ingester 库连接 GreptimeDB 时设置用户名和密码。

下方的代码展示了以最简单的配置连接到 GreptimeDB 的方法。如果想要自定义连接选项，请参考 API 文档。请注意每个选项的注释，它们提供了对其各自角色的详细解释。

java

// GreptimeDB has a default database named "public" in the default catalog "greptime",
// we can use it as the test database
String database = "public";
// By default, GreptimeDB listens on port 4001 using the gRPC protocol.
// We can provide multiple endpoints that point to the same GreptimeDB cluster.
// The client will make calls to these endpoints based on a load balancing strategy.
String[] endpoints = {"127.0.0.1:4001"};
// Sets authentication information.
AuthInfo authInfo = new AuthInfo("username", "password");
GreptimeOptions opts = GreptimeOptions.newBuilder(endpoints, database)
        // If the database does not require authentication, we can use AuthInfo.noAuthorization() as the parameter.
        .authInfo(authInfo)
        // A good start ^_^
        .build();
GreptimeDB client = GreptimeDB.create(opts);

行对象

表中的每条行数据包含三种类型的列：Tag、Timestamp 和 Field。更多信息请参考数据模型。列值的类型可以是 String、Float、Int、Timestamp 等。更多信息请参考数据类型。

Java ingester SDK 使用 Table 来表示表中的多行数据。我们可以将行数据项添加到 Table 对象中，然后写入 GreptimeDB。

我们还可以基本的 POJO 对象作为另一种替代方法进行写入。这种方法需要使用 Greptime 的注解，但它们很容易使用。

创建行数据

下面的例子展示了如何创建包含 Tag、Timestamp 和 Field 列的行。Tag 列是 String 类型，Timestamp 列是 Timestamp 类型，Field 列是 Float 类型。

java

// Creates schemas
TableSchema cpuMetricSchema = TableSchema.newBuilder("cpu_metric") //
        .addColumn("host", SemanticType.Tag, DataType.String) //
        .addColumn("ts", SemanticType.Timestamp, DataType.TimestampMillisecond) //
        .addColumn("cpu_user", SemanticType.Field, DataType.Float64) //
        .addColumn("cpu_sys", SemanticType.Field, DataType.Float64) //
        .build();
Table cpuMetric = Table.from(cpuMetricSchema);
String host = "127.0.0.1";
long ts = System.currentTimeMillis();
double cpuUser = 0.1;
double cpuSys = 0.12;
cpuMetric.addRow(host, ts, cpuUser, cpuSys);

为了提高写入数据的效率，你可以一次创建多行数据写入 GreptimeDB。

java

// Creates schemas
TableSchema cpuMetricSchema = TableSchema.newBuilder("cpu_metric") //
        .addColumn("host", SemanticType.Tag, DataType.String) //
        .addColumn("ts", SemanticType.Timestamp, DataType.TimestampMillisecond) //
        .addColumn("cpu_user", SemanticType.Field, DataType.Float64) //
        .addColumn("cpu_sys", SemanticType.Field, DataType.Float64) //
        .build();
TableSchema memMetricSchema = TableSchema.newBuilder("mem_metric") //
        .addColumn("host", SemanticType.Tag, DataType.String) //
        .addColumn("ts", SemanticType.Timestamp, DataType.TimestampMillisecond) //
        .addColumn("mem_usage", SemanticType.Field, DataType.Float64) //
        .build();
Table cpuMetric = Table.from(cpuMetricSchema);
Table memMetric = Table.from(memMetricSchema);
// Adds row data items
for (int i = 0; i < 10; i++) {
    String host = "127.0.0." + i;
    long ts = System.currentTimeMillis();
    double cpuUser = i + 0.1;
    double cpuSys = i + 0.12;
    cpuMetric.addRow(host, ts, cpuUser, cpuSys);
}
for (int i = 0; i < 10; i++) {
    String host = "127.0.0." + i;
    long ts = System.currentTimeMillis();
    double memUsage = i + 0.2;
    memMetric.addRow(host, ts, memUsage);
}

或者我们可以使用 POJO 对象构建数据：

java

@Metric(name = "cpu_metric")
public class Cpu {
    @Column(name = "host", tag = true, dataType = DataType.String)
    private String host;
    @Column(name = "ts", timestamp = true, dataType = DataType.TimestampMillisecond)
    private long ts;
    @Column(name = "cpu_user", dataType = DataType.Float64)
    private double cpuUser;
    @Column(name = "cpu_sys", dataType = DataType.Float64)
    private double cpuSys;
    // getters and setters
    // ...
}
@Metric(name = "mem_metric")
public class Memory {
    @Column(name = "host", tag = true, dataType = DataType.String)
    private String host;
    @Column(name = "ts", timestamp = true, dataType = DataType.TimestampMillisecond)
    private long ts;
    @Column(name = "mem_usage", dataType = DataType.Float64)
    private double memUsage;
    // getters and setters
    // ...
}
// Add rows
List<Cpu> cpus = new ArrayList<>();
for (int i = 0; i < 10; i++) {
    Cpu c = new Cpu();
    c.setHost("127.0.0." + i);
    c.setTs(System.currentTimeMillis());
    c.setCpuUser(i + 0.1);
    c.setCpuSys(i + 0.12);
    cpus.add(c);
}
List<Memory> memories = new ArrayList<>();
for (int i = 0; i < 10; i++) {
    Memory m = new Memory();
    m.setHost("127.0.0." + i);
    m.setTs(System.currentTimeMillis());
    m.setMemUsage(i + 0.2);
    memories.add(m);
}

保存行数据

下方的例子展示了如何将行数据保存到 GreptimeDB 中。

java

// Saves data
// For performance reasons, the SDK is designed to be purely asynchronous.
// The return value is a future object. If you want to immediately obtain
// the result, you can call `future.get()`.
CompletableFuture<Result<WriteOk, Err>> future = greptimeDB.write(cpuMetric, memMetric);
Result<WriteOk, Err> result = future.get();
if (result.isOk()) {
    LOG.info("Write result: {}", result.getOk());
} else {
    LOG.error("Failed to write: {}", result.getErr());
}

我们还可以使用 POJO 对象进行写入：

java

// Saves data
CompletableFuture<Result<WriteOk, Err>> puts = greptimeDB.writePOJOs(cpus, memories);
Result<WriteOk, Err> result = puts.get();
if (result.isOk()) {
    LOG.info("Write result: {}", result.getOk());
} else {
    LOG.error("Failed to write: {}", result.getErr());
}

更新行数据

请参考更新数据了解更新机制。下面的例子展示了先保存一行数据，然后更新这行数据。

java

Table cpuMetric = Table.from(myMetricCpuSchema);
// save a row data
long ts = 1703832681000L;
cpuMetric.addRow("host1", ts, 0.23, 0.12);
Result<WriteOk, Err> putResult = greptimeDB.write(cpuMetric).get();
// update the row data
Table newCpuMetric = Table.from(myMetricCpuSchema);
// The same tag `host1`
// The same time index `1703832681000`
// The new value: cpu_user = `0.80`, cpu_sys = `0.81`
long ts = 1703832681000L;
myMetricCpuSchema.addRow("host1", ts, 0.80, 0.81);
// overwrite the existing data
Result<WriteOk, Err> updateResult = greptimeDB.write(myMetricCpuSchema).get();

或者我们可以使用 POJO 对象进行更新：

java

Cpu cpu = new Cpu();
cpu.setHost("host1");
cpu.setTs(1703832681000L);
cpu.setCpuUser(0.23);
cpu.setCpuSys(0.12);
// save a row data
Result<WriteOk, Err> putResult = greptimeDB.writePOJOs(cpu).get();
// update the row data
Cpu newCpu = new Cpu();
// The same tag `host1`
newCpu.setHost("host1");
// The same time index `1703832681000`
newCpu.setTs(1703832681000L);
// The new value: cpu_user = `0.80`, cpu_sys = `0.81`
cpu.setCpuUser(0.80);
cpu.setCpuSys(0.81);
// overwrite the existing data
Result<WriteOk, Err> updateResult = greptimeDB.writePOJOs(newCpu).get();

请参考此处获取更多代码示例。

调试日志

ingester SDK 提供了用于调试的指标和日志。请参考 Metrics & Display 和 Magic Tools 了解如何启用或禁用日志。

Ingester 库参考

API 文档

查询数据

GreptimeDB 使用 SQL 作为主要查询语言，兼容 MySQL 和 PostgreSQL。因此，我们推荐使用成熟的 SQL 驱动来查询数据。

安装

如果你使用的是 Maven，请将以下内容添加到 pom.xml 的依赖项列表中：

xml

<!-- MySQL usage dependency -->
<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <version>8.0.33</version>
</dependency>

连接到数据库

下方的例子展示了如何连接到 GreptimeDB：

这里我们使用 MySQL 作为示例来演示如何连接到 GreptimeDB。

java


public static Connection getConnection() throws IOException, ClassNotFoundException, SQLException {
    Properties prop = new Properties();
    prop.load(QueryJDBC.class.getResourceAsStream("/db-connection.properties"));
    String dbName = (String) prop.get("db.database-driver");
    String dbConnUrl = (String) prop.get("db.url");
    String dbUserName = (String) prop.get("db.username");
    String dbPassword = (String) prop.get("db.password");
    Class.forName(dbName);
    Connection dbConn = DriverManager.getConnection(dbConnUrl, dbUserName, dbPassword);
    return Objects.requireNonNull(dbConn, "Failed to make connection!");
}

你需要一个 properties 文件来存储数据库连接信息，将其放在 Resources 目录中并命名为 db-connection.properties。文件内容如下：

txt

# DataSource
db.database-driver=com.mysql.cj.jdbc.Driver
db.url=jdbc:mysql://localhost:4002/public
db.username=
db.password=

或者你可以从这里获取文件。

Raw SQL

我们推荐使用 Raw SQL 来体验 GreptimeDB 的全部功能。下面的例子展示了如何使用 Raw SQL 查询数据：

java

try (Connection conn = getConnection()) {
    Statement statement = conn.createStatement();
    // DESC table;
    ResultSet rs = statement.executeQuery("DESC cpu_metric");
    LOG.info("Column | Type | Key | Null | Default | Semantic Type ");
    while (rs.next()) {
        LOG.info("{} | {} | {} | {} | {} | {}", //
                rs.getString(1), //
                rs.getString(2), //
                rs.getString(3), //
                rs.getString(4), //
                rs.getString(5), //
                rs.getString(6));
    }
    // SELECT COUNT(*) FROM cpu_metric;
    rs = statement.executeQuery("SELECT COUNT(*) FROM cpu_metric");
    while (rs.next()) {
        LOG.info("Count: {}", rs.getInt(1));
    }
    // SELECT * FROM cpu_metric ORDER BY ts DESC LIMIT 5;
    rs = statement.executeQuery("SELECT * FROM cpu_metric ORDER BY ts DESC LIMIT 5");
    LOG.info("host | ts | cpu_user | cpu_sys");
    while (rs.next()) {
        LOG.info("{} | {} | {} | {}", //
                rs.getString("host"), //
                rs.getTimestamp("ts"), //
                rs.getDouble("cpu_user"), //
                rs.getDouble("cpu_sys"));
    }
}