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
@@ -0,0 +1,619 @@
1
+ """Operators of the one plan.
2
+
3
+ Each operator is closed: its output is its stated columns (`columns`), each
4
+ with its slot (`slots`, a `TermSlot`), a bag of rows unless its facts say it
5
+ is a set (`prograph.plan.ir.facts`), in an order only where `Order` gives
6
+ one and the reader consumes it. Operators are frozen; a rewrite builds new
7
+ ones. A missing cell is an unbound term or a null value, as its slot says
8
+ (`TermSlot.bound`, `TermSlot.null`).
9
+
10
+ The leaves read source maps (`prograph.schema.source_map`): `MapScan` reads
11
+ one map's logical table as raw columns, and `MakeTerm` expressions above it
12
+ build the terms. `Values` holds constant rows and `Unit` is the one empty
13
+ row.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ from dataclasses import dataclass
19
+ from typing import Any, Dict, Optional, Tuple, Union as TUnion
20
+
21
+ from prograph.plan.ir.expr import Agg, Expr, SEMANTICS, SPARQL, CYPHER
22
+ from prograph.schema.source_map import EdgeMap, NodeMap, TermMap
23
+
24
+
25
+ class PlanError(ValueError):
26
+ """An operator built against its own definition."""
27
+
28
+
29
+ class Op:
30
+ """An operator of the plan."""
31
+
32
+ def children(self) -> Tuple["Op", ...]:
33
+ return ()
34
+
35
+ @property
36
+ def columns(self) -> Tuple[str, ...]:
37
+ return self.__dict__["_columns"]
38
+
39
+ def _set_columns(self, columns: Tuple[str, ...]) -> None:
40
+ if len(set(columns)) != len(columns):
41
+ raise PlanError(f"{type(self).__name__} outputs a column twice: {columns}")
42
+ object.__setattr__(self, "_columns", tuple(columns))
43
+
44
+ @property
45
+ def facts(self) -> Any:
46
+ """The operator's inferred facts (`prograph.plan.ir.facts.facts`)."""
47
+ from prograph.plan.ir.facts import facts
48
+ return facts(self)
49
+
50
+ @property
51
+ def slots(self) -> Dict[str, Any]:
52
+ """Each output column's `TermSlot`."""
53
+ return dict(self.facts.slots)
54
+
55
+
56
+ def _shared(left: Op, right: Op) -> Tuple[str, ...]:
57
+ return tuple(c for c in left.columns if c in right.columns)
58
+
59
+
60
+ def _merged(left: Op, right: Op) -> Tuple[str, ...]:
61
+ return left.columns + tuple(c for c in right.columns if c not in left.columns)
62
+
63
+
64
+ # -- leaves -------------------------------------------------------------------------
65
+
66
+
67
+ @dataclass(frozen=True)
68
+ class ScanColumn:
69
+ """One column a `MapScan` reads, output as `name`.
70
+
71
+ Attributes:
72
+ name: The output column.
73
+ column: The source column.
74
+ parent: Read from the parent row of the map's joint query
75
+ (`EdgeMap.join`, R2RML 8), not the map's own row.
76
+ held: The datatype the column's type gives (`prograph.schema.xsd.
77
+ column_datatype`), None where unknown.
78
+ zone: For a date-time column, `slot.ZONED` or `LOCAL`.
79
+ """
80
+ name: str
81
+ column: str
82
+ parent: bool = False
83
+ held: Optional[str] = None
84
+ zone: Optional[str] = None
85
+ digits: Optional[Tuple[int, int]] = None # a DECIMAL column's precision and scale
86
+ # The dialect function a column is read through (`entry.held`): CHAR_TEXT for a CHAR(n) column
87
+ # (its padding), FLOAT32_VALUE for a 32-bit float (the double its shortest text names).
88
+ reader: Optional[str] = None
89
+ # A string column whose SQL equality is byte equality (`collations.compares_bytes`): an IRI over it
90
+ # may be held as its value (`slot.held_as_values`).
91
+ bytewise: bool = False
92
+ # A uuid column (`reader` UUID_TEXT or UUID_TEXT_UPPER) a SPARQL plan carries as the native column through
93
+ # its steps: its text is read where it is written (`lower.make_term`), so a join with another uuid key
94
+ # compares columns (rule `uuid-text`).
95
+ uuid: bool = False
96
+ # A date-time column's fractional-second digits where its type states them (`CypherType.precision`),
97
+ # read by R13 (`rewrite._one_text`); set on a joint query's join columns only.
98
+ precision: Optional[int] = None
99
+
100
+
101
+ @dataclass(frozen=True)
102
+ class GraphColumn:
103
+ """A quad scan's graph: `name` holds, for each row, each distinct term
104
+ the graph maps give it (R2RML 11.1), so a row is read once per graph its
105
+ triple is in. A constant map of `RR_DEFAULT_GRAPH` is the default graph
106
+ (`terms.DEFAULT_GRAPH`). A graph map with no value in a row puts the
107
+ row's triple in no graph by that map."""
108
+ name: str
109
+ maps: Tuple[TermMap, ...]
110
+
111
+ def __post_init__(self) -> None:
112
+ if not self.maps:
113
+ raise PlanError("a graph column has at least one graph map")
114
+
115
+
116
+ @dataclass(frozen=True)
117
+ class MapScan(Op):
118
+ """One source map's logical table (a table or an rr:sqlQuery, with the
119
+ map's row filter), read as raw columns: a bag of the source's rows, or
120
+ for an edge map with a joint query (`EdgeMap.join`, R2RML 8), of each
121
+ child row with each parent row the join conditions match (SQL equality,
122
+ NULL matching nothing).
123
+
124
+ Attributes:
125
+ map: The node or edge map.
126
+ reads: The columns read.
127
+ graph: The graph column, for a quad scan.
128
+ required: Output columns a row must have a value in: a row with
129
+ none there gives no triple (R2RML 11.2), filtered here, once.
130
+ unique_keys: Column sets of the map's own source the planner may
131
+ rely on as unique (a key declared RELY, `on_duplicate: trust`,
132
+ `trust_keys`, a checked key): the planner's input, decided
133
+ before planning. A stated key is identity, not uniqueness, and
134
+ is not one unless the caller says so. An rr:sqlQuery source has
135
+ no known key, whatever is given.
136
+ not_null: Columns of the map's own source that hold no NULL.
137
+ parent_unique_keys: As `unique_keys`, for the joint query's parent.
138
+ parent_not_null: As `not_null`, for the parent.
139
+ child_set: Of a joint query: the child's rows are read as a set of the
140
+ child columns read and joined on (R12), so each parent row is
141
+ matched once per distinct child value, not per child row. Set only
142
+ where a Distinct above counts no row twice.
143
+ parent_map: Of a joint query: the parent's node map (the referencing
144
+ object map's parent triples map), for R13, which reads the parent
145
+ as an existence check.
146
+ join_reads: Of a joint query: each join condition's child column as
147
+ the scan would read it (its datatype, zone, digits, reader), named
148
+ by the column, in the conditions' order; R13 reads it in the place
149
+ of the parent column it is joined to.
150
+ """
151
+ map: TUnion[NodeMap, EdgeMap]
152
+ reads: Tuple[ScanColumn, ...]
153
+ graph: Optional[GraphColumn] = None
154
+ required: Tuple[str, ...] = ()
155
+ unique_keys: Tuple[Tuple[str, ...], ...] = ()
156
+ not_null: Tuple[str, ...] = ()
157
+ parent_unique_keys: Tuple[Tuple[str, ...], ...] = ()
158
+ parent_not_null: Tuple[str, ...] = ()
159
+ child_set: bool = False
160
+ parent_map: Optional[NodeMap] = None
161
+ join_reads: Tuple[ScanColumn, ...] = ()
162
+
163
+ def __post_init__(self) -> None:
164
+ names = tuple(r.name for r in self.reads)
165
+ if self.graph is not None:
166
+ names = names + (self.graph.name,)
167
+ self._set_columns(names)
168
+ if not set(self.required) <= set(names):
169
+ raise PlanError(f"required columns {self.required} are not all read")
170
+ if any(r.parent for r in self.reads) and self.joint is None:
171
+ raise PlanError("a parent column is read only through a joint query")
172
+ if self.child_set and self.joint is None:
173
+ raise PlanError("the child is a set only in a joint query")
174
+ if (self.parent_map is not None or self.join_reads) and self.joint is None:
175
+ raise PlanError("a parent map and join reads are a joint query's")
176
+
177
+ @property
178
+ def joint(self) -> Any:
179
+ return self.map.join if isinstance(self.map, EdgeMap) else None
180
+
181
+ @property
182
+ def query_source(self) -> bool:
183
+ """The map's own rows come from an rr:sqlQuery."""
184
+ return self.map.source.query is not None
185
+
186
+
187
+ @dataclass(frozen=True)
188
+ class Values(Op):
189
+ """Constant rows (VALUES, a constant term), None for UNDEF or null."""
190
+ names: Tuple[str, ...]
191
+ rows: Tuple[Tuple[Any, ...], ...]
192
+
193
+ def __post_init__(self) -> None:
194
+ self._set_columns(self.names)
195
+ if any(len(r) != len(self.names) for r in self.rows):
196
+ raise PlanError("a Values row has one cell per column")
197
+
198
+
199
+ @dataclass(frozen=True)
200
+ class Unit(Op):
201
+ """One row of no columns: the join's identity, a BGP of no triple."""
202
+
203
+ def __post_init__(self) -> None:
204
+ self._set_columns(())
205
+
206
+
207
+ # -- joins --------------------------------------------------------------------------
208
+
209
+
210
+ @dataclass(frozen=True)
211
+ class Join(Op):
212
+ """SPARQL's compatible join (18.3): each pair of a left and a right row
213
+ that agree on every shared column where both have a value, merged (a
214
+ shared column takes the value of the side that has one), and for which
215
+ `condition`, over the merged row, is true. With no shared column whose
216
+ cells may be missing it is the inner join on equality; a Cypher plan
217
+ states its joins as `condition`s over columns it does not share."""
218
+ left: Op
219
+ right: Op
220
+ condition: Optional[Expr] = None
221
+
222
+ def __post_init__(self) -> None:
223
+ self._set_columns(_merged(self.left, self.right))
224
+
225
+ def children(self) -> Tuple[Op, ...]:
226
+ return (self.left, self.right)
227
+
228
+ @property
229
+ def shared(self) -> Tuple[str, ...]:
230
+ return _shared(self.left, self.right)
231
+
232
+
233
+ @dataclass(frozen=True)
234
+ class LeftJoin(Op):
235
+ """SPARQL's LeftJoin(P1, P2, F) (18.5): the compatible pairs for which
236
+ F over the merged row is true, and each left row with no such pair,
237
+ alone. Cypher's OPTIONAL MATCH is one, its WHERE as F: all or nothing."""
238
+ left: Op
239
+ right: Op
240
+ condition: Optional[Expr] = None
241
+
242
+ def __post_init__(self) -> None:
243
+ self._set_columns(_merged(self.left, self.right))
244
+
245
+ def children(self) -> Tuple[Op, ...]:
246
+ return (self.left, self.right)
247
+
248
+
249
+ @dataclass(frozen=True)
250
+ class Unwind(Op):
251
+ """Cypher's UNWIND of a list expression: each input row once per element of `list` (read in that
252
+ row), the element under `name`, a null element kept; a null or empty list gives no row."""
253
+ input: Op
254
+ name: str
255
+ list: Expr
256
+
257
+ def __post_init__(self) -> None:
258
+ if self.name in self.input.columns:
259
+ raise PlanError(f"Unwind binds {self.name!r}, already in scope")
260
+ self._set_columns(self.input.columns + (self.name,))
261
+
262
+ def children(self) -> Tuple[Op, ...]:
263
+ return (self.input,)
264
+
265
+
266
+ @dataclass(frozen=True)
267
+ class LateralJoin(Op):
268
+ """For each left row, the right plan evaluated with the left row's
269
+ columns in scope (a `Col` the right side does not output is the left
270
+ row's), and the left row joined with each of its rows; with `optional`,
271
+ a left row whose right plan gives none is kept alone. For EXISTS that
272
+ does not decorrelate, Cypher's CALL, comprehensions and a per-row
273
+ UNWIND. The right side outputs no column of the left's."""
274
+ left: Op
275
+ right: Op
276
+ optional: bool = False
277
+
278
+ def __post_init__(self) -> None:
279
+ if _shared(self.left, self.right):
280
+ raise PlanError(f"a lateral join's sides share {_shared(self.left, self.right)}")
281
+ self._set_columns(self.left.columns + self.right.columns)
282
+
283
+ def children(self) -> Tuple[Op, ...]:
284
+ return (self.left, self.right)
285
+
286
+
287
+ # -- set operators ------------------------------------------------------------------
288
+
289
+
290
+ @dataclass(frozen=True)
291
+ class Union(Op):
292
+ """The bag union of its inputs; a column an input does not output is
293
+ missing in that input's rows. Columns in order of first appearance."""
294
+ inputs: Tuple[Op, ...]
295
+
296
+ def __post_init__(self) -> None:
297
+ if not self.inputs:
298
+ raise PlanError("a union has an input")
299
+ out: Tuple[str, ...] = ()
300
+ for i in self.inputs:
301
+ out = out + tuple(c for c in i.columns if c not in out)
302
+ self._set_columns(out)
303
+
304
+ def children(self) -> Tuple[Op, ...]:
305
+ return self.inputs
306
+
307
+
308
+ @dataclass(frozen=True)
309
+ class Minus(Op):
310
+ """SPARQL's MINUS (18.5): each left row, unless some right row is
311
+ compatible with it and shares a column with a value on both sides. A
312
+ right side that shares no variable removes nothing. `within` columns
313
+ (inside GRAPH ?g, the active graph's hidden column) must match but are
314
+ no shared variable: MINUS is evaluated within each graph."""
315
+ left: Op
316
+ right: Op
317
+ within: Tuple[str, ...] = ()
318
+
319
+ def __post_init__(self) -> None:
320
+ self._set_columns(self.left.columns)
321
+
322
+ def children(self) -> Tuple[Op, ...]:
323
+ return (self.left, self.right)
324
+
325
+
326
+ @dataclass(frozen=True)
327
+ class SemiJoin(Op):
328
+ """Each left row for which some right row is compatible with it and
329
+ `condition` over the merged row is true: EXISTS, where it
330
+ decorrelates. A left row is kept once, however many match."""
331
+ left: Op
332
+ right: Op
333
+ condition: Optional[Expr] = None
334
+
335
+ def __post_init__(self) -> None:
336
+ self._set_columns(self.left.columns)
337
+
338
+ def children(self) -> Tuple[Op, ...]:
339
+ return (self.left, self.right)
340
+
341
+ @property
342
+ def shared(self) -> Tuple[str, ...]:
343
+ return _shared(self.left, self.right)
344
+
345
+
346
+ @dataclass(frozen=True)
347
+ class AntiJoin(Op):
348
+ """Each left row for which no right row is compatible with it with
349
+ `condition` true: NOT EXISTS, where it decorrelates. Unlike `Minus`, a
350
+ right side that shares no column removes every left row when it has a
351
+ row."""
352
+ left: Op
353
+ right: Op
354
+ condition: Optional[Expr] = None
355
+
356
+ def __post_init__(self) -> None:
357
+ self._set_columns(self.left.columns)
358
+
359
+ def children(self) -> Tuple[Op, ...]:
360
+ return (self.left, self.right)
361
+
362
+ # -- row operators ------------------------------------------------------------------
363
+
364
+
365
+ @dataclass(frozen=True)
366
+ class Filter(Op):
367
+ """The rows for which `condition` is true (an error or unknown is
368
+ false)."""
369
+ input: Op
370
+ condition: Expr
371
+
372
+ def __post_init__(self) -> None:
373
+ self._set_columns(self.input.columns)
374
+
375
+ def children(self) -> Tuple[Op, ...]:
376
+ return (self.input,)
377
+
378
+
379
+ @dataclass(frozen=True)
380
+ class Extend(Op):
381
+ """Each row with a new column `name` holding `expr`'s value (SPARQL's
382
+ BIND, a computed column): missing where `expr` has no value or is an
383
+ error. `name` is not a column of the input (SPARQL 18.2.1)."""
384
+ input: Op
385
+ name: str
386
+ expr: Expr
387
+
388
+ def __post_init__(self) -> None:
389
+ if self.name in self.input.columns:
390
+ raise PlanError(f"Extend binds {self.name!r}, already in scope")
391
+ self._set_columns(self.input.columns + (self.name,))
392
+
393
+ def children(self) -> Tuple[Op, ...]:
394
+ return (self.input,)
395
+
396
+
397
+ @dataclass(frozen=True)
398
+ class Ordinal(Op):
399
+ """Each row with a new column `name`: its number (1, 2, ...) among the input's rows equal on `by`, in
400
+ the order of the `order` columns' values. Rows equal on `by` and `order` are numbered in any order,
401
+ so a query that reads only those columns gets the same multiset of numbers however the engine numbers
402
+ them (a relationship's ordinal among the rows of one start and end, `lpg_view.relationship_identity`).
403
+ Numbered over its whole input: no rule moves a filter below it."""
404
+ input: Op
405
+ name: str
406
+ by: Tuple[str, ...]
407
+ order: Tuple[str, ...]
408
+ constant: bool = False # every row 1: rows a check compares with no equal row (no window computed)
409
+
410
+ def __post_init__(self) -> None:
411
+ if self.name in self.input.columns:
412
+ raise PlanError(f"Ordinal binds {self.name!r}, already in scope")
413
+ missing = [c for c in self.by + self.order if c not in self.input.columns]
414
+ if missing:
415
+ raise PlanError(f"Ordinal reads {missing}, not columns of its input")
416
+ self._set_columns(self.input.columns + (self.name,))
417
+
418
+ def children(self) -> Tuple[Op, ...]:
419
+ return (self.input,)
420
+
421
+
422
+ @dataclass(frozen=True)
423
+ class Project(Op):
424
+ """The columns `names`, in that order; a name the input lacks is a
425
+ column with no value in any row (SPARQL's projection of a variable not
426
+ in scope)."""
427
+ input: Op
428
+ names: Tuple[str, ...]
429
+
430
+ def __post_init__(self) -> None:
431
+ self._set_columns(self.names)
432
+
433
+ def children(self) -> Tuple[Op, ...]:
434
+ return (self.input,)
435
+
436
+
437
+ @dataclass(frozen=True)
438
+ class Distinct(Op):
439
+ """One row of each set of equal rows: cells compared as terms (sameTerm),
440
+ or values by equivalence (Cypher's DISTINCT), a missing cell equal to a
441
+ missing cell."""
442
+ input: Op
443
+
444
+ def __post_init__(self) -> None:
445
+ self._set_columns(self.input.columns)
446
+
447
+ def children(self) -> Tuple[Op, ...]:
448
+ return (self.input,)
449
+
450
+
451
+ @dataclass(frozen=True)
452
+ class Reduced(Op):
453
+ """SPARQL's REDUCED: some duplicate rows may go, never more than the
454
+ duplicates. Any multiplicity from one to the input's is an answer."""
455
+ input: Op
456
+
457
+ def __post_init__(self) -> None:
458
+ self._set_columns(self.input.columns)
459
+
460
+ def children(self) -> Tuple[Op, ...]:
461
+ return (self.input,)
462
+
463
+
464
+ @dataclass(frozen=True)
465
+ class Aggregate(Op):
466
+ """One row per group of the input's rows equal on `group` (keys
467
+ compared as terms: `1`, `1.0` and `01` are three groups; a missing key
468
+ its own group), holding the group's keys and each aggregate. With no
469
+ `group`, one row however many input rows (none included)."""
470
+ input: Op
471
+ group: Tuple[str, ...]
472
+ aggregates: Tuple[Tuple[str, Agg], ...]
473
+
474
+ def __post_init__(self) -> None:
475
+ missing = [g for g in self.group if g not in self.input.columns]
476
+ if missing:
477
+ raise PlanError(f"grouped by {missing}, not columns of the input")
478
+ self._set_columns(self.group + tuple(n for n, _ in self.aggregates))
479
+
480
+ def children(self) -> Tuple[Op, ...]:
481
+ return (self.input,)
482
+
483
+
484
+ @dataclass(frozen=True)
485
+ class SortKey:
486
+ """A sort key: a column, its direction, and its order: SPARQL's (15.1:
487
+ unbound, blank nodes, IRIs, literals, literals by `<` where comparable)
488
+ or Cypher's orderability (null last ascending)."""
489
+ column: str
490
+ descending: bool = False
491
+ semantics: str = SPARQL
492
+
493
+ def __post_init__(self) -> None:
494
+ if self.semantics not in SEMANTICS:
495
+ raise PlanError(f"no order semantics {self.semantics!r}")
496
+
497
+
498
+ @dataclass(frozen=True)
499
+ class Order(Op):
500
+ """The input's rows sorted by `keys`, ties in any order."""
501
+ input: Op
502
+ keys: Tuple[SortKey, ...]
503
+
504
+ def __post_init__(self) -> None:
505
+ missing = [k.column for k in self.keys if k.column not in self.input.columns]
506
+ if missing:
507
+ raise PlanError(f"sorted by {missing}, not columns of the input")
508
+ self._set_columns(self.input.columns)
509
+
510
+ def children(self) -> Tuple[Op, ...]:
511
+ return (self.input,)
512
+
513
+
514
+ @dataclass(frozen=True)
515
+ class Slice(Op):
516
+ """The rows from `offset`, at most `limit` of them (None: all)."""
517
+ input: Op
518
+ offset: int = 0
519
+ limit: Optional[int] = None
520
+
521
+ def __post_init__(self) -> None:
522
+ if self.offset < 0 or (self.limit is not None and self.limit < 0):
523
+ raise PlanError("a slice's offset and limit are not negative")
524
+ self._set_columns(self.input.columns)
525
+
526
+ def children(self) -> Tuple[Op, ...]:
527
+ return (self.input,)
528
+
529
+
530
+ # -- paths --------------------------------------------------------------------------
531
+
532
+
533
+ @dataclass(frozen=True)
534
+ class Closure(Op):
535
+ """Paths of `min` to `max` steps (None: no bound) over the step
536
+ relation, a plan whose rows are the steps from `start` to `end`.
537
+
538
+ `SPARQL` mode (18.4, ALP): the set of (start, end) pairs some walk of
539
+ an allowed length joins; a zero-length pair is (t, t) for each term `t`
540
+ of `terms` (every subject and object of the graph, or the bound
541
+ constant). Sequence, alternative and inverse are not closures: they
542
+ are joins, unions and a column swap.
543
+
544
+ `CYPHER` mode: one row per trail, a walk that repeats no step's
545
+ `edge` (the relationship's identity), with its relationships'
546
+ identities, as a list of their texts in walk order, in `path`; a
547
+ zero-length trail for each node of `terms`. Uniqueness against the
548
+ MATCH's other relationships is a condition on `path` above.
549
+
550
+ `partition` columns (a graph) are carried: the closure is taken within
551
+ each of their values, and `terms` gives them too.
552
+
553
+ Output columns: `partition`, `start`, `end`, then `path` if given, then the `carry` lists.
554
+ """
555
+ step: Op
556
+ start: str
557
+ end: str
558
+ mode: str = SPARQL
559
+ min: int = 1
560
+ max: Optional[int] = None
561
+ terms: Optional[Op] = None
562
+ terms_column: str = "term"
563
+ edge: Optional[str] = None
564
+ path: Optional[str] = None
565
+ # CYPHER mode: step columns carried as lists, each trail's in walk order (the first step's value
566
+ # first); the output has each under its own name, a list of the column's values (rule cypher-trails).
567
+ carry: Tuple[str, ...] = ()
568
+ partition: Tuple[str, ...] = ()
569
+ # A bound end the walk starts from: ("start", term) walks forward from that term,
570
+ # ("end", term) backward from it; None walks every pair. The answer is the same; the work is the
571
+ # seed's reach, not the whole graph's.
572
+ seed: Optional[Tuple[str, Any]] = None
573
+ # CYPHER mode only: "any" keeps, for each (start, end), one trail of the least length (GQL's ANY
574
+ # SHORTEST: the one whose relationship identities sort least); "all" every one of that length (ALL
575
+ # SHORTEST); None every trail.
576
+ shortest: Optional[str] = None
577
+ # A shortest closure's searches (CYPHER, `shortest`): `starts` the start nodes asked for (a relation of
578
+ # one column, `start`'s name), the search seeded with them; `ends` likewise where the ends are bound;
579
+ # `depth` an output column of each row's length.
580
+ starts: Optional["Op"] = None
581
+ ends: Optional["Op"] = None
582
+ pairs: Optional["Op"] = None # the (start, end) pairs asked, where both are bound (the guard's)
583
+ depth: Optional[str] = None
584
+ # Whether a shortest search may come back to its start (a directed pattern's shortest cycle); an
585
+ # undirected one may not (a closed walk there may repeat a relationship, which a trail does not).
586
+ closed: bool = True
587
+ # Where a search's depth guard names the way to bound it, as the call the closure came from knows it
588
+ # ("" : the Cypher pattern's `*1..n`; an APOC procedure's `maxLevel`).
589
+ bound_by: str = ""
590
+
591
+ def __post_init__(self) -> None:
592
+ if self.shortest is not None and (self.mode != CYPHER or self.shortest not in ("any", "all")):
593
+ raise PlanError("a shortest closure is a Cypher one, of any or all shortest trails")
594
+ if self.mode not in (SPARQL, CYPHER):
595
+ raise PlanError(f"no closure mode {self.mode!r}")
596
+ if self.min < 0 or (self.max is not None and self.max < self.min):
597
+ raise PlanError("a closure's bounds are 0 <= min <= max")
598
+ wanted = (self.start, self.end) + self.partition + ((self.edge,) if self.edge else ()) + self.carry
599
+ missing = [c for c in wanted if c not in self.step.columns]
600
+ if missing:
601
+ raise PlanError(f"the step relation lacks {missing}")
602
+ if self.min == 0:
603
+ if self.terms is None:
604
+ raise PlanError("a zero-length path needs the graph's terms")
605
+ missing = [c for c in (self.terms_column,) + self.partition
606
+ if c not in self.terms.columns]
607
+ if missing:
608
+ raise PlanError(f"the terms relation lacks {missing}")
609
+ if self.mode == CYPHER and self.edge is None:
610
+ raise PlanError("a trail needs each step's relationship")
611
+ if self.carry and (self.mode != CYPHER or self.shortest is not None):
612
+ raise PlanError("only a Cypher closure of trails carries step columns")
613
+ if self.mode == SPARQL and self.path is not None:
614
+ raise PlanError("a SPARQL path has no path value")
615
+ self._set_columns(self.partition + (self.start, self.end)
616
+ + ((self.path,) if self.path else ()) + self.carry + ((self.depth,) if self.depth else ()))
617
+
618
+ def children(self) -> Tuple[Op, ...]:
619
+ return (self.step,) + tuple(x for x in (self.terms, self.starts, self.ends, self.pairs) if x is not None)