MarkLogic Server 11.0 Product Documentation

Java Application Developer's Guide — Chapter 7

GraphManager Interface Summary

The following table summarizes key GraphManager methods. For a complete list of methods, see the Java Client API Documentation.

Creating a GraphManager Object

Operations on graphs, such as loading triples and reading a graph, require a com.marklogic.client.semantics.GraphManager object. To create a GraphManager, use DatabaseClient.newGraphManager.

For example, the following code snippet creates a DatabaseClient, and then uses it to create a GraphManager.

import com.marklogic.client.DatabaseClientFactory;
import com.marklogic.client.DatabaseClient;
import com.marklogic.client.DatabaseClient.DigestAuthContext;
import com.marklogic.client.semantics.GraphManager;
...
DatabaseClient client = DatabaseClientFactory.newClient(
    "localhost", 8000, "myDatabase", 
    new DigestAuthContext("username", "password"));
GraphManager gmgr = client.newGraphManager();

You do not have to create a new DatabaseClient object to create a GraphManager. You can re-use any client object previously created by your application that represents the desired connection to MarkLogic.

Specifying the Triple Format

When reading and writing triples, you must specify the triples format MIME type. You can specify the format in the following ways:

• Use the withMimeType method on your triples Handle to set the format on a per source basis. For example, the following code initializes a FileHandle for reading triples in Turtle format:

  import com.marklogic.client.io.FileHandle;
  ...
  FileHandle fileHandle = 
    new FileHandle(new File("example.ttl"))
      .withMimetype(RDFMimeTypes.TURTLE);

• Use GraphManager.setDefaultMimeType to set a format to be used across all operations performed through a given GraphManager. For example, the following code sets the default MIME type to Turtle:

  import com.marklogic.client.io.FileHandle;
  ...
  GraphManager graphMgr = ...;
  graphMgr.setDefaultMimeType(RDFMimeTypes.TURTLE);

Setting a default MIME type frees you from setting the MIME type on every triples handle and enables use of the GraphManager.*As methods, such as GraphManager.writeAs and GraphManager.readAs. For example:

graphMgr.setDefaultMimeType(RDFMimeTypes.TURTLE);
...
graphMgr.writeAs(
    someGraphURI, new FileHandle(new File("example.ttl")));

Set the MIME type to one of the values exposed by the RDFMimeTypes class, such as RDFMimeTypes.RDFJSON or RDFMimeTypes.TURTLE. For more details about triples formats accepted by MarkLogic, see Supported RDF Triple Formats in Semantics Developer's Guide.

To learn more about Handles, see Using Handles for Input and Output.

Creating or Overwriting a Graph

Use GraphManager.write and GraphManager.writeAs to create or overwrite a graph. If a graph already exists with the specified URI, the effect is the same as removing the existing graph and then recreating it f rom the input triple data.

Note that if you use GraphManager.write to load quads, any graph URI in a quad is ignored in favor of the graph URI parameter passed into write.

For example, the following code loads triples from a file into a graph. For the complete example, see Example: Loading, Managing, and Querying Triples.

public static void loadGraph(String filename, String graphURI, String format) {
    System.out.println("Creating graph " + graphURI);
    FileHandle tripleHandle = 
      new FileHandle(new File(filename)).withMimetype(format);
    graphMgr.write(graphURI, tripleHandle);
}

Use the following procedure to load semantic triples into a graph in MarkLogic.

1. If you have not already done so, create a com.marklogic.client.semantics.GraphManager. as described in Creating a GraphManager Object. For example:

   GraphManager graphMgr = client.newGraphManager();

2. Create a Handle associated with the input triples. The Handle type depends on the source for your content, such as a file or in-memory data. For example, the following Handle can be used to read triples in Turtle format from a file:

   FileHandle tripleHandle = 
     new FileHandle(new File("example.ttl"));

3. If no default triples format is set on your GraphManager, specify the triples format for the Handle, using the withMimetype method. For more details, see Querying Semantic Triples With SPARQL. For example:

   tripleHandle.withMimeType(RDFMimeTypes.TURTLE);

4. Write the triples to MarkLogic using GraphManager.write . For example:
   1. To load triples into a named graph, specify the graph URI as the graph URI parameter. For example:

      graphMgr.write(someGraphURI, tripleHandle);

   2. To load triples into the default graph, specify GraphManager.DEFAULT_GRAPH as the graph URI parameter. For example:

      graphMgr.write(GraphManager.DEFAULT_GRAPH, tripleHandle);

5. If your application no longer needs to connect to MarkLogic, release the connection resources by calling the DatabaseClient object's release() method.

   client.release();

As an alternative to GraphManager.write, if you already have triples in an in-memory object, you can use GraphManager.writeAs to short circuit explicit creation of a handle. For example:

graphManager.setDefaultMimeType(RDFMimeTypes.RDFJSON);
...
Object graphData = ...;
graphMgr.writeAs(someGraphURI, graphData);

For more details on this technique, see Shortcut Methods as an Alternative to Creating Handles.

Reading Triples from a Graph

Use GraphManager.read or GraphManager.readAs to read the contents of a graph in MarkLogic. You must specify the serialization format from the triples, either on the read Handle or the GraphManager; for details, see Specifying the Triple Format.

The following example retrieves the contents of the default graph, in Turtle format and makes the results available to the application through a StringHandle:

StringHandle triples = graphMgr.read(
    GraphManager.DEFAULT_GRAPH,
    new StringHandle().withMimetype(RDFMimeTypes.TURTLE));
//...work with the triples as one big string

For a complete example, see Example: Loading, Managing, and Querying Triples.

Replacing Quad Data in Graphs

Use GraphManager.replaceGraphs and GraphManager.replaceGraphsAs to remove all quads from all graphs and then insert quad data into the graphs specified in the new quads. Unmanaged triples are not affected by this operation. The end result is the same as first calling GraphManager.delete (or deleteAs) and then inserting the quads.

The quad data can be in either NQuad or TriG format. Set the MIME type appropriate, as described in Specifying the Triple Format.

The following example adds a single triple in Turtle format to the default graph. This triple is passed via a StringHandle.

StringHandle quadHandle = new StringHandle()
    .with(someQuadData)
    .withMimetype(RDFMimeTypes.NQUAD);
graphMgr.replaceGraphs(quadHandle);

The following example performs a similar operation, using replaceAs:

graphMgr.setDefaultMimeType(RDFMimeTypes.NQUAD);
...
File graphData = new File(filename);
graphMgr.replaceGraphsAs(graphData);

Adding Triples to an Existing Graph

Use GraphManager.merge or GraphManager.mergeAs to merge triples into an existing graph. You must specify the serialization format from the triples, either on the read Handle or the GraphManager; for details, see Specifying the Triple Format.

For quad data, use mergeGraphs or mergeGraphsAs. For details, see Adding Quads into an Existing Graph.

The following example adds a single triple in Turtle format to the default graph. This triple is passed via a StringHandle.

StringHandle stringHandle = new StringHandle()
    .with("<http://example.org/subject2> " +
          "<http://example.org/predicate2> " +
          "<http://example.org/object2> .")
    .withMimetype(RDFMimeTypes.TURTLE);
graphMgr.merge("myExample/graphUri", stringHandle);

The following example performs a similar operation, using mergeAs:

graphMgr.setDefaultMimeType(RDFMimeTypes.TURTLE);
...
Object graphData = ...;
graphMgr.mergeAs(someGraphURI, graphData);

Adding Quads into an Existing Graph

Use GraphManager.mergeGraphs and GraphManager.mergeGraphsAs to add quads to an existing graph. If a quad specifies the URI of an existing graph, the quad data is merged into that graph. If no such graph exists, the graph is created.

The quad data can be in either NQuad or TriG format. Set the MIME type appropriate, as described in Specifying the Triple Format.

The following example adds a single triple in Turtle format to the default graph. This triple is passed via a StringHandle.

StringHandle quadHandle = new StringHandle()
    .with(someQuadData)
    .withMimetype(RDFMimeTypes.NQUAD);
graphMgr.mergeGraphs(quadHandle);

The following example performs a similar operation, using mergeAs:

graphMgr.setDefaultMimeType(RDFMimeTypes.NQUAD);
...
File graphData = new File(filename);
graphMgr.mergeGraphsAs(graphData);

Deleting a Graph

Use GraphManager.delete to remove a single graph. Use GraphManager.deleteGraphs to delete all graphs.

The following example removes a single graph with the specified URI:

graphMgr.delete(someGraphURI);

The following example removes all graphs:

graphMgr.deleteGraphs(someGraphURI);

For a complete example, see Example: Loading, Managing, and Querying Triples.

Basic Steps for SPARQL Query Evaluation

Evaluating a SPARQL query consists of the following basic steps:

1. Create a query manager using DatabaseClient.newSPARQLQueryManager. For example:

   DatabaseClient client = ...;
   SPARQLQueryManager sqmgr = client.newSPARQLManager();

2. Create a query using SPARQLQueryManager.newSPARQLQueryDefinition and configure the query as needed. For example:

   SPARQLQueryDefinition query = sqmgr.newSPARQLQueryDefinition(
     "SELECT * WHERE { ?s ?p ?o } LIMIT 10")
     .withBinding("o", "http://example.org/object1");

3. Evaluate the query and receive results by calling one of the execute* methods of SPARQLQueryManager. For example, use executeSelect for a SELECT query:

   JacksonHandle results = new JacksonHandle();
   results.setMimetype(SPARQLMimeTypes.SPARQL_JSON));
   results = sqmgr.executeSelect(query, results);

The format of the results you receive depends on the type of query you evaluate and how you configure your results Handle and/or the SPARQLQueryManager. For details, see Handling Query Results.

For example, the following evaluates a SPARQL SELECT query and returns the results as JSON. For a complete example, see Example: Loading, Managing, and Querying Triples.

SPARQLQueryManager qm = client.newSPARQLQueryManager();
SPARQLQueryDefinition query = qm.newQueryDefinition(
    "SELECT ?person " +
    "WHERE { ?person <http://example.org/marklogic/predicate/livesIn> \"London\" }"
);

JsonNode results = qm.executeSelect(query, new JacksonHandle()).get();
// ... Process results

Handling Query Results

The layout and available format of the results from a SPARQL query depend on the type of query. For details, see the following topics:

• SELECT Results
• CONSTRUCT and DESCRIBE Results
• ASK Results

JacksonHandle handle = new JacksonHandle();
handle.setMimeType(SPARQLMimeTypes.SPARQL_JSON);

JacksonHandle handle = new JacksonHandle();
handle.setMimeType(RDFMimeTypes.RDFJSON);

Defining Variable Bindings

If your query depends on runtime variable definitions, you can define variable bindings one at a time using the fluent SPARQLQueryDefinition.withBinding definition, or build up a set of bindings using SPARQLBindings and then attach them to the query using SPARQLQueryDefinition.setBindings.

The following example incrementally attaches bindings to a query definition using withBindings:

// incrementally attach bindings to a query
SPARQLQueryDefinition query = ...;
query.withBinding("o", "http://example.org/object1")
     .withBinding(...);

The following example builds up a setting of bindings and then attaches them all to the query at once, using setBindings:

// build up a set of bindings and attach them to a query
SPARQLBindings bindings = new SPARQLBindings();
bindings.bind("o", "http://example.org/object1");
bindings.bind(...);
query.setBindings(bindings);

Both SPARQLQueryDefinition.withBinding and SPARQLBindings enable you to specify a language tag or RDF type for the bound value.

For more details, see SPARQLBindings in the Java Client API Documentation.

Limiting the Number of Results

