How to perform SPARQL queries

Sometimes it is useful to be able to perform SPARQL queries on your dataset to find out some specific information about your data. WissKI allows displaying almost any kind of data in views, however that often comes with a lot of configuration overhead, that is not really appropriate for a "quick lookup".

For this purpose WissKI offers two possibilities on how to perform SPARQL queries:

Via the web interface
Using the SPARQL endpoint

Via Web Interface¶

You can access the SPARQL web interface by navigating to Configuration → WissKI Salz Adapters and clicking Editfor the adapter you want to query. It is also possible to directly access the web interface by visiting the endpoint routes of the endpoint section in the browser. Now you can access the Query or Update tabs to send queries to your SPARQL backend.

The tabs offer different query types:

Query: read-only queries, e.g. SELECT, ASK, etc.
Update: write queries, e.g. INSERT, DELETE, etc.

Endpoint¶

If that is not enough for you and you wish to perform queries programmatically with tools like curl or a programming language like Python, you will need to use the SPARQL endpoints.

Usually you can also directly access the API endpoints of your graph database, but there may be some instances where the graph database is not, or should not be publicly accessible.

WissKI offers these endpoints, similar to the Query and Update tabs in the adapter, where ADAPTER_ID refers to the machine name of the adapter you want to query.

/wisski/endpoint/ADAPTER_ID: read-only queries, e.g. SELECT, ASK, etc.
/wisski/endpoint/ADAPTER_ID/statements: write queries, e.g. INSERT, DELETE, etc.

If you know how to use the SPARQL endpoints of one of the commonly used graph databases, these routes should be fairly familiar to you. Accessing these routes from the browser will redirect you to the respective query interface.

Authentication¶

These routes are not publicly accessible per default, so you will have to configure them to be accessible from an external client.

Permissions¶

You can set the permissions for the endpoints by navigating to People → Permissions and then filtering for salz. Alternatively you can also access the route that filters for the permissions set by the wisski_adapter_sparql11_pb module: /admin/people/permissions/module/wisski_adapter_sparql11_pb.

The permissions you can set here define who can access the Query, Update and Import tabs in the WissKI Salz Adapter configuration, as well as the previously mentioned endpoints /wisski/endpoint/ADAPTER_ID/*. For the endpoints to be accessible via HTTP basic authentication, you will need to enable the HTTP Basic Authentication core module. You can do this either via Drupal's Extend interface, or via drush en basic_auth if you have drush installed and ssh access to your WissKI.

If you want to make an endpoint fully public, you can give the respective permission to the Anonymous user. This also makes the route accessible without having to enable the HTTP Basic Authentication module.

Query¶

In the following example we'll send a simple SELECT query to the default adapter of the https://dummy.wisski. We will also use HTTP basic authentication with the username: wisski-user and password password.

curlPython

curl -G \ 
  -u wisski-user:password \
  -H "Accept: application/sparql-results+json" \
  --data-urlencode "query=SELECT DISTINCT ?g WHERE { GRAPH ?g { ?s ?p ?o } } LIMIT 10" \
  "https://dummy.wisski/wisski/endpoint/default"

import requests
import json

query_endpoint = "https://dummy.wisski/wisski/endpoint/default"
auth = ("wisski-user", "password")
headers = {
    "Accept": "application/sparql-results+json",
}
params = {
    "query": "SELECT DISTINCT ?g WHERE { GRAPH ?g { ?s ?p ?o } } LIMIT 10"
}

response = requests.get(query_endpoint, auth=auth, params=params, headers=headers)
# Pretty print the response
print(json.dumps(response.json(), indent=2))

Important

Note the Accept header. It determines which format the endpoint returns. The most common ones are:

application/sparql-results+json: returns json
application/sparql-results+xml: returns xml

Since the WissKI endpoints only pass the headers though to the triplestore backend, refer to the API documentation of your backend to find other valid response formats.

Update¶

To perform writing queries, you will have to send a POST request to the /wisski/endpoint/default/statements, where the query in contained in the body. Just like before we'll use HTTP basic authentication, but this time we're sending an INSERT query.

curlPython

curl -X POST \
  -u wisski-user:password \
  -H "Accept: application/sparql-results+json" \
  -H "Content-Type: application/sparql-update" \
  --data "INSERT DATA { <http://this.is> <http://a.sparlq> <http://insert.test> }" \
  "https://dummy.wisski/wisski/endpoint/default/statements"

import requests

update_endpoint = "https://dummy.wisski/wisski/endpoint/default/statements"
auth = ("wisski-user", "password")
headers = {
    "Accept": "application/sparql-results+json",
    "Content-Type": "application/sparql-update",
}
body = "INSERT DATA { <http://this.is> <http://a.wisski> <http://sparql.test> }"

response = requests.post(update_endpoint, auth=auth, data=body, headers=headers)
# The response is usually empty for updates, so we just print the status code
print(response.status_code)

Important

Note the Content-Type header! You can also use application/sparql-query and send a read query like SELECT via this endpoint.