March 16, 2016 .. 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 theconstruct()
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: - subTriples – the triples so far as a
rdfextras.sparql.graph.SPARQLGraph
- pattern – a
GraphPattern
used to construct a graph
Returns: if pattern is not None, an array of binding dictionaries
- subTriples – the triples so far as a
-
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.-
cluster
(selection)[source]¶ cluster: a combination of
clusterBackward()
andclusterForward()
.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 NoneReturns: 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.
query
(graph, selection, patterns, optionalPatterns=[], initialBindings={}, dSCompliance=False, loadContexts=False)[source]¶ A shorthand for the creation of a
Query
instance, returning the result of aselect()
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 ofGraphPattern
instances. Each pattern in the list represent an ‘OR’ (or ‘UNION’) branch in SPARQL. - optionalPatterns – either a
GraphPattern
instance or a list ofGraphPattern
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 ofGraphPattern
instances. Each pattern in the list represent an ‘OR’ (or ‘UNION’) branch in SPARQL. - optionalPatterns – either a
GraphPattern
instance or a list ofGraphPattern
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- patterns – either a