SPARQL querying
Introduction
Carbon LDP™ resources can be queried using SPARQL, a W3C standard query language.
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
orfalse
indicating wheter any data matched the patterns(s).
- Returns
- 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:
- Subject: any document, fragment or named fragment referenced by a URI
- Predicate: the name or URI of a property of the resource
- 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:
- Subject:
project-x/
(the project’s ID/URI) - Predicate:
ex:name
- 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
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-results+json
) - Serialized XML SPARQL result (
application/sparql-results+xml
)
- Serialized JSON SPARQL result (
- ASK:
- Serialized JSON SPARQL result (
application/sparql-results+json
) - Serialized XML SPARQL result (
application/sparql-results+xml
)
- Serialized JSON SPARQL result (
- DESCRIBE: RDF Dataset Languages like:
-
- JSON-LD:
application/ld+json
- TriG:
application/trig
- Turtle:
application/turtle
- RDF XML:
application/rdf+xml
- JSON-LD:
- CONSTRUCT: RDF Dataset Languages like:
-
- JSON-LD:
application/ld+json
- TriG:
application/trig
- Turtle:
application/turtle
- RDF XML:
application/rdf+xml
- JSON-LD:
Body
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>
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:
Introduction from the W3C.
Specification from the W3C.
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.