We’re overhauling Dgraph’s docs to make them clearer and more approachable. If
you notice any issues during this transition or have suggestions, please
let us know.
The official Java client can be found
here. Follow the install
instructions to get it up
and running.
Supported versions
More details on the supported versions can be found at this link.Quickstart
Build and run the DgraphJavaSample project in thesamples
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 clientDgraphClient
and the async client DgraphAsyncClient
. A DgraphClient
or
DgraphAsyncClient
can be initialized by passing it a list of
DgraphBlockingStub
clients. The anyClient()
API can randomly pick a stub,
which can then be used for gRPC operations.
Using the synchronous client
You can find a
DgraphJavaSample
project, which contains an end-to-end working example of how to use the Java
client.
Creating a client
The following code snippet shows how to create a synchronous client using three connections.Login using access control lists
If Access Control Lists (ACL) is enabled then you can log-in to the default namespace (0
) with the following
method:
Multi-tenancy
If multi-tenancy is enabled, by default the login method on client logs into the namespace0
. In order to log into a
different namespace, use the loginIntoNamespace
method on the client:
dgraphClient
object can be used to do any further
operations.
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, g doesn’t support reading PKCS#1 format keys. To convert the format, you could use theopenssl
tool.
First, let’s install the openssl
tool:
Check Dgraph version
Checking the version of the Dgraph server this client is interacting with is as easy as:Altering the database
To set the schema, create anOperation
object, set the schema and pass it to
DgraphClient#alter
method.
setRunInBackground(true)
as shown below before calling
alter
. You can find more details
here.
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 start from a
clean slate, without bringing the instance down.
Creating a transaction
There are two types of transactions in dgraph, queries (reads) and mutations (writes). Both the synchronousDgraphClient
and the asynchronous
DgraphAsyncClient
clients support the two types of transactions by providing
the newTransaction
and the newReadOnlyTransaction
APIs. Creating a
transaction is a local operation and incurs no network overhead.
In most of the cases, the normal read-write transactions is used, which can have
any number of query or mutate operations. However, if a transaction only has
queries, you might benefit from a read-only transaction, which can share the
same read timestamp across multiple such read-only transactions and can result
in lower latencies.
For normal read-write transactions, it’s a good practice to call
Transaction#discard()
in a finally
block after running the transaction.
Calling Transaction#discard()
after Transaction#commit()
is a no-op and you
can call discard()
multiple times with no additional side-effects.
Transaction.discard
,
which is equivalent to a no-op.
Running a mutation
Transaction#mutate
runs a mutation. It takes in a Mutation
object, which
provides two main ways to set data: JSON and RDF N-Quad. You can choose
whichever way is convenient.
We’re going to use JSON. First we define a Person
class to represent a person.
This data is serialized into JSON.
Person
object, serialize it and use it in Mutation
object.
CommitNow
field in Mutation
object to indicate
that the mutation must be immediately committed.
Mutation can be run using the doRequest
function as well.
Committing a transaction
A transaction can be committed using theTransaction#commit()
method. If your
transaction consisted solely of calls to Transaction#query()
, and no calls to
Transaction#mutate()
, then calling Transaction#commit()
isn’t necessary.
An error is returned if other transactions running concurrently modify the same
data that was modified in this transaction. It is up to the user to retry
transactions when they fail.
Running a query
You can run a query by callingTransaction#query()
. You need to pass in a DQL
query string, and a map (optional, could be empty) of any variables that you
might want to set in the query.
The response would contain a JSON
field, which has the JSON encoded result.
You need to decode it before you can do anything useful with it.
Let’s run the following query:
People
class that helps us deserialize the JSON result:
doRequest
function to run the query.
Running a Query with RDF response
You can get query results as an RDF response by calling eitherqueryRDF()
or
queryRDFWithVars()
. The response contains the getRdf()
method, which
provides the RDF encoded output.
If you are querying for
uid
values only, use a JSON format response.uid
is 0x2
):
Running an upsert: query + mutation
Thetxn.doRequest
function allows you to run upserts consisting of one query
and one mutation. Variables can be defined in the query and used in the
mutation. You could also use txn.doRequest
to perform a query followed by a
mutation.
Running a conditional upsert
The upsert block also allows specifying a conditional mutation block using an@if
directive. The mutation is executed only when the specified condition is
true. If the condition is false, the mutation is silently ignored.
See more about Conditional Upsert
Here.
Setting deadlines
It is recommended that you always set a deadline for each client call, after which the client terminates. This is in line with the recommendation for any gRPC client. Read this forum post for more details.Setting metadata headers
Certain headers such as authentication tokens need to be set globally for all subsequent calls. Below is an example of setting a header with the name “auth-token”:Helper methods
Delete multiple edges
The example below uses the helper methodHelpers#deleteEdges
to delete
multiple edges corresponding to predicates on a node with the given UID. The
helper method takes an existing mutation, and returns a new mutation with the
deletions applied.
Closing the database connection
To disconnect from Dgraph, callManagedChannel#shutdown
on the gRPC channel
object created when creating a Dgraph client.
Using the asynchronous client
Dgraph Client for Java also bundles an asynchronous API, which can be used by instantiating theDgraphAsyncClient
class. The usage is almost exactly the
same as the DgraphClient
(show in previous section) class. The main
differences is that the DgraphAsyncClient#newTransacation()
returns an
AsyncTransaction
class. The API for AsyncTransaction
is exactly
Transaction
. The only difference is that instead of returning the results
directly, it returns immediately with a corresponding CompletableFuture<T>
object. This object represents the computation which runs asynchronously to
yield the result in the future. Read more about CompletableFuture<T>
in the
Java 8 documentation.
Here is the asynchronous version of the preceding code, which runs a query.
Checking the request latency
If you would like to see the latency for either a mutation or query request, the latency field in the returned result can be helpful. Here is an example to log the latency of a query request:Concurrent mutations and conflicts
This how-to guide provides an example on how to handle concurrent modifications using a multi-threaded Java Program. The example demonstrates transaction conflicts in Dgraph. Steps to run this example are as follows. Step 1: start a new terminal and launch Dgraph with the following command line.samples/concurrent-modification
. In order to run
this example, execute the following maven command from the
‘concurrent-modification’ folder.