Dgraph Client for Java

A minimal implementation for a Dgraph client for Java 11 and above, using grpc.

Note: v25.0.0 adds RunDQL, ID allocation, and namespace management APIs. v24.0.0 features an upgraded protobuf dependency which requires an upgrade to JDK 11. On account of this breaking change, all legacy applications built upon JDK 8 would be impacted.

This client follows the Dgraph Go client closely.

Before using this client, we highly recommend that you go through docs.dgraph.io, and understand how to run and work with Dgraph.

Use Discuss Issues for reporting issues about this repository.

Table of Contents

• Dgraph Client for Java

• Table of Contents

• Download
• Supported Versions
  • Note regarding Java 1.8.x support:
• Quickstart
• Intro
• Using the Synchronous Client
  • Creating a Client
  • Creating a Secure Client using TLS
  • Check Dgraph version
  • Login Using ACL
  • Altering the Database
  • Creating a Transaction
  • Running a Mutation
  • Committing a Transaction
  • Running a Query
  • Running a Query with RDF response
  • Running an Upsert: Query + Mutation
  • Running a Conditional Upsert
  • Setting Deadlines
  • Setting deadlines for all requests
  • Setting deadlines for a single request
  • Setting Metadata Headers
  • Helper Methods
  • Delete multiple edges
  • Running DQL Directly
  • Convenience Methods
  • Namespace Management
  • ID Allocation
  • Closing the DB Connection
• Using the Asynchronous Client
• Checking the request latency

• Development

  • Building the source
  • Code Style
  • Running unit tests

• Using the Asynchronous Client

• Checking the request latency

• Development

• Building the source
• Code Style
• Running unit tests

Download

grab via Maven:

<dependency>
  <groupId>io.dgraph</groupId>
  <artifactId>dgraph4j</artifactId>
  <version>25.0.0</version>
</dependency>

or Gradle:

compile 'io.dgraph:dgraph4j:25.0.0'

Supported Versions

Depending on the version of Dgraph that you are connecting to, you will have to use a different version of this client.

Note regarding Java 1.8.x support

v24.0.0 features an upgraded protoc-protobuf dependency that requires an upgrade to JDK 11. This version is incompatible with Java 1.8 and and requires an upgrade to Java 11.

The following is only applicable to dgraph4j versions < v24.X.X.

• If you aren't using gRPC with TLS, then the above version table will work for you with Java 1.8.x too.
• If you're using gRPC with TLS on Java 1.8.x, then you will need to follow gRPC docs here. Basically, it will require you to add the following dependency in your app with correct version for the corresponding grpc-netty version used by dgraph4j. You can find out the correct version of the dependency to use from the version combination table in this section in grpc-netty docs.

For maven:

xml <dependency> <groupId>io.netty</groupId> <artifactId>netty-tcnative-boringssl-static</artifactId> <version></version> </dependency>

For Gradle:

groovy compile 'io.netty:netty-tcnative-boringssl-static:<See table in gRPC docs for correct version>'

The following table lists the grpc-netty versions used by different dgraph4j versions over time, along with the supported versions of netty-tcnative-boringssl-static for the corresponding grpc-netty version:

For example, when using dgraph4j v24.0.0, the version of the netty-tcnative-boringssl-static dependency to be used is 4.1.100.Final, as suggested by gRPC docs for grpc-netty v1.65.1.

Quickstart

Build and run the DgraphJavaSample project in the samples folder, which contains an end-to-end example of using the Dgraph Java client. Follow the instructions in the README of that project.

Intro

This library supports two styles of clients, the synchronous client DgraphClient and the async client DgraphAsyncClient. A DgraphClient or DgraphAsyncClient can be initialised by passing it a list of DgraphBlockingStub clients. The anyClient() API can randomly pick a stub, which can then be used for GRPC operations. In the next section, we will explain how to create a synchronous client and use it to mutate or query dgraph. For the async client, more details can be found in the Using the Asynchronous Client section.

Using the Synchronous Client

Creating a Client

Using a Connection String

