MarkLogic 10 Product Documentation

Semantic Graph Developer's Guide — Chapter 9

SPARQL Query Parameters

Some of the parameters supported for SPARQL query on the SPARQL endpoint, using POST /v1/graphs/sparql or GET /v1/graphs/sparql, include:

• query - SPARQL query to execute
• default-graph-uri* - The URI of the graph or graphs to use as the default graphs in the query operation. This is addressed as http://host:port/v1/graphs/sparql?default-graph-uri=<default-graph-uri*>
• named-graph-uri* - The URI of the graph or graphs to include in the query operation. This is addressed as http://host:port/v1/graphs/sparql?named-graph-uri=<named-graph-uri*>

  The * indicates that one or more default-graph-uri or named-graph-uri parameters can be specified. The named-graph-uri parameter is used with FROM NAMED and GRAPH in queries to specify the IRI(s) to be substituted for a name within particular kinds of queries. You can have one or more named-graph-uri specified as part of a query.

• database? - The database on which to perform the query.
• base? - The initial base IRI for the query.
• 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 accepts an XSD type, for example string, date or unsignedLong.
• bind:{name}@{lang}* - A binding name, language tag, and value. Use this pattern to bind to language-tagged strings.
• 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. The default is 1.
• pageLength? - The maximum number of results to return in this request.

These optional search query parameters can be used to constrain which documents will be searched with the SPARQL query:

• q? - A string query.
• structuredQuery? - A structured search query string, a serialized representation of a search:query element.
• options? - The name of query options.

If you do not specify a graph name with a query, the UNION of all graphs will be queried. If you specify default-graph-uri, one or more graph names that you specify will be queried (this is not the default graph that contains the unnamed triples). You can also query http://marklogic.com/semantics#default-graph, where unnamed triples are stored.

