prograph 1.3.3__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (237) hide show
  1. prograph/__init__.py +36 -0
  2. prograph/__main__.py +5 -0
  3. prograph/_version.py +375 -0
  4. prograph/cli/__init__.py +1 -0
  5. prograph/cli/_iri_utils.py +124 -0
  6. prograph/cli/emit_genie_space.py +107 -0
  7. prograph/cli/generate_views.py +140 -0
  8. prograph/cli/main.py +420 -0
  9. prograph/cli/schema_inferrer.py +746 -0
  10. prograph/cli/ttl_loader.py +289 -0
  11. prograph/cli/upload_genie_space.py +84 -0
  12. prograph/config/__init__.py +27 -0
  13. prograph/config/yaml_config.py +848 -0
  14. prograph/demos/__init__.py +14 -0
  15. prograph/demos/turbofan/README.md +74 -0
  16. prograph/demos/turbofan/SCENARIO.md +209 -0
  17. prograph/demos/turbofan/__init__.py +75 -0
  18. prograph/demos/turbofan/create_tables.sql +206 -0
  19. prograph/demos/turbofan/data/engine-instances.ttl +1123 -0
  20. prograph/demos/turbofan/data/sensor-timeseries.csv +90 -0
  21. prograph/demos/turbofan/demo.py +162 -0
  22. prograph/demos/turbofan/genie_qa_notebook.py +434 -0
  23. prograph/demos/turbofan/graph.yaml +1098 -0
  24. prograph/demos/turbofan/instance_graph_demo.py +32 -0
  25. prograph/demos/turbofan/load.py +223 -0
  26. prograph/demos/turbofan/mapping.r2rml.ttl +991 -0
  27. prograph/demos/turbofan/ontology/engine-maintenance.ttl +606 -0
  28. prograph/demos/turbofan/payload-shapes.ttl +33 -0
  29. prograph/demos/turbofan/queries/example-queries.sparql +215 -0
  30. prograph/demos/turbofan/shapes.ttl +75 -0
  31. prograph/demos/turbofan/tables.py +106 -0
  32. prograph/demos/turbofan/turbofan_schema.py +393 -0
  33. prograph/demos/turbofan/validation_demo.py +153 -0
  34. prograph/describe.py +231 -0
  35. prograph/endpoint/__init__.py +12 -0
  36. prograph/endpoint/app.py +722 -0
  37. prograph/endpoint/cli.py +280 -0
  38. prograph/endpoint/credentials.py +240 -0
  39. prograph/endpoint/engines.py +418 -0
  40. prograph/endpoint/negotiate.py +101 -0
  41. prograph/endpoint/results.py +181 -0
  42. prograph/endpoint/service.py +31 -0
  43. prograph/engine.py +2718 -0
  44. prograph/execution.py +455 -0
  45. prograph/executors/__init__.py +6 -0
  46. prograph/executors/base.py +11 -0
  47. prograph/executors/databricks_sql_executor.py +51 -0
  48. prograph/executors/duckdb_executor.py +24 -0
  49. prograph/executors/mysql_executor.py +20 -0
  50. prograph/executors/oracle_executor.py +24 -0
  51. prograph/executors/pandas_executor.py +72 -0
  52. prograph/executors/postgresql_executor.py +35 -0
  53. prograph/executors/spark_executor.py +88 -0
  54. prograph/executors/sqlserver_executor.py +35 -0
  55. prograph/extras/__init__.py +1 -0
  56. prograph/extras/graphql/__init__.py +33 -0
  57. prograph/extras/graphql/execute.py +25 -0
  58. prograph/extras/graphql/schema.py +314 -0
  59. prograph/extras/instance_graph.py +559 -0
  60. prograph/genie/__init__.py +83 -0
  61. prograph/genie/databricks_uploader.py +306 -0
  62. prograph/genie/deploy.py +393 -0
  63. prograph/genie/formats.py +414 -0
  64. prograph/genie/instruction_generator.py +375 -0
  65. prograph/genie/sample_query_generator.py +256 -0
  66. prograph/genie/shacl_views.py +318 -0
  67. prograph/genie/space_emitter.py +329 -0
  68. prograph/genie/view_generator.py +628 -0
  69. prograph/genie/view_writer.py +172 -0
  70. prograph/graph/__init__.py +1 -0
  71. prograph/graph/ansi_session.py +348 -0
  72. prograph/graph/databricks_sql_graph.py +300 -0
  73. prograph/graph/drivers.py +143 -0
  74. prograph/graph/duckdb_graph.py +68 -0
  75. prograph/graph/mysql_graph.py +38 -0
  76. prograph/graph/oracle_graph.py +285 -0
  77. prograph/graph/pandas_graph.py +343 -0
  78. prograph/graph/postgresql_graph.py +644 -0
  79. prograph/graph/spark_graph.py +556 -0
  80. prograph/graph/sql_graph.py +83 -0
  81. prograph/graph/sqlserver_graph.py +72 -0
  82. prograph/hints.py +95 -0
  83. prograph/logging.py +550 -0
  84. prograph/mcp/__init__.py +29 -0
  85. prograph/mcp/__main__.py +180 -0
  86. prograph/mcp/bootstrap.py +98 -0
  87. prograph/mcp/server.py +601 -0
  88. prograph/mcp/sparql.py +397 -0
  89. prograph/mcp/tools.py +504 -0
  90. prograph/nlp/__init__.py +79 -0
  91. prograph/nlp/client.py +305 -0
  92. prograph/nlp/databricks_tools.py +369 -0
  93. prograph/nlp/graph_context.py +313 -0
  94. prograph/nlp/interface.py +652 -0
  95. prograph/nlp/prompts/__init__.py +19 -0
  96. prograph/nlp/prompts/examples.py +258 -0
  97. prograph/nlp/prompts/system.py +239 -0
  98. prograph/nlp/providers/__init__.py +14 -0
  99. prograph/nlp/providers/anthropic.py +274 -0
  100. prograph/nlp/providers/databricks.py +312 -0
  101. prograph/nlp/providers/openai.py +203 -0
  102. prograph/nlp/schema_context.py +78 -0
  103. prograph/ontology/__init__.py +53 -0
  104. prograph/ontology/alignment.py +542 -0
  105. prograph/ontology/hierarchy.py +310 -0
  106. prograph/ontology/imports.py +587 -0
  107. prograph/ontology/layer.py +991 -0
  108. prograph/ontology/skos.py +61 -0
  109. prograph/owl/__init__.py +27 -0
  110. prograph/owl/defined_classes.py +323 -0
  111. prograph/parameters.py +242 -0
  112. prograph/parser/__init__.py +1 -0
  113. prograph/parser/cypher/CypherLexer.py +836 -0
  114. prograph/parser/cypher/CypherListener.py +966 -0
  115. prograph/parser/cypher/CypherParser.py +10854 -0
  116. prograph/parser/cypher/CypherVisitor.py +543 -0
  117. prograph/parser/cypher/__init__.py +1 -0
  118. prograph/parser/sparql/SparqlLexer.py +801 -0
  119. prograph/parser/sparql/SparqlParser.py +10146 -0
  120. prograph/parser/sparql/SparqlParserListener.py +1056 -0
  121. prograph/parser/sparql/SparqlParserVisitor.py +593 -0
  122. prograph/parser/sparql/__init__.py +8 -0
  123. prograph/plan/__init__.py +3 -0
  124. prograph/plan/ir/__init__.py +1 -0
  125. prograph/plan/ir/casts.py +338 -0
  126. prograph/plan/ir/consistency.py +397 -0
  127. prograph/plan/ir/construct.py +90 -0
  128. prograph/plan/ir/cost.py +234 -0
  129. prograph/plan/ir/cypher_answer.py +1081 -0
  130. prograph/plan/ir/cypher_apoc.py +717 -0
  131. prograph/plan/ir/cypher_apoc_convert.py +505 -0
  132. prograph/plan/ir/cypher_apoc_date.py +845 -0
  133. prograph/plan/ir/cypher_apoc_map.py +496 -0
  134. prograph/plan/ir/cypher_apoc_meta.py +384 -0
  135. prograph/plan/ir/cypher_apoc_path.py +597 -0
  136. prograph/plan/ir/cypher_apoc_procedures.py +163 -0
  137. prograph/plan/ir/cypher_apoc_text.py +785 -0
  138. prograph/plan/ir/cypher_front.py +5474 -0
  139. prograph/plan/ir/cypher_functions.py +565 -0
  140. prograph/plan/ir/cypher_lists.py +935 -0
  141. prograph/plan/ir/cypher_maps.py +370 -0
  142. prograph/plan/ir/cypher_mixed.py +604 -0
  143. prograph/plan/ir/cypher_ontology.py +226 -0
  144. prograph/plan/ir/cypher_procedures.py +191 -0
  145. prograph/plan/ir/cypher_runtime_errors.py +107 -0
  146. prograph/plan/ir/cypher_temporal.py +1357 -0
  147. prograph/plan/ir/cypher_temporal_arith.py +339 -0
  148. prograph/plan/ir/cypher_values.py +546 -0
  149. prograph/plan/ir/cypher_write.py +612 -0
  150. prograph/plan/ir/dataset.py +643 -0
  151. prograph/plan/ir/dates.py +102 -0
  152. prograph/plan/ir/entry.py +992 -0
  153. prograph/plan/ir/expr.py +260 -0
  154. prograph/plan/ir/facts.py +1171 -0
  155. prograph/plan/ir/fresh.py +291 -0
  156. prograph/plan/ir/freshness.py +625 -0
  157. prograph/plan/ir/identity.py +797 -0
  158. prograph/plan/ir/java_datetime.py +265 -0
  159. prograph/plan/ir/java_regex.py +391 -0
  160. prograph/plan/ir/join_order.py +39 -0
  161. prograph/plan/ir/key_checks.py +433 -0
  162. prograph/plan/ir/keys.py +454 -0
  163. prograph/plan/ir/lower.py +5323 -0
  164. prograph/plan/ir/ops.py +619 -0
  165. prograph/plan/ir/owl_rl.py +1119 -0
  166. prograph/plan/ir/owl_rl_rules.py +725 -0
  167. prograph/plan/ir/profiles.py +694 -0
  168. prograph/plan/ir/ql.py +987 -0
  169. prograph/plan/ir/rdfs.py +342 -0
  170. prograph/plan/ir/rewrite.py +1782 -0
  171. prograph/plan/ir/saturate.py +339 -0
  172. prograph/plan/ir/semantics.py +103 -0
  173. prograph/plan/ir/slot.py +509 -0
  174. prograph/plan/ir/sparql_front.py +3418 -0
  175. prograph/plan/ir/strings.py +534 -0
  176. prograph/plan/ir/term_functions.py +274 -0
  177. prograph/plan/ir/terms.py +84 -0
  178. prograph/plan/ir/xpath_regex.py +264 -0
  179. prograph/plan/run_record.py +65 -0
  180. prograph/plan/sql/__init__.py +21 -0
  181. prograph/plan/sql/dialect.py +3726 -0
  182. prograph/plan/sql/mysql_serializer.py +103 -0
  183. prograph/plan/sql/names.py +65 -0
  184. prograph/plan/sql/oracle_serializer.py +306 -0
  185. prograph/plan/sql/pg_serializer.py +501 -0
  186. prograph/plan/sql/rel_algebra.py +781 -0
  187. prograph/plan/sql/sql_serializer.py +1419 -0
  188. prograph/plan/sql/sqlserver_serializer.py +603 -0
  189. prograph/provenance.py +222 -0
  190. prograph/r2rml/__init__.py +48 -0
  191. prograph/r2rml/catalog.py +259 -0
  192. prograph/r2rml/compile.py +372 -0
  193. prograph/r2rml/direct.py +140 -0
  194. prograph/r2rml/export.py +495 -0
  195. prograph/r2rml/model.py +180 -0
  196. prograph/r2rml/parser.py +546 -0
  197. prograph/r2rml/schema.py +120 -0
  198. prograph/read_only.py +122 -0
  199. prograph/results.py +157 -0
  200. prograph/rules/__init__.py +168 -0
  201. prograph/rules/__main__.py +32 -0
  202. prograph/schema/__init__.py +60 -0
  203. prograph/schema/change_set.py +50 -0
  204. prograph/schema/collations.py +198 -0
  205. prograph/schema/compile_schema.py +388 -0
  206. prograph/schema/context.py +845 -0
  207. prograph/schema/examples.py +234 -0
  208. prograph/schema/iri.py +817 -0
  209. prograph/schema/literals.py +94 -0
  210. prograph/schema/lpg_view.py +617 -0
  211. prograph/schema/mapping.py +1803 -0
  212. prograph/schema/maps_schema.py +40 -0
  213. prograph/schema/naming.py +77 -0
  214. prograph/schema/query_sources.py +59 -0
  215. prograph/schema/rows.py +215 -0
  216. prograph/schema/source_map.py +1103 -0
  217. prograph/schema/store_view.py +459 -0
  218. prograph/schema/types.py +569 -0
  219. prograph/schema/xsd.py +569 -0
  220. prograph/shacl/__init__.py +30 -0
  221. prograph/shacl/dqv.py +58 -0
  222. prograph/shacl/generate.py +255 -0
  223. prograph/shacl/report.py +138 -0
  224. prograph/shacl/validator.py +164 -0
  225. prograph/store.py +1737 -0
  226. prograph/utils/__init__.py +6 -0
  227. prograph/utils/exceptions.py +308 -0
  228. prograph/utils/helpers.py +126 -0
  229. prograph/warnings.py +46 -0
  230. prograph/writes.py +369 -0
  231. prograph-1.3.3.dist-info/METADATA +281 -0
  232. prograph-1.3.3.dist-info/RECORD +237 -0
  233. prograph-1.3.3.dist-info/WHEEL +5 -0
  234. prograph-1.3.3.dist-info/entry_points.txt +3 -0
  235. prograph-1.3.3.dist-info/licenses/LICENSE +201 -0
  236. prograph-1.3.3.dist-info/licenses/NOTICE +10 -0
  237. prograph-1.3.3.dist-info/top_level.txt +1 -0
