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'
SELECT
solutions#
- class pyoxigraph.QuerySolutions#
An iterator of
QuerySolution
returned by a SPARQLSELECT
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')
. IfNone
, abytes
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"}}]}}'
- 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
orstr
) 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')
. IfNone
, abytes
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 SPARQLCONSTRUCT
orDESCRIBE
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:
N-Quads (
RdfFormat.N_QUADS
)Turtle (
RdfFormat.TURTLE
)TriG (
RdfFormat.TRIG
)N3 (
RdfFormat.N3
)RDF/XML (
RdfFormat.RDF_XML
)
It supports also some media type and extension aliases. For example,
application/turtle
could also be used for Turtle andapplication/xml
orxml
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')
. IfNone
, abytes
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:
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 withopen('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 abool
.- Return type:
- 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:
>>> 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 orNone
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 orNone
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:
>>> QueryResultsFormat.JSON.iri 'http://www.w3.org/ns/formats/SPARQL_Results_JSON'
- media_type#
- Returns:
the format IANA media type.
- Return type:
>>> QueryResultsFormat.JSON.media_type 'application/sparql-results+json'