May 02, 2015 .. currentmodule:: rdfextras.sparql.query

query - SPARQL Query

class rdfextras.sparql.query.SessionBNode[source]

Special ‘session’ BNodes. I.e., BNodes at the query side which refer to BNodes in persistence

class rdfextras.sparql.query.EnoughAnswers[source]

Raised within expand when the specified LIMIT has been reached

class rdfextras.sparql.query._SPARQLNode(parent, bindings, statements, tripleStore, expr=None)[source]

The SPARQL implementation is based on the creation of a tree, each level for each statement in the ‘where’ clause of SPARQL.

Each node maintains a ‘binding’ dictionary, with the variable names and either a None if not yet bound, or the binding itself. The method ‘expand’ tries to make one more step of binding by looking at the next statement: it takes the statement of the current node, binds the variables if there is already a binding, and looks at the triple store for the possibilities. If it finds valid new triplets, that will bind some more variables, and children will be created with the next statement in the ‘where’ array with a new level of bindings. This is done for each triplet found in the store, thereby branching off the tree. If all variables are already bound but the statement, with the bound variables, is not ‘true’ (ie, there is no such triple in the store), the node is marked as ‘clash’ and no more expansion is made; this node will then be thrown away by the parent. If I{all} children of a node is a clash, then it is marked as a clash itself.

At the end of the process, the leaves of the tree are searched; if a leaf is such that:

  • all variables are bound
  • there is no clash

then the bindings are returned as possible answers to the query.

The optional clauses are treated separately: each ‘valid’ leaf is assigned an array of expansion trees that contain the optional clauses (that may have some unbound variables bound at the leaf, though).

Variables:
  • parent – parent in the tree, a _SPARQLNode
  • children – the children (in an array of _SPARQLNodes)
  • bindings – copy of the bindings dictionary locally
  • statement – the current statement, a (s,p,o,f) tuple (‘f’ is the local filter or None)
  • rest – the rest of the statements (an array)
  • clash – Boolean, intialized to False
  • bound – Boolean True or False depending on whether all variables are bound in self.binding
  • optionalTrees – array of _SPARQLNode instances forming expansion trees for optional statements
expandAtClient(constraints)[source]

The expansion itself. See class comments for details.

Parameters:constraints – array of global constraining (filter) methods
expandOptions(bindings, statements, constraints)[source]

Managing optional statements. These affect leaf nodes only, if they contain ‘real’ results. A separate Expansion tree is appended to such a node, one for each optional call.

Parameters:
  • bindings – current bindings dictionary
  • statements – array of statements from the ‘where’ clause. The first element is for the current node, the rest for the children. If empty, then no expansion occurs (ie, the node is a leaf). The bindings at this node are taken into account (replacing the unbound variables with the real resources) before expansion
  • constraints – array of constraint (filter) methods
expandSubgraph(subTriples, pattern)[source]

Method used to collect the results. There are two ways to invoke the method:

1. if the pattern argument is not None, then this means the construction of a separate triple store with the results. This means taking the bindings in the node, and constructing the graph via the construct() method. This happens on the valid leaves; intermediate nodes call the same method recursively 2. otherwise, a leaf returns an array of the bindings, and intermediate methods aggregate those.

In both cases, leaf nodes may successively expand the optional trees that they may have.

Parameters:
Returns:

if pattern is not None, an array of binding dictionaries

returnResult(select)[source]

Collect the result by search the leaves of the the tree. The variables in the select are exchanged against their bound equivalent (if applicable). This action is done on the valid leaf nodes only, the intermediate nodes only gather the children’s results and combine it in one array.

Parameters:select – the array of unbound variables in the original select that do not appear in any of the optionals. If None, the full binding should be considered (this is the case for the SELECT * feature of SPARQL)
Returns:an array of dictionaries with non-None bindings.
class rdfextras.sparql.query.Query(sparqlnode, triples, parent1=None, parent2=None)[source]

Result of a SPARQL query. It stores to the top of the query tree, and allows some subsequent inquiries on the expanded tree. This class should not be instantiated by the user, it is done by the queryObject() function.

ask()[source]

Whether a specific pattern has a solution or not. :rtype: Boolean

cluster(selection)[source]

cluster: a combination of clusterBackward() and clusterForward().

Parameters:selection – a selection to define the seeds for clustering via the selection; the result of select used for the clustering seed
clusterBackward(selection)[source]

Backward clustering, using all the results of the query as seeds (when appropriate). It is based on the usage of the rdfextras.sparql.graph.SPARQLGraph.clusterBackward() method for triple store.