prograph/execution.py ADDED
@@ -0,0 +1,455 @@
1
+ """Query execution context and cancellation.
2
+
3
+ A `QueryContext` is one query's handle: `engine.execute(..., context=ctx)` runs the query with it, and
4
+ `ctx.cancel()` from another thread stops it. The engine sets the context around the query
5
+ (`running`), and every statement the query starts registers with it through its `StatementGuard`, so
6
+ a cancel stops the statement the database is running (docs/reference/configuration.md, Cancellation),
7
+ and no later statement of the query starts (`checkpoint`).
8
+ """
9
+
10
+ import logging
11
+ import uuid
12
+ import time
13
+ from dataclasses import dataclass, field
14
+ from enum import Enum
15
+ from threading import Lock
16
+ from typing import Any, Callable, Dict, Iterator, Optional, Set, TYPE_CHECKING
17
+
18
+ from prograph.rules import home
19
+
20
+ logger = logging.getLogger(__name__)
21
+
22
+ if TYPE_CHECKING:
23
+ from databricks.sdk import WorkspaceClient
24
+
25
+
26
+ class QueryStatus(Enum):
27
+ """Query execution status."""
28
+ PENDING = "pending"
29
+ RUNNING = "running"
30
+ COMPLETED = "completed"
31
+ CANCELLED = "cancelled"
32
+ FAILED = "failed"
33
+
34
+
35
+ _ENDED = (QueryStatus.COMPLETED, QueryStatus.CANCELLED, QueryStatus.FAILED)
36
+
37
+
38
+ @home("query-cancel", "Cancelling a query stops its running statement and starts no other",
39
+ terms=("cancel", "QueryContext", "QueryCancelledException", "interrupt", "adbc_cancel",
40
+ "cancelJobGroup", "query id", "cancel_query"))
41
+ @dataclass
42
+ class QueryContext:
43
+ """One query's handle, to cancel it from another thread.
44
+
45
+ `query_id` is a random uuid4: a server hands it to the caller as the capability to cancel
46
+ the query, so it is never logged nor put in a message. `cancel()` stops the statement the
47
+ query is running (each engine's way: `StatementGuard`), and the query raises
48
+ `QueryCancelledException`; no later statement of it starts.
49
+
50
+ Example:
51
+ >>> ctx = QueryContext()
52
+ >>> engine.execute("SELECT ?s WHERE { ?s ?p ?o }", context=ctx)
53
+ >>> # In another thread:
54
+ >>> ctx.cancel()
55
+ """
56
+ query_id: str = field(default_factory=lambda: str(uuid.uuid4()))
57
+ status: QueryStatus = QueryStatus.PENDING
58
+ start_time: Optional[float] = None
59
+ end_time: Optional[float] = None
60
+ error: Optional[str] = None
61
+
62
+ # A Spark-routed SQL warehouse statement (the SDK's statement id), cancelled through the SDK.
63
+ _statement_id: Optional[str] = field(default=None, repr=False)
64
+ _workspace_client: Optional['WorkspaceClient'] = field(default=None, repr=False)
65
+
66
+ _cancelled: bool = field(default=False, repr=False)
67
+ # A write the query made is committed (`committing`): from then on a cancel changes nothing.
68
+ _committed: bool = field(default=False, repr=False)
69
+ _lock: Lock = field(default_factory=Lock, repr=False)
70
+ # The statements running now, each by its guard.
71
+ _guards: Set["StatementGuard"] = field(default_factory=set, repr=False)
72
+
73
+ @property
74
+ def is_cancelled(self) -> bool:
75
+ """Check if cancellation has been requested."""
76
+ return self._cancelled
77
+
78
+ @property
79
+ def elapsed_ms(self) -> Optional[float]:
80
+ """Get elapsed time in milliseconds."""
81
+ if self.start_time is None:
82
+ return None
83
+ end = self.end_time or time.time()
84
+ return (end - self.start_time) * 1000
85
+
86
+ def mark_running(self) -> None:
87
+ """Mark query as running."""
88
+ with self._lock:
89
+ self.status = QueryStatus.RUNNING
90
+ self.start_time = time.time()
91
+
92
+ def mark_completed(self) -> None:
93
+ """Mark query as completed."""
94
+ with self._lock:
95
+ self.status = QueryStatus.CANCELLED if self._cancelled else QueryStatus.COMPLETED
96
+ self.end_time = time.time()
97
+
98
+ def mark_failed(self, error: str) -> None:
99
+ """Mark query as failed (cancelled, where a cancel stopped it)."""
100
+ with self._lock:
101
+ self.status = QueryStatus.CANCELLED if self._cancelled else QueryStatus.FAILED
102
+ self.error = error
103
+ self.end_time = time.time()
104
+
105
+ def mark_cancelled(self) -> None:
106
+ """Mark query as cancelled."""
107
+ with self._lock:
108
+ self.status = QueryStatus.CANCELLED
109
+ self.end_time = time.time()
110
+
111
+ def set_statement_id(self, statement_id: str, client: 'WorkspaceClient') -> None:
112
+ """Set SQL Warehouse statement ID for cancellation."""
113
+ with self._lock:
114
+ self._statement_id = statement_id
115
+ self._workspace_client = client
116
+
117
+ def _attach(self, guard: "StatementGuard") -> None:
118
+ """A statement starts: refused once the query is cancelled (it never starts)."""
119
+ with self._lock:
120
+ if self._cancelled:
121
+ raise QueryCancelledException(CANCELLED)
122
+ self._guards.add(guard)
123
+
124
+ def _detach(self, guard: "StatementGuard") -> None:
125
+ with self._lock:
126
+ self._guards.discard(guard)
127
+
128
+ def _running(self, guard: "StatementGuard") -> bool:
129
+ with self._lock:
130
+ return guard in self._guards
131
+
132
+ def cancel(self) -> bool:
133
+ """Cancel the query: the statement it is running is stopped (each engine's way,
134
+ `StatementGuard`), and no later statement of it starts. True when the query had not
135
+ ended; False, and nothing changes, once it has (completed, failed or cancelled)."""
136
+ with self._lock:
137
+ if self.status in _ENDED or self._committed:
138
+ return False
139
+ if self._cancelled:
140
+ return True # asked once already: its statement is being stopped
141
+ self._cancelled = True
142
+ running = list(self._guards)
143
+ for guard in running:
144
+ guard.interrupt()
145
+ if self._statement_id and self._workspace_client:
146
+ try:
147
+ self._workspace_client.statement_execution.cancel_execution(self._statement_id)
148
+ except Exception as e: # noqa: BLE001 - the statement may have ended
149
+ logger.debug("cancel_warehouse_statement_failed", exc_info=e)
150
+ return True
151
+
152
+ def check_cancelled(self) -> None:
153
+ """Raise QueryCancelledException once the query is cancelled."""
154
+ if self._cancelled:
155
+ raise QueryCancelledException(CANCELLED)
156
+
157
+ def _commit(self) -> None:
158
+ """The query's write is about to commit: raise where it was cancelled first; else from now on
159
+ a cancel returns False and changes nothing, one atomic step, so a committed write is never
160
+ reported cancelled (a retry would write it again)."""
161
+ with self._lock:
162
+ if self._cancelled:
163
+ raise QueryCancelledException(CANCELLED)
164
+ self._committed = True
165
+
166
+
167
+ class QueryCancelledException(Exception):
168
+ """Raised when a query is cancelled during execution."""
169
+ pass
170
+
171
+
172
+ CANCELLED = "the query was cancelled"
173
+
174
+
175
+ # What stops a query from outside: a cancellation, and a timeout (a warehouse
176
+ # statement past `statement_timeout`, raised as TimeoutError). Both are
177
+ # Exception subclasses, so a broad `except Exception` would catch them; each
178
+ # such handler on the query's path re-raises these unchanged, in every
179
+ # execution mode: neither is a refusal, a defect, or a reason to answer in
180
+ # Python. KeyboardInterrupt and SystemExit are not
181
+ # Exceptions and pass every such handler by themselves.
182
+ INTERRUPTS = (QueryCancelledException, TimeoutError)
183
+
184
+
185
+
186
+ # The statement deadline (`prograph serve --timeout`): a time.monotonic() past which a database
187
+ # statement this context started is cancelled. A server sets it around a query; every backend that can
188
+ # stop its statement from another thread arms a timer with it (`StatementGuard`).
189
+ import contextvars as _contextvars
190
+ import threading as _threading
191
+ from contextlib import contextmanager as _contextmanager
192
+
193
+ _DEADLINE: "_contextvars.ContextVar[Optional[float]]" = _contextvars.ContextVar(
194
+ "prograph_statement_deadline", default=None)
195
+
196
+ # The query running in this context (`engine.execute`'s `context`), which every statement it starts
197
+ # registers with.
198
+ _CURRENT: "_contextvars.ContextVar[Optional[QueryContext]]" = _contextvars.ContextVar(
199
+ "prograph_query_context", default=None)
200
+
201
+
202
+ @_contextmanager
203
+ def statement_deadline(seconds: Optional[float]):
204
+ """Statements started inside are cancelled `seconds` from now (None: no deadline)."""
205
+ token = _DEADLINE.set(time.monotonic() + seconds if seconds else None)
206
+ try:
207
+ yield
208
+ finally:
209
+ _DEADLINE.reset(token)
210
+
211
+
212
+ @_contextmanager
213
+ def running(context: Optional[QueryContext]):
214
+ """Statements started inside belong to `context` (None: to no query): its `cancel()` stops them."""
215
+ token = _CURRENT.set(context)
216
+ try:
217
+ yield
218
+ finally:
219
+ _CURRENT.reset(token)
220
+
221
+
222
+ # Whether the query running here is expected to run long (`expect_long`): a Databricks SQL statement is
223
+ # then submitted without waiting, so a cancel reaches it at once (`databricks_sql_graph.run_statement`);
224
+ # any other is run blocking, its result in the first response (an async statement costs every query a few
225
+ # round trips: +0.45 s each on a SQL warehouse, measured). A short statement's cancel lands at that first
226
+ # response.
227
+ _LONG: "_contextvars.ContextVar[bool]" = _contextvars.ContextVar("prograph_long_statement", default=False)
228
+
229
+
230
+ @_contextmanager
231
+ def statement_expectation():
232
+ """Around one query: statements inside are expected short until `expect_long` says otherwise."""
233
+ token = _LONG.set(False)
234
+ try:
235
+ yield
236
+ finally:
237
+ _LONG.reset(token)
238
+
239
+
240
+ def expect_long(flag: bool) -> None:
241
+ """The query's plan expects a long run (inside `statement_expectation`)."""
242
+ _LONG.set(bool(flag))
243
+
244
+
245
+ def long_expected() -> bool:
246
+ return _LONG.get()
247
+
248
+
249
+ def checkpoint() -> None:
250
+ """Before a step of the query runs (a statement, a rung of a closure's ladder, a retry): raise
251
+ QueryCancelledException where the query running here was cancelled, so that step never starts."""
252
+ context = _CURRENT.get()
253
+ if context is not None:
254
+ context.check_cancelled()
255
+
256
+
257
+ def committing() -> None:
258
+ """Right before the query's write commits (`Store.write_select`): raise QueryCancelledException
259
+ where the query was cancelled, so the write rolls back; else the query can no longer be cancelled,
260
+ and answers as written."""
261
+ context = _CURRENT.get()
262
+ if context is not None:
263
+ context._commit()
264
+
265
+
266
+ # A cancel that lands before the database has the statement (between the guard and the driver's
267
+ # execute; on Spark, before the statement's jobs are submitted, which cancelJobGroup does not reach)
268
+ # would be lost: the stop is sent again, every _RESEND_EVERY seconds, for as long as the statement is
269
+ # registered (it is until it ends).
270
+ _RESEND_EVERY = 0.25
271
+
272
+
273
+ @home("statement-deadline", "A server's timeout cancels the statement it started",
274
+ terms=("timeout", "cancel", "cursor.cancel", "deadline", "queued", "STATEMENT_TIMEOUT"))
275
+ class StatementGuard:
276
+ """One database statement's cancel handle. `stop` stops the statement from another thread, the
277
+ engine's own way (Databricks `cursor.cancel`, DuckDB `connection.interrupt`, ADBC
278
+ `cursor.adbc_cancel`, Spark `cancelJobGroup`, pyodbc `cursor.cancel`, oracledb
279
+ `connection.cancel`); None where the driver has none (the query then stops before its next
280
+ statement only). Made as the statement starts: refused with QueryCancelledException once the
281
+ query (`running`) is cancelled; registered with the query, whose `cancel()` calls `stop`; and
282
+ armed with the statement deadline, whose timer calls `stop` too, queued or running. `check()`
283
+ raises what stopped it: QueryCancelledException for a cancel, TimeoutError for the deadline,
284
+ not the database's error. As a context manager it is stopped at the end and checks then;
285
+ a streamed result keeps it until the reader ends (`reader`). Best effort: a stop that fails is
286
+ logged, and the warehouse's STATEMENT_TIMEOUT stays behind the deadline."""
287
+
288
+ def __init__(self, cursor: Any = None, *, stop: Optional[Callable[[], Any]] = None):
289
+ self.halt = stop if stop is not None else getattr(cursor, "cancel", None)
290
+ self.fired, self.cancelled, self._timer = False, False, None
291
+ self.context = _CURRENT.get()
292
+ if self.context is not None:
293
+ self.context._attach(self)
294
+ deadline = _DEADLINE.get()
295
+ if deadline is not None and self.halt is not None:
296
+ self.seconds = max(0.0, deadline - time.monotonic())
297
+ self._timer = _threading.Timer(self.seconds, self._cancel)
298
+ self._timer.daemon = True
299
+ self._timer.start()
300
+
301
+ def _stop_statement(self) -> None:
302
+ if self.halt is None:
303
+ return
304
+ try:
305
+ self.halt()
306
+ except Exception as error: # noqa: BLE001 - best effort; the warehouse's timeout remains
307
+ logger.warning("statement cancel failed: %s", type(error).__name__)
308
+
309
+ def _cancel(self) -> None:
310
+ """The deadline passed."""
311
+ self.fired = True
312
+ self._stop_statement()
313
+
314
+ def interrupt(self) -> None:
315
+ """The query was cancelled (`QueryContext.cancel`): stop the statement, and again while it
316
+ is still registered (`_RESEND_EVERY`)."""
317
+ self.cancelled = True
318
+ self._stop_statement()
319
+ if self.halt is not None and self.context is not None:
320
+ self._resend()
321
+
322
+ def _resend(self) -> None:
323
+ def again() -> None:
324
+ if self.context._running(self):
325
+ self._stop_statement()
326
+ self._resend()
327
+ timer = _threading.Timer(_RESEND_EVERY, again)
328
+ timer.daemon = True
329
+ timer.start()
330
+
331
+ def check(self) -> None:
332
+ if self.cancelled or (self.context is not None and self.context.is_cancelled):
333
+ raise QueryCancelledException(CANCELLED)
334
+ if self.fired:
335
+ raise TimeoutError("the query passed the server's timeout; ProGraph cancelled its statement")
336
+
337
+ def stop(self) -> None:
338
+ """The statement ended: no deadline, no longer the query's."""
339
+ if self._timer is not None:
340
+ self._timer.cancel()
341
+ if self.context is not None:
342
+ self.context._detach(self)
343
+
344
+ def __enter__(self) -> "StatementGuard":
345
+ return self
346
+
347
+ def __exit__(self, kind: Any, error: Any, trace: Any) -> bool:
348
+ self.stop()
349
+ if kind is None or issubclass(kind, Exception):
350
+ # What stopped the statement, not the database's error for it (chained to it).
351
+ self.check()
352
+ return False
353
+
354
+ @_contextmanager
355
+ def opening(self, close: Optional[Callable[[], Any]] = None):
356
+ """Around opening a streamed result (`reader` keeps the guard after): where opening fails,
357
+ the guard is stopped, `close` runs, and the failure is what stopped the statement where
358
+ something did (`check`)."""
359
+ try:
360
+ yield self
361
+ except BaseException as error:
362
+ self.stop()
363
+ if close is not None:
364
+ close()
365
+ if isinstance(error, Exception):
366
+ self.check()
367
+ raise
368
+
369
+ def reader(self, reader: Any, close: Optional[Callable[[], Any]] = None) -> Any:
370
+ """`reader` (a RecordBatchReader whose statement this guard stops) as a reader that keeps
371
+ the guard until it ends, read through, failed or closed; a failure while reading is what
372
+ stopped the statement where something did (`check`). `close` runs at the end too."""
373
+ import pyarrow as pa
374
+ guard = self
375
+
376
+ def batches() -> Iterator[Any]:
377
+ try:
378
+ try:
379
+ yield from reader
380
+ except Exception:
381
+ guard.check()
382
+ raise
383
+ finally:
384
+ guard.stop()
385
+ try:
386
+ reader.close()
387
+ finally:
388
+ if close is not None:
389
+ close()
390
+ return pa.RecordBatchReader.from_batches(reader.schema, batches())
391
+
392
+
393
+ def until_read(reader: Any, context: QueryContext) -> Any:
394
+ """A streamed answer (`return_type="batches"`) whose query ends when its reader does: read
395
+ through it completes, a failure (a cancel among them) ends it so."""
396
+ import pyarrow as pa
397
+
398
+ def batches() -> Iterator[Any]:
399
+ try:
400
+ yield from reader
401
+ except Exception as error:
402
+ context.mark_failed(str(error))
403
+ raise
404
+ finally:
405
+ reader.close()
406
+ if context.status not in _ENDED:
407
+ context.mark_completed()
408
+ return pa.RecordBatchReader.from_batches(reader.schema, batches())
409
+
410
+
411
+ class RunningQueries:
412
+ """A server's running queries by id (`prograph serve`: /sparql and the MCP tools), so that
413
+ `POST /queries/{id}/cancel` and the MCP tool `cancel_query` can cancel one. A query is here
414
+ from its start until its answer ends; its id is its context's random uuid4, the capability to
415
+ cancel it, which no log holds."""
416
+
417
+ def __init__(self) -> None:
418
+ self._lock = Lock()
419
+ self._running: Dict[str, QueryContext] = {}
420
+
421
+ def open(self, proposed: Optional[str] = None) -> QueryContext:
422
+ """A new query's context, registered. `proposed`: an id the caller chose, so it can cancel
423
+ the query before the answer (and its id) arrives: a random uuid4 in its canonical text,
424
+ not one running now; anything else raises ValueError."""
425
+ context = QueryContext()
426
+ if proposed is not None:
427
+ try:
428
+ parsed = uuid.UUID(proposed)
429
+ except (ValueError, AttributeError, TypeError):
430
+ raise ValueError("a query id is a random UUID (version 4)") from None
431
+ if parsed.version != 4 or str(parsed) != proposed.lower():
432
+ raise ValueError("a query id is a random UUID (version 4)")
433
+ context.query_id = str(parsed)
434
+ with self._lock:
435
+ if context.query_id in self._running:
436
+ raise ValueError("that query id is running already")
437
+ self._running[context.query_id] = context
438
+ return context
439
+
440
+ def close(self, context: QueryContext) -> None:
441
+ """The query's answer ended: its id cancels nothing from now."""
442
+ with self._lock:
443
+ if self._running.get(context.query_id) is context:
444
+ del self._running[context.query_id]
445
+
446
+ def cancel(self, query_id: str) -> bool:
447
+ """Cancel the running query `query_id`: True if one was running (and is cancelled now),
448
+ False otherwise; a query that has ended is unchanged."""
449
+ with self._lock:
450
+ context = self._running.get(query_id)
451
+ return context is not None and context.cancel()
452
+
453
+ def __len__(self) -> int:
454
+ with self._lock:
455
+ return len(self._running)
@@ -0,0 +1,6 @@
1
+ """The backends' executors: each holds the graph object that runs SQL on
2
+ its database (DuckDB over frames, Spark, a SQL connection)."""
3
+
4
+ from prograph.executors.base import BaseExecutor
5
+
6
+ __all__ = ["BaseExecutor"]
@@ -0,0 +1,11 @@
1
+ """Base executor interface for the backends.
2
+
3
+ An executor holds the graph object that runs SQL on its database;
4
+ queries themselves run through the one plan (prograph.plan.ir).
5
+ """
6
+
7
+ from abc import ABC
8
+
9
+
10
+ class BaseExecutor(ABC):
11
+ """Base class of the backends' executors."""
@@ -0,0 +1,51 @@
1
+ """Databricks SQL executor for graph queries.
2
+
3
+ Executes graph queries by generating SQL and running it against a
4
+ Databricks SQL Warehouse via the ``databricks-sql-connector`` (PEP 249).
5
+ No DataFrames, no SparkSession, pure SQL end to end.
6
+ """
7
+
8
+ from typing import Any, Dict, Optional
9
+
10
+ from prograph.executors.base import BaseExecutor
11
+ from prograph.graph.databricks_sql_graph import DatabricksSQLGraph
12
+ from prograph.read_only import ExecutorRefusesWrites
13
+
14
+
15
+ class DatabricksSQLExecutor(ExecutorRefusesWrites, BaseExecutor):
16
+ """Execute graph queries against a Databricks SQL Warehouse.
17
+
18
+ Generates SQL from graph queries and executes them via Photon.
19
+ All execution is SQL-only; there is no DataFrame fallback.
20
+ """
21
+
22
+ def __init__(
23
+ self,
24
+ schema: Any,
25
+ connection: Any,
26
+ catalog: Optional[str] = None,
27
+ schema_name: Optional[str] = None,
28
+ table_stats: Optional[Dict[str, int]] = None,
29
+ ansi_session: bool = False,
30
+ ):
31
+ """Initialize the Databricks SQL executor.
32
+
33
+ Args:
34
+ schema: GraphSchema with node/relationship mappings.
35
+ connection: A ``databricks.sql`` connection (PEP 249).
36
+ catalog: Unity Catalog name for table resolution.
37
+ schema_name: Unity Catalog schema for table resolution.
38
+ table_stats: Optional table row counts for optimization.
39
+ ansi_session: Turn ANSI mode on for the connection, and put it
40
+ back when the graph is closed.
41
+ """
42
+ self.schema = schema
43
+ self.graph = DatabricksSQLGraph(
44
+ schema, connection,
45
+ catalog=catalog,
46
+ schema_name=schema_name,
47
+ table_stats=table_stats,
48
+ ansi_session=ansi_session,
49
+ )
50
+ # Set catalog/schema context on the connection
51
+ self.graph.set_catalog_context()
@@ -0,0 +1,24 @@
1
+ """DuckDB executor for graph queries.
2
+
3
+ Embedded SQL execution, no server, no credentials, no infrastructure.
4
+ ``pip install duckdb`` and go.
5
+ """
6
+
7
+ from typing import Any, Dict, Optional
8
+
9
+ from prograph.executors.base import BaseExecutor
10
+ from prograph.graph.duckdb_graph import DuckDBGraph
11
+ from prograph.read_only import ExecutorRefusesWrites
12
+
13
+
14
+ class DuckDBExecutor(ExecutorRefusesWrites, BaseExecutor):
15
+ """Execute graph queries against an embedded DuckDB database."""
16
+
17
+ def __init__(
18
+ self,
19
+ schema: Any,
20
+ connection: Any,
21
+ table_stats: Optional[Dict[str, int]] = None,
22
+ ):
23
+ self.schema = schema
24
+ self.graph = DuckDBGraph(schema, connection, table_stats=table_stats)
@@ -0,0 +1,20 @@
1
+ """MySQL executor for graph queries."""
2
+
3
+ from typing import Any, Dict, Optional
4
+
5
+ from prograph.executors.base import BaseExecutor
6
+ from prograph.graph.mysql_graph import MySQLGraph
7
+ from prograph.read_only import ExecutorRefusesWrites
8
+
9
+
10
+ class MySQLExecutor(ExecutorRefusesWrites, BaseExecutor):
11
+ """Execute graph queries against a MySQL database."""
12
+
13
+ def __init__(
14
+ self,
15
+ schema: Any,
16
+ connection: Any,
17
+ table_stats: Optional[Dict[str, int]] = None,
18
+ ):
19
+ self.schema = schema
20
+ self.graph = MySQLGraph(schema, connection, table_stats=table_stats)
@@ -0,0 +1,24 @@
1
+ """Oracle executor for graph queries.
2
+
3
+ Executes graph queries by generating Oracle SQL and running it
4
+ against an Oracle database via the ``oracledb`` driver.
5
+ """
6
+
7
+ from typing import Any, Dict, Optional
8
+
9
+ from prograph.executors.base import BaseExecutor
10
+ from prograph.graph.oracle_graph import OracleGraph
11
+ from prograph.read_only import ExecutorRefusesWrites
12
+
13
+
14
+ class OracleExecutor(ExecutorRefusesWrites, BaseExecutor):
15
+ """Execute graph queries against an Oracle database."""
16
+
17
+ def __init__(
18
+ self,
19
+ schema: Any,
20
+ connection: Any,
21
+ table_stats: Optional[Dict[str, int]] = None,
22
+ ):
23
+ self.schema = schema
24
+ self.graph = OracleGraph(schema, connection, table_stats=table_stats)
@@ -0,0 +1,72 @@
1
+ """Pandas executor for graph queries over DataFrames.
2
+
3
+ This executor enables graph queries against Pandas DataFrames
4
+ using a schema mapping to define the virtual graph structure. Read-only:
5
+ its mutators refuse.
6
+ """
7
+
8
+ from typing import Dict
9
+
10
+ try:
11
+ import pandas as pd
12
+ PANDAS_AVAILABLE = True
13
+ except ImportError:
14
+ PANDAS_AVAILABLE = False
15
+ pd = None
16
+
17
+ from prograph.executors.base import BaseExecutor
18
+ from prograph.graph.pandas_graph import PandasGraph
19
+ from prograph.schema.mapping import GraphSchema
20
+ from prograph.read_only import ExecutorRefusesWrites
21
+
22
+
23
+ class PandasExecutor(ExecutorRefusesWrites, BaseExecutor):
24
+ """Execute graph queries against Pandas DataFrames.
25
+
26
+ This executor provides a virtual graph over DataFrames, read-only.
27
+
28
+ Example:
29
+ >>> schema = GraphSchema()
30
+ >>> schema.add_node_mapping(NodeMapping(
31
+ ... source_table='movies',
32
+ ... label='Movie',
33
+ ... id_column='movie_id',
34
+ ... property_columns={'title': 'title'},
35
+ ... ))
36
+ >>> executor = PandasExecutor(schema, {'movies': movies_df})
37
+ >>> # Use with ProGraph
38
+ """
39
+
40
+ def __init__(
41
+ self,
42
+ schema: GraphSchema,
43
+ dataframes: Dict[str, 'pd.DataFrame']
44
+ ):
45
+ """Initialize the Pandas executor.
46
+
47
+ Args:
48
+ schema: GraphSchema defining node and relationship mappings
49
+ dataframes: Dictionary mapping table names to DataFrames
50
+
51
+ Raises:
52
+ ImportError: If pandas is not installed
53
+ ValueError: If schema or dataframes is invalid
54
+ """
55
+ if not PANDAS_AVAILABLE:
56
+ raise ImportError(
57
+ "pandas is required for the Pandas backend. "
58
+ "Install it with: pip install pandas"
59
+ )
60
+
61
+ if schema is None:
62
+ raise ValueError("schema is required for Pandas backend")
63
+ if dataframes is None:
64
+ raise ValueError("dataframes dict is required for Pandas backend")
65
+
66
+ self.schema = schema
67
+ self.dataframes = dataframes
68
+ self.graph = PandasGraph(schema, dataframes)
69
+
70
+
71
+ def __repr__(self) -> str:
72
+ return f"PandasExecutor({self.graph})"