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,459 @@
1
+ """The owned store's property-graph view (one-plan 2.10; design 66): one generic node map
2
+ and one generic relationship map over the store's effective statements, read beside the user's maps.
3
+
4
+ - **A label** is an `rdf:type` statement whose object is the label's class IRI, read as a column: a node
5
+ pattern of label L reads the generic map filtered on L's class, so `MATCH (n:AnyLabel)` finds created
6
+ nodes of a label no mapping declares, and nothing needs refreshing when a writer adds a label.
7
+ - **A node** is a subject in the store's minted namespace with the `ELEMENT` statement (a node of no label
8
+ and no property exists too). Its identity is its minted IRI, a template over the digest, so it meets no
9
+ user map's subject (`TermMap.may_equal`).
10
+ - **A property** is a literal statement whose predicate is the key's: the predicate a user's map gives the
11
+ key (under one of the node's labels where it is written), else the YAML default (`iri.default_property_iri`),
12
+ so a YAML mapping of the label and the store give one predicate and SPARQL and Cypher agree.
13
+ - **A relationship** is a statement with an IRI object and an `edge_id` (its minted IRI); its type is the
14
+ `REL_TYPE` statement on the edge id (the predicate is the RDF one, `iri.relationship_iri`'s, which does not
15
+ keep the type's spelling), its properties statements whose subject is the edge id.
16
+
17
+ Each pattern gets an instance of the generic map for what it reads: its label or type as a filter, the
18
+ keys and label flags the query reads as columns. A key's values are of one type in the store (its
19
+ statements' datatype); a key the store holds in several types is not built.
20
+ """
21
+
22
+ from __future__ import annotations
23
+
24
+ from dataclasses import dataclass, field
25
+ from typing import Any, Dict, List, Optional, Sequence, Tuple
26
+
27
+ from prograph.rules import module_home
28
+ from prograph.schema import xsd
29
+ from prograph.schema.iri import (DEFAULT_VOCAB_IRI, default_class_iri, default_property_iri,
30
+ default_relationship_iri)
31
+ from prograph.schema.source_map import (IRI, LITERAL, EdgeMap, EndRef, Key, NodeMap, PredicateObject, Source,
32
+ TermMap)
33
+
34
+ module_home("store-lpg-view", "The owned store's property-graph view: one generic node and relationship map",
35
+ terms=("store view", "generic map", "label as a column", "created node", "store label",
36
+ "class IRI of a label", "predicate of a key", "store relationship"))
37
+
38
+ STORE_MAP = "owned-store:" # the id prefix of the generic maps' instances
39
+ DIGEST = "digest" # a node instance's column: its minted IRI after the store's prefix
40
+ EDGE_ID, START, END, TYPE = "edge_id", "start_iri", "end_iri", "rel_type"
41
+
42
+ # A literal's datatype -> the SQL type its text is read back as (the dialect's name for it, `_type`).
43
+ _SQL_OF = {xsd.INTEGER: "BIGINT", xsd.DOUBLE: "DOUBLE", xsd.BOOLEAN: "BOOLEAN", xsd.STRING: "VARCHAR"}
44
+
45
+
46
+ def _abstract(sql_type: str) -> str:
47
+ """`_SQL_OF`'s type as the name the dialects' type maps know (`Dialect.type_name`: STRING, LONG)."""
48
+ return {"VARCHAR": "STRING", "BIGINT": "LONG"}.get(sql_type, sql_type)
49
+
50
+
51
+ def _sql_of(dt: str) -> Optional[Any]:
52
+ """The type a literal of datatype `dt` is read back as: a value's SQL type (`_SQL_OF`), a list property's an
53
+ array of its elements'; a temporal's the source type it is read as (`_temporal_kind`), a list of temporals
54
+ a list of it; None for a datatype the view does not read."""
55
+ from prograph.schema import types as T
56
+ from prograph.store import list_element
57
+ element = list_element(dt)
58
+ if element is not None:
59
+ if _temporal_kind(element) is not None:
60
+ return T.list_of(_temporal_kind(element))
61
+ return _SQL_OF[element] + "[]" if element in _SQL_OF else None
62
+ return _temporal_kind(dt) or _SQL_OF.get(dt)
63
+
64
+
65
+ def _temporal_kind(dt: Optional[str]) -> Optional[Any]:
66
+ """The source type (`prograph.schema.types`) a temporal property of datatype `dt` is read back as
67
+ (`cypher_temporal.stored_kind`: a DATE, or a struct of the temporal's integer parts), so the Cypher
68
+ scan makes it the Cypher value as it does a mapped column's (rule cypher-source-temporal); None for
69
+ another datatype."""
70
+ from prograph.plan.ir.cypher_temporal import stored_kind
71
+ from prograph.schema.xsd import DATE
72
+ from prograph.store import TEMPORAL_DATATYPE
73
+ if dt == DATE:
74
+ return stored_kind("urn:prograph:cypher:date")
75
+ if dt is not None and dt.startswith(TEMPORAL_DATATYPE):
76
+ return stored_kind("urn:prograph:cypher:" + dt[len(TEMPORAL_DATATYPE):])
77
+ return None
78
+
79
+
80
+ def readable_datatype(dt: Optional[str]) -> bool:
81
+ """Whether a stored literal of datatype `dt` is read back as a Cypher value (`_SQL_OF`, and a decimal through
82
+ `lower.number_reader`; no list)."""
83
+ return dt in _SQL_OF or dt == xsd.DECIMAL
84
+
85
+
86
+ def is_store_map(m: Any) -> bool:
87
+ """Whether `m` is an instance of the store's generic node or relationship map."""
88
+ return str(getattr(m, "id", "")).startswith(STORE_MAP)
89
+
90
+
91
+ def label_column(label: str) -> str:
92
+ return f"l:{label}"
93
+
94
+
95
+ def key_column(key: str) -> str:
96
+ return f"p:{key}"
97
+
98
+
99
+ @dataclass
100
+ class StoreView:
101
+ """The store's names and generic maps, for one set of the user's maps (`lpg_view.build`).
102
+
103
+ Attributes:
104
+ store: The owned store (`prograph.store.Store`).
105
+ column_types: The schema's recorded column types, where an instance's columns are recorded so the
106
+ plan reads them typed (`entry._held`).
107
+ classes: label -> its class IRI, from the user's maps (a label they do not declare: the default).
108
+ key_predicates: key -> the predicates the user's maps give it, by label (None: any label).
109
+ rel_predicates: relationship type -> the predicate the user's maps give it.
110
+ """
111
+ store: Any
112
+ column_types: Dict[str, Dict[str, Any]]
113
+ classes: Dict[str, str] = field(default_factory=dict)
114
+ key_predicates: Dict[str, List[Tuple[Optional[str], str]]] = field(default_factory=dict)
115
+ rel_predicates: Dict[str, str] = field(default_factory=dict)
116
+ _instances: Dict[Any, Any] = field(default_factory=dict)
117
+
118
+ # -- names ----------------------------------------------------------------------------------------
119
+
120
+ def class_of(self, label: str) -> str:
121
+ """The class IRI of `label`: its mapping's, else the YAML default."""
122
+ return self.classes.get(label) or default_class_iri(label)
123
+
124
+ def predicate_of(self, key: str, labels: Sequence[str] = ()) -> str:
125
+ """The predicate a created element's property `key` is written under: the one a user's map of one of
126
+ its `labels` gives the key (in the order written), else the YAML default."""
127
+ given = self.key_predicates.get(key, [])
128
+ for label in labels:
129
+ for owner, predicate in given:
130
+ if owner == label:
131
+ return predicate
132
+ return default_property_iri(key)
133
+
134
+ def predicates_of(self, key: str) -> Tuple[str, ...]:
135
+ """Every predicate a store statement of property `key` may have (`predicate_of` for any labels)."""
136
+ return tuple(dict.fromkeys([p for _, p in self.key_predicates.get(key, [])] + [default_property_iri(key)]))
137
+
138
+ def rel_predicate_of(self, rel_type: str) -> str:
139
+ """The predicate of a created relationship of `rel_type`: its mapping's, else the YAML default."""
140
+ return self.rel_predicates.get(rel_type) or default_relationship_iri(rel_type)
141
+
142
+ def labels(self) -> Tuple[str, ...]:
143
+ """The labels of the store's created nodes now (read at the store's version)."""
144
+ out = [self.label_of(iri) for iri in self.store.profile().classes]
145
+ return tuple(dict.fromkeys(x for x in out if x))
146
+
147
+ def label_of(self, iri: Optional[str]) -> Optional[str]:
148
+ """The label a class IRI names: its mapping's, else the default vocabulary's local part."""
149
+ if iri is None:
150
+ return None
151
+ by_class = {c: label for label, c in self.classes.items()}
152
+ if iri in by_class:
153
+ return by_class[iri]
154
+ return iri[len(DEFAULT_VOCAB_IRI):] if iri.startswith(DEFAULT_VOCAB_IRI) else None
155
+
156
+ def types(self) -> Tuple[str, ...]:
157
+ """The relationship types of the store's created relationships now."""
158
+ return tuple(self.store.profile().types)
159
+
160
+ def _key_of(self, predicate: str) -> Optional[str]:
161
+ for key, given in self.key_predicates.items():
162
+ if any(p == predicate for _, p in given):
163
+ return key
164
+ return predicate[len(DEFAULT_VOCAB_IRI):] if predicate.startswith(DEFAULT_VOCAB_IRI) else None
165
+
166
+ def keys(self, of: str = "all") -> Tuple[str, ...]:
167
+ """The property keys the store's statements hold now (a predicate no key names is none): those of
168
+ its nodes (`of="node"`), its relationships (`"rel"`) or both."""
169
+ profile = self.store.profile()
170
+ held = profile.node_props if of == "node" else profile.rel_props if of == "rel" else \
171
+ profile.node_props | profile.rel_props
172
+ out = [self._key_of(p) for _, p, _ in sorted(held, key=str)]
173
+ return tuple(dict.fromkeys(k for k in out if k))
174
+
175
+ def datatype_of(self, key: str, owner: Optional[str], rel: bool = False,
176
+ extra: Optional[Dict[str, str]] = None, guards: Optional[set] = None) -> Optional[str]:
177
+ """The one datatype the store holds `key`'s values in on created nodes of `owner` (a label; None:
178
+ every created node), or with `rel` on relationships of type `owner`; None where it holds none.
179
+ A key of two datatypes there is not built (as for a mapped key of two types: one column, one type);
180
+ another label's or type's values do not count."""
181
+ from prograph.plan.ir.facts import NotBuilt
182
+ predicates = set(self.predicates_of(key))
183
+ profile = self.store.profile()
184
+ if rel:
185
+ held = {dt for t, p, dt in profile.rel_props if p in predicates and (owner is None or t == owner)}
186
+ else:
187
+ cls = self.class_of(owner) if owner is not None else None
188
+ held = {dt for c, p, dt in profile.node_props if p in predicates and (owner is None or c == cls)}
189
+ what = f"{'relationships' if rel else 'nodes'}{f' of {owner}' if owner else ''}"
190
+ if extra and key in extra and _sql_of(extra[key]) is not None:
191
+ # A type the query's own step writes, read after it: it wins over what the store held before the
192
+ # step (a SET that changes the type retracts the old values); a value of another type still held
193
+ # when the read runs raises there (`_value`'s guard, `TWO_TYPES`).
194
+ if held - {extra[key]} and guards is not None:
195
+ guards.add(key) # this read's own guard: the owner's old type, held before the step
196
+ return extra[key]
197
+ if len(held) > 1:
198
+ raise NotBuilt(f"property {key} of created {what} held in several types ({', '.join(sorted(held))})")
199
+ if held and _sql_of(next(iter(held))) is None:
200
+ raise NotBuilt(f"property {key} of created {what} of datatype {next(iter(held))}")
201
+ return next(iter(held)) if held else None
202
+
203
+ # -- the generic maps' instances -------------------------------------------------------------------
204
+
205
+ def _register(self, table: str, columns: Dict[str, str]) -> None:
206
+ from prograph.schema import types as T
207
+ self.column_types[table] = {c: T.of_sql_type(t) if isinstance(t, str) else t for c, t in columns.items()}
208
+
209
+ def _value(self, key: str, dt: str, where: str = "", other: bool = False) -> str:
210
+ """A key's value in an element's statements (its datatype `dt`), or with `other` whether the element
211
+ holds a value of another type (1, else null)."""
212
+ predicates = ", ".join(self._sql(p) for p in self.predicates_of(key))
213
+ test = f"o_datatype <> {self._sql(dt)}" if other else f"o_datatype = {self._sql(dt)}"
214
+ if other:
215
+ return f"max(CASE WHEN predicate IN ({predicates}) AND o_kind = '{LITERAL}' AND {test}{where} THEN 1 END)"
216
+ # The text's one value, then cast (an element holds one value of a key: PostgreSQL has no max of a
217
+ # boolean); a list's JSON text read as an array of its elements' type.
218
+ text = f"max(CASE WHEN predicate IN ({predicates}) AND o_kind = '{LITERAL}' AND {test}{where} THEN o_text END)"
219
+ return self._read(text, dt)
220
+
221
+ def _read(self, text: str, dt: str) -> str:
222
+ """A statement's text (SQL) read back as a value of datatype `dt`: cast to its SQL type; a list's JSON
223
+ text as an array of its elements' type; a temporal's as the source value `_temporal_kind` names (a
224
+ DATE, a struct of its parts), a list of temporals an array of them."""
225
+ from prograph.store import list_element
226
+ from prograph.plan.sql.dialect import get_dialect_instance
227
+ from prograph.schema import types as T
228
+ from prograph.schema.xsd import DATE
229
+ d = get_dialect_instance(self.store.dialect)
230
+ element = list_element(dt)
231
+ kind = _temporal_kind(element if element is not None else dt)
232
+ if kind is not None and (element or dt) != DATE:
233
+ fields = ", ".join(f"{f} {d.type_name('STRING') if f == 'zone' else d.type_name('LONG')}"
234
+ for f in T.temporal_struct_fields(kind))
235
+ return d.render_function("STORE_PARTS_LIST_READ" if element else "STORE_PARTS_READ", [text, fields])
236
+ if element is not None:
237
+ sql = d.type_name("DATE") if element == DATE else d.type_name(_abstract(_SQL_OF[element]))
238
+ return d.render_function("STORE_LIST_READ", [text, sql])
239
+ return f"CAST({text} AS {self._type(dt)})"
240
+
241
+ def _guarded(self, query: str, guards: set, held: Dict[str, str], columns: Sequence[str]) -> str:
242
+ """`query`'s rows with each guarded key raising where the row's element holds a value of another
243
+ type than the one read (a type the query's writes did not replace): checked on the rows of the
244
+ instance's label or type only (after its filter), never read as null."""
245
+ if not guards:
246
+ return query
247
+ from prograph.plan.ir.cypher_write import TWO_TYPES
248
+ from prograph.plan.sql.dialect import get_dialect_instance
249
+ render = get_dialect_instance(self.store.dialect).render_function
250
+ replaced = {key_column(k): (
251
+ f"CASE WHEN {self._q('g:' + k)} = 1 THEN "
252
+ f"{self._read(render('RAISE_ERROR', [self._sql(TWO_TYPES + k)]), held[k])} "
253
+ f"ELSE {self._q(key_column(k))} END") for k in guards}
254
+ # Every column the instance has, the guarded ones replaced and the guards left out (an explicit list:
255
+ # `SELECT * EXCLUDE ... REPLACE` is DuckDB's alone).
256
+ return (f"SELECT {', '.join(f'{replaced[c]} AS {self._q(c)}' if c in replaced else self._q(c) for c in columns)} "
257
+ f"FROM ({query}) AS _g")
258
+
259
+ def _cached(self, cache: tuple) -> Any:
260
+ # The store's version, and whether its reads see a running step's own rows (`Store.read_own`).
261
+ version = (self.store.version, self.store.view_key)
262
+ if self._instances.get("version") != version:
263
+ self._instances.clear() # instances of an older version are never read again
264
+ self._instances["version"] = version
265
+ return self._instances.get(cache)
266
+
267
+ def _name(self, kind: str, owner: Optional[str], cache: tuple) -> str:
268
+ """An instance's source name: one per pattern shape, so the recorded column types stay bounded."""
269
+ import hashlib
270
+ key = cache if self.store.view_key is None else (cache, self.store.view_key)
271
+ digest = hashlib.sha1(repr(key).encode("utf-8")).hexdigest()[:12]
272
+ return f"{STORE_MAP}{kind}:{owner or ''}#{digest}"
273
+
274
+ def node_map(self, label: Optional[str], keys: Sequence[str], labels: Sequence[str],
275
+ extra: Optional[Dict[str, str]] = None, force: bool = False) -> Optional[Tuple[NodeMap, Dict]]:
276
+ """The generic node map for a pattern of `label` (None: every created node), reading `keys` and a
277
+ flag for each of `labels`, and its properties (key -> its predicate-object map) for the view; None
278
+ where the store holds no created node of the label (the pattern reads no store then)."""
279
+ from prograph.plan.ir.dataset import property_graph_graphs
280
+ from prograph.store import ELEMENT, RDF_TYPE
281
+ profile = self.store.profile()
282
+ if not force and (not profile.nodes or label is not None and self.class_of(label) not in profile.classes):
283
+ return None
284
+ guards: set = set()
285
+ held = {k: self.datatype_of(k, label, extra=extra, guards=guards) for k in keys}
286
+ held = {k: dt for k, dt in held.items() if dt is not None}
287
+ flags = list(dict.fromkeys(list(labels) + ([label] if label is not None else [])))
288
+ cache = ("node", label, tuple(sorted(held.items())), tuple(flags), tuple(sorted(guards)))
289
+ if self._cached(cache) is not None:
290
+ return self._instances[cache]
291
+ prefix = self.store.minted_prefix()
292
+ typed = f"predicate = {self._sql(RDF_TYPE)} AND o_kind = '{IRI}' AND o_text = "
293
+ columns = {DIGEST: "VARCHAR"}
294
+ select = [f"substr(subject, {len(prefix) + 1}) AS {self._q(DIGEST)}"]
295
+ for k, dt in held.items():
296
+ select.append(f"{self._value(k, dt)} AS {self._q(key_column(k))}")
297
+ if k in guards:
298
+ select.append(f"{self._value(k, dt, other=True)} AS {self._q('g:' + k)}")
299
+ columns[key_column(k)] = _sql_of(dt)
300
+ for name in flags:
301
+ select.append(f"CASE WHEN max(CASE WHEN {typed}{self._sql(self.class_of(name))} THEN 1 END) = 1 "
302
+ f"THEN TRUE END AS {self._q(label_column(name))}")
303
+ columns[label_column(name)] = "BOOLEAN"
304
+ # Each filter a starts_with or an IS NOT NULL, which PostgreSQL estimates (a substr equality or an
305
+ # aggregate's `= 1` it takes for one row in two hundred: a join of two patterns then a nested loop
306
+ # that reads the view again for each row, 66 s for 5,000 nodes).
307
+ having = [f"max(CASE WHEN predicate = {self._sql(ELEMENT)} THEN 1 END) IS NOT NULL"]
308
+ if label is not None:
309
+ having.append(f"max(CASE WHEN {typed}{self._sql(self.class_of(label))} THEN 1 END) IS NOT NULL")
310
+ query = (f"SELECT {', '.join(select)} FROM ({self.store.effective_sql(property_graph_graphs())}) AS _e "
311
+ f"WHERE {self.store.db.starts_with}(subject, {self._sql(prefix)}) GROUP BY subject "
312
+ f"HAVING {' AND '.join(having)}")
313
+ query = self._guarded(query, guards, held, list(columns))
314
+ name = self._name("node", label, cache)
315
+ self._register(name, columns)
316
+ pos = tuple(PredicateObject(predicate=self.predicate_of(k, [label] if label else []),
317
+ object=TermMap(LITERAL, column=key_column(k)), property_name=k)
318
+ for k in held)
319
+ m = NodeMap(id=name, order=-1, source=Source(table=name, qualified=name, query=query),
320
+ key=Key(columns=(DIGEST,), trust="trusted"),
321
+ subject=TermMap(IRI, template=((prefix, False), (DIGEST, True))),
322
+ classes=(self.class_of(label),) if label else (), predicate_objects=pos, label=label,
323
+ identity="owned-store", property_columns=tuple((k, key_column(k)) for k in held))
324
+ out = (m, {k: (po,) for k, po in zip(held, pos)})
325
+ self._instances[cache] = out
326
+ return out
327
+
328
+ def fact_map(self, key: str, facts: Sequence[NodeMap], target: Optional[Tuple[str, Any]] = None) -> NodeMap:
329
+ """One map over the stored OWL RL facts that give node property `key` (`facts`: the store's derived maps of
330
+ a literal object, one datatype, `lpg_view.LPGView.stored_values`): its rows (subject, value), the value's
331
+ text read back as the datatype's SQL type, so the plan reads it typed (`cypher-derived-labels`). A decimal
332
+ is read as `held-number` reads a decimal held as text (`lower.number_reader`: DECIMAL(38, 18)). `target`,
333
+ (datatype, digits): the mapped column's numeric type the value is promoted to (rule `stored-fact-promotion`;
334
+ a decimal with no digits is DECIMAL(38, 18))."""
335
+ from prograph.plan.ir.lower import number_reader
336
+ from prograph.plan.sql.dialect import get_dialect_instance
337
+ pos = [po for m in facts for po in m.predicate_objects]
338
+ dt = pos[0].object.datatype
339
+ cache = ("fact", key, tuple(m.source.query for m in facts), target)
340
+ if self._cached(cache) is not None:
341
+ return self._instances[cache]
342
+ d = get_dialect_instance(self.store.dialect)
343
+
344
+ def read(column: str) -> str:
345
+ if dt == xsd.DECIMAL:
346
+ return d.render_function(number_reader(dt), [column])
347
+ return f"CAST({column} AS {self._type(dt)})"
348
+ held, sql_type = dt, _SQL_OF.get(dt) or "DECIMAL(38,18)"
349
+ if target is not None:
350
+ held, digits = target
351
+ sql_type = {xsd.INTEGER: "BIGINT", xsd.DOUBLE: "DOUBLE"}.get(held) or \
352
+ (f"DECIMAL({digits[0]},{digits[1]})" if digits else "DECIMAL(38,18)")
353
+ cast = (lambda v: v) if target is None else \
354
+ (lambda v: f"CAST({v} AS {d.type_name(_abstract(sql_type)) if held != xsd.DECIMAL else sql_type})")
355
+ parts = [f"SELECT {self._q('subject')} AS {self._q('subject')}, {cast(read(self._q(po.object.column)))} "
356
+ f"AS {self._q('value')} FROM ({m.source.query}) AS _f" for m, po in zip(facts, pos)]
357
+ name = "owned-facts:" + self._name("fact", key, cache)[len(STORE_MAP):] # not a generic map (`is_store_map`)
358
+ self._register(name, {"subject": "VARCHAR", "value": sql_type})
359
+ m = NodeMap(id=name, order=-1, source=Source(table=name, qualified=name, query=" UNION ALL ".join(parts)),
360
+ key=Key(columns=("subject",), stated=False), subject=TermMap(IRI, column="subject"), classes=(),
361
+ predicate_objects=(PredicateObject(predicate=pos[0].predicate,
362
+ object=TermMap(LITERAL, column="value", datatype=held)),))
363
+ self._instances[cache] = m
364
+ return m
365
+
366
+ def edge_map(self, rel_type: Optional[str], keys: Sequence[str], extra: Optional[Dict[str, str]] = None,
367
+ force: bool = False) -> Optional[EdgeMap]:
368
+ """The generic relationship map for a pattern of `rel_type` (None: every created relationship),
369
+ reading `keys`: its ends' IRIs (`START`, `END`), its edge id and its type as columns; None where the
370
+ store holds no created relationship of the type."""
371
+ from prograph.plan.ir.dataset import property_graph_graphs
372
+ from prograph.store import REL_TYPE
373
+ types = self.store.profile().types
374
+ if not force and (not types or rel_type is not None and rel_type not in types):
375
+ return None
376
+ guards: set = set()
377
+ held = {k: self.datatype_of(k, rel_type, rel=True, extra=extra, guards=guards) for k in keys}
378
+ held = {k: dt for k, dt in held.items() if dt is not None}
379
+ cache = ("edge", rel_type, tuple(sorted(held.items())), tuple(sorted(guards)))
380
+ if self._cached(cache) is not None:
381
+ return self._instances[cache]
382
+ prefix = self.store.minted_prefix()
383
+ effective = self.store.effective_sql(property_graph_graphs())
384
+ columns = {START: "VARCHAR", END: "VARCHAR", EDGE_ID: "VARCHAR", TYPE: "VARCHAR"}
385
+ about = [f"max(CASE WHEN predicate = {self._sql(REL_TYPE)} THEN o_text END) AS {self._q(TYPE)}"]
386
+ if rel_type is not None: # the type's filter, an IS NOT NULL (the estimate below)
387
+ about.append(f"max(CASE WHEN predicate = {self._sql(REL_TYPE)} AND o_text = {self._sql(rel_type)} "
388
+ f"THEN 1 END) AS {self._q('t:')}")
389
+ for k, dt in held.items():
390
+ about.append(f"{self._value(k, dt)} AS {self._q(key_column(k))}")
391
+ if k in guards:
392
+ about.append(f"{self._value(k, dt, other=True)} AS {self._q('g:' + k)}")
393
+ columns[key_column(k)] = _sql_of(dt)
394
+ # One group per relationship, keyed by its edge id: its statement from start to end (an IRI object
395
+ # with the edge id) and the statements about the edge id (its type, its properties). One GROUP BY, no
396
+ # join of the effective view to itself (PostgreSQL, its estimates of the view poor, joined the two
397
+ # halves by a nested loop: 92 s for 50,000 relationships), and filters it estimates (`node_map`).
398
+ rel = f"edge_id IS NOT NULL AND o_kind = '{IRI}'"
399
+ query = (f"SELECT {', '.join(self._q(c) for c in [START, END, EDGE_ID, TYPE] + [key_column(k) for k in held] + ['g:' + k for k in sorted(guards)])} "
400
+ f"FROM (SELECT max(CASE WHEN {rel} THEN subject END) AS {self._q(START)}, "
401
+ f"max(CASE WHEN {rel} THEN o_text END) AS {self._q(END)}, _k AS {self._q(EDGE_ID)}, {', '.join(about)} "
402
+ f"FROM (SELECT *, CASE WHEN {rel} THEN edge_id ELSE subject END AS _k FROM ({effective}) AS _r "
403
+ f"WHERE {rel} OR {self.store.db.starts_with}(subject, {self._sql(prefix)})) AS _e GROUP BY _k) AS _a "
404
+ f"WHERE {self._q(START)} IS NOT NULL AND {self.store.db.starts_with}(_a.{self._q(EDGE_ID)}, {self._sql(prefix)}) "
405
+ f"AND {self._q(TYPE)} IS NOT NULL"
406
+ + (f" AND _a.{self._q('t:')} IS NOT NULL" if rel_type is not None else ""))
407
+ query = self._guarded(query, guards, held, list(columns))
408
+ name = self._name("relationship", rel_type, cache)
409
+ self._register(name, columns)
410
+ m = EdgeMap(id=name, order=-1, source=Source(table=name, qualified=name, query=query),
411
+ predicate=self.rel_predicate_of(rel_type) if rel_type else None, rel_type=rel_type,
412
+ start=EndRef(map_id=None, label=None, columns=(START,), listed=False,
413
+ term=TermMap(IRI, column=START), exists=False),
414
+ end=EndRef(map_id=None, label=None, columns=(END,), listed=False,
415
+ term=TermMap(IRI, column=END), exists=False),
416
+ property_columns=tuple((k, key_column(k)) for k in held), row_key=(EDGE_ID,))
417
+ self._instances[cache] = m
418
+ return m
419
+
420
+
421
+ def step_map(self, step: str) -> NodeMap:
422
+ """The subjects one write step wrote (its rows by step key, the effective view aside): what a
423
+ RETURN after CREATE is joined to by minted IRI (`cypher_write`)."""
424
+ name = f"{STORE_MAP}step" # one name for every step: its column's type is the same
425
+ self._register(name, {"subject": "VARCHAR"})
426
+ query = f"SELECT DISTINCT subject FROM {self.store.table} WHERE step = {self._sql(step)}"
427
+ return NodeMap(id=name, order=-1, source=Source(table=name, qualified=name, query=query),
428
+ key=Key(columns=("subject",), trust="trusted"), subject=TermMap(IRI, column="subject"),
429
+ classes=(), predicate_objects=(), identity="owned-store")
430
+
431
+ # -- the store's SQL: its engine's literals, names and types ----------------------------------------
432
+
433
+ def _sql(self, text: str) -> str:
434
+ """An SQL string literal (the dialect's literal home)."""
435
+ from prograph.plan.sql.dialect import get_dialect_instance
436
+ return get_dialect_instance(self.store.dialect).literal(text)
437
+
438
+ def _q(self, name: str) -> str:
439
+ """An SQL identifier (the dialect's quoting home)."""
440
+ from prograph.plan.sql.dialect import get_dialect_instance
441
+ return get_dialect_instance(self.store.dialect).quote(name)
442
+
443
+ def _type(self, dt: str) -> str:
444
+ """The SQL type a literal of datatype `dt` is read back as, in the store's engine (a DATE a date's)."""
445
+ from prograph.plan.sql.dialect import get_dialect_instance
446
+ from prograph.schema.xsd import DATE
447
+ from prograph.store import list_element
448
+ element = list_element(dt)
449
+ d = get_dialect_instance(self.store.dialect)
450
+ if dt == DATE:
451
+ return d.type_name("DATE")
452
+ return d.type_name(_abstract(_SQL_OF[element])) + "[]" if element is not None \
453
+ else d.type_name(_abstract(_SQL_OF[dt]))
454
+
455
+
456
+ def store_identity(m: EdgeMap) -> TermMap:
457
+ """A created relationship's identity: its minted edge id."""
458
+ return TermMap(IRI, column=EDGE_ID)
459
+