CubiQL (formerly called graphql-qb) is a proof of concept GraphQL service for querying Linked Data Cubes that was produced as part of the OpenGovIntelligence project, funded by the European Union’s Horizon 2020 research and innovation programme under grant agreement No 693849.
The primary aim of CubiQL is to facilitate the querying of multidimensional QB datasets through GraphQL in an easier more familiar way than through SPARQL.
The project is built with leiningen - after installing it you can build an uberjar with
$ lein uberjar
this will create a cubiql-version-standalone.jar file in the target/uberjar directory. The server can then be started with:
$ java -jar target/uberjar/cubiql-standalone.jar OPTIONS
The available options are:
| Name | Description | Required | Default |
|---|---|---|---|
| port | Port to run server on | no | 8080 |
| endpoint | Endpoint for datasets | yes | |
| configuration | Configuration for the dataset structure | no |
For example to run the server against a remote SPARQL endpoint on port 9000:
$ java -jar cubiql-standalone.jar --port 9000 --endpoint http://remote-endpoint/sparql/query
The endpoint can also refer to a local directory containing RDF data files. The repository contains test datasets in the data directory. When running from the root directory this repository can be specified with:
$ java -jar cubiql-standalone.jar --port 9000 --endpoint data
During development lein run can be used instead of building the uberjar:
$ lein run --endpoint data
The server hosts a GraphQL endpoint at http://localhost:PORT/graphql which follows the protocol described here.
The following examples expect the server to be running locally on port 8080 with the example dataset. You can run the server with
$ lein run --endpoint data
-
Dataset Discovery
-
Dataset metadata
-
Filtering (any combination of the following filtering examples is valid)
- By Dimension (boolean or)
- By Dimension (boolean and)
- Filtering datasets about gender
- Filtering datasets about population group
- By Measure (boolean or)
- By Measure (boolean and)
- By Attribute (boolean or)
- By Attribute (boolean and)
- By Dimension/Attribute value (boolean or)
- By Dimension/Attribute value (boolean and)
- By Dimension hierarchical level (boolean or)
- By Dimension hierarchical level (boolean and)
-
Locking Dimensions
-
Aggregations (scoped to current filters/locks)
-
Misc
-
Pagination
As CubiQL provides access to datacubes and slices containing potentially large amounts of observations, observations are paginated following the graphql recommendation. Paginating through the data might not however suit all consumers, and might even timeout on larger datasets. So we anticipate providing a download_link field into the observations schema #43.
You can see an example of a pagination query here. You'll notice that this query has been parameterised by a $page parameter, which is provided in the supplied variable map. So to get the next page of results you just need to supply a new map of variables with page bound to the last value of the next_page field.
You can browse our schema by following these steps:
- Run the graphql voyager introspection query on your endpoint
- Copy the result of the above query to your clipboard
- Visit https://apis.guru/graphql-voyager/
- Select 'Change Schema'
- Select the 'Introspection' tab
- Paste the schema into the text area
- Click change display
You'll see something like:
table2qb is a command-line tool for generating RDF data cubes from tidy CSV data. See the end-to-end example of using table2qb and CubiQL together to generate and query RDF data cubes.
Copyright © 2017 Swirrl IT Ltd.
Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.