Skip to content
On this page



This guide shows you how to create an application that use the Java SDK to connect to a GreptimeDB server.

The Java SDK lets you connect to and communicate with GreptimeDB server from a Java application.

Consult the following steps to connect your Java application with a GreptimeDB server.

Set up Your Project

Install the Java Development Kit(JDK)

Make sure that your system has JDK 8 or later installed. For more information on how to check your version of Java and install the JDK, see the Oracle Overview of JDK Installation documentation

Create the Project

This guide demonstrates how to add Java SDK dependencies using Maven. It is advisable to utilize an integrated development environment (IDE) like Intellij IDEA or Eclipse IDE for easier configuration of Maven in building and running your project.

If you are not using an IDE, see Building Maven for more information on how to set up your project.

Add GreptiemDB Java SDK as a Dependency

If you are using Maven, add the following to your pom.xml dependencies list:


The latest version can be viewed here.

After configuring your dependencies, make sure they are available to your project. This may require refreshing the project in your IDE or running the dependency manager.

Start a GreptiemDB Server

See Installation for more details.

Create Java Client to Write And Query

Now, we can create a file to contain your application caslled in the base package directory of you project. Use the following sample code to run a write and a query, replacing the value of endpoints variable with your real connection string.

package io.greptime.example;

import io.greptime.GreptimeDB;
import io.greptime.models.ColumnDataType;
import io.greptime.models.Err;
import io.greptime.models.QueryOk;
import io.greptime.models.QueryRequest;
import io.greptime.models.Result;
import io.greptime.models.SelectExprType;
import io.greptime.models.SelectRows;
import io.greptime.models.SemanticType;
import io.greptime.models.TableName;
import io.greptime.models.TableSchema;
import io.greptime.models.WriteOk;
import io.greptime.models.WriteRows;
import io.greptime.options.GreptimeOptions;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import java.util.List;
import java.util.Map;
import java.util.concurrent.CompletableFuture;

 * @author jiachun.fjc
public class QuickStart {

    private static final Logger LOG = LoggerFactory.getLogger(QuickStart.class);

    public static void main(String[] args) throws Exception {
        String endpoint = "";
        GreptimeOptions opts = GreptimeOptions.newBuilder(endpoint) //
                .writeMaxRetries(1) //
                .readMaxRetries(2) //
                .routeTableRefreshPeriodSeconds(-1) //

        GreptimeDB greptimeDB = new GreptimeDB();

        if (!greptimeDB.init(opts)) {
            throw new RuntimeException("Fail to start GreptimeDB client");



    private static void runInsert(GreptimeDB greptimeDB) throws Exception {
        TableSchema schema =
                        .newBuilder(TableName.with("public", "monitor"))
                        .semanticTypes(SemanticType.Tag, SemanticType.Timestamp, SemanticType.Field, SemanticType.Field)
                        .dataTypes(ColumnDataType.String, ColumnDataType.TimestampMillisecond, ColumnDataType.Float64,
                                ColumnDataType.Float64) //
                        .columnNames("host", "ts", "cpu", "memory") //

        WriteRows rows = WriteRows.newBuilder(schema).build();
        rows.insert("", System.currentTimeMillis(), 0.1, null) //
                .insert("", System.currentTimeMillis(), 0.3, 0.5) //

        // 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(rows);

        Result<WriteOk, Err> result = future.get();

        if (result.isOk()) {
  "Write result: {}", result.getOk());
        } else {
            LOG.error("Failed to write: {}", result.getErr());

    private static void runQuery(GreptimeDB greptimeDB) throws Exception {
        QueryRequest request = QueryRequest.newBuilder() //
                .exprType(SelectExprType.Sql) //
                .ql("SELECT * FROM monitor;") //

        // 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<QueryOk, Err>> future = greptimeDB.query(request);

        Result<QueryOk, Err> result = future.get();

        if (result.isOk()) {
            QueryOk queryOk = result.getOk();
            SelectRows rows = queryOk.getRows();
            // `collectToMaps` will discard type information, if type information is needed,
            // please use `collect`.
            List<Map<String, Object>> maps = rows.collectToMaps();
            for (Map<String, Object> map : maps) {
      "Query row: {}", map);
        } else {
            LOG.error("Failed to query: {}", result.getErr());

When you run the QuickStart class, it should output the details of write and query which will look something like this:

[main] INFO  QuickStart:88 - Write result: WriteOk{success=2, failure=0, tableName=TableName{databaseName='public', tableName='monitor'}}

[main] INFO  QuickStart:114 - Query row: {memory=null, host=, cpu=0.1, ts=2023-03-16T07:20:26.043}
[main] INFO  QuickStart:114 - Query row: {memory=null, host=, cpu=0.1, ts=2023-03-16T07:21:48.050}
[main] INFO  QuickStart:114 - Query row: {memory=null, host=, cpu=0.1, ts=2023-03-16T07:29:47.780}
[main] INFO  QuickStart:114 - Query row: {memory=0.5, host=, cpu=0.3, ts=2023-03-16T07:20:26.096}
[main] INFO  QuickStart:114 - Query row: {memory=0.5, host=, cpu=0.3, ts=2023-03-16T07:21:48.103}
[main] INFO  QuickStart:114 - Query row: {memory=0.5, host=, cpu=0.3, ts=2023-03-16T07:29:47.882}

If you receive no output or an error, check whether you included the proper connection string in your Java class.

After completing this step, you should have a working application that uses the Java SDK to connect to your GreptimeDB, run a write and a query, and print out the result.