Exposing an interface to the data cubes

Now that we have our data in a database, how can we query those? Traditionally every RDF triple store offers a standards-compliant SPARQL endpoint. Unfortunately the SPARQL query language is not that well known, which is why the project decided to offer a more familiar interface based on the upcoming GraphQL approach.

A SPARQL endpoint

A SPARQL endpoint is available out-of-the-box once you have loaded the RDF into a triple store: the data can be queried using SPARQL via the SPARQL protocol.

The SPARQL specification is available at https://www.w3.org/TR/sparql11-overview/. To learn SPARQL by example, go to https://www.cambridgesemantics.com/blog/semantic-university/learn-sparql/sparql-by-example/. For complete coverage, see the book “Learning SPARQL, 2nd edition”, by Bob DuCharme, ISBN 978-1-449-37143-2.

Let’s look at an example SPARQL query on our Olympics data cube.

SPARQL query

Under Explore, click Query to enter a SPARQL query. The screenshot shows the query we have entered to look for observations with numberofmedals > 20. Of these observations we capture the properties: country, year, and sex, and then return these properties ordered by country and then number (descending).

The full query looks like this:

prefix owl: <http://www.w3.org/2002/07/owl#> 
prefix void: <http://rdfs.org/ns/void#> 
prefix dcterms: <http://purl.org/dc/terms/> 
prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> 
prefix dcat: <http://www.w3.org/ns/dcat#> 
prefix sdmx-dimension: <http://purl.org/linked-data/sdmx/2009/dimension#> 
prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> 
prefix sdmx-attribute: <http://purl.org/linked-data/sdmx/2009/attribute#> 
prefix qb: <http://purl.org/linked-data/cube#> 
prefix skos: <http://www.w3.org/2004/02/skos/core#> 
prefix xsd: <http://www.w3.org/2001/XMLSchema#> 
prefix sdmx-concept: <http://purl.org/linked-data/sdmx/2009/concept#> 
SELECT DISTINCT ?country ?year ?sex ?number
WHERE {?obs a qb:Observation;
        sdmx-dimension:refArea    ?countryid ;
        sdmx-dimension:refPeriod  ?year ;
        sdmx-dimension:sex        ?sexid ;
        <https://example.org/ns/olympics#numberofmedals>  ?number .
        FILTER (?number > 20)
       ?countryid skos:prefLabel ?country.
        FILTER (lang(?country) = 'en')
      ?sexid skos:prefLabel ?sex.
  FILTER (lang(?sex) = 'en')
 }
ORDER BY ?country desc(?number)       
     

Clicking on Execute gives us this result:

query response

The SPARQL endpoint is also exposed (not using the web interface) at http://localhost:8080/rdf4j-server/repositories/datacube_olympics. This is the endpoint URL that - when made public - we need to communicate so that external developers can access it.

Adding a GraphQL/CubiQL interface

Not all developers however are fluent in SPARQL, hence the OGI project did find it important to offer a programming interface that is more familiar to the broad legion of web developers in the form of CubiQL.

GraphQL is becoming very popular amongst developers, because it allows to request precisely the data one needs (even if those data belong to different resources). The requests and responses are formulated in the familiar and popular JSON format. More info on GraphQL can be found at https://graphql.org/.

CubiQL is an implementation of the GraphQL query language for querying RDF data cubes. More background information on CubiQL is available here: https://github.com/Swirrl/graphql-qb.

In the previous section we reached the point were we had a SPARQL endpoint for our data running at http://localhost:8080/rdf4j-server/repositories/datacube_olympics.

To add a CubiQL interface, we need to run the CubiQL server.

Download the latest jar at https://github.com/Swirrl/graphql-qb/releases. Once downloaded, start the CubiQL server using the following command:

 java -jar graphql-qb-0.6.0-standalone.jar 
       --port 9090 
       --endpoint http://localhost:8080/rdf4j-server/repositories/datacube_olympics
     

where

When started, the CubiQL endpoint becomes available at http://localhost:9090/graphql.

We can then use a GraphQL IDE such as GraphiQL (https://github.com/graphql/graphiql for more) and point it to our CubiQL endpoint http://localhost:9090/graphql to check if the endpoint is working.

In the left pane we define the structure of the data we want to retrieve.

When made public, it is this GraphQL endpoint we need to communicate to the outside world.

See also:

Learning SPARQL