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:

_images/cluster-error-not-leader.png

Let’s import some data in our cluster.

  1. On the leader node, in our case http://graphdb1.example.com:7200, 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.

    _images/create-repo-in-cluster.png
  4. Import some data in it from Import ‣ User data ‣ Upload RDF files. For this example, let’s use the W3.org 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.

    _images/query-cluster.png

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")
                .withServerUrl("http://graphdb1.example.com:7200")
                .withServerUrl("http://graphdb2.example.com:7200")
                .withCluster()
                .build();

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

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

Tip

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:

<dependency>
    <groupId>com.ontotext.graphdb</groupId>
    <artifactId>graphdb-client-api</artifactId>
    <version>${graphdb.version}</version>
</dependency>

Note

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 http://graphdb.example.com:7200/repositories/myrepo, the external proxy will be on http://graphdb.example.com:7204/repositories/myrepo.

See how to configure the external cluster proxy.