This library supports connecting to a Dgraph cluster using connection strings. Dgraph connections strings take the form dgraph://{username:password@}host:port?args.

username and password are optional. If username is provided, a password must also be present. If supplied, these credentials are used to log into a Dgraph cluster through the ACL mechanism.

Valid connection string args:

Note that using sslmode=require disables certificate validation and significantly reduces the security of TLS. This mode should only be used in non-production (e.g., testing or development) environments.

Some example connection strings:

Using the DgraphClient.open function with a connection string:

// open a connection to an ACL-enabled, non-TLS cluster and login as groot
DgraphClient client = DgraphClient.open("dgraph://groot:password@localhost:8090");

// some time later...
client.shutdown();

Using Managed Channels

The following code snippet shows how to create a synchronous client using three connections.

ManagedChannel channel1 = ManagedChannelBuilder
    .forAddress("localhost", 9080)
    .usePlaintext().build();
DgraphStub stub1 = DgraphGrpc.newStub(channel1);

ManagedChannel channel2 = ManagedChannelBuilder
    .forAddress("localhost", 9082)
    .usePlaintext().build();
DgraphStub stub2 = DgraphGrpc.newStub(channel2);

ManagedChannel channel3 = ManagedChannelBuilder
    .forAddress("localhost", 9083)
    .usePlaintext().build();
DgraphStub stub3 = DgraphGrpc.newStub(channel3);

DgraphClient dgraphClient = new DgraphClient(stub1, stub2, stub3);

Creating a Secure Client using TLS

To setup a client using TLS, you could use the following code snippet. The server needs to be setup using the instructions provided here.

If you are doing client verification, you need to convert the client key from PKCS#1 format to PKCS#8 format. By default, grpc doesn't support reading PKCS#1 format keys. To convert the format, you could use the openssl tool.

First, let's install the openssl tool:

apt install openssl

Now, use the following command to convert the key:

openssl pkcs8 -in client.name.key -topk8 -nocrypt -out client.name.java.key

Now, you can use the following code snippet to connect to Alpha over TLS:

SslContextBuilder builder = GrpcSslContexts.forClient();
builder.trustManager(new File("<path to ca.crt>"));
// Skip the next line if you are not performing client verification.
builder.keyManager(new File("<path to client.name.crt>"), new File("<path to client.name.java.key>"));
SslContext sslContext = builder.build();

ManagedChannel channel = NettyChannelBuilder.forAddress("localhost", 9080)
    .sslContext(sslContext)
    .build();
DgraphGrpc.DgraphStub stub = DgraphGrpc.newStub(channel);
DgraphClient dgraphClient = new DgraphClient(stub);

Check Dgraph version

Checking the version of the Dgraph server this client is interacting with is as easy as:

Version v = dgraphClient.checkVersion();
System.out.println(v.getTag());

Checking the version, before doing anything else can be used as a test to find out if the client is able to communicate with the Dgraph server. This will also help reduce the latency of the first query/mutation which results from some dynamic library loading and linking that happens in JVM (see this issue for more details).

Login Using ACL

If ACL is enabled then you can log-in to the default namespace (0) with following:

dgraphClient.login(USER_ID, USER_PASSWORD);

For logging-in to some other namespace, use the loginIntoNamespace method on the client:

dgraphClient.loginIntoNamespace(USER_ID, USER_PASSWORD, NAMESPACE);

Once logged-in, the dgraphClient object can be used to do any further operations.

Altering the Database

To set the schema, create an Operation object, set the schema and pass it to DgraphClient#alter method.

String schema = "name: string @index(exact) .";
Operation operation = Operation.newBuilder().setSchema(schema).build();
dgraphClient.alter(operation);

Starting Dgraph version 20.03.0, indexes can be computed in the background. You can call the function setRunInBackground(true) as shown below before calling alter. You can find more details here.

String schema = "name: string @index(exact) .";
Operation operation = Operation.newBuilder()
        .setSchema(schema)
        .setRunInBackground(true)
        .build();
dgraphClient.alter(operation);

Operation contains other fields as well, including drop predicate and drop all. Drop all is useful if you wish to discard all the data, and