Skip to content

Datastories

It is possible to create a collection of Markdown files that contain integrated SPARQL queries and charts to be served by an instance of SHMARQL. By default, the Material for MkDocs theme is used, but you can create your own custom themes and styling too.

When you run a SHMARQL instance, there is a set of default files in the /src/docs/ directory that serve as the default user interface. You can override these files and create your own files in a local docs directory. For example, if you had a local directory called docs, you could use it like this:

1
docker run -v $(pwd)/docs:/src/docs -v $(pwd)/navigation.yml:/src/docs/.nav.yml -p 8000:8000 --rm -it ghcr.io/epoz/shmarql:latest

Or, you could build your own custom image that replaces the docs folder in a build step. See for example how this is done for the NFDI4Memory consortium.

SPARQL Queries

You can embed any SPARQL query in your datastory by creating block and setting the type to sparql, like this: (1)

  1. Note that in the actual markdown your triple-quotes should be back-tics ` and not single quotes ' for example purposes we are choosing to try and show the blocks visually. Tips on how to do this properly are welcome 😉
1
2
3
'''sparql
select \* where {?s ?p ?o} limit 10
'''

By setting the type of the block to shmarql the source query will not be shown in the page, but executed and the results displayed.

1
2
3
'''shmarql
select \* where {?s ?p ?o} limit 10
'''

Charting

It is possible to create charts using the Plotly library in the Markdown files. This is done by adding some comments to the top of the embedded SPARQL queries, which signal that the output should be a chart and not just a table of results.

For example, you can create a bar chart like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
'''sparql
# shmarql-view: barchart
# shmarql-x: type
# shmarql-y: count
# shmarql-label: Instance Count

PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>

SELECT ?type (xsd:integer(COUNT(?subject)) AS ?count)
WHERE {
  ?subject a ?type .
}
GROUP BY ?type
ORDER BY desc(?count)
'''

It is also possible to make other chart types, for example a map using some coordinates from Wikidata.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
# shmarql-view: mapchart
# shmarql-zoom: 6
# shmarql-lat: 49.006889
# shmarql-lon: 8.403653

select ?item ?geo where {
  SERVICE <https://query.wikidata.org/sparql> {
    SELECT DISTINCT * WHERE {
      ?item wdt:P31/wdt:P279* wd:Q16917;
            wdt:P625 ?geo .
    }
  }
}