SPARQL querying

In this guide, we’ll use different scenarios to go through the REST API methods (detailing the different headers and basic request bodies) you can use to perform SPARQL queries in your Carbon LDP platform.

We have created a Postman Collection with all the examples featured in this documentation. The examples for this section are contained in the sparql-querying folder.

Introduction

Carbon LDP resources can be queried using SPARQL, a W3C standard query language.

The more you know…

SPARQL is the standard query language and protocol for retrieving Linked Data from the web or RDF triple stores. Basically, if your information follows the RDF standard of being composed by a subject, predicate, and object, which it does when it is stored in Carbon LDP, it can be queried by SPARQL.

 

SPARQL has some similarities to SQL, the Structured Query Language for relational databases, but there are also fundamental differences. The main difference with SPARQL is that, instead of filtering results to get a desired outcome (like in SQL), you apply patterns that are tested over the data to retrieve results. These patterns are given along with a query form to define the shape of the results.

There are four different query forms:

  • SELECT
    • Returns the matched data in a table-like structure
  • ASK
    • Returns true or false indicating wheter any data matched the patterns(s).
  • CONSTRUCT
    • Restructures the matched data into a graph described by a specified template
  • DESCRIBE
    • Returns a description of how the data is internally stored

A pattern is defined by using three elements:

  1. Subject: any document, fragment or named fragment referenced by a URI
  2. Predicate: the name or URI of a property of the resource
  3. Object: the value of the property

For example, if we wanted to match a document that represented a project which has the property ex:name with the value "Project X", we could use the pattern:

  1. Subject: project-x/(the project’s ID/URI)
  2. Predicate: ex:name
  3. Object: "Project X"

This example pattern fully defines all of its elements. Each pattern element has the exact value we’re trying to match. But querying involves retrieving more data than we already have, so any pattern element can also be a variable.

A variable acts like a wildcard, matching any values the pattern element can have. But unlike wildcards, a variable stores any value it matches (you can think of them kind of like the columns requested on SQL queries).

Executing a SPARQL query

Create the POST request

Create the following HTTP request to execute a SPARQL query on the platform.

POST http://localhost:8083/

HTTP Header Value Required/Optional
Content-Type application/sparql-query Required
Accept application/json or application/xml Optional (defaults to application/sparql-results+xml)
PREFIX ex: <http://example.org/ns#>

ASK {
    ?s ex:name "Project X"
}

Review the POST request

It is important that before issuing this request, you understand all its parts. Next, you’ll get more information about each part in the request.

Content-Type
Since the request method is POST it requires a body. Therefore, the Content-Type HTTP header tells the platform what kind of content to expect in the body of the request. In the examples we use application/sparql-query (SPARQL) because we are describing a SPARQL query that we need the platform to execute. Note that it is essential that you include this header with the appropriate value. Otherwise, if you include the header with a valid value other than application/sparql-query your request might be accepted by the platform and a new document can be accidentally created, instead of running a SPARQL query.
Accept
Because of the different results that can be obtained from an SPARQL query, this header will vary depending on the query form that you are executing. Both the SELECT and ASK query forms return simple values . Therefore, the platform supports returning either JSON (application/sparql-results+json) or XML (application/sparql-results+xml) serialized SPARQL result formats. On the other hand, the DESCRIBE and CONSTRUCT forms are expected to return RDF graphs. Hence, the platform’s response can include different RDF Dataset Languages supported by Carbon LDP. The expected response bodies will have one of the following formats, based on the query form used:

  • SELECT:
    • Serialized JSON SPARQL result (application/sparql-result+json)
    • Serialized XML SPARQL result (application/sparql-result+xml)
  • ASK:
    • Serialized JSON SPARQL result (application/sparql-result+json)
    • Serialized XML SPARQL result (application/sparql-result+xml)
  • DESCRIBE: RDF Dataset Languages like:
    • JSON-LD: application/ld+json
    • TriG: application/trig
    • Turtle: application/turtle
    • RDF XML: application/rdf+xml
  • CONSTRUCT: RDF Dataset Languages like:
    • JSON-LD: application/ld+json
    • TriG: application/trig
    • Turtle: application/turtle
    • RDF XML: application/rdf+xml
Body
The body of the request is a SPARQL query. For this example we are executing an ASK query to check if any document in our platform contains the property ex:name with the value "Project X". Carbon LDP can also execute SELECT, DESCRIBE, and CONSTRUCT queries using this method. If there is anything from the request body you don’t understand you can check the SPARQL W3C specifications, which Carbon LDP complies to.

Issue the POST request

A successful request will result in HTTP status code 200 OK.

HTTP Header Value
Content-Type application/sparql-result+json or application/sparql-result+xml

As part of the response headers:

  • The Content-Type will describe the format in which the result of the query is returned. If you set an Accept header for your request it will conform to this format.

Furthermore, the response body will contain the result obtained from your query. Naturally, this result may vary depending on the documents that you have in your platform when running the query. For this example, you should get something like this:

{
    "head": {},
    "boolean": true
}
<?xml version='1.0' encoding='UTF-8'?>
<sparql xmlns='http://www.w3.org/2005/sparql-results#'>
    <head></head>
    <boolean>true</boolean>
</sparql>
Try it out… While in this guide we only presented the example of how to execute an ASK query, we have included examples of the other query forms supported by Carbon LDP in our Postman Collection in the sparql-querying folder. Feel free to experiment with them.

Conclusion

In this guide we have described the proper way of executing SPARQL queries on the platform via the REST API. Normally, developers will prefer use of the Carbon LDP Workbench (GUI) and an SDK, which together simplify the process of building and working with the platform. Still, all functions of the platform can be accessed through the REST API and those developers who understand the REST API may find it advantageous to use in some cases.

Want to know more?

Now that you understand how to query with SPARQL using the REST API, you may want to learn more about the SPARQL language. We recommend the following references:

 

RDF Icon

SPARQL 1.1 Overview

Introduction from the W3C.

RDF IconSPARQL 1.1 Query Language

Specification from the W3C.

RDF IconLearning SPARQL

Book about Querying and Updating with SPARQL 1.1, by Bob DuCharme, O’REILLY®.

 

Finally, you might be interested in knowing how you can make the most of using SPARQL within Carbon LDP. We have documented some recipes for advanced document reading that you might find useful when working with the platform, check them out here.