Swirrl

As part of the work for the OpenDataCommunities Linked Open Data Site that we recently released (see last week’s blog post), we’ve been improving and upgrading PublishMyData, our Linked Data publishing platform.

One of the most interesting new features that we’ve added is designed to make writing and executing SPARQL queries easier.

Parameterised Queries

The problem

If you’re writing an application which consumes Linked Data by executing SPARQL queries against an HTTP endpoint, it’s often the case that you want to call lots of very similar SPARQL queries, which change only subtly based on user input. This can lead to a lot of cumbersome string manipulation code in your app.

For example, say you wanted to find which local authority is associated with a postcode user: you might write a query like this (in this case, for postcode M1 7HL)

SELECT ?la ?laName ?osDistrict 
WHERE {
  <http://data.ordnancesurvey.co.uk/id/postcodeunit/M17HL>
    <http://data.ordnancesurvey.co.uk/ontology/postcode/district> ?osDistrict .
  ?la <http://opendatacommunities.org/def/local-government/governs> ?osDistrict .
  ?la <http://www.w3.org/2000/01/rdf-schema#label> ?laName .
} 
LIMIT 1

… and you’d execute it by making a call to a URL like this (click for results):
http://opendatacommunities.org/sparql?query=SELECT+%3Fla+%3FlaName+%3FosDistrict+%0D%0AWHERE+%7B%0D%0A++%3Chttp%3A%2F%2Fdata.ordnancesurvey.co.uk%2Fid%2Fpostcodeunit%2FM17HL%3E+%3Chttp%3A%2F%2Fdata.ordnancesurvey.co.uk%2Fontology%2Fpostcode%2Fdistrict%3E+%3FosDistrict+.%0D%0A++%3Fla+%3Chttp%3A%2F%2Fopendatacommunities.org%2Fdef%2Flocal-government%2Fgoverns%3E+%3FosDistrict+.%0D%0A++%3Fla+%3Chttp%3A%2F%2Fwww.w3.org%2F2000%2F01%2Frdf-schema%23label%3E+%3FlaName+.%0D%0A%7D+%0D%0ALIMIT+1

(i.e. http://<domain>/sparql.format?query=<url-encoded-query>)

The solution

To help address this problem, we’ve introduced a feature which allows you to just write the SPARQL query once, and then pass parameters for the parts that change on the query string when you make the call to the endpoint.

Our new feature lets you add %{tokens} to your SPARQL, like this:

SELECT ?la ?laName ?osDistrict 
WHERE {
  <http://data.ordnancesurvey.co.uk/id/postcodeunit/%{postcode}>
    <http://data.ordnancesurvey.co.uk/ontology/postcode/district> ?osDistrict .
  ?la <http://opendatacommunities.org/def/local-government/governs> ?osDistrict .
  ?la <http://www.w3.org/2000/01/rdf-schema#label> ?laName .
} 
LIMIT 1

… and pass values for the tokens on the query string like this (notice the postcode parameter at the end):

http://opendatacommunities.org/sparql?query=SELECT+%3Fla+%3FlaName+%3FosDistrict+%0D%0AWHERE+%7B%0D%0A++%3Chttp%3A%2F%2Fdata.ordnancesurvey.co.uk%2Fid%2Fpostcodeunit%2F%25%7Bpostcode%7D%3E%0D%0A++++%3Chttp%3A%2F%2Fdata.ordnancesurvey.co.uk%2Fontology%2Fpostcode%2Fdistrict%3E+%3FosDistrict+.%0D%0A++%3Fla+%3Chttp%3A%2F%2Fopendatacommunities.org%2Fdef%2Flocal-government%2Fgoverns%3E+%3FosDistrict+.%0D%0A++%3Fla+%3Chttp%3A%2F%2Fwww.w3.org%2F2000%2F01%2Frdf-schema%23label%3E+%3FlaName+.%0D%0A%7D+%0D%0ALIMIT+1&postcode=M17HL

(i.e. http://<domain>/sparql.format?query=<url-encoded-query>&token=value)

You can do this with multiple parameters and for all the normal supported SPARQL formats. If you try to execute a query which expects parameters for tokens (in HTML format) but don’t provide values for all of them in the query string, then you will be prompted to enter the missing parameters (try this).

Named Queries

As well as allowing users to define their own parameterised queries as described above, in some cases it’s useful for the curators of the data to pre-define some useful queries.

The approach described above for parameterising queries is much friendlier than having to resort to a lot of string manipulation in client apps. But as you can see above, the URLs for calling the parameterised queries can still be quite long and unwieldy.

Our Named Query feature allows short, friendly, self-explanatory URLs to be created for common or useful SPARQL queries.

In fact, on the OpenDataCommunities site, we’ve done just that for the postcode query we discussed earlier. (Named queries appear in the Example Queries section of the relevant dataset’s API tab)

By using the named query instead of writing their own, app developers can use the following URL in their code:

http://opendatacommunities.org/sparql/local-authority-from-postcode?postcode=M17HL

Much nicer!

For full details of how to programmatically access the data on OpenDataCommunities, see the developer documentation.

At the moment, these features are only supported on OpenDataCommunities, but we will be rolling them out to existing PublishMyData sites in the near future. Of course, all new PublishMyData sites will be able to take advantage of these features.