Any valid IRI can be used for these graph names (for example, /my_graph/ or http://www.example.com/rdf-graph-store/). The default-graph-uri is used to specify one or more default graphs to query as part of the operation, and the named-graph-uri can specify one or more additional graphs to use in the operation. If no dataset is defined, the dataset will include all triples (the UNION of all graphs).

If you specify a dataset in both the request parameters and the query, the dataset defined with named-graph-uri or default-graph-uri takes precedence. When you specify more than one default-graph-uri or named-graph-uri in a query via the REST Client API, the format will be http://host:port/v1/graphs/sparql?named-graph-uri=<named-graph-uri*> for each graph named in the query.

For example, this is a simple REST request to send the SPARQL query in the bills.sparql file and return the results as JSON:

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

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

{"head":{"vars":["bill","title"]}, 
"results":{"bindings":[
   {"bill":{"type":"uri",
   "value":"http://www.rdfabout.com/rdf/usgov/congress/108/
            bills/h1171"},
   "title":{"type":"literal", "value":"H.R. 108/1171: Iris Scan
            Security Act of 2003",
   "datatype":"http://www.w3.org/2001/XMLSchema#string"}},
   {"bill":{"type":"uri",
   "value":"http://www.rdfabout.com/rdf/usgov/congress/108/
            bills/h1314"}, 
   "title":{"type":"literal", "value":"H.R. 108/1314: Screening
            Mammography Act of 2003",
   "datatype":"http://www.w3.org/2001/XMLSchema#string"}},
   {"bill":{"type":"uri",
   "value":"http://www.rdfabout.com/rdf/usgov/congress/108/
            bills/h1384"}, 
   "title":{"type":"literal", "value":"H.R. 108/1384: To amend the
            Railroad Retirement Act of 1974 to eliminate a limitation
            on benefits.", 
   "datatype":"http://www.w3.org/2001/XMLSchema#string"}},
   {"bill":{"type":"uri",
   "value":"http://www.rdfabout.com/rdf/usgov/congress/108/
            bills/h1418"}, 
   "title":{"type":"literal", "value":"H.R. 108/1418: Veterans'
            Housing Equity Act", 
   "datatype":"http://www.w3.org/2001/XMLSchema#string"}},
...
}]}}

In the command line example above, long lines have been broken into multiple lines using the UNIX line continuation character '\' and extra line breaks have been added for readability. Extra line breaks for readability have been added in the results.

SPARQL Update Parameters

In addition to the query parameters, these parameters can be used with SPARQL Update on the POST /v1/graphs/sparql endpoint:

• update - The URL-encoded SPARQL Update operation. Only use this parameter when you put the request parameters in the request body and use application/x-www-form-urlencoded as the request content type.
• using-graph-uri* - The URI of the graph or graphs to address as part of a SPARQL Update operation. This is addressed as http://host:port/v1/graphs/sparql?using-graph-uri=<using-graph-uri*>
• using-named-graph-uri* - The URI of a named graph or graphs to address as part of a SPARQL update operation. This is addressed as http://host:port/v1/graphs/sparql?using-named-graph-uri=<using-named-graph-uri*>
• perm:{role}* - Assign permissions to the inserted graph(s), and the permission has a role and a capability. When you insert a new graph, you can set its permissions to allow a certain capability for a certain role. Valid values for the permissions: read, update, execute. These permissions only apply to newly created graphs. See Managing Graph Permissions for more about permissions.
• 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.
• database? - The database on which to perform the query.
• base? - The initial base IRI for the query.
• 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 accepts an XSD type, for example string, date or unsignedLong.
• bind:{name}@{lang}* - A binding name, language tag, and value. Use this pattern to bind to language-tagged strings.

See Target RDF Graph for more information about graphs. See Querying Triples in the REST Application Developer's Guide for more information about using the REST Client API with RDF triples.

Unsupported Serialization

A GET or POST request for a response in an unsupported serialization yields a 406 Not Acceptable error. If the SPARQL payload fails to parse, the response yields a 400 Bad Request error.

For example:

<rapi:error xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:status-code>400</rapi:status-code>
  <rapi:status>Bad Request</rapi:status>
  <rapi:message-code>RESTAPI-INVALIDCONTENT</rapi:message-code>
  <rapi:message>RESTAPI-INVALIDCONTENT: (err:FOER0000) Invalid content:
  Unexpected Payload: c:\space\example.ttl</rapi:message>
</rapi:error>

For more about the REST Client API error handling, see Error Reporting in the REST Application Developer's Guide.

SPARQL Query Types and Output Formats

When you query the SPARQL endpoint with REST Client APIs (GET /v1/graphs/sparql or POST /v1/graphs/sparql), you can specify the result output format. The response type format depends on the type of query and the MIME type in the HTTP Accept header.

A SPARQL SELECT query can return results as XML, JSON, HTML, or CSV, while a SPARQL CONSTRUCT query can return the results as triples in N-Triples or N-Quads format, or XMLor JSON triples in any of the supported triples formats. A SPARQL DESCRIBE query returns triples in XML, N-Triples, or N-Quads format describing the triples found by the query. Using SPARQL ASK query will return a boolean (true or false) in either XML or JSON. See Types of SPARQL Queries for more information about query types.

This table describes the MIME types and Accept Header/Output formats (MIME type) for different types of SPARQL queries.

You can request any of the triple MIME types (application/rdf+xml, text/turtle, and so on), but use application/n-triples for best performance. See Serialization for details.

The following examples use this SPARQL SELECT query to find US Congress bills that were sponsored by Robert Andrews (A000210):

#filename bills.sparql 
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns> 
PREFIX bill: <http://www.rdfabout.com/rdf/schema/usbill/>
PREFIX people: <http://www.rdfabout.com/rdf/usgov/congress/people/>
PREFIX dc: <http://purl.org/dc/elements/1.1/>

SELECT  ?bill ?title 
WHERE { ?bill rdf:type bill:HouseBill ;
           dc:title ?title ;
           bill:sponsor people:A000210 .
    }
    LIMIT 5

The SPARQL query is saved as bills.sparql. The query limits responses to 5 results. Using curl and the REST Client API, you can query the SPARQL endpoint and get the results back in a variety of formats.

If you use curl to make a PUT or POST request and read in the request body from a file, use --data-binary rather than -d to specify the input file. When you use --data-binary, curl inserts the data from the file into the request body as-is. When you use -d, curl strips newlines from the input, which can make your triple data or SPARQL syntactically invalid.

Example: Returning Results as XML

The SPARQL SELECT query in the bills.sparql file returns the response in XML format in this example.

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

=>

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

<sparql xmlns="http://www.w3.org/2005/sparql-results/">
 <head><variable name="bill"/>
       <variable name="title"/>
 </head>
 <results>
   <result>
     <binding name="bill">
      <uri>http://www.rdfabout.com/rdf/usgov/congress/108/bills/h1171
      </uri>
     </binding><binding name="title">
       <literal datatype="http://www.w3.org/2001/XMLSchema#string">
       H.R. 108/1171: Iris Scan Security Act of 2003
       </literal>
     </binding>
   </result>
   <result>
     <binding name="bill">
      <uri>http://www.rdfabout.com/rdf/usgov/congress/108/bills/h1314/
      </uri>
     </binding>
     <binding name="title">
      <literal datatype="http://www.w3.org/2001/XMLSchema#string">
      H.R. 108/1314: Screening Mammography Act of 2003</literal>
     </binding>
   </result>
   <result>
     <binding name="bill"><uri>http://www.rdfabout.com/rdf/usgov
     /congress/108/bills/h1384/</uri>
     </binding>
...
   </result>
 </results>
</sparql>

In the example above, long lines have been broken into multiple lines using the UNIX line continuation character '\' and extra line breaks have been added for readability. Extra line breaks for readability have also been added in the results.

Example: Returning Results as JSON

The SPARQL SELECT query in the bills.sparql file returns the response in JSON format in this example:

curl --anyauth --user admin:password -i -X POST \
--data-binary @./bills.sparql \
-H "Content-type: application/sparql-query" \
-H "Accept: application/sparql-results+json" \
http://localhost:8050/v1/graphs/sparql

=>

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

{"head":{"vars":["bill","title"]}, 
"results":{"bindings":[
   {"bill":{"type":"uri",
   "value":"http://www.rdfabout.com/rdf/usgov/congress/108/
            bills/h1171"},
   "title":{"type":"literal", "value":"H.R. 108/1171: Iris Scan
            Security Act of 2003",
   "datatype":"http://www.w3.org/2001/XMLSchema#string"}},
   {"bill":{"type":"uri",
   "value":"http://www.rdfabout.com/rdf/usgov/congress/108/
            bills/h1314"}, 
   "title":{"type":"literal", "value":"H.R. 108/1314: Screening
            Mammography Act of 2003",
   "datatype":"http://www.w3.org/2001/XMLSchema#string"}},
   {"bill":{"type":"uri",
   "value":"http://www.rdfabout.com/rdf/usgov/congress/108/
            bills/h1384"}, 
   "title":{"type":"literal", "value":"H.R. 108/1384: To amend the
            Railroad Retirement Act of 1974 to eliminate a limitation
            on benefits.", 
   "datatype":"http://www.w3.org/2001/XMLSchema#string"}},
   {"bill":{"type":"uri",
   "value":"http://www.rdfabout.com/rdf/usgov/congress/108/
            bills/h1418"}, 
   "title":{"type":"literal", "value":"H.R. 108/1418: Veterans'
            Housing Equity Act", 
   "datatype":"http://www.w3.org/2001/XMLSchema#string"}},
...
}]}}

In the command line example above, long lines have been broken into multiple lines using the UNIX line continuation character '\' and extra line breaks have been added for readability. Extra line breaks for readability have also been added in the results.

Example: Returning Results as HTML

The same SPARQL SELECT query in the bills.sparql file returns the response in HTML format in this example:

curl --anyauth --user admin:password -i -X POST \
--data-binary @./bills.sparql \
-H "Content-type: application/sparql-query" \
-H "Accept: text/html" http://localhost:8050/v1/graphs/sparql"

=>

HTTP/1.1 200 OK
Content-type: text/html; charset=UTF-8
Server: MarkLogic
Content-Length: 1448
Connection: Keep-Alive
Keep-Alive: timeout=5

<html xmlns="http://www.w3.org/1999/xhtml">
 <head>
  <title>SPARQL results</title>
 </head>
 <body><table border="1">
 <tr>
  <th>bill</th>
  <th>title</th></tr>
 <tr>
  <td><a href="/v1/graphs/things?iri=http%3a//www.rdfabout.com/
    rdf/usgov/congress/108/bills/h1171">http://www.rdfabout.com/
    rdf/usgov/congress/108/bills/h1171</a>
  </td>
  <td>H.R. 108/1171: Iris Scan Security Act of 2003</td>
 </tr><tr>
  <td><a href="/v1/graphs/things?iri=http%3a//www.rdfabout.com/
    rdf/usgov/congress/108/bills/h1314">http://www.rdfabout.com/
    rdf/usgov/congress/108/bills/h1314</a>
  </td>
  <td>H.R. 108/1314: Screening Mammography Act of 2003</td>
 </tr><tr>
  <td><a href="/v1/graphs/things?iri=http%3a//www.rdfabout.com/
    rdf/usgov/congress/108/bills/h1384">http://www.rdfabout.com/
    rdf/usgov/congress/108/bills/h1384</a>
  </td>
  <td>H.R. 108/1384: To amend the Railroad Retirement Act of
    1974 to eliminate a limitation on benefits.
  </td>
 </tr>
...
 </table>
 </body>
</html>

In the preceding example, long lines have been broken into multiple lines using the UNIX line continuation character '\' and extra line breaks have been added for readability. Extra line breaks for readability have also been added in the results.

Example: Returning Results as CSV

Here is the same SPARQL SELECT query (bills.sparql) with the results returned in CSV format:

curl --anyauth --user Admin:janem-3 -i -X POST --data-binary \
@./bills.sparql -H "Content-type: application/sparql-query" \
-H "Accept: text/csv" http://janem-3:8000/v1/graphs/sparql
=>
bill,title

http://www.rdfabout.com/rdf/usgov/congress/108/bills/h1171,H.R. 108/1171: Iris Scan Security Act of 2003

http://www.rdfabout.com/rdf/usgov/congress/108/bills/h1314,H.R. 108/1314: Screening Mammography Act of 2003

http://www.rdfabout.com/rdf/usgov/congress/108/bills/h1384,H.R. 108/1384: To amend the Railroad Retirement Act of 1974 to eliminate a limitation on benefits.

http://www.rdfabout.com/rdf/usgov/congress/108/bills/h1418,H.R. 108/1418: Veterans' Housing Equity Act

http://www.rdfabout.com/rdf/usgov/congress/108/bills/h1419,H.R. 108/1419: Seniors' Family Business Enhancement Act[jmckean@janem-3 ~]$

In the preceding example, long lines have been broken into multiple lines using the UNIX line continuation character '\' and extra line breaks have been added for readability. Extra line breaks for readability have also been added in the results.

Example: Returning Results as N-triples

For this example, we will use a DESCRIBE query that was introduced and used earlier:

DESCRIBE <http://dbpedia.org/resource/Pascal_Bedrossian>

The following command uses this query to match triples that describe Pascal and return the results as N-Triples. Long lines in the command below have been broken with the UNIX line continuation character \. The query is URL encoded and passed as the value of the query request parameter.

curl -X GET --digest --user "admin:password" \
-H "Accept: application/n-triples" \
-H "Content-type: application/x-www-form-urlencoded"\
"http://localhost:8321/v1/graphs/sparql?query=DESCRIBE%20%3Chttp\
%3A%2F%2Fdbpedia.org%2Fresource%2FPascal_Bedrossian%3E"
=>
<http://dbpedia.org/resource/Pascal_Bedrossian> <http://dbpedia.org/ontology/birthPlace> <http://dbpedia.org/resource/France> .
<http://dbpedia.org/resource/Pascal_Bedrossian> <http://dbpedia.org/ontology/birthPlace> <http://dbpedia.org/resource/Marseille> .
<http://dbpedia.org/resource/Pascal_Bedrossian> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://xmlns.com/foaf/0.1/Person> .
<http://dbpedia.org/resource/Pascal_Bedrossian> <http://xmlns.com/foaf/0.1/surname> "Bedrossian"@en .
<http://dbpedia.org/resource/Pascal_Bedrossian> <http://xmlns.com/foaf/0.1/givenName> "Pascal"@en .
<http://dbpedia.org/resource/Pascal_Bedrossian> <http://xmlns.com/foaf/0.1/name> "Pascal Bedrossian"@en .
<http://dbpedia.org/resource/Pascal_Bedrossian> <http://purl.org/dc/elements/1.1/description> "footballer"@en .
<http://dbpedia.org/resource/Pascal_Bedrossian> <http://dbpedia.org/ontology/birthDate> "1974-11-28"^^<http://www.w3.org/2001/XMLSchema#date> .

Example: Returning a Boolean as XML or JSON

In this example, a SPARQL ASK query (from an earlier example) is used to determine whether Carolyn Kennedy was born after Eunice Kennedy.

Here are the contents of the ask-sparql.sparql file used in the following query:

#file: ask-sparql.sparql
PREFIX db: <http://dbpedia.org/resource/>
PREFIX onto: <http://dbpedia.org/ontology/>
ASK
{
    db:Carolyn_Bessette-Kennedy onto:birthDate ?by .
    db:Eunice_Kennedy_Shriver onto:birthDate ?bd .
    FILTER (?by>?bd).
}

If you use curl to make a PUT or POST request and read in the request body from a file, use --data-binary rather than -d to specify the input file. When you use --data-binary, curl inserts the data from the file into the request body as-is. When you use -d, curl strips newlines from the input, which can make your triple data or SPARQL syntactically invalid.

This request, containing SPARQL ASK query, returns the boolean result as XML:

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

=>

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

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

Here is the same request (containing the SPARQL ASK query) where the boolean result is returned as JSON:

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

=>

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

{"boolean":true}

SPARQL Queries in a POST Request

This section describes how SPARQL query can be used to manage graphs and triple data through /v1/graphs/sparql endpoint.

http://hostname:port/v1/graphs/sparql

where the hostname and port are the host and port on which you are running MarkLogic.

You can specify your input SPARQL query to POST /v1/graphs/sparql in the following ways:

• Include a SPARQL query as a file in the POST body
• Include the SPARQL query as URL-encoded data

This is a SPARQL DESCRIBE query used to find out about US Congress bill 44. The query is saved as a file, named bill44.sparql.

#file name bill44.sparql
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns> 
PREFIX bill: <http://www.rdfabout.com/rdf/schema/usbill/>
DESCRIBE ?x WHERE { ?x rdf:type bill:HouseBill ; 
                       bill:number "44" . }

If you use curl to make a PUT or POST request and read in the request body from a file, use --data-binary rather than -d to specify the input file. When you use --data-binary, curl inserts the data from the file into the request body as-is. When you use -d, curl strips newlines from the input, which can make your triple data or SPARQL syntactically invalid.

The endpoint requires a SPARQL query to be either a parameter or in the POST body. In the following example, the bill44.sparql file with the DESCRIBE query is passed to the body of the POST request:

# Windows users, see Modifying the Example Commands for Windows  
curl --anyauth --user admin:password \
-i -X POST --data-binary @./bill44.sparql \
-H "Content-type: application/sparql-query" \
-H "Accept: application/rdf+xml" \
http://localhost:8000/v1/graphs/sparql 

The request body MIME type is specified as application/sparql-query and the requested response MIME type (the Accept:) is specified as application/rdf+xml. The output is returned as triples in XML format. See Response Output Formats for more details.

The query returns the following triples describing bill 44:

<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns">
 <OfficialTitle rdf:ID="bnodebnode309771418819f878"
    xmlns="http://www.rdfabout.com/rdf/schema/usbill/">
  <rdf:typerdf:resource="http://www.rdfabout.com/rdf/schema/usbill
    /OfficialTitle"/>
  <rdf:value rdf:datatype="http://www.w3.org/2001/XMLSchema#string">
    To amend the Internal Revenue Code of 1986 to provide reduced
    capital gain rates for qualified economic stimulus gain and to 
    index the basis of assets of individuals for purposes of 
    determining gains and losses.</rdf:value></OfficialTitle>
 <ShortTitle rdf:ID="bnodebnode30b47143b819db78"
   xmlns="http://www.rdfabout.com/rdf/schema/usbill/">
  <rdf:type rdf:resource="http://www.rdfabout.com/rdf/schema/usbill
   /ShortTitle"/>
  <rdf:value rdf:datatype="http://www.w3.org/2001/XMLSchema#string">
   Investment Tax Incentive Act of 2003</rdf:value></ShortTitle>
 <ShortTitle rdf:ID="bnodebnodee1860b72fb58b315"
   xmlns="http://www.rdfabout.com/rdf/schema/usbill/">
  <rdf:type rdf:resource="http://www.rdfabout.com/rdf/schema/usbill
   /ShortTitle"/>
  <rdf:value rdf:datatype="http://www.w3.org/2001/XMLSchema#string">
   Investment Tax Incentive Act of 2003</rdf:value></ShortTitle>
 <HouseBill rdf:about="http://www.rdfabout.com/rdf/usgov/congress/108
   /bills/h44" xmlns="http://www.rdfabout.com/rdf/schema/usbill/">
 <inCommittee rdf:resource="http://www.rdfabout.com/rdf/usgov
   /congress/committees/HouseWaysandMeans"/>
 <cosponsor rdf:resource="http://www.rdfabout.com/rdf/usgov/congress
   /people/A000358"/>
 <cosponsor rdf:resource="http://www.rdfabout.com/rdf/usgov/congress
   /people/B000208"/>
 <cosponsor rdf:resource="http://www.rdfabout.com/rdf/usgov/congress
   /people/B000575"/>
 <cosponsor 
.....

Another way to use the POST request is to specify the URL-encoded query as the value of the query parameter and use application/x-www-form-urlencoded as the request body MIME type, as described in the Semantics documentation of the REST Client API.

The following SPARQL SELECT query finds the House of Congress bills that were cosponsored by the person with a Congress BioGuideID of A000358:

PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns> 
PREFIX bill: <http://www.rdfabout.com/rdf/schema/usbill/>
PREFIX people: <http://www.rdfabout.com/rdf/usgov/congress/people/>
SELECT ?x WHERE { ?x rdf:type bill:HouseBill ; bill:cosponsor  people:A000358. }

In this example, the SELECT query is URL-encoded and then sent as form-encoded data:

curl -X POST --anyauth --user admin:password \
-H "Accept:application/sparql-results+xml" --data-binary \
"query=PREFIX%20rdf%3A%20%3Chttp%3A%2F%2Fwww.w3.org%2F1999%2F02%2F22-r
df-syntax-ns\
%23%3E%20%0APREFIX%20bill%3A%20%3Chttp%3A%2F%2Fwww.rdfabout.com%2Frdf\
%2Fschema%2Fusbill%2F%3E%0APREFIX%20people%3A%20%3Chttp%3A%2F%2Fwww.rdfabout.com\
%2Frdf%2Fusgov%2Fcongress%2Fpeople%2F%3E%0ASELECT%20%3Fx%20WHERE%20%7B%20%3Fx\
%20rdf%3Atype%20bill%3AHouseBill%20%3B%20bill%3Acosponsor%20%20people%3AA000358.%20%7D%0A"\
-H "Content-type:application/x-www-form-urlencoded" \
http://localhost:8000/v1/graphs/sparql
=>

<sparql xmlns="http://www.w3.org/2005/sparql-results/">
   <head><variable name="x"/></head>
  <results>
    <result><binding name="x">
     <uri>http://www.rdfabout.com/rdf/usgov/congress/108/bills/h1036
     </uri></binding></result> 
    <result><binding name="x"> 
     <uri>http://www.rdfabout.com/rdf/usgov/congress/108/bills/h1057
     </uri></binding></result>
    <result><binding name="x"> 
     <uri>http://www.rdfabout.com/rdf/usgov/congress/108/bills/h1078
     </uri></binding></result> 
    <result><binding name="x">
     <uri>http://www.rdfabout.com/rdf/usgov/congress/108/bills/h110
     </uri></binding></result>
    <result><binding name="x">
     <uri>http://www.rdfabout.com/rdf/usgov/congress/108/bills/h1117
     </uri></binding></result>
    <result><binding name="x">
     <uri>http://www.rdfabout.com/rdf/usgov/congress/108/bills/h1153
     </uri></binding></result>
.......
    <result><binding name="x">
     <uri>http://www.rdfabout.com/rdf/usgov/congress/108/bills/h975
     </uri></binding></result>
  </results>
</sparql>

For readability, the long command line is broken into multiple lines using the UNIX line continuation character '\'. Extra line breaks have been inserted for readability of the URL-encoded query.

SPARQL Queries in a GET Request

For a GET request, the SPARQL query in the query request parameter must be URL-encoded. Here is the SPARQL DESCRIBE query, searching for a US Congress bill (44), before it is encoded:

PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
PREFIX bill: <http://www.rdfabout.com/rdf/schema/usbill/>
DESCRIBE ?x 
WHERE { 
  ?x rdf:type bill:HouseBill ;
    bill:number "44" . }

In this example curl sends an HTTP GET request to execute the SPARQL DESCRIBE query :

curl -X GET --digest --user "user:password" \
-H "accept: application/sparql-results+xml" \
"http://localhost:8000/v1/graphs/sparql?query=PREFIX%20rdf%3A%20%3C\
http%3A%2F%2Fwww.w3.org%2F1999%2F02%2F22-rdf-syntax-ns%23%3E%20%0A\
PREFIX%20bill%3A%20%3Chttp%3A%2F%2Fwww.rdfabout.com%2Frdf%2Fschema\
%2Fusbill%2F%3E%0ADESCRIBE%20%3Fx%20WHERE%20%7B%20%3Fx%20rdf%3Atype\
%20bill%3AHouseBill%20%3B%20%20bill%3Anumber%20%2244%22%20.%20%7D"

Your results will be similar to these triples:

<http://www.rdfabout.com/rdf/usgov/congress/108/bills/h44>
<http://purl.org/dc/elements/1.1/title> "H.R. 108/44: Investment Tax
Incentive Act of 2003" .

<http://www.rdfabout.com/rdf/usgov/congress/108/bills/h44>
<http://purl.org/dc/terms/created> "2003-01-07" .

<http://www.rdfabout.com/rdf/usgov/congress/108/bills/h44>
<http://purl.org/ontology/bibo/shortTitle> "H.R. 44: Investment Tax
Incentive Act of 2003" .

<http://www.rdfabout.com/rdf/usgov/congress/108/bills/h44>
<http://www.rdfabout.com/rdf/schema/usbill/congress> "108" .

<http://www.rdfabout.com/rdf/usgov/congress/108/bills/h44>
<http://www.rdfabout.com/rdf/schema/usbill/cosponsor>
<http://www.rdfabout.com/rdf/usgov/congress/people/A000358> .

<http://www.rdfabout.com/rdf/usgov/congress/108/bills/h44>
<http://www.rdfabout.com/rdf/schema/usbill/cosponsor>
<http://www.rdfabout.com/rdf/usgov/congress/people/B000208> .

<http://www.rdfabout.com/rdf/usgov/congress/108/bills/h44>
<http://www.rdfabout.com/rdf/schema/usbill/cosponsor>
<http://www.rdfabout.com/rdf/usgov/congress/people/B000575> .

The triples describe information about bill 44 in the U.S. Congress; it's title, when it was created, who cosponsored the bill, and so on.

SPARQL Update in a POST Request

You can send requests using the POST method by including SPARQL Update in the request body. Set the Content-type HTTP header to application/sparql-update.

Here is the SPARQL Update before it is added to the request body:

PREFIX dc: <http://purl.org/dc/elements/1.1/> 
WITH <BOOKS> 
DELETE {?b dc:title "A new book"} 
INSERT
{?b dc:title "Inside MarkLogic Server" }
WHERE {?b dc:title "A new book".}

In the graph named <BOOKS>, SPARQL Update matches a triple with dc:title in the predicate position and A new book in the object position and deletes it. Then a new triple is inserted (?b dc:title "MarkLogic Server").

In this example, the SPARQL Update is sent in the request body using application/sparql-update and the -d option for the query:

# Windows users, see Modifying the Example Commands for Windows  

curl --anyauth --user admin:admin -i -X POST \
-H "Content-type:application/sparql-update" \
-H "Accept:application/sparql-results+xml" \
-d 'PREFIX dc: <http://purl.org/dc/elements/1.1/> \
WITH <BOOKS> \
DELETE {?b dc:title "A new book"} \
INSERT {?b dc:title "Inside MarkLogic Server" } \
WHERE {?b dc:title "A new book".}' \
http://localhost:8000/v1/graphs/sparql

For clarity, long command lines are broken into multiple lines using the line continuation characters \ . Remove the line continuation characters when you use the curl command. (For Windows the line continuation character is ^.)

Alternatively, you can use curl to execute a SPARQL Update from a file as part of a POST request. The SPARQL Update is saved in a file named booktitle.sparql. Here are the file contents:

PREFIX dc: <http://purl.org/dc/elements/1.1/>
INSERT DATA
{
<http://example/book1> dc:title "book title" ;
dc:creator "author name" .
}

The POST request with the SPARQL Update in a file would look like this:

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

Notice that the request uses the --data-binary option instead of -d to call the file containing the SPARQL Update. You can include using-graph-uri, using-named-graph-uri and role-capability as HTTP request parameters. The perm parameter is expected in this syntax, with role and capability.

perm:admin=update&perm:admin=execute

See Default Permissions and Required Privileges for more about permissions.

SPARQL Update via POST with URL-encoded Parameters

You can also send update protocol requests via the HTTP POST method by URL-encoding the parameters. When you do this, URL percent-encode all parameters and include them as parameters within the request body via the application/x-www-form-urlencoded media type. The content type header of the HTTP request is set to application/x-www-form-urlencoded.

This next example uses SPARQL Update and POST with URL-encoded parameters to insert data (along with a set of permissions) into graph C1.

curl --anyauth --user admin:admin -i -X POST \
--data-urlencode update='PREFIX dc: <http://purl.org/dc/elements/1.1/> \
INSERT DATA \
{<http://example/book1> dc:title "book title" ; \
dc:creator "author name" .}' \
-H "Content-type:application/x-www-form-urlencoded" \
-H "Accept:application/sparql-results+xml" \
'http://localhost:8000/v1/graphs/sparql?using-named-graph-uri=C1 \
&perm:admin=update&perm:admin+execute'

If you supply the using-graph-uri or using-named-graph-uri parameters when using this protocol to convey a SPARQL 1.1 Update request that uses the USING NAMED, or WITH clause, the operation will result in an error.

This curl example uses POST with URL-encoding for the SPARQL Update and permissions:

curl --anyauth --user admin:admin -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"} }' \
--data-urlencode perm:rest-writer=read \
--data-urlencode perm:rest-writer=update \
http://localhost:8321/v1/graphs/sparql

If a new RDF graph is created, the server responds with a 201 Created message. The response to an update request indicates success or failure of the request via HTTP response status code (200 or 400). If the request body is empty, the server responds with 204 No Content.

Default Permissions and Required Privileges

All graphs created and managed using the REST Client API 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.

For example, if you create a new graph using PUT /v1/graphs and do not specify any permissions, the graph will have permissions similar to the following:

<metadata xmlns="http://marklogic.com/rest-api">
  <permissions>
    <permission>
      <role-name>rest-writer</role-name>
      <capability>update</capability>
    </permission>
    <permission>
      <role-name>rest-reader</role-name>
      <capability>read</capability>
    </permission>
  </permissions>
</metadata>

{"permissions":[
  {"role-name":"rest-writer",
   "capabilities":["update"]
  },
  {"role-name":"rest-reader",
    "capabilities":["read"]
  }
]}

If you explicitly specify other permissions when creating the graph, the above default permissions are still set, as well as 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 REST Client API to manage or query semantic data.

For details, see Security Requirements in the REST Application Developer's Guide.

Setting Permissions as Part of Another Operation

Use the perm request parameter to set, overwrite, or add permissions as part of another graph operation. To manage permissions when not modifying graph content, use the category parameter instead. For details, see Setting Permissions Standalone.

The perm parameter has the following form:

perm:role=capability

Where role is the name of a role defined in MarkLogic and capability is one of read, insert, update, or execute.

You can specify the perm parameter multiple times to grant multiple capabilities to the same role or set permissions for multiple roles. For example, the following set of parameters grants the readers role the read capability and the writers role the update capability:

perm:readers=read&perm:writers=update

Setting or changing the permissions on a graph does not affect the permissions on documents that contain embedded triples in that graph.

You can use the perm parameter with the following operations:

PUT /v1/graphs?graph=uri&perm:role=capability
PUT /v1/graphs?default&perm:role=capability

POST /v1/graphs/sparql?perm:role=capability

POST /v1/graphs?graph=uri&perm:role=capability
POST /v1/graphs?default&perm:role=capability

The following restrictions apply:

• When you use the perm parameter with /v1/graphs, you must also include either the graph or the default request parameter.
• You cannot use the perm parameter in conjunction with category=permissions or category=metadata.
• When you use the perm parameter to specify permissions as part of a SPARQL Update operation, the permissions only affect graphs created as part of the update. The permissions on pre-existing graphs remain unchanged.

Setting Permissions Standalone

Set the category request parameter to permissions to manage permissions without affecting the contents of a graph. For example, a request of the following form that includes permissions metadata in the request body sets the permissions on the default graph, but does not change the graph contents.

PUT /v1/graphs?default&category=permissions

To set or add permissions along with your graph content, use the perm request parameter. For details, see Setting Permissions as Part of Another Operation.

You can set the category parameter to either permissions or metadata. They are equivalent in the context of graph management.

The request body must contain permissions metadata. In XML, the metadata can be rooted at either a metadata element or the permissions element. Also, in XML, the metadata must be in the namespace http://marklogic.com/rest-api.

For example, all of the following are acceptable:

<metadata xmlns="http://marklogic.com/rest-api">
  <permissions>
    <permission>
      <role-name>roleA</role-name>
      <capability>read</capability>
      <capability>update</capability>
    </permission>
    <permission>
      <role-name>roleB</role-name>
      <capability>read</capability>
    </permission>
  </permissions>
</metadata>

{"permissions":[
  {"role-name":"roleA",
   "capabilities":[
     "read", "update"
   ]
  },
  {"role-name":"roleB",
    "capabilities":["read"]
  }
]}

<permissions 
    xmlns="http://marklogic.com/rest-api">
  <permission>
    <role-name>roleA</role-name>
    <capability>read</capability>
    <capability>update</capability>
  </permission>
  <permission>
    <role-name>roleB</role-name>
    <capability>read</capability>
  </permission>
</permissions>

Setting or changing the permissions on a graph does not effect the permissions on documents that contain embedded triples in that graph.

You can use the category=permissions pattern to manage graph permissions with the following methods. In all cases, the graph contents are unaffected.

PUT /v1/graphs?graph=uri&category=permissions
PUT /v1/graphs?default&category=permissions

POST /v1/graphs?graph=uri&category=permissions
POST /v1/graphs?default&category=permissions

DELETE /v1/graphs?graph=uri&category=permissions
DELETE /v1/graphs?default&category=permissions

The following restrictions apply:

• When you use category=permissions or category=metadata with /v1/graphs, you must also include either the graph or the default request parameter.
• You cannot use category=permissions or category=metadata in conjunction with the perm parameter.

Retrieving Graph Permissions

To retrieve permissions metadata about a named graph, make a GET request of the following form:

GET /v1/graphs?graph=graphURI&category=permissions

To retrieve permissions metadata about the default graph, make a GET request of the following form:

GET /v1/graphs?default&category=permissions

You can request metadata in either XML or JSON. The default format is XML.

For example, the following command retrieves permissions for the graph with URI /my/graph, as XML. In this case, the graph includes both the default rest-writer and read-reader permissions and permissions for a custom role named GroupA.

curl --anyauth --user user:password -X GET -i \
  -H "Accept: application/xml" \
  'http://localhost:8000/v1/graphs?graph=/my/graph&category=permissions'

HTTP/1.1 200 OK
Content-type: application/xml; charset=utf-8
Server: MarkLogic
Content-Length: 868
Connection: Keep-Alive
Keep-Alive: timeout=5

<rapi:metadata uri="/my/graph" ...
     xmlns:rapi="http://marklogic.com/rest-api" ...>
  <rapi:permissions>
    <rapi:permission>
      <rapi:role-name>rest-writer</rapi:role-name>
      <rapi:capability>update</rapi:capability>
    </rapi:permission>
    <rapi:permission>
      <rapi:role-name>rest-reader</rapi:role-name>
      <rapi:capability>read</rapi:capability>
    </rapi:permission>
    <rapi:permission>
      <rapi:role-name>GroupA</rapi:role-name>
      <rapi:capability>read</rapi:capability>
      <rapi:capability>update</rapi:capability>
    </rapi:permission>
  </rapi:permissions>
</rapi:metadata>

The following data is the equivalent permissions metadata, expressed as JSON:

{"permissions":[
  {"role-name":"rest-writer","capabilities":["update"]},
  {"role-name":"rest-reader","capabilities":["read"]},
  {"role-name":"GroupA","capabilities":["read","update"]}
]}