Using a cluster

See also

• Overview of clusters provides a brief introduction to clusters in GraphDB.

• Creating and managing a cluster walks through the steps for creating and monitoring a cluster group.

• To learn more about clusters, check the Cluster states and election procedures section.

Note

This section assumes that you have set up a working cluster.

Once created, a cluster can be used almost like a single GraphDB configuration. However, all write operations must 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 see how some imported data looks in a 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. Note 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 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.

   

Using the GraphDB client API for Java

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

The following demonstrates how to create an instance of GraphDBHTTPRepository:

package com.ontotext.example;

import com.ontotext.graphdb.repository.http.GraphDBHTTPRepository;
import com.ontotext.graphdb.repository.http.GraphDBHTTPRepositoryBuilder;
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 must 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 always be tried, so we recommend that you specify at least two of them in case one of them is down.

Since release 10, GraphDB 10 has included an additional mechanism that allows the use of any cluster nodes with any standard client — for example, 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 an external proxy

The cluster can also be used through an external proxy. To do this, instead of providing the GraphDB HTTP address, 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.

Setting local consistency

Local consistency determines the freshness of the query results. At the lowest level (using the REST API), it is controlled by setting the X-GraphDB-Local-Consistency header to one of the following values:

• last-committed: Sets Last Committed local consistency. The queries will always return results that include the last completed transaction.

• none: Sets no local consistency. The queries may return results from a node that has not yet seen the last completed transaction. This is the default setting.

You can set the header just like any other header in your HTTP client library. For example, with curl:

curl 'http://graphdb1.example.com:7200/repositories/myrepo'\
  -H 'X-GraphDB-Local-Consistency: last-committed'\
  -H 'Content-Type: application/sparql-query'\
  -d 'select * { ?s ?p ?o } limit 5'

Using the GraphDB Java client API

The GraphDB client API for Java has built-in support for setting the local consistency using the RequestHeaderAware interface:

/**
 * An interface for adding and setting HTTP request headers.
 */
public interface RequestHeaderAware {
    ...
    /**
     * Convenience method for setting the X-GraphDB-Local-Consistency header.
     *
     * @param localConsistency the desired local consistency level
     */
    default void setLocalConsistencyHeader(LocalConsistency localConsistency) {
        setHeader(GraphDBHTTPProtocol.LOCAL_CONSISTENCY_HEADER_NAME, localConsistency.toString());
    }
}

The connections returned by GraphDBHTTPRepository implement the RequestHeaderAware interface. In order to request Last Committed local consistency, you need to call setLocalConsistencyHeader() with LocalConsistency.LAST_COMMITTED:

package com.ontotext.example;

import com.ontotext.graphdb.replicationcluster.LocalConsistency;
import com.ontotext.graphdb.repository.http.GraphDBHTTPRepository;
import com.ontotext.graphdb.repository.http.GraphDBHTTPRepositoryBuilder;
import com.ontotext.graphdb.repository.http.RequestHeaderAware;

public class Example {
    public static void main(String[] args) {
        try (RepositoryConnection connection = repository.getConnection()) {
            // Sets local consistency to "Last Committed"
            ((RequestHeaderAware) connection).setLocalConsistencyHeader(LocalConsistency.LAST_COMMITTED);

            // Use connection to evaluate queries
            ...
        }
    }
}