src/rdflib/plugins/stores/sparqlstore.py
1"""
2This is an RDFLib store around Ivan Herman et al.'s SPARQL service wrapper.
3This was first done in layer-cake, and then ported to RDFLib
4"""
5
6from __future__ import annotations
7
8import collections
9import re
10from typing import (
11 TYPE_CHECKING,
12 Any,
13 Callable,
14 Dict,
15 Generator,
16 Iterable,
17 Iterator,
18 List,
19 Mapping,
20 Optional,
21 Tuple,
22 Union,
23 overload,
24)
25
26from rdflib.graph import DATASET_DEFAULT_GRAPH_ID, Graph
27from rdflib.plugins.stores.regexmatching import NATIVE_REGEX
28from rdflib.store import Store
29from rdflib.term import BNode, Identifier, Node, URIRef, Variable
30
31if TYPE_CHECKING:
32 import typing_extensions as te # noqa: I001
33 from rdflib.graph import (
34 _TripleType,
35 _ContextType,
36 _QuadType,
37 _TripleChoiceType,
38 _TriplePatternType,
39 _SubjectType,
40 _PredicateType,
41 _ObjectType,
42 _ContextIdentifierType,
43 )
44 from rdflib.plugins.sparql.sparql import Query, Update
45 from rdflib.query import Result, ResultRow
46
47from .sparqlconnector import SPARQLConnector
48
49# Defines some SPARQL keywords
50LIMIT = "LIMIT"
51OFFSET = "OFFSET"
52ORDERBY = "ORDER BY"
53
54BNODE_IDENT_PATTERN = re.compile(r"(?P<label>_\:[^\s]+)")
55
56_NodeToSparql = Callable[["Node"], str]
57
58
59def _node_to_sparql(node: Node) -> str:
60 if isinstance(node, BNode):
61 raise Exception(
62 "SPARQLStore does not support BNodes! "
63 "See http://www.w3.org/TR/sparql11-query/#BGPsparqlBNodes"
64 )
65 return node.n3()
66
67
68class SPARQLStore(SPARQLConnector, Store):
69 """An RDFLib store around a SPARQL endpoint
70
71 This is context-aware and should work as expected
72 when a context is specified.
73
74 For ConjunctiveGraphs, reading is done from the "default graph". Exactly
75 what this means depends on your endpoint, because SPARQL does not offer a
76 simple way to query the union of all graphs as it would be expected for a
77 ConjuntiveGraph. This is why we recommend using Dataset instead, which is
78 motivated by the SPARQL 1.1.
79
80 Fuseki/TDB has a flag for specifying that the default graph
81 is the union of all graphs (`tdb:unionDefaultGraph` in the Fuseki config).
82
83 !!! warning "Blank nodes
84
85 By default the SPARQL Store does not support blank-nodes!
86
87 As blank-nodes act as variables in SPARQL queries,
88 there is no way to query for a particular blank node without
89 using non-standard SPARQL extensions.
90
91 See http://www.w3.org/TR/sparql11-query/#BGPsparqlBNodes
92
93 You can make use of such extensions through the `node_to_sparql`
94 argument. For example if you want to transform BNode('0001') into
95 "<bnode:b0001>", you can use a function like this:
96
97 ```python
98 >>> def my_bnode_ext(node):
99 ... if isinstance(node, BNode):
100 ... return '<bnode:b%s>' % node
101 ... return _node_to_sparql(node)
102 >>> store = SPARQLStore('http://dbpedia.org/sparql',
103 ... node_to_sparql=my_bnode_ext)
104
105 ```
106
107 You can request a particular result serialization with the
108 `returnFormat` parameter. This is a string that must have a
109 matching plugin registered. Built in is support for `xml`,
110 `json`, `csv`, `tsv` and `application/rdf+xml`.
111
112 The underlying SPARQLConnector uses the urllib library.
113 Any extra kwargs passed to the SPARQLStore connector are passed to
114 urllib when doing HTTP calls. I.e. you have full control of
115 cookies/auth/headers.
116
117 Form example:
118
119 ```python
120 >>> store = SPARQLStore('...my endpoint ...', auth=('user','pass'))
121
122 ```
123
124 will use HTTP basic auth.
125 """
126
127 formula_aware = False
128 transaction_aware = False
129 graph_aware = True
130 regex_matching = NATIVE_REGEX
131
132 def __init__(
133 self,
134 query_endpoint: Optional[str] = None,
135 sparql11: bool = True,
136 context_aware: bool = True,
137 node_to_sparql: _NodeToSparql = _node_to_sparql,
138 returnFormat: Optional[str] = "xml", # noqa: N803
139 auth: Optional[Tuple[str, str]] = None,
140 **sparqlconnector_kwargs,
141 ):
142 super(SPARQLStore, self).__init__(
143 query_endpoint=query_endpoint,
144 returnFormat=returnFormat,
145 auth=auth,
146 **sparqlconnector_kwargs,
147 )
148
149 self.node_to_sparql = node_to_sparql
150 self.nsBindings: Dict[str, Any] = {}
151 self.sparql11 = sparql11
152 self.context_aware = context_aware
153 self.graph_aware = context_aware
154 self._queries = 0
155
156 # type error: Missing return statement
157 def open(self, configuration: Union[str, tuple[str, str]], create: bool = False) -> Optional[int]: # type: ignore[return]
158 """This method is included so that calls to this Store via Graph, e.g. Graph("SPARQLStore"),
159 can set the required parameters
160 """
161 if type(configuration) is str:
162 self.query_endpoint = configuration
163 else:
164 raise Exception(
165 "configuration must be a string (a single query endpoint URI)"
166 )
167
168 # Database Management Methods
169 def create(self, configuration: str) -> None:
170 raise TypeError(
171 "The SPARQL Store is read only. Try SPARQLUpdateStore for read/write."
172 )
173
174 def destroy(self, configuration: str) -> None:
175 raise TypeError("The SPARQL store is read only")
176
177 # Transactional interfaces
178 def commit(self) -> None:
179 raise TypeError("The SPARQL store is read only")
180
181 def rollback(self) -> None:
182 raise TypeError("The SPARQL store is read only")
183
184 def add(
185 self, _: _TripleType, context: _ContextType = None, quoted: bool = False
186 ) -> None:
187 raise TypeError("The SPARQL store is read only")
188
189 def addN(self, quads: Iterable[_QuadType]) -> None: # noqa: N802
190 raise TypeError("The SPARQL store is read only")
191
192 # type error: Signature of "remove" incompatible with supertype "Store"
193 def remove( # type: ignore[override]
194 self, _: _TriplePatternType, context: Optional[_ContextType]
195 ) -> None:
196 raise TypeError("The SPARQL store is read only")
197
198 # type error: Signature of "update" incompatible with supertype "SPARQLConnector"
199 def update( # type: ignore[override]
200 self,
201 query: Union[Update, str],
202 initNs: Dict[str, Any] = {}, # noqa: N803
203 initBindings: Dict[str, Identifier] = {}, # noqa: N803
204 queryGraph: Identifier = None, # noqa: N803
205 DEBUG: bool = False, # noqa: N803
206 ) -> None:
207 raise TypeError("The SPARQL store is read only")
208
209 def _query(self, *args: Any, **kwargs: Any) -> Result:
210 self._queries += 1
211
212 return super(SPARQLStore, self).query(*args, **kwargs)
213
214 def _inject_prefixes(self, query: str, extra_bindings: Mapping[str, Any]) -> str:
215 bindings = set(list(self.nsBindings.items()) + list(extra_bindings.items()))
216 if not bindings:
217 return query
218 return "\n".join(
219 [
220 "\n".join(["PREFIX %s: <%s>" % (k, v) for k, v in bindings]),
221 "", # separate ns_bindings from query with an empty line
222 query,
223 ]
224 )
225
226 # type error: Signature of "query" incompatible with supertype "SPARQLConnector"
227 # type error: Signature of "query" incompatible with supertype "Store"
228 def query( # type: ignore[override]
229 self,
230 query: Union[Query, str],
231 initNs: Optional[Mapping[str, Any]] = None, # noqa: N803
232 initBindings: Optional[Mapping[str, Identifier]] = None, # noqa: N803
233 queryGraph: Optional[str] = None, # noqa: N803
234 DEBUG: bool = False, # noqa: N803
235 ) -> Result:
236 self.debug = DEBUG
237 assert isinstance(query, str)
238
239 if initNs is not None and len(initNs) > 0:
240 query = self._inject_prefixes(query, initNs)
241
242 if initBindings:
243 if not self.sparql11:
244 raise Exception("initBindings not supported for SPARQL 1.0 Endpoints.")
245 v = list(initBindings)
246
247 # VALUES was added to SPARQL 1.1 on 2012/07/24
248 query += "\nVALUES ( %s )\n{ ( %s ) }\n" % (
249 " ".join("?" + str(x) for x in v),
250 " ".join(self.node_to_sparql(initBindings[x]) for x in v),
251 )
252
253 return self._query(
254 query, default_graph=queryGraph if self._is_contextual(queryGraph) else None
255 )
256
257 # type error: Return type "Iterator[Tuple[Tuple[Node, Node, Node], None]]" of "triples" incompatible with return type "Iterator[Tuple[Tuple[Node, Node, Node], Iterator[Optional[Graph]]]]"
258 def triples( # type: ignore[override]
259 self, spo: _TriplePatternType, context: Optional[_ContextType] = None
260 ) -> Iterator[Tuple[_TripleType, None]]:
261 """
262 - tuple **(s, o, p)**
263 the triple used as filter for the SPARQL select.
264 (None, None, None) means anything.
265 - context **context**
266 the graph effectively calling this method.
267
268 Returns a tuple of triples executing essentially a SPARQL like
269 SELECT ?subj ?pred ?obj WHERE { ?subj ?pred ?obj }
270
271 **context** may include three parameter
272 to refine the underlying query:
273
274 * LIMIT: an integer to limit the number of results
275 * OFFSET: an integer to enable paging of results
276 * ORDERBY: an instance of Variable('s'), Variable('o') or Variable('p') or, by default, the first 'None' from the given triple
277
278 !!! warning "Limit and offset
279
280 - Using LIMIT or OFFSET automatically include ORDERBY otherwise this is
281 because the results are retrieved in a not deterministic way (depends on
282 the walking path on the graph)
283 - Using OFFSET without defining LIMIT will discard the first OFFSET - 1 results
284
285 ```python
286 a_graph.LIMIT = limit
287 a_graph.OFFSET = offset
288 triple_generator = a_graph.triples(mytriple):
289 # do something
290 # Removes LIMIT and OFFSET if not required for the next triple() calls
291 del a_graph.LIMIT
292 del a_graph.OFFSET
293 ```
294 """
295
296 s, p, o = spo
297
298 vars = []
299 if not s:
300 s = Variable("s")
301 vars.append(s)
302
303 if not p:
304 p = Variable("p")
305 vars.append(p)
306 if not o:
307 o = Variable("o")
308 vars.append(o)
309
310 if vars:
311 v = " ".join([term.n3() for term in vars])
312 verb = "SELECT %s " % v
313 else:
314 verb = "ASK"
315
316 nts = self.node_to_sparql
317 query = "%s { %s %s %s }" % (verb, nts(s), nts(p), nts(o))
318
319 # The ORDER BY is necessary
320 if (
321 hasattr(context, LIMIT)
322 or hasattr(context, OFFSET)
323 or hasattr(context, ORDERBY)
324 ):
325 var = None
326 if isinstance(s, Variable):
327 var = s
328 elif isinstance(p, Variable):
329 var = p
330 elif isinstance(o, Variable):
331 var = o
332 elif hasattr(context, ORDERBY) and isinstance(
333 getattr(context, ORDERBY), Variable
334 ):
335 var = getattr(context, ORDERBY)
336 # type error: Item "None" of "Optional[Variable]" has no attribute "n3"
337 query = query + " %s %s" % (ORDERBY, var.n3()) # type: ignore[union-attr]
338
339 try:
340 query = query + " LIMIT %s" % int(getattr(context, LIMIT))
341 except (ValueError, TypeError, AttributeError):
342 pass
343 try:
344 query = query + " OFFSET %s" % int(getattr(context, OFFSET))
345 except (ValueError, TypeError, AttributeError):
346 pass
347
348 result = self._query(
349 query,
350 # type error: Item "None" of "Optional[Graph]" has no attribute "identifier"
351 default_graph=context.identifier if self._is_contextual(context) else None, # type: ignore[union-attr]
352 )
353
354 if vars:
355 if type(result) is tuple:
356 if result[0] == 401:
357 raise ValueError(
358 "It looks like you need to authenticate with this SPARQL Store. HTTP unauthorized"
359 )
360 for row in result:
361 if TYPE_CHECKING:
362 # This will be a ResultRow because if vars is truthish then
363 # the query will be a SELECT query.
364 assert isinstance(row, ResultRow)
365 yield (
366 # type error: No overload variant of "get" of "ResultRow" matches argument types "Node", "Node"
367 row.get(s, s), # type: ignore[call-overload]
368 row.get(p, p), # type: ignore[call-overload]
369 row.get(o, o), # type: ignore[call-overload]
370 ), None # why is the context here not the passed in graph 'context'?
371 else:
372 if result.askAnswer:
373 yield (s, p, o), None
374
375 def triples_choices(
376 self,
377 _: _TripleChoiceType,
378 context: Optional[_ContextType] = None,
379 ) -> Generator[
380 Tuple[
381 Tuple[_SubjectType, _PredicateType, _ObjectType],
382 Iterator[Optional[_ContextType]],
383 ],
384 None,
385 None,
386 ]:
387 """
388 A variant of triples that can take a list of terms instead of a
389 single term in any slot. Stores can implement this to optimize
390 the response time from the import default 'fallback' implementation,
391 which will iterate over each term in the list and dispatch to
392 triples.
393 """
394 raise NotImplementedError("Triples choices currently not supported")
395
396 def __len__(self, context: Optional[_ContextType] = None) -> int:
397 if not self.sparql11:
398 raise NotImplementedError(
399 "For performance reasons, this is not"
400 + "supported for sparql1.0 endpoints"
401 )
402 else:
403 q = "SELECT (count(*) as ?c) WHERE {?s ?p ?o .}"
404
405 result = self._query(
406 q,
407 # type error: Item "None" of "Optional[Graph]" has no attribute "identifier"
408 default_graph=(
409 context.identifier # type: ignore[union-attr]
410 if self._is_contextual(context)
411 else None
412 ),
413 )
414 # type error: Item "Tuple[Node, ...]" of "Union[Tuple[Node, Node, Node], bool, ResultRow]" has no attribute "c"
415 return int(next(iter(result)).c) # type: ignore[union-attr]
416
417 # type error: Return type "Generator[Identifier, None, None]" of "contexts" incompatible with return type "Generator[Graph, None, None]" in supertype "Store"
418 def contexts( # type: ignore[override]
419 self, triple: Optional[_TripleType] = None
420 ) -> Generator[_ContextIdentifierType, None, None]:
421 """
422 Iterates over results to `SELECT ?NAME { GRAPH ?NAME { ?s ?p ?o } }`
423 or `SELECT ?NAME { GRAPH ?NAME {} }` if triple is `None`.
424
425 Returns instances of this store with the SPARQL wrapper
426 object updated via addNamedGraph(?NAME).
427
428 This causes a named-graph-uri key / value pair to be sent over
429 the protocol.
430
431 Please note that some SPARQL endpoints are not able to find empty named
432 graphs.
433 """
434
435 if triple:
436 nts = self.node_to_sparql
437 s, p, o = triple
438 params = (
439 nts(s if s else Variable("s")),
440 nts(p if p else Variable("p")),
441 nts(o if o else Variable("o")),
442 )
443 q = "SELECT ?name WHERE { GRAPH ?name { %s %s %s }}" % params
444 else:
445 q = "SELECT ?name WHERE { GRAPH ?name {} }"
446
447 result = self._query(q)
448 # type error: Item "bool" of "Union[Tuple[Node, Node, Node], bool, ResultRow]" has no attribute "name"
449 # error: Generator has incompatible item type "Union[Any, Identifier]"; expected "IdentifiedNode"
450 return (row.name for row in result) # type: ignore[union-attr,misc]
451
452 # Namespace persistence interface implementation
453 def bind(self, prefix: str, namespace: URIRef, override: bool = True) -> None:
454 bound_prefix = self.prefix(namespace)
455 if override and bound_prefix:
456 del self.nsBindings[bound_prefix]
457 self.nsBindings[prefix] = namespace
458
459 def prefix(self, namespace: URIRef) -> Optional[str]:
460 """ """
461 return dict([(v, k) for k, v in self.nsBindings.items()]).get(namespace)
462
463 def namespace(self, prefix: str) -> Optional[URIRef]:
464 return self.nsBindings.get(prefix)
465
466 def namespaces(self) -> Iterator[Tuple[str, URIRef]]:
467 for prefix, ns in self.nsBindings.items():
468 yield prefix, ns
469
470 def add_graph(self, graph: Graph) -> None:
471 raise TypeError("The SPARQL store is read only")
472
473 def remove_graph(self, graph: Graph) -> None:
474 raise TypeError("The SPARQL store is read only")
475
476 @overload
477 def _is_contextual(self, graph: None) -> te.Literal[False]: ...
478
479 @overload
480 def _is_contextual(self, graph: Optional[Union[Graph, str]]) -> bool: ...
481
482 def _is_contextual(self, graph: Optional[Union[Graph, str]]) -> bool:
483 """Returns `True` if the "GRAPH" keyword must appear
484 in the final SPARQL query sent to the endpoint.
485 """
486 if (not self.context_aware) or (graph is None):
487 return False
488 if isinstance(graph, str):
489 return graph != "__UNION__"
490 else:
491 return graph.identifier != DATASET_DEFAULT_GRAPH_ID
492
493 def subjects(
494 self,
495 predicate: Optional[_PredicateType] = None,
496 object: Optional[_ObjectType] = None,
497 ) -> Generator[_SubjectType, None, None]:
498 """A generator of subjects with the given predicate and object"""
499 for t, c in self.triples((None, predicate, object)):
500 yield t[0]
501
502 def predicates(
503 self,
504 subject: Optional[_SubjectType] = None,
505 object: Optional[_ObjectType] = None,
506 ) -> Generator[_PredicateType, None, None]:
507 """A generator of predicates with the given subject and object"""
508 for t, c in self.triples((subject, None, object)):
509 yield t[1]
510
511 def objects(
512 self,
513 subject: Optional[_SubjectType] = None,
514 predicate: Optional[_PredicateType] = None,
515 ) -> Generator[_ObjectType, None, None]:
516 """A generator of objects with the given subject and predicate"""
517 for t, c in self.triples((subject, predicate, None)):
518 yield t[2]
519
520 def subject_predicates(
521 self, object: Optional[_ObjectType] = None
522 ) -> Generator[Tuple[_SubjectType, _PredicateType], None, None]:
523 """A generator of (subject, predicate) tuples for the given object"""
524 for t, c in self.triples((None, None, object)):
525 yield t[0], t[1]
526
527 def subject_objects(
528 self, predicate: Optional[_PredicateType] = None
529 ) -> Generator[Tuple[_SubjectType, _ObjectType], None, None]:
530 """A generator of (subject, object) tuples for the given predicate"""
531 for t, c in self.triples((None, predicate, None)):
532 yield t[0], t[2]
533
534 def predicate_objects(
535 self, subject: Optional[_SubjectType] = None
536 ) -> Generator[Tuple[_PredicateType, _ObjectType], None, None]:
537 """A generator of (predicate, object) tuples for the given subject"""
538 for t, c in self.triples((subject, None, None)):
539 yield t[1], t[2]
540
541
542class SPARQLUpdateStore(SPARQLStore):
543 """A store using SPARQL queries for reading and SPARQL Update for changes.
544
545 This can be context-aware, if so, any changes will be to the given named
546 graph only.
547
548 In favor of the SPARQL 1.1 motivated Dataset, we advise against using this
549 with ConjunctiveGraphs, as it reads and writes from and to the
550 "default graph". Exactly what this means depends on the endpoint and can
551 result in confusion.
552
553 For Graph objects, everything works as expected.
554
555 See the [`SPARQLStore`][rdflib.plugins.stores.sparqlstore.SPARQLStore] base class for more information.
556 """
557
558 where_pattern = re.compile(r"""(?P<where>WHERE\s*\{)""", re.IGNORECASE)
559
560 ##############################################################
561 # Regex for injecting GRAPH blocks into updates on a context #
562 ##############################################################
563
564 # Observations on the SPARQL grammar (http://www.w3.org/TR/2013/REC-sparql11-query-20130321/):
565 # 1. Only the terminals STRING_LITERAL1, STRING_LITERAL2,
566 # STRING_LITERAL_LONG1, STRING_LITERAL_LONG2, and comments can contain
567 # curly braces.
568 # 2. The non-terminals introduce curly braces in pairs only.
569 # 3. Unescaped " can occur only in strings and comments.
570 # 3. Unescaped ' can occur only in strings, comments, and IRIRefs.
571 # 4. \ always escapes the following character, especially \", \', and
572 # \\ denote literal ", ', and \ respectively.
573 # 5. # always starts a comment outside of string and IRI
574 # 6. A comment ends at the next newline
575 # 7. IRIREFs need to be detected, as they may contain # without starting a comment
576 # 8. PrefixedNames do not contain a #
577 # As a consequence, it should be rather easy to detect strings and comments
578 # in order to avoid unbalanced curly braces.
579
580 # From the SPARQL grammar
581 STRING_LITERAL1 = "'([^'\\\\]|\\\\.)*'"
582 STRING_LITERAL2 = '"([^"\\\\]|\\\\.)*"'
583 STRING_LITERAL_LONG1 = "'''(('|'')?([^'\\\\]|\\\\.))*'''"
584 STRING_LITERAL_LONG2 = '"""(("|"")?([^"\\\\]|\\\\.))*"""'
585 String = "(%s)|(%s)|(%s)|(%s)" % (
586 STRING_LITERAL1,
587 STRING_LITERAL2,
588 STRING_LITERAL_LONG1,
589 STRING_LITERAL_LONG2,
590 )
591 IRIREF = '<([^<>"{}|^`\\]\\\\[\\x00-\\x20])*>'
592 COMMENT = "#[^\\x0D\\x0A]*([\\x0D\\x0A]|\\Z)"
593
594 # Simplified grammar to find { at beginning and } at end of blocks
595 BLOCK_START = "{"
596 BLOCK_END = "}"
597 ESCAPED = "\\\\."
598
599 # Match anything that doesn't start or end a block:
600 BlockContent = "(%s)|(%s)|(%s)|(%s)" % (String, IRIREF, COMMENT, ESCAPED)
601 BlockFinding = "(?P<block_start>%s)|(?P<block_end>%s)|(?P<block_content>%s)" % (
602 BLOCK_START,
603 BLOCK_END,
604 BlockContent,
605 )
606 BLOCK_FINDING_PATTERN = re.compile(BlockFinding)
607
608 # Note that BLOCK_FINDING_PATTERN.finditer() will not cover the whole
609 # string with matches. Everything that is not matched will have to be
610 # part of the modified query as is.
611
612 ##################################################################
613
614 def __init__(
615 self,
616 query_endpoint: Optional[str] = None,
617 update_endpoint: Optional[str] = None,
618 sparql11: bool = True,
619 context_aware: bool = True,
620 postAsEncoded: bool = True, # noqa: N803
621 autocommit: bool = True,
622 dirty_reads: bool = False,
623 **kwds,
624 ):
625 """
626 Args:
627 autocommit: if set, the store will commit after every
628 writing operations. If False, we only make queries on the
629 server once commit is called.
630 dirty_reads if set, we do not commit before reading. So you
631 cannot read what you wrote before manually calling commit.
632 """
633
634 SPARQLStore.__init__(
635 self,
636 query_endpoint,
637 sparql11,
638 context_aware,
639 update_endpoint=update_endpoint,
640 **kwds,
641 )
642
643 self.postAsEncoded = postAsEncoded
644 self.autocommit = autocommit
645 self.dirty_reads = dirty_reads
646 self._edits: Optional[List[str]] = None
647 self._updates = 0
648
649 def query(self, *args: Any, **kwargs: Any) -> Result:
650 if not self.autocommit and not self.dirty_reads:
651 self.commit()
652 return SPARQLStore.query(self, *args, **kwargs)
653
654 # type error: Signature of "triples" incompatible with supertype "Store"
655 def triples( # type: ignore[override]
656 self, *args: Any, **kwargs: Any
657 ) -> Iterator[Tuple[_TripleType, None]]:
658 if not self.autocommit and not self.dirty_reads:
659 self.commit()
660 return SPARQLStore.triples(self, *args, **kwargs)
661
662 # type error: Signature of "contexts" incompatible with supertype "Store"
663 def contexts( # type: ignore[override]
664 self, *args: Any, **kwargs: Any
665 ) -> Generator[_ContextIdentifierType, None, None]:
666 if not self.autocommit and not self.dirty_reads:
667 self.commit()
668 return SPARQLStore.contexts(self, *args, **kwargs)
669
670 def __len__(self, *args: Any, **kwargs: Any) -> int:
671 if not self.autocommit and not self.dirty_reads:
672 self.commit()
673 return SPARQLStore.__len__(self, *args, **kwargs)
674
675 def open(
676 self, configuration: Union[str, Tuple[str, str]], create: bool = False
677 ) -> None:
678 """Sets the endpoint URLs for this `SPARQLStore`
679
680 Args:
681 configuration: either a tuple of (query_endpoint, update_endpoint),
682 or a string with the endpoint which is configured as query and update endpoint
683 create: if True an exception is thrown.
684 """
685
686 if create:
687 raise Exception("Cannot create a SPARQL Endpoint")
688
689 if isinstance(configuration, tuple):
690 self.query_endpoint = configuration[0]
691 if len(configuration) > 1:
692 self.update_endpoint = configuration[1]
693 else:
694 self.query_endpoint = configuration
695 self.update_endpoint = configuration
696
697 def _transaction(self) -> List[str]:
698 if self._edits is None:
699 self._edits = []
700 return self._edits
701
702 # Transactional interfaces
703 def commit(self) -> None:
704 """`add()`, `addN()`, and `remove()` are transactional to reduce overhead of many small edits.
705 Read and update() calls will automatically commit any outstanding edits.
706 This should behave as expected most of the time, except that alternating writes
707 and reads can degenerate to the original call-per-triple situation that originally existed.
708 """
709 if self._edits and len(self._edits) > 0:
710 self._update("\n;\n".join(self._edits))
711 self._edits = None
712
713 def rollback(self) -> None:
714 self._edits = None
715
716 def add(
717 self,
718 spo: _TripleType,
719 context: Optional[_ContextType] = None,
720 quoted: bool = False,
721 ) -> None:
722 """Add a triple to the store of triples."""
723
724 if not self.update_endpoint:
725 raise Exception("UpdateEndpoint is not set")
726
727 assert not quoted
728 (subject, predicate, obj) = spo
729
730 nts = self.node_to_sparql
731 triple = "%s %s %s ." % (nts(subject), nts(predicate), nts(obj))
732 if self._is_contextual(context):
733 if TYPE_CHECKING:
734 # _is_contextual will never return true if context is None
735 assert context is not None
736 q = "INSERT DATA { GRAPH %s { %s } }" % (nts(context.identifier), triple)
737 else:
738 q = "INSERT DATA { %s }" % triple
739 self._transaction().append(q)
740 if self.autocommit:
741 self.commit()
742
743 def addN(self, quads: Iterable[_QuadType]) -> None: # noqa: N802
744 """Add a list of quads to the store."""
745 if not self.update_endpoint:
746 raise Exception("UpdateEndpoint is not set - call 'open'")
747
748 contexts = collections.defaultdict(list)
749 for subject, predicate, obj, context in quads:
750 contexts[context].append((subject, predicate, obj))
751 data: List[str] = []
752 nts = self.node_to_sparql
753 for context in contexts:
754 triples = [
755 "%s %s %s ." % (nts(subject), nts(predicate), nts(obj))
756 for subject, predicate, obj in contexts[context]
757 ]
758 data.append(
759 "INSERT DATA { GRAPH %s { %s } }\n"
760 % (nts(context.identifier), "\n".join(triples))
761 )
762 self._transaction().extend(data)
763 if self.autocommit:
764 self.commit()
765
766 # type error: Signature of "remove" incompatible with supertype "Store"
767 def remove( # type: ignore[override]
768 self, spo: _TriplePatternType, context: Optional[_ContextType]
769 ) -> None:
770 """Remove a triple from the store"""
771 if not self.update_endpoint:
772 raise Exception("UpdateEndpoint is not set - call 'open'")
773
774 (subject, predicate, obj) = spo
775 if not subject:
776 subject = Variable("S")
777 if not predicate:
778 predicate = Variable("P")
779 if not obj:
780 obj = Variable("O")
781
782 nts = self.node_to_sparql
783 triple = "%s %s %s ." % (nts(subject), nts(predicate), nts(obj))
784 if self._is_contextual(context):
785 if TYPE_CHECKING:
786 # _is_contextual will never return true if context is None
787 assert context is not None
788 cid = nts(context.identifier)
789 q = "WITH %(graph)s DELETE { %(triple)s } WHERE { %(triple)s }" % {
790 "graph": cid,
791 "triple": triple,
792 }
793 else:
794 q = "DELETE { %s } WHERE { %s } " % (triple, triple)
795 self._transaction().append(q)
796 if self.autocommit:
797 self.commit()
798
799 def setTimeout(self, timeout) -> None: # noqa: N802
800 self._timeout = int(timeout)
801
802 def _update(self, update):
803 self._updates += 1
804
805 SPARQLConnector.update(self, update)
806
807 # type error: Signature of "update" incompatible with supertype "SPARQLConnector"
808 # type error: Signature of "update" incompatible with supertype "Store"
809 def update( # type: ignore[override]
810 self,
811 query: Union[Update, str],
812 initNs: Dict[str, Any] = {}, # noqa: N803
813 initBindings: Dict[str, Identifier] = {}, # noqa: N803
814 queryGraph: Optional[str] = None, # noqa: N803
815 DEBUG: bool = False, # noqa: N803
816 ):
817 """Perform a SPARQL Update Query against the endpoint, INSERT, LOAD, DELETE etc.
818
819 Setting initNs adds PREFIX declarations to the beginning of
820 the update. Setting initBindings adds inline VALUEs to the
821 beginning of every WHERE clause. By the SPARQL grammar, all
822 operations that support variables (namely INSERT and DELETE)
823 require a WHERE clause.
824 Important: initBindings fails if the update contains the
825 substring 'WHERE {' which does not denote a WHERE clause, e.g.
826 if it is part of a literal.
827
828 !!! info "Context-aware query rewriting"
829
830 - **When:** If context-awareness is enabled and the graph is not the default graph of the store.
831 - **Why:** To ensure consistency with the [`Memory`][rdflib.plugins.stores.memory.Memory] store.
832 The graph must accept "local" SPARQL requests (requests with no GRAPH keyword)
833 as if it was the default graph.
834 - **What is done:** These "local" queries are rewritten by this store.
835 The content of each block of a SPARQL Update operation is wrapped in a GRAPH block
836 except if the block is empty.
837 This basically causes INSERT, INSERT DATA, DELETE, DELETE DATA and WHERE to operate
838 only on the context.
839 - **Example:** `"INSERT DATA { <urn:michel> <urn:likes> <urn:pizza> }"` is converted into
840 `"INSERT DATA { GRAPH <urn:graph> { <urn:michel> <urn:likes> <urn:pizza> } }"`.
841 - **Warning:** Queries are presumed to be "local" but this assumption is **not checked**.
842 For instance, if the query already contains GRAPH blocks, the latter will be wrapped in new GRAPH blocks.
843 - **Warning:** A simplified grammar is used that should tolerate
844 extensions of the SPARQL grammar. Still, the process may fail in
845 uncommon situations and produce invalid output.
846 """
847 if not self.update_endpoint:
848 raise Exception("Update endpoint is not set!")
849
850 self.debug = DEBUG
851 assert isinstance(query, str)
852 query = self._inject_prefixes(query, initNs)
853
854 if self._is_contextual(queryGraph):
855 if TYPE_CHECKING:
856 # _is_contextual will never return true if context is None
857 assert queryGraph is not None
858 query = self._insert_named_graph(query, queryGraph)
859
860 if initBindings:
861 # For INSERT and DELETE the WHERE clause is obligatory
862 # (http://www.w3.org/TR/2013/REC-sparql11-query-20130321/#rModify)
863 # Other query types do not allow variables and don't
864 # have a WHERE clause. This also works for updates with
865 # more than one INSERT/DELETE.
866 v = list(initBindings)
867 values = "\nVALUES ( %s )\n{ ( %s ) }\n" % (
868 " ".join("?" + str(x) for x in v),
869 " ".join(self.node_to_sparql(initBindings[x]) for x in v),
870 )
871
872 query = self.where_pattern.sub("WHERE { " + values, query)
873
874 self._transaction().append(query)
875 if self.autocommit:
876 self.commit()
877
878 def _insert_named_graph(self, query: str, query_graph: str) -> str:
879 """Inserts GRAPH <query_graph> {} into blocks of SPARQL Update operations
880
881 For instance, `INSERT DATA { <urn:michel> <urn:likes> <urn:pizza> }`
882 is converted into
883 `INSERT DATA { GRAPH <urn:graph> { <urn:michel> <urn:likes> <urn:pizza> } }`
884 """
885 if isinstance(query_graph, Node):
886 query_graph = self.node_to_sparql(query_graph)
887 else:
888 query_graph = "<%s>" % query_graph
889 graph_block_open = " GRAPH %s {" % query_graph
890 graph_block_close = "} "
891
892 # SPARQL Update supports the following operations:
893 # LOAD, CLEAR, DROP, ADD, MOVE, COPY, CREATE, INSERT DATA, DELETE DATA, DELETE/INSERT, DELETE WHERE
894 # LOAD, CLEAR, DROP, ADD, MOVE, COPY, CREATE do not make much sense in a context.
895 # INSERT DATA, DELETE DATA, and DELETE WHERE require the contents of their block to be wrapped in a GRAPH <?> { }.
896 # DELETE/INSERT supports the WITH keyword, which sets the graph to be
897 # used for all following DELETE/INSERT instruction including the
898 # non-optional WHERE block. Equivalently, a GRAPH block can be added to
899 # all blocks.
900 #
901 # Strategy employed here: Wrap the contents of every top-level block into a `GRAPH <?> { }`.
902
903 level = 0
904 modified_query = []
905 pos = 0
906 for match in self.BLOCK_FINDING_PATTERN.finditer(query):
907 if match.group("block_start") is not None:
908 level += 1
909 if level == 1:
910 modified_query.append(query[pos : match.end()])
911 modified_query.append(graph_block_open)
912 pos = match.end()
913 elif match.group("block_end") is not None:
914 if level == 1:
915 since_previous_pos = query[pos : match.start()]
916 if modified_query[-1] is graph_block_open and (
917 since_previous_pos == "" or since_previous_pos.isspace()
918 ):
919 # In this case, adding graph_block_start and
920 # graph_block_end results in an empty GRAPH block. Some
921 # endpoints (e.g. TDB) can not handle this. Therefore
922 # remove the previously added block_start.
923 modified_query.pop()
924 modified_query.append(since_previous_pos)
925 else:
926 modified_query.append(since_previous_pos)
927 modified_query.append(graph_block_close)
928 pos = match.start()
929 level -= 1
930 modified_query.append(query[pos:])
931
932 return "".join(modified_query)
933
934 def add_graph(self, graph: Graph) -> None:
935 if not self.graph_aware:
936 Store.add_graph(self, graph)
937 elif graph.identifier != DATASET_DEFAULT_GRAPH_ID:
938 self.update("CREATE GRAPH %s" % self.node_to_sparql(graph.identifier))
939
940 def remove_graph(self, graph: Graph) -> None:
941 if not self.graph_aware:
942 Store.remove_graph(self, graph)
943 elif graph.identifier == DATASET_DEFAULT_GRAPH_ID:
944 self.update("DROP DEFAULT")
945 else:
946 self.update("DROP GRAPH %s" % self.node_to_sparql(graph.identifier))
947
948 def subjects(
949 self,
950 predicate: Optional[_PredicateType] = None,
951 object: Optional[_ObjectType] = None,
952 ) -> Generator[_SubjectType, None, None]:
953 """A generator of subjects with the given predicate and object"""
954 for t, c in self.triples((None, predicate, object)):
955 yield t[0]
956
957 def predicates(
958 self,
959 subject: Optional[_SubjectType] = None,
960 object: Optional[_ObjectType] = None,
961 ) -> Generator[_PredicateType, None, None]:
962 """A generator of predicates with the given subject and object"""
963 for t, c in self.triples((subject, None, object)):
964 yield t[1]
965
966 def objects(
967 self,
968 subject: Optional[_SubjectType] = None,
969 predicate: Optional[_PredicateType] = None,
970 ) -> Generator[_ObjectType, None, None]:
971 """A generator of objects with the given subject and predicate"""
972 for t, c in self.triples((subject, predicate, None)):
973 yield t[2]
974
975 def subject_predicates(
976 self, object: Optional[_ObjectType] = None
977 ) -> Generator[Tuple[_SubjectType, _PredicateType], None, None]:
978 """A generator of (subject, predicate) tuples for the given object"""
979 for t, c in self.triples((None, None, object)):
980 yield t[0], t[1]
981
982 def subject_objects(
983 self, predicate: Optional[_PredicateType] = None
984 ) -> Generator[Tuple[_SubjectType, _ObjectType], None, None]:
985 """A generator of (subject, object) tuples for the given predicate"""
986 for t, c in self.triples((None, predicate, None)):
987 yield t[0], t[2]
988
989 def predicate_objects(
990 self, subject: Optional[_SubjectType] = None
991 ) -> Generator[Tuple[_PredicateType, _ObjectType], None, None]:
992 """A generator of (predicate, object) tuples for the given subject"""
993 for t, c in self.triples((subject, None, None)):
994 yield t[1], t[2]
995
996
997__all__ = ["SPARQLUpdateStore", "SPARQLStore"]