Using a Cluster

Once created, a cluster can be used almost like a single GraphDB configuration. However, all write operations need to be performed on the current leader node. Read operations are allowed on any node.

When using the Workbench, make sure you have opened the leader node (go to Setup ‣ Cluster to check). If you are connected to a follower and try to perform a write operation, you will get an error message:


Let’s import some data in our cluster.

  1. On the leader node, in our case, go to Setup ‣ Repositories and create a repository (for Location, select Local).

  2. We can see that the repository was created on all nodes because they are connected in a cluster. Unlike GraphDB version 9.x and older where the cluster was defined at repository level, since GraphDB 10, it is defined at instance level. This means that when you create a repository on any of the nodes, it is automatically included in the cluster.

  3. Connect to the repository.

  4. Import some data in it from Import ‣ User data ‣ Upload RDF files. For this example, let’s use the wine ontology.

  5. If we open the SPARQL editor and run a basic SELECT query against the imported data, we will see that it behaves just like a regular GraphDB instance.


Using the GraphDB client API for Java

The GraphDB client API for Java is an extension of RDF4J’s HTTPRepository that adds support for automatic leader discovery.

You can create an instance of GraphDBHTTPRepository like this:

package com.ontotext.example;

import org.eclipse.rdf4j.query.TupleQueryResult;
import org.eclipse.rdf4j.repository.RepositoryConnection;

public class Example {
    public static void main(String[] args) {
        GraphDBHTTPRepository repository = new GraphDBHTTPRepositoryBuilder().withRepositoryId("my-repo")

        try (RepositoryConnection connection = repository.getConnection()) {
            connection.prepareUpdate("insert data { <urn:fact1> a <urn:Fact> ;" +
                            "  <urn:contents> 'GraphDB rocks!'@en }").execute();

            String query = "select ?fact ?contents { ?fact a <urn:Fact> ; <urn:contents> ?contents }";
            try (TupleQueryResult tqr = connection.prepareTupleQuery(query).evaluate()) {
                while (tqr.hasNext()) {


The client needs to be configured with at least one server URL that is part of the cluster. The remaining server URLs will be discovered automatically. The server URLs that are provided when the client is created will be tried always, so it is recommended to specify at least two of them in case one of them is down.

GraphDB 10 includes an additional mechanism that allows using any of the cluster nodes with any standard client, e.g., RDF4J’s HTTPRepository or your own software that already works with GraphDB.

The GraphDBHTTPRepository class is part of the graphdb-client-api module. Use the following Maven configuration to include it in your project:



Do not forget to set the graphdb.version property to the actual GraphDB version you want to use, or replace the ${graphdb.version} string with the version.

Using a cluster with external proxy

The cluster can also be used through an external proxy. To do this, instead of the providing the GraphDB HTTP address, you need to provide that of the proxy. For example, if for the repository “myrepo” GraphDB is on, the external proxy will be on

See how to configure the external cluster proxy.