POST /v1/graphs/sparql

Summary

Perform a SPARQL query or SPARQL Update on one or more graphs. These two operations are mutually exclusive.

URL Parameters
query?	A URL-encoded SPARQL query operation. You should only use this parameter when you put request parameters in the request body and use `application/x-www-form-urlencoded` as the request content type. You cannot use this parameter in conjunction with the `update` parameter.
update?	A URL-encoded SPARQL Update operation. You should only use this parameter when you put request parameters in the request body and use `application/x-www-form-urlencoded` as the request content type. You cannot use this parameter in conjunction with the `query` parameter.
default-graph-uri*	The URI of the graph or graphs to use as the default graph. Use with SPARQL query only.
named-graph-uri*	The URI of a named graph or graphs to include in the query operation. Use with SPARQL query only.
using-graph-uri*	The URI of the graph or graphs to address as part of a SPARQL Update operation. Use with SPARQL Update only.
using-named-graph-uri*	The URI of a named graph or graphs to address as part of a SPARQL Update operation. Use with SPARQL Update only.
database?	Perform this operation on the named content database instead of the default content database associated with the REST API instance. Using an alternative database requires the "eval-in" privilege; for details, see Security Requirements in the REST Application Developer's Guide.
dedup?	Enable de-duplication capability. Valid values are `on` (default) or `off`.
base?	The initial base IRI for the query.
default-permissions?	This parameter is deprecated. Use `perm:{role}*` instead. The permissions to use when creating a new graph. If not supplied, the user's default permissions will be used. This parameter is ignored if the operation is not creating a graph.
perm:{role}*	Assign the specified permission to any graphs created on behalf of a SPARQL update operation. The parameter should be of the form perm:role=capability. For example, `perm:editor=update`. Valid capability values: `read, update, insert, execute`.
txid?	The transaction identifier of the multi-statement transaction in which to service this request. Use the `/transactions` service to create and manage multi-statement transactions.
start?	The index of the first result to return. Results are numbered beginning with 1. Default: 1. This parameter only applies when evaluating a SPARQL SELECT query.
pageLength?	The maximum number of results to return in this request. By default, all results are returned. This parameter is only applies when evaluating a SPARQL SELECT query.
q?	A string query. For syntax details, see Searching Using String Queries in the Search Developer's Guide. and `search:search`.
structuredQuery?	A structured search query string. That is, a serialized representation of a `search:query` element. See Searching Using Structured Queries in the Search Developer's Guide.
options?	The name of query options previously created via a PUT or POST request to the `/v1/config/query` service.
collection*	Filter results to include only matches in the named collection(s).
directory?	Filter results to include only matches from documents in the specified database directory.
ruleset*	The name of rulesets to include for inferring triples. Ruleset names can be those of the built-in rulesets, or user-managed rulesets stored in the schemas database.
default-rulesets?	A flag whether to include database-default inference or not. Valid values are `include` (default) or `exclude`.
optimize?	A number indicating how much time for the query engine to spend analyzing a query. (See sem:sparql.)
bind:{name}*	A binding name and value. This format assumes that the type of the bind variable is an IRI.
bind:{name}:{type}*	A binding name, type, and value. This parameter format accepts any XSD type, or a two-character language code.
bind:{name}@{lang}*	A binding name, type, and value. Use this pattern to bind to language-tagged strings.
timestamp?	A timestamp returned in the `ML-Effective-Timestamp` header of a previous request. Use this parameter to iteratively fetch SPARQL query results based on the database contents at a fixed point-in-time. For more details, see Performing Point-in-Time Operations in the REST Application Developer's Guide. You cannot use this parameter with a SPARQL update.

Request Headers
Accept*	The expected MIME type of the response when performing a query. The response MIME type depends on the type of information generated by the query. For details, see Response Output Formats in the Semantic Graph Developer's Guide.
Content-type	The MIME type of the query in the request body. Allowed values: `application/x-www-form-urlencoded`, `application/xml`, `application/json`, `application/sparql-query`, `application/sparql-update`.

Response Headers
Content-type	The MIME type of the data in the response body, when performing a query. The MIME type depends on the type of information generated by the query. For details, see Response Output Formats in the Semantic Graph Developer's Guide.
ML-Effective-Timestamp	The system timestamp at which this operation was performed. You can use the value in the `timestamp` parameter of a subsequent request. This header is only returned for SPARQL query requests. For more details, see Performing Point-in-Time Operations in the REST Application Developer's Guide.

