SPARQLWrapper

2.0.0 · active · verified Sat Apr 11

SPARQLWrapper is a Python library that provides a simple wrapper around a SPARQL service to remotely execute queries. It helps in creating the query invocation and, optionally, converting the result into a more manageable format like JSON or an RDFLib Graph. The current major version is 2.0.0, which was a significant update focusing on Python 3 compatibility. Releases occur periodically, with the last major release in March 2022.

Warnings

breaking Version 2.0.0 completely dropped support for Python 2. Codebases using SPARQLWrapper on Python 2 must migrate to Python 3 before upgrading to 2.0.0 or later.
Fix: Ensure your project is running on Python 3.7+ (as per PyPI metadata) and update your environment accordingly.
breaking SPARQLWrapper 2.0.0 requires RDFLib version 6.1.1 or higher. Older versions of RDFLib may cause compatibility issues, especially with CONSTRUCT/DESCRIBE query results.
Fix: Upgrade RDFLib to `rdflib>=6.1.1` in your project's dependencies.
gotcha If `setReturnFormat()` is not explicitly called, SPARQLWrapper defaults to XML for SELECT queries and HTML for ASK queries, which might not be what you expect for easy programmatic access. Always set the desired return format (e.g., `JSON`, `RDFXML`) for predictable results.
Fix: Always call `sparql.setReturnFormat(FORMAT_CONSTANT)` (e.g., `JSON`, `RDFXML`, `TURTLE`) before executing a query.
gotcha When fetching results, you can either use `sparql.query().convert()` or `sparql.queryAndConvert()`. The latter is often preferred for simplicity as it directly returns the converted Python object (e.g., a dictionary for JSON), avoiding an intermediate stream object.
Fix: For immediate conversion, use `results = sparql.queryAndConvert()`. If you need to access the raw HTTP response stream, use `raw_response = sparql.query()` and then `converted_results = raw_response.convert()`.
gotcha SPARQLWrapper raises specific exceptions like `QueryBadFormed`, `EndPointNotFound`, `EndPointInternalError`, and `Unauthorized` for various issues. Not catching these can lead to unhandled program termination.
Fix: Wrap your query execution in a `try...except` block to gracefully handle potential SPARQL-related errors, importing specific exceptions from `SPARQLWrapper.SPARQLExceptions`.

Install

pip install sparqlwrapper Install latest version

Imports

SPARQLWrapper
```
from SPARQLWrapper import SPARQLWrapper
```
JSON
```
from SPARQLWrapper import JSON
```
Commonly imported constant for setting JSON return format.

Quickstart

This quickstart demonstrates how to initialize SPARQLWrapper with an endpoint, set a SPARQL SELECT query, specify JSON as the return format, and process the results. It retrieves 5 English labels from a generic SPARQL endpoint, defaulting to DBpedia if no `SPARQL_ENDPOINT` environment variable is set.

import os
from SPARQLWrapper import SPARQLWrapper, JSON

# Use a placeholder for the endpoint URL, expecting an environment variable
# or defaulting to a known public endpoint if available (e.g., DBpedia or a test endpoint)
SPARQL_ENDPOINT = os.environ.get('SPARQL_ENDPOINT', 'http://dbpedia.org/sparql')

sparql = SPARQLWrapper(SPARQL_ENDPOINT)

# Example: Query for the first 5 English labels of DBPedia resources
sparql.setQuery("""
    PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
    SELECT ?resource ?label
    WHERE {
        ?resource rdfs:label ?label .
        FILTER (lang(?label) = 'en')
    }
    LIMIT 5
""")

sparql.setReturnFormat(JSON)

try:
    # queryAndConvert() directly returns a Python object (e.g., dict for JSON)
    results = sparql.queryAndConvert()
    
    print("Query Results:")
    for result in results["results"]["bindings"]:
        resource_uri = result["resource"]["value"]
        label = result["label"]["value"]
        print(f"Resource: {resource_uri}, Label: {label}")

except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →