SPARQL - An Absolute Beginner's Guide

This very short tutorial will tell you:

1. What SPARQL is
2. How to build a simple query
3. Building a useful query
4. Requesting SPARQL from WikiData

OK? Let's go!

1. WTF is SPARQL?

SPARQL (pronounced "Sparkle") is a way of querying semantic database.

Wikipedia - the free online encyclopedia - is built on Wikidata. That's a semantic database which is built on "triples". For example:

1. Jill
2. was born in
3. London

or

1. Jill
2. is the child of
3. Jane

This means we can ask the database "give me all the people born in London". Or, "give me all people who Jill is the child of".

SPARQL lets us create queries based on data relationships.

2. A Simple Query

Let's ask WikiData to find all the people who were born in London.

SELECT ?person WHERE {  
  ?person wdt:P19  wd:Q84
} limit 10

That will select 10 people born in London. Here's what each line does.

SELECT ?person WHERE {

Ask the database to assign results to a variable called ?person

?person wdt:P19 wd:Q84

Assign to the variable, data where the property "born in" is the entity "London".

• wdt means property, and P19 means born in.
• wd means entity, and Q84 is the ID of London.

} limit 10

Just get us 10 results.

You can run this query on WikiData

3. Building a more useful query

If you've run that query, you will see that it isn't very useful! It just gives us back a list of IDs. We want human readable information!

Here's how we do it:

SELECT ?person ?personLabel WHERE {
  ?person wdt:P19 wd:Q84;
  SERVICE wikibase:label { bd:serviceParam wikibase:language "[AUTO_LANGUAGE],en". }
} limit 10

I've added two new things here:

?personLabel

This gives us the "Label" - or human readable name - for the result.

SERVICE wikibase:label { bd:serviceParam wikibase:language "[AUTO_LANGUAGE],en". }

This ensures we are querying the English WikiData.

Run the query to see the results

4. Requesting SPARQL from WikiData

As you've seen from the above links, you can use the WikiData editor to craft requests. You can then see the results visually.

If you want to use the results in a program or website, it's a little more complicated.

The easy way

Once you have written out your query, you can URL encode it and send it directly to a SPARQL endpoint. For example:

https://query.wikidata.org/sparql?query=SELECT%20%3Fperson%20%3FpersonLabel%20WHERE%20%7B%0A%20%20%3Fperson%20wdt%3AP19%20wd%3AQ84%3B%0A%20%20SERVICE%20wikibase%3Alabel%20%7B%20bd%3AserviceParam%20wikibase%3Alanguage%20%22%5BAUTO_LANGUAGE%5D%2Cen%22.%20%7D%0A%7D%20limit%2010

You will receive back the results in XML.

The hard - but more useful - way

There are hundreds of different libraries for SPARQL. Whatever your favourite programming language, you will be able to find a way to interact with SPARQL.

Here's a quick snippet of JavaScript which doesn't use a library.

class SPARQLQueryDispatcher {
    constructor( endpoint ) {
        this.endpoint = endpoint;
    }

    query( sparqlQuery ) {
        const fullUrl = this.endpoint + '?query=' + encodeURIComponent( sparqlQuery );
        const headers = { 'Accept': 'application/sparql-results+json' };

        return fetch( fullUrl, { headers } ).then( body => body.json() );
    }
}

const endpointUrl = 'https://query.wikidata.org/sparql';
const sparqlQuery = `SELECT ?person ?personLabel WHERE {
  ?person wdt:P19 wd:Q84;
  SERVICE wikibase:label { bd:serviceParam wikibase:language "[AUTO_LANGUAGE],en". }
} limit 10`;

const queryDispatcher = new SPARQLQueryDispatcher( endpointUrl );
queryDispatcher.query( sparqlQuery ).then( console.log );

Next steps

We've only just scratched the surface of the power of SPARQL. If you're interested in learning more, please leave a comment. Thanks!