Parameters:selection – a selection to define the seeds for clustering via the selection; the result of select used for the clustering seed
Returns:a new triple store of type rdfextras.sparql.graph.SPARQLGraph
clusterForward(selection)[source]

Forward clustering, using all the results of the query as seeds (when appropriate). It is based on the usage of the rdfextras.sparql.graph.SPARQLGraph.clusterForward() method for triple store.

Parameters:selection – a selection to define the seeds for clustering via the selection; the result of select used for the clustering seed
Returns:a new triple store of type rdfextras.sparql.graph.SPARQLGraph
construct(pattern=None)[source]

Expand the subgraph based on the pattern or, if None, the internal bindings.

In the former case the binding is used to instantiate the triplets in the patterns; in the latter, the original statements are used as patterns.

The result is a separate triple store containing the subgraph.

Parameters:pattern – a rdfextras.sparql.graph.GraphPattern instance or None
Returns:a new triple store of type rdfextras.sparql.graph.SPARQLGraph
describe(selection, forward=True, backward=True)[source]

The DESCRIBE Form in the SPARQL draft is still in state of flux, so this is just a temporary method, in fact. It may not correspond to what the final version of describe will be (if it stays in the draft at all, that is). At present, it is simply a wrapper around cluster().

Parameters:
  • selection – a selection to define the seeds for clustering via the selection; the result of select used for the clustering seed
  • forward – cluster forward Boolean, yes or no
  • backward – cluster backward Boolean yes or no
select(selection, distinct=True, limit=None, orderBy=None, orderAscend=None, offset=0)[source]

Run a selection on the query.

Parameters:
  • selection – Either a single query string, or an array or tuple of query strings.
  • distinct – Boolean - if True, identical results are filtered out.
  • limit – if set to a(non-negative) integer value, the first ‘limit’ number of results are returned, otherwise all the results are returned.
  • orderBy – either a function or a list of strings (corresponding to variables in the query). If None, no sorting occurs on the results. If the parameter is a function, it must take two dictionary arguments (the binding dictionaries), return -1, 0, and 1, corresponding to smaller, equal, and greater, respectively.
  • orderAscend – if not None, then an array of booleans of the same length as orderBy, True for ascending and False for descending. If None, an ascending order is used.
  • offset – the starting point of return values in the array of results. This parameter is only relevant when some sort of order is defined.
Returns:

selection results as a list of tuples

Raises SPARQLError:
 

invalid selection argument

class rdfextras.sparql.query.SPARQLQueryResult(qResult)[source]

Query result class for SPARQL

Returns, variously: * xml - as an XML string conforming to the SPARQL XML result format. * python - as Python objects * json - as JSON * graph - as an RDFLib Graph, for CONSTRUCT and DESCRIBE queries

selectionF

access the ‘selectionF’ attribute; deprecated and provided only for backwards compatibility

rdfextras.sparql.query.isGroundQuad(quad)[source]
rdfextras.sparql.query.query(graph, selection, patterns, optionalPatterns=, []initialBindings={}, dSCompliance=False, loadContexts=False)[source]

A shorthand for the creation of a Query instance, returning the result of a select() right away. Good for most of the usage, when no more action (clustering, etc) is required.

Parameters:
  • selection – a list or tuple with the selection criteria, or a single string. Each entry is a string that begins with ”?”.
  • patterns – either a GraphPattern instance or a list of GraphPattern instances. Each pattern in the list represent an ‘OR’ (or ‘UNION’) branch in SPARQL.
  • optionalPatterns – either a GraphPattern instance or a list of GraphPattern instances. Each of the elements in the ‘patterns’ parameter is combined with each of the optional patterns and the results are concatenated. The list may be empty.
Returns:

list of query results as a list of tuples

rdfextras.sparql.query.queryObject(graph, patterns, optionalPatterns=, []initialBindings=None, dSCompliance=False, loadContexts=False)[source]

Creation of a Query instance.

Parameters:
  • patterns – either a GraphPattern instance or a list of GraphPattern instances. Each pattern in the list represent an ‘OR’ (or ‘UNION’) branch in SPARQL.
  • optionalPatterns – either a GraphPattern instance or a list of GraphPattern instances. Each eof the elements in the ‘patterns’ parameter is combined with each of the optional patterns and the results are concatenated. The list may be empty.
Returns:

a Query object

Previous topic

processor - SPARQL processor

Next topic

RDFLib Stores