Loading TOC...
Matches for cat:rest-api (cat:rest-api (url-encode)) have been highlighted. remove

MarkLogic Server 11.0 Product Documentation
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:

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.

See Also

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>

Stack Overflow iconStack Overflow: Get the most useful answers to questions from the MarkLogic community, or ask your own question.