SPARQL utility objects#

Oxigraph provides also some utilities related to SPARQL queries:

Variable#

class pyoxigraph.Variable(value)#

A SPARQL query variable.

Parameters:

value (str) – the variable name as a string.

Raises:

ValueError – if the variable name is invalid according to the SPARQL grammar.

The str function provides a serialization compatible with SPARQL:

>>> str(Variable('foo'))
'?foo'
value#
Returns:

the variable name.

Return type:

str

>>> Variable("foo").value
'foo'

SELECT solutions#

class pyoxigraph.QuerySolutions#

An iterator of QuerySolution returned by a SPARQL SELECT query

>>> store = Store()
>>> store.add(Quad(NamedNode('http://example.com'), NamedNode('http://example.com/p'), Literal('1')))
>>> list(store.query('SELECT ?s WHERE { ?s ?p ?o }'))
[<QuerySolution s=<NamedNode value=http://example.com>>]
serialize(output=None, format=None)#

Writes the query results into a file.

It currently supports the following formats:

  • XML (QueryResultsFormat.XML)

  • JSON (QueryResultsFormat.JSON)

  • CSV (QueryResultsFormat.CSV)

  • TSV (QueryResultsFormat.TSV)

It supports also some media type and extension aliases. For example, application/json could also be used for JSON.

Parameters:
  • output (IO[bytes] or str or os.PathLike[str] or None, optional) – The binary I/O object or file path to write to. For example, it could be a file path as a string or a file writer opened in binary mode with open('my_file.ttl', 'wb'). If None, a bytes buffer is returned with the serialized content.

  • format (QueryResultsFormat or None, optional) – the format of the query results serialization. If None, the format is guessed from the file name extension.

Return type:

bytes or None

Raises:
  • ValueError – if the format is not supported.

  • OSError – if a system error happens while writing the file.

>>> store = Store()
>>> store.add(Quad(NamedNode('http://example.com'), NamedNode('http://example.com/p'), Literal('1')))
>>> results = store.query("SELECT ?s ?p ?o WHERE { ?s ?p ?o }")
>>> results.serialize(format=QueryResultsFormat.JSON)
b'{"head":{"vars":["s","p","o"]},"results":{"bindings":[{"s":{"type":"uri","value":"http://example.com"},"p":{"type":"uri","value":"http://example.com/p"},"o":{"type":"literal","value":"1"}}]}}'
variables#
Returns:

the ordered list of all variables that could appear in the query results

Return type:

list[Variable]

>>> store = Store()
>>> store.query('SELECT ?s WHERE { ?s ?p ?o }').variables
[<Variable value=s>]
class pyoxigraph.QuerySolution#

Tuple associating variables and terms that are the result of a SPARQL SELECT query.

It is the equivalent of a row in SQL.

It could be indexes by variable name (Variable or str) or position in the tuple (int). Unpacking also works.

>>> store = Store()
>>> store.add(Quad(NamedNode('http://example.com'), NamedNode('http://example.com/p'), Literal('1')))
>>> solution = next(store.query('SELECT ?s ?p ?o WHERE { ?s ?p ?o }'))
>>> solution[Variable('s')]
<NamedNode value=http://example.com>
>>> solution['s']
<NamedNode value=http://example.com>
>>> solution[0]
<NamedNode value=http://example.com>
>>> s, p, o = solution
>>> s
<NamedNode value=http://example.com>

ASK results#

class pyoxigraph.QueryBoolean#

A boolean returned by a SPARQL ASK query.

It can be easily casted to a regular boolean using the bool() function.

>>> store = Store()
>>> store.add(Quad(NamedNode('http://example.com'), NamedNode('http://example.com/p'), Literal('1')))
>>> bool(store.query('ASK { ?s ?p ?o }'))
True
serialize(output=None, format=None)#

Writes the query results into a file.

It currently supports the following formats:

  • XML (QueryResultsFormat.XML)

  • JSON (QueryResultsFormat.JSON)

  • CSV (QueryResultsFormat.CSV)

  • TSV (QueryResultsFormat.TSV)

It supports also some media type and extension aliases. For example, application/json could also be used for JSON.

Parameters:
  • output (IO[bytes] or str or os.PathLike[str] or None, optional) – The binary I/O object or file path to write to. For example, it could be a file path as a string or a file writer opened in binary mode with open('my_file.ttl', 'wb'). If None, a bytes buffer is returned with the serialized content.

  • format (QueryResultsFormat or None, optional) – the format of the query results serialization. If None, the format is guessed from the file name extension.

Return type:

bytes or None

Raises:
  • ValueError – if the format is not supported.

  • OSError – if a system error happens while writing the file.

>>> store = Store()
>>> store.add(Quad(NamedNode('http://example.com'), NamedNode('http://example.com/p'), Literal('1')))
>>> results = store.query("ASK { ?s ?p ?o }")
>>> results.serialize(format=QueryResultsFormat.JSON)
b'{"head":{},"boolean":true}'

CONSTRUCT results#

class pyoxigraph.QueryTriples#

An iterator of Triple returned by a SPARQL CONSTRUCT or DESCRIBE query

>>> store = Store()
>>> store.add(Quad(NamedNode('http://example.com'), NamedNode('http://example.com/p'), Literal('1')))
>>> list(store.query('CONSTRUCT WHERE { ?s ?p ?o }'))
[<Triple subject=<NamedNode value=http://example.com> predicate=<NamedNode value=http://example.com/p> object=<Literal value=1 datatype=<NamedNode value=http://www.w3.org/2001/XMLSchema#string>>>]
serialize(output=None, format=None)#

Writes the query results into a file.

It currently supports the following formats:

It supports also some media type and extension aliases. For example, application/turtle could also be used for Turtle and application/xml or xml for RDF/XML.

Parameters:
  • output (IO[bytes] or str or os.PathLike[str] or None, optional) – The binary I/O object or file path to write to. For example, it could be a file path as a string or a file writer opened in binary mode with open('my_file.ttl', 'wb'). If None, a bytes buffer is returned with the serialized content.

  • format (RdfFormat or None, optional) – the format of the RDF serialization. If None, the format is guessed from the file name extension.

Return type:

bytes or None

Raises:
  • ValueError – if the format is not supported.

  • OSError – if a system error happens while writing the file.

>>> store = Store()
>>> store.add(Quad(NamedNode('http://example.com'), NamedNode('http://example.com/p'), Literal('1')))
>>> results = store.query("CONSTRUCT { ?s ?p ?o } WHERE { ?s ?p ?o }")
>>> results.serialize(format=RdfFormat.N_TRIPLES)
b'<http://example.com> <http://example.com/p> "1" .\n'

Query results parsing#

pyoxigraph.parse_query_results(input=None, format=None, *, path=None)#

Parses SPARQL query results.

It currently supports the following formats:

  • XML (QueryResultsFormat.XML)

  • JSON (QueryResultsFormat.JSON)

  • TSV (QueryResultsFormat.TSV)

It supports also some media type and extension aliases. For example, application/json could also be used for JSON.

Parameters:
  • input (bytes or str or IO[bytes] or IO[str] or None, optional) – The str, bytes or I/O object to read from. For example, it could be the file content as a string or a file reader opened in binary mode with open('my_file.ttl', 'rb').

  • format (QueryResultsFormat or None, optional) – the format of the query results serialization. If None, the format is guessed from the file name extension.

  • path (str or os.PathLike[str] or None, optional) – The file path to read from. Replaces the input parameter.

Returns:

an iterator of QuerySolution or a bool.

Return type:

QuerySolutions or QueryBoolean

Raises:
  • ValueError – if the format is not supported.

  • SyntaxError – if the provided data is invalid.

  • OSError – if a system error happens while reading the file.

>>> list(parse_query_results('?s\t?p\t?o\n<http://example.com/s>\t<http://example.com/s>\t1\n', QueryResultsFormat.TSV))
[<QuerySolution s=<NamedNode value=http://example.com/s> p=<NamedNode value=http://example.com/s> o=<Literal value=1 datatype=<NamedNode value=http://www.w3.org/2001/XMLSchema#integer>>>]
>>> parse_query_results('{"head":{},"boolean":true}', QueryResultsFormat.JSON)
<QueryBoolean true>
class pyoxigraph.QueryResultsFormat#

SPARQL query results serialization formats.

The following formats are supported:

  • XML (QueryResultsFormat.XML)

  • JSON (QueryResultsFormat.JSON)

  • CSV (QueryResultsFormat.CSV)

  • TSV (QueryResultsFormat.TSV)

file_extension#
Returns:

the format IANA-registered file extension.

Return type:

str

>>> QueryResultsFormat.JSON.file_extension
'srj'
static from_extension(extension)#

Looks for a known format from an extension.

It supports some aliases.

Parameters:

extension (str) – the extension.

Returns:

QueryResultsFormat if the extension is known or None if not.

Return type:

QueryResultsFormat or None

>>> QueryResultsFormat.from_extension("json")
<QueryResultsFormat SPARQL Results in JSON>
static from_media_type(media_type)#

Looks for a known format from a media type.

It supports some media type aliases. For example, “application/xml” is going to return QueryResultsFormat.XML even if it is not its canonical media type.

Parameters:

media_type (str) – the media type.

Returns:

QueryResultsFormat if the media type is known or None if not.

Return type:

QueryResultsFormat or None

>>> QueryResultsFormat.from_media_type("application/sparql-results+json; charset=utf-8")
<QueryResultsFormat SPARQL Results in JSON>
iri#
Returns:

the format canonical IRI according to the Unique URIs for file formats registry.

Return type:

str

>>> QueryResultsFormat.JSON.iri
'http://www.w3.org/ns/formats/SPARQL_Results_JSON'
media_type#
Returns:

the format IANA media type.

Return type:

str

>>> QueryResultsFormat.JSON.media_type
'application/sparql-results+json'
name#
Returns:

the format name.

Return type:

str

>>> QueryResultsFormat.JSON.name
'SPARQL Results in JSON'