Response

Upon success, MarkLogic Server returns status 200 (OK) and the response body contains the query result. The response body will be empty for an update. If your request results in an unsupported format, MarkLogic Server returns status 406 (Not Acceptable).

Required Privileges

SPARQL query operations require the rest-reader role, or the following privilege:

http://marklogic.com/xdmp/privileges/rest-reader

SPARQL Update operations require the rest-reader and the rest-writer role, or the following privileges:

http://marklogic.com/xdmp/privileges/rest-reader

http://marklogic.com/xdmp/privileges/rest-writer

Usage Notes

When you use the query request parameter, this interface implements the POST method of the W3C SPARQL Protocol for query; for details, see http://www.w3.org/TR/2013/REC-sparql11-protocol-20130321#query-operation.

When you use the update request parameter, this interface implements the POST method of the W3C SPARQL Protocol for update; for details, see http://www.w3.org/TR/2013/REC-sparql11-protocol-20130321#update-operation.

You can use this method in the following ways:

Set the request Content-type header to application/x-www-form-urlencoded and encode all parameters in the request body. Set the query parameter for a SPARQL query, or set the update parameter for a SPARQL update.
Set the request Content-type header to application/sparql-query and put a SPARQL query in the request body.
Set the request Content-type header to application/sparql-update and put a SPARQL update in the request body.
Set the request Content-type header to application/xml or application/json and put an XML or JSON combined query in the request body. The combined query should include a sparql XML element or JSON property that contains a serialized SPARQL query and can also include a string query and/or structured, cts, or QBE query. For more information about using combined query, see Specifying Dynamic Query Options with Combined Query in the REST Application Developer's Guide and POST /v1/search.

You can specify the RDF dataset against which to execute the query or update using the named-graph-uri and default-graph-uri request parameters, or within the query or update. If the dataset is specified in both the request parameters and the SPARQL code, the dataset defined by the request parameters is used. If neither is specified, all graphs are included in the operation.

You must not use the using-graph-uri or using-named-graph-uri parameters if your SPARQL Update code uses the USING, USING NAMED, or WITH clause.

If the graph(s) you query use embedded (unmanaged) triples, you can constrain your SPARQL query results to triples occurring in documents that match document search criteria. You can either bundle your SPARQL query, search criteria, and search options in an XML or JSON combined query; or specify the search parameters using the following parameters: q, structuredQuery, and options. Applying document search criteria to graphs containing managed triples is not recommended because it can yield unexpected results when the search matches the internal documents in which triples are stored.

The collection lexicon must be enabled on the database when using the GRAPH "?g" construct in SPARQL queries. Use the Admin Interface to check or enable the collection lexicon.

The response MIME type depends on the type of SPARQL query or SPARQL Update and the Accept header MIME type. The four types of SPARQL query (SELECT, CONSTRUCT, DESCRIBE, ASK) return data in different formats. For details, see Response Output Formats in the Semantic Graph Developer's Guide.

Example

NOTE: Be sure to use --data-binary rather than -d if extracting
the request body from a file with curl, as shown below.

$ cat mexico.sparql
SELECT ?s WHERE {
  ?s 
  <http://dbpedia.org/ontology/birthPlace> 
  <http://dbpedia.org/resource/Mexico> 
}
LIMIT 5

$ curl --anyauth --user user:password -i -X POST \
    --data-binary @./mexico.sparql \
    -H "Content-type: application/sparql-query" \
    -H "Accept: application/sparql-results+xml" \
    http://localhost:8000/v1/graphs/sparql

==> Run a SPARQL query, placing the unencoded query in the POST body.
    MarkLogic Server responds with output similar to the following:

HTTP/1.1 200 OK
Content-type: application/sparql-results+xml
Server: MarkLogic
Content-Length: 213
Connection: Keep-Alive
Keep-Alive: timeout=5

<sparql xmlns="http://www.w3.org/2005/sparql-results#">
  <head>
    <variable name="s"/>
  </head>
  <results>
    <result>
	  <binding name="s">
	    <uri>http://dbpedia.org/resource/Aaron_Herrera</uri>
	  </binding>
	</result>
    <result>
	  <binding name="s">
	    <uri><http://dbpedia.org/resource/Abel_Ramirez></uri>
	  </binding>
	</result>
    <result>
	  <binding name="s">
	    <uri>http://dbpedia.org/resource/Abel_Salazar_(actor)</uri>
	  </binding>
	</result>
    <result>
	  <binding name="s">
	    <uri>http://dbpedia.org/resource/Abigail_Elizalde</uri>
	  </binding>
	</result>
    <result>
	  <binding name="s">
	    <uri>http://dbpedia.org/resource/Abismo_Negro</uri>
	  </binding>
	</result>
  </results>
</sparql>

The following is the equivalent result returned as 
application/sparql-results+json:

{
  "head":{
    "vars":["s"]
	}, 
	"results":{
	  "bindings":[{
	    "s":{
		  "type":"uri", 
		  "value":"http://dbpedia.org/resource/Aaron_Herrera"
		  }}, 
		  {
		"s":{
		  "type":"uri", 
		  "value":"<http://dbpedia.org/resource/Abel_Ramirez>"
		  }}, 
		  {
		"s":{
		  "type":"uri", 
		  "value":"http://dbpedia.org/resource/Abel_Salazar_(actor)"
		  }},
		  {
		"s":{
		  "type":"uri", "value":"http://dbpedia.org/resource/Abigail_Elizalde"
		  }}, 
		  {
		"s":{
		  "type":"uri", 
		  "value":"http://dbpedia.org/resource/Abismo_Negro"
		  }}
		]
	}
}

Example

   => This request uses the encoded version of this SPARQL query:
   SELECT ?s 
   WHERE {
    ?s <http://dbpedia.org/ontology/birthPlace> <http://dbpedia.org/resource/Mexico> 
   }
   
   
$  curl --anyauth --user user:password -i -X POST \
   --data "query=SELECT%20%3Fs%20WHERE%20%7B%3Fs%20%3Chttp%3A%2F%2Fdbpedia.org
   %2Fontology%2FbirthPlace%3E%20%3Chttp%3A%2F%2Fdbpedia.org%2Fresource%
   2FMexico%3E%7D" \
   -H "Content-type:application/x-www-form-urlencoded" \
   -H "Accept:application/sparql-results+xml" \
   http://localhost:8000/v1/graphs/sparql

==> Run a SPARQL query, passing a URL-encoded query as form data.
    MarkLogic Server responds with triples similar to the following:

HTTP/1.1 200 OK
Content-type: application/sparql-results+xml
Server: MarkLogic
Content-Length: 241432
Connection: Keep-Alive
Keep-Alive: timeout=5

<sparql xmlns="http://www.w3.org/2005/sparql-results#"><head><variable name="s"/>
</head><results>
<result><binding name="s"><uri>http://dbpedia.org/resource/Aaron_Herrera
</uri></binding></result>
<result><binding name="s"><uri><http://dbpedia.org/resource/Abel_Ramirez></uri>
</binding></result>
<result><binding name="s"><uri>http://dbpedia.org/resource/Abel_Salazar_(actor)</uri>
</binding></result>
<result><binding name="s"><uri>http://dbpedia.org/resource/Abigail_Elizalde</uri>
</binding></result>
<result><binding name="s"><uri>http://dbpedia.org/resource/Abismo_Negro</uri>
</binding></result>
</sparql>

Example

(: Example using curl with SPARQL Update :)

Note: Put the SPARQL Update into the body of the request. 

curl --anyauth --user user:password -i -X POST \
  -H "Content-type:application/x-www-form-urlencoded" \
  -H "Accept:application/sparql-results+xml" \
  --data-urlencode update='PREFIX dc: <http://purl.org/dc/elements/1.1/>
INSERT DATA{ GRAPH <C1> {<http://example/book1/> dc:title "C book"} }' \
'http://localhost:8000/v1/graphs/sparql'

=>
The SPARQL Update is passed as the URL-encoded value of the request parameter. 
MarkLogic Server responds with triples similar to the following:

HTTP/1.1 200 OK
Content-type: application/sparql-results+xml; charset=UTF-8
Server: MarkLogic
Content-Length: 82
Connection: Keep-Alive
Keep-Alive: timeout=5

<sparql xmlns="http://www.w3.org/2005/sparql-results#"><head/><results/></sparql>

POST /v1/graphs/sparql

Summary

Response

Required Privileges

Usage Notes

See Also

Example

Example

Example