When you evaluate a SPARQL SELECT query, by default, all results are returned. You can limit the number of results returned in a page using SPARQLQueryManager.setPageLength or a SPARQL LIMIT clause. You can retrieve successive pages of results by repeatedly calling executeSelect with a different page start position. For example:

// Change the max page length
sqmgr.setPageLength(NRESULTS);

// Fetch at most the first N results
long start = 1;
JacksonHandle results = sparqlMgr.executeSelect(query, handle, start);

// Fetch the next N results
start += N;
JacksonHandle results = sparqlMgr.executeSelect(query, handle, start);

Inferencing Support

Inferencing enables discovery of new facts based on a combination of data and rules for understanding that data. The Java Client API includes the following features that facilitate inferencing:

• Enabling or Disabling Automatic Inferencing
• Associating a Rule Set with a Query

Default Graph Permissions and Required Privileges

All graphs created and managed using the Java, REST, or Node.js Client APIs grant read capability to the rest-reader role and update capability to the rest-writer role. These default permissions are always assigned to a graph, even if you do not explicitly specify them.

If you explicitly specify other permissions when creating a graph, the default permissions are still set, in addition to the permissions you specify.

You can use custom roles to limit access to selected users on a graph by graph basis. Your custom roles must include equivalent rest-reader and rest-writer privileges. Otherwise, users with these roles cannot use the Java Client API to manage or query semantic data. For details, see Controlling Access to Documents and Other Artifacts in the REST Application Developer's Guide.

For more information on the MarkLogic security model, see the Security Guide.

Setting Graph Permissions

When you create a graph with the Java Client API, MarkLogic assigns a set of default permissions, even if you do not specify any explicit permissions; for details, see Default Graph Permissions and Required Privileges. You can modify permissions on a graph as a standalone operation or as part of another operation, such as when creating or merging graphs.

Graph permissions are encapsulated in a GraphPermissions object. To create a set of graph permissions, use GraphManager.newGraphPermissions or GraphManager.permission.

To modify permissions standalone, use the following GraphManager methods:

• GraphManager.writePermissions
• GraphManager.mergePermissions
• GraphManager.deletePermissions

To modify permissions as part of another operation, such as GraphManager.write or GraphManager.merge, include a GraphPermissions object in your call.

The following example sets the permissions on the graph with URI myExample/graphUri. The code grants the role example_manager read and update permissions on the graph.

graphMgr.writePermissions("myExample/graphUri",
    graphMgr.permission("example_manager", Capability.READ)
            .permission("example_manager", Capability.UPDATE));

The following example sets the graph permissions as part of a graph merge operation:

graphMgr.merge(
  "myExample/graphUri", someTriplesHandle,
  graphManager.permission("role1", Capability.READ)
              .permission("role2", Capability.READ, Capability.UPDATE));

Retrieving Graph Permissions

To retrieve permissions metadata for a named graph or the default graph, use GraphManager.getPermissions. Explore the resulting GraphPermissions object using Map operations. The Map keys are role names, such as rest-reader, and the values are the capabilities.

For example, the following code fetches the permissions on the default graph and prints the capabilities associated with the rest-reader role:

GraphPermissions permissions =
     graphMgr.getPermissions(GraphManager.DEFAULT_GRAPH);
System.out.println(permissions.get("rest-reader");

Managing Permissions on Unmanaged Triples

Unmanaged triples are stored in documents, alongside other content, rather than being inserted into the triple store. You control access to unmanaged triples through the permissions on the documents that contain them.

For example, a SPARQL query will only return a matching unmanaged triple if the user running the query has read permissions on the document that contains the triple.

Permissions are considered document metadata. Set permissions using the DocumentManager interface and a MetadataHandle. For example, set permissions using DocumentMetadataHandle.setPermissions, and then including the metadata handle in a call to DocumentManager.write. For more details, see Reading, Modifying, and Writing Metadata.

For more information document permissions, see Protecting Documents in the Security Guide.