Package com.marklogic.client.semantics

Interface SPARQLQueryManager

public interface SPARQLQueryManager

A manager for executing SPARQL queries in MarkLogic Server and retrieving the results.

For example perform a SPARQL SELECT:

    SPARQLQueryManager sparqlMgr = databaseClient.newSPARQLQueryManager();
    String sparql = "SELECT * WHERE { ?s ?p ?o } LIMIT 10";
    SPARQLQueryDefinition query = sparqlMgr.newQueryDefinition(sparql)
        .withBinding("o", "http://example.org/object1");
    JacksonHandle handle = new JacksonHandle();
    handle.setMimetype(SPARQLMimeTypes.SPARQL_JSON);
    JacksonHandle results = sparqlMgr.executeSelect(query, handle);
    JsonNode tuples = results.get().path("results").path("bindings");
    for ( JsonNode row : tuples ) {
        String s = row.path("s").path("value").asText();
        String p = row.path("p").path("value").asText();
        ...
    }

Or perform a SPARQL CONSTRUCT:

    String sparql = "CONSTRUCT { <a> <b> <c> } WHERE { ?s ?p ?o } LIMIT 10";
    SPARQLQueryDefinition query = sparqlMgr.newQueryDefinition(sparql);
    SPARQLBindings bindings = query.getBindings();
    query.setBindings(bindings.bind("o", "http://example.org/object1"));
    JacksonHandle handle = new JacksonHandle();
    handle.setMimetype(RDFMimeTypes.RDFJSON);
    JacksonHandle triples = sparqlMgr.executeConstruct(query, handle);
    JsonNode a = triples.get().path("a");
    JsonNode b = a.path("b");
    JsonNode c = b.get(0).path("value");

Each new instance of SPARQLQueryManager is created by DatabaseClient.newSPARQLQueryManager(). While these examples use JacksonHandle, any SPARQLResultsReadHandle may be used--including custom handles. For executeSelect JSONReadHandles will need to use SPARQLMimeTypes.SPARQL_JSON mimetype, and XMLReadHandles will need to use SPARQLMimeTypes.SPARQL_XML mimetype, other SPARQLResultsReadHandles accept any text and can therefore accept results in any of the SPARQLMimeTypes. For executeDescribe and executeConstruct JSONReadHandles will need to use RDFMimeTypes.RDFJSON mimetype, and XMLReadHandles will need to use RDFMimeTypes.RDFXML mimetype, other TriplesReadHandles accept any text and can therefore accept results in any of the RDFMimeTypes.

SPARQLQueryManager is thread-safe other than setPageLength. In other words the only state maintained by an instance is the page length. Common usage is to call setPageLength only once then use the instance across many threads. If you intend to call setPageLength from multiple threads, create a new SPARQLQueryManager for each thread.

For details about RDF, SPARQL, and semantics in MarkLogic see the Semantics Developer's Guide.

Method Summary

Modifier and Type	Method	Description
void	clearPageLength()	Reset this instance to have no page length set.
java.lang.Boolean	executeAsk(SPARQLQueryDefinition qdef)	Execute a SPARQL "ASK" statement.
java.lang.Boolean	executeAsk(SPARQLQueryDefinition qdef, Transaction tx)	Execute a SPARQL "ASK" statement.
<T extends TriplesReadHandle> T	executeConstruct(SPARQLQueryDefinition qdef, T handle)	Execute a SPARQL "CONSTRUCT" statement.
<T extends TriplesReadHandle> T	executeConstruct(SPARQLQueryDefinition qdef, T handle, Transaction tx)	Execute a SPARQL "CONSTRUCT" statement.
<T extends TriplesReadHandle> T	executeDescribe(SPARQLQueryDefinition qdef, T handle)	Execute a SPARQL "DESCRIBE" query (which implements the Concise Bounded Description specification).
<T extends TriplesReadHandle> T	executeDescribe(SPARQLQueryDefinition qdef, T handle, Transaction tx)	Execute a SPARQL "DESCRIBE" query (which implements the Concise Bounded Description specification).
<T extends SPARQLResultsReadHandle> T	executeSelect(SPARQLQueryDefinition qdef, T handle)	Execute a SPARQL "SELECT" query.
<T extends SPARQLResultsReadHandle> T	executeSelect(SPARQLQueryDefinition qdef, T handle, long start)	Execute a SPARQL "SELECT" query.
<T extends SPARQLResultsReadHandle> T	executeSelect(SPARQLQueryDefinition qdef, T handle, long start, Transaction tx)	Execute a SPARQL "SELECT" query.
<T extends SPARQLResultsReadHandle> T	executeSelect(SPARQLQueryDefinition qdef, T handle, Transaction tx)	Execute a SPARQL "SELECT" query.
void	executeUpdate(SPARQLQueryDefinition qdef)	Execute a SPARQL update statement.
void	executeUpdate(SPARQLQueryDefinition qdef, Transaction tx)	Execute a SPARQL update statement.
long	getPageLength()
SPARQLQueryDefinition	newQueryDefinition()	Instantiate a new SPARQLQueryDefinition.
SPARQLQueryDefinition	newQueryDefinition(TextWriteHandle sparql)	Instantiate a new SPARQLQueryDefinition with the SPARQL from the provided TextWriteHandle.
SPARQLQueryDefinition	newQueryDefinition(java.lang.String sparql)	Instantiate a new SPARQLQueryDefinition with provided SPARQL.
GraphPermissions	permission(java.lang.String role, Capability... capabilities)	For use with SPARQL update, where specified permissions will apply to any records created by the update.
void	setPageLength(long pageLength)	Set a page length for all SPARQL "SELECT" queries sent by this instance.

Method Detail

newQueryDefinition

SPARQLQueryDefinition newQueryDefinition()

Instantiate a new SPARQLQueryDefinition.

Returns:

an empty SPARQLQueryDefinition

newQueryDefinition

SPARQLQueryDefinition newQueryDefinition(java.lang.String sparql)

Instantiate a new SPARQLQueryDefinition with provided SPARQL.

Parameters:

sparql - a sparql query as text

Returns:

the query as SPARQLQueryDefinition

newQueryDefinition

SPARQLQueryDefinition newQueryDefinition(TextWriteHandle sparql)

Instantiate a new SPARQLQueryDefinition with the SPARQL from the provided TextWriteHandle.

Parameters:

sparql - the handle containing a sparql query as text

Returns:

the query as SPARQLQueryDefinition

executeSelect

<T extends SPARQLResultsReadHandle> T executeSelect(SPARQLQueryDefinition qdef,
                                                    T handle)

Execute a SPARQL "SELECT" query.

Type Parameters:

T - the type of SPARQLResultsReadHandle to return

Parameters:

qdef - the query

handle - the handle capable of reading sparql results

Returns:

the results in the provided SPARQLResultsReadHandle

executeSelect

<T extends SPARQLResultsReadHandle> T executeSelect(SPARQLQueryDefinition qdef,
                                                    T handle,
                                                    Transaction tx)

Execute a SPARQL "SELECT" query.

Type Parameters:

T - the type of SPARQLResultsReadHandle to return

Parameters:

qdef - the query

handle - the handle capable of reading sparql results

tx - the transaction context for this operation

Returns:

the results in the provided SPARQLResultsReadHandle

executeSelect

<T extends SPARQLResultsReadHandle> T executeSelect(SPARQLQueryDefinition qdef,
                                                    T handle,
                                                    long start)

Execute a SPARQL "SELECT" query.

Type Parameters:

T - the type of SPARQLResultsReadHandle to return

Parameters:

qdef - the query

handle - the handle capable of reading sparql results

start - when paging through results, the first result of this page--must be > 0. Use together with setPageLength(long).

Returns:

the results in the provided SPARQLResultsReadHandle

executeSelect

<T extends SPARQLResultsReadHandle> T executeSelect(SPARQLQueryDefinition qdef,
                                                    T handle,
                                                    long start,
                                                    Transaction tx)

Execute a SPARQL "SELECT" query.

Type Parameters:

T - the type of SPARQLResultsReadHandle to return

Parameters:

qdef - the query

handle - the handle capable of reading sparql results

start - when paging through results, the first result of this page--must be > 0. Use together with setPageLength(long).

tx - the transaction context for this operation

Returns:

the results in the provided SPARQLResultsReadHandle

getPageLength

long getPageLength()

Returns:

the currently set pageLength or -1 if no page length has been set

setPageLength

void setPageLength(long pageLength)

Set a page length for all SPARQL "SELECT" queries sent by this instance.

Parameters:

pageLength - the non-negative number of results per page

clearPageLength

void clearPageLength()

Reset this instance to have no page length set.

executeConstruct

<T extends TriplesReadHandle> T executeConstruct(SPARQLQueryDefinition qdef,
                                                 T handle)

Execute a SPARQL "CONSTRUCT" statement.

Type Parameters:

T - the type of TriplesReadHandle to return

Parameters:

qdef - the SPARQL "CONSTRUCT" statement

handle - the handle capable of reading triples or quads results

Returns:

the results in the provided TriplesReadHandle

executeConstruct

<T extends TriplesReadHandle> T executeConstruct(SPARQLQueryDefinition qdef,
                                                 T handle,
                                                 Transaction tx)

Execute a SPARQL "CONSTRUCT" statement.

Type Parameters:

T - the type of TriplesReadHandle to return

Parameters:

qdef - the SPARQL "CONSTRUCT" statement

handle - the handle capable of reading triples or quads results

tx - the transaction context for this query

Returns:

the results in the provided TriplesReadHandle

executeDescribe

<T extends TriplesReadHandle> T executeDescribe(SPARQLQueryDefinition qdef,
                                                T handle)

Execute a SPARQL "DESCRIBE" query (which implements the Concise Bounded Description specification).

Type Parameters:

T - the type of TriplesReadHandle to return

Parameters:

qdef - the query

handle - the handle capable of reading triples or quads results

Returns:

the results in the provided TriplesReadHandle

executeDescribe

<T extends TriplesReadHandle> T executeDescribe(SPARQLQueryDefinition qdef,
                                                T handle,
                                                Transaction tx)

Execute a SPARQL "DESCRIBE" query (which implements the Concise Bounded Description specification).

Type Parameters:

T - the type of TriplesReadHandle to return

Parameters:

qdef - the query

handle - the handle capable of reading triples or quads results

tx - the transaction context for this query

Returns:

the results in the provided TriplesReadHandle

executeAsk

java.lang.Boolean executeAsk(SPARQLQueryDefinition qdef)

Execute a SPARQL "ASK" statement.

Parameters:

qdef - the SPARQL "CONSTRUCT" statement

Returns:

the answer as Boolean

executeAsk

java.lang.Boolean executeAsk(SPARQLQueryDefinition qdef,
                             Transaction tx)

Execute a SPARQL "ASK" statement.

Parameters:

qdef - the SPARQL "CONSTRUCT" statement

tx - the transaction context for this query

Returns:

the answer as Boolean

executeUpdate

void executeUpdate(SPARQLQueryDefinition qdef)

Execute a SPARQL update statement. For an example of using with permisisons see permission(java.lang.String, com.marklogic.client.semantics.Capability...).

Parameters:

qdef - the SPARQL update statement

executeUpdate

void executeUpdate(SPARQLQueryDefinition qdef,
                   Transaction tx)

Execute a SPARQL update statement. For an example of using with permisisons see permission(java.lang.String, com.marklogic.client.semantics.Capability...).

Parameters:

qdef - the SPARQL update statement

tx - the transaction context for this operation

permission

GraphPermissions permission(java.lang.String role,
                            Capability... capabilities)

For use with SPARQL update, where specified permissions will apply to any records created by the update. Create a GraphPermissions builder object with the specified role and capabilities.

For example:

    String sparqlUpdate = "INSERT DATA { <a> <b> <c> }";
    SPARQLQueryDefinition qdef = sparqlMgr.newQueryDefinition(sparqlUpdate);
    qdef.setUpdatePermissions(sparqlMgr.permission("rest-reader", Capability.UPDATE));
    sparqlMgr.executeUpdate(qdef);

Parameters:

role - the name of the role receiving these capabilities

capabilities - the capabilities (READ, UPDATE, or EXECUTE) granted to this role

Returns:

the new GraphPermissions object with these capabilities set