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,291 @@
1
+ """Fresh values: UUID(), STRUUID(), RAND() and BNODE() (SPARQL 1.1 17.4.2.9, 17.4.2.12, 17.4.2.13,
2
+ 17.4.4.5, decided 2026-11-10).
3
+
4
+ A SPARQL binding is one value (18.5, Extend): `BIND(UUID() AS ?u)` then `?u` in a join, a FILTER
5
+ and the result read the same UUID. SQL does not promise to evaluate an expression once per row (an
6
+ optimizer may inline it, Spark may re-run a task), so a value the engine draws at random could
7
+ disagree with itself. Here a value is a function of its solution instead (`PerSolutionHash`):
8
+
9
+ digest = MD5(nonce : call : key : ordinal)
10
+
11
+ - `nonce`: chosen when the query is planned, so each execution's values are new;
12
+ - `call`: the call's place in the query, so two calls in one solution differ;
13
+ - `key`: every physical column the row carries, each written length-prefixed (`FRESH_PIECE`),
14
+ so solutions that differ in any part of any term differ;
15
+ - `ordinal`: ROW_NUMBER() among the rows of one key (`ROW_ORDINAL`), so duplicate solutions
16
+ differ; left out (0) where the facts prove the rows distinct. Identical rows cannot be told
17
+ apart, so however often an engine evaluates it, it yields the same multiset of values.
18
+
19
+ UUID()/STRUUID() write the digest as a version-4-shaped UUID (`UUID_OF_HEX`: the version and
20
+ variant digits fixed, 120 bits from the digest), not a random one. RAND() is 52 bits of the digest
21
+ over 2^52 (`UNIT_OF_HEX`), in [0, 1). BNODE() is a label under a reserved prefix (U+001F, then
22
+ `fresh:`, then the digest); BNODE(str) leaves the call out, so equal strings in one solution give
23
+ one node.
24
+
25
+ The strategy for UUID, STRUUID and RAND is pluggable (`STRATEGY`): another strategy (the engine's
26
+ own `uuid()`/`rand()`, which relies on the engine evaluating once) can be added beside
27
+ `PerSolutionHash`. BNODE is always `PerSolutionHash`: its label is never seen, only its identity,
28
+ which is what the hash guarantees.
29
+ """
30
+
31
+ from __future__ import annotations
32
+
33
+ import contextlib
34
+ import contextvars
35
+ import secrets
36
+ from dataclasses import dataclass
37
+ from typing import Any, Optional, Tuple
38
+
39
+ from prograph.plan.ir import expr as E
40
+ from prograph.plan.ir import ops as O
41
+ from prograph.rules import home
42
+
43
+ FRESH = frozenset({"UUID", "STRUUID", "RAND", "BNODE", "MINT"})
44
+
45
+ # The reserved start of a fresh blank node's label: a control character no mapping's template
46
+ # writes in practice, then a word; the digest follows (see the module's doc).
47
+ BNODE_PREFIX = "\x1ffresh:"
48
+
49
+
50
+ @dataclass(frozen=True)
51
+ class Row:
52
+ """The row a fresh value is a function of: its key's SQL text and its ordinal among equal keys."""
53
+ key: Any
54
+ ordinal: Any
55
+
56
+
57
+ class FreshStrategy:
58
+ """How UUID(), STRUUID() and RAND() get their values (`STRATEGY`). `row` is the evaluating
59
+ row (`Row`), `call` the call's id, `nonce` the execution's."""
60
+ name = "abstract"
61
+
62
+ def uuid_text(self, nonce: str, call: str, row: Row) -> Any:
63
+ """A UUID's text, `xxxxxxxx-xxxx-4xxx-8xxx-xxxxxxxxxxxx`."""
64
+ raise NotImplementedError
65
+
66
+ def unit(self, nonce: str, call: str, row: Row) -> Any:
67
+ """A double in [0, 1)."""
68
+ raise NotImplementedError
69
+
70
+
71
+ class PerSolutionHash(FreshStrategy):
72
+ """B: a digest of the nonce, the call, the row's key and its ordinal (the module's doc)."""
73
+ name = "per-solution-hash"
74
+
75
+ def uuid_text(self, nonce: str, call: str, row: Row) -> Any:
76
+ from prograph.plan.ir import lower as L
77
+ return L.fn("UUID_OF_HEX", digest(nonce, call, row))
78
+
79
+ def unit(self, nonce: str, call: str, row: Row) -> Any:
80
+ from prograph.plan.ir import lower as L
81
+ return L.fn("UNIT_OF_HEX", digest(nonce, call, row))
82
+
83
+
84
+ DEFAULT = PerSolutionHash()
85
+ STRATEGY: contextvars.ContextVar[FreshStrategy] = contextvars.ContextVar("fresh_strategy", default=DEFAULT)
86
+ # The execution's nonce, set when a query is lowered (`entry._lowered`); one per call of `run`.
87
+ NONCE: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar("fresh_nonce", default=None)
88
+ # The row being evaluated, set while an Extend holding a fresh call is lowered (`Lowering._Extend`).
89
+ ROW: contextvars.ContextVar[Optional[Row]] = contextvars.ContextVar("fresh_row", default=None)
90
+
91
+
92
+ def new_nonce() -> str:
93
+ return secrets.token_hex(8)
94
+
95
+
96
+ def digest(nonce: str, call: str, row: Row, *more: Any) -> Any:
97
+ """MD5 (32 lower-case hex digits) of the nonce, the call, the row's key and ordinal, and `more`."""
98
+ from prograph.plan.ir import lower as L
99
+ parts = [L.text(f"{nonce}:{call}:"), row.key, L.text(":"), L.fn("CAST_STRING", row.ordinal)]
100
+ for m in more:
101
+ parts += [L.text(":"), m]
102
+ return L.fn("MD5", L.concat(parts))
103
+
104
+
105
+ def holds(e: E.Expr) -> bool:
106
+ """Whether `e` calls a fresh function."""
107
+ if isinstance(e, E.Call) and e.semantics in (E.SPARQL, E.CYPHER) and e.name in FRESH:
108
+ return True
109
+ return any(holds(c) for c in e.children())
110
+
111
+
112
+ def volatile(op: O.Op) -> bool:
113
+ """Whether a fresh value is made in `op`'s subtree: no rewrite moves, copies or drops such an
114
+ Extend (`rewrite._down`)."""
115
+ cached = op.__dict__.get("_volatile")
116
+ if cached is None:
117
+ cached = isinstance(op, O.Extend) and holds(op.expr)
118
+ if not cached:
119
+ for v in vars(op).values():
120
+ if isinstance(v, O.Op) and volatile(v):
121
+ cached = True
122
+ break
123
+ if isinstance(v, tuple) and any(isinstance(x, O.Op) and volatile(x) for x in v):
124
+ cached = True
125
+ break
126
+ object.__setattr__(op, "_volatile", cached)
127
+ return cached
128
+
129
+
130
+ @contextlib.contextmanager
131
+ def per_element(position: Any):
132
+ """Inside a list comprehension or quantifier over its elements by `position` (an element's 1-based
133
+ place in the list, `cypher_lists._over_elements`): the row a fresh value is a function of is the
134
+ solution's row and that position, so each element draws its own value, and a draw read twice for one
135
+ element (a quantifier's true and null counts) is one value. Outside an Extend (no row) unchanged."""
136
+ from prograph.plan.ir import lower as L
137
+ row = ROW.get()
138
+ if row is None:
139
+ yield
140
+ return
141
+ key = L.concat([row.key, L.text("@"), L.fn("FRESH_PIECE", position), L.text("|")])
142
+ token = ROW.set(Row(key=key, ordinal=row.ordinal))
143
+ try:
144
+ yield
145
+ finally:
146
+ ROW.reset(token)
147
+
148
+
149
+ def per_element_draw(e: E.Expr) -> bool:
150
+ """Whether `e` draws a fresh value inside a list comprehension or quantifier (`per_element`)."""
151
+ if isinstance(e, E.Call) and e.semantics == E.CYPHER and e.name in ("ALL", "ANY", "NONE", "SINGLE",
152
+ "COMPREHENSION"):
153
+ if any(holds(a) for a in e.args[2:]):
154
+ return True
155
+ return any(per_element_draw(c) for c in e.children())
156
+
157
+
158
+ def cypher_rand_slot() -> Any:
159
+ """Cypher's rand(): a float value, never null (the same draw as SPARQL's RAND, `fresh_cell`)."""
160
+ from prograph.plan.ir.slot import Bound, value_slot
161
+ from prograph.schema import xsd
162
+ return value_slot(xsd.DOUBLE, Bound.NEVER)
163
+
164
+
165
+ def cypher_rand_cell(e: E.Call, cells) -> Any:
166
+ """Cypher's rand() as a value of the one draw `fresh_cell` makes (rule fresh-values): [0, 1), one per
167
+ solution, so `rand()` read twice in a solution is two calls, each one value."""
168
+ from prograph.plan.ir import lower as L
169
+ drawn = fresh_cell(E.Call("RAND", e.args, E.SPARQL), cells)
170
+ return L.Cell(cypher_rand_slot(), drawn.value)
171
+
172
+
173
+ def fresh_slot(e: E.Call, slots) -> Any:
174
+ from prograph.plan.ir.facts import expr_slot
175
+ from prograph.plan.ir.slot import Bound, Slot, literal_slot
176
+ from prograph.schema import xsd
177
+ from prograph.schema.source_map import BLANK, IRI
178
+ if e.name in ("UUID", "MINT"):
179
+ return Slot(kinds=frozenset({IRI}), bound=Bound.ALWAYS)
180
+ if e.name == "STRUUID":
181
+ return literal_slot(xsd.STRING, Bound.ALWAYS, native=True)
182
+ if e.name == "RAND":
183
+ return literal_slot(xsd.DOUBLE, Bound.ALWAYS, native=True)
184
+ if len(e.args) == 1:
185
+ return Slot(kinds=frozenset({BLANK}), bound=Bound.ALWAYS)
186
+ from prograph.plan.ir.strings import YES, _simple
187
+ arg = expr_slot(e.args[1], slots)
188
+ sure = _simple(arg) == YES and arg.present is Bound.ALWAYS
189
+ return Slot(kinds=frozenset({BLANK}), bound=Bound.ALWAYS if sure else Bound.MAYBE)
190
+
191
+
192
+ @home("fresh-values", "UUID(), STRUUID(), RAND() and BNODE(): one value per solution, in SQL",
193
+ terms=("UUID", "STRUUID", "RAND", "BNODE", "fresh value", "nondeterministic", "nonce",
194
+ "blank node constructor", "per-solution hash"))
195
+ def fresh_cell(e: E.Call, cells) -> Any:
196
+ """The cell of a fresh call over the row `ROW` names (the module's doc). Outside an Extend
197
+ (a FILTER, ORDER BY, an aggregate's argument) there is no such row: not built."""
198
+ from prograph.plan.ir import lower as L
199
+ from prograph.plan.ir.facts import NotBuilt, expr_slot
200
+ row, nonce = ROW.get(), NONCE.get()
201
+ if e.name == "MINT":
202
+ return mint_cell(e, cells)
203
+ if row is None or nonce is None:
204
+ if e.semantics == E.CYPHER:
205
+ raise NotBuilt("rand() outside a RETURN or WITH item: draw it in a WITH item first")
206
+ raise NotBuilt(f"{e.name}() outside BIND or a SELECT expression")
207
+ slot = expr_slot(e, L._slots(cells))
208
+ call = e.args[0].value.lexical
209
+ strategy = STRATEGY.get()
210
+ if e.name == "UUID":
211
+ return L.Cell(slot, L.concat([L.text("urn:uuid:"), strategy.uuid_text(nonce, call, row)]))
212
+ if e.name == "STRUUID":
213
+ return L.Cell(slot, strategy.uuid_text(nonce, call, row))
214
+ if e.name == "RAND":
215
+ return L.Cell(slot, strategy.unit(nonce, call, row))
216
+ # BNODE: always the per-solution hash.
217
+ if len(e.args) == 1:
218
+ return L.Cell(slot, L.concat([L.text(BNODE_PREFIX), digest(nonce, call, row)]))
219
+ from prograph.plan.ir.strings import _valid_simple
220
+ arg = L.expr_cell(e.args[1], cells)
221
+ label = L.concat([L.text(BNODE_PREFIX), digest(nonce, "bnode-of", row, L.fn("FRESH_PIECE", L.lexical(arg)))])
222
+ valid = L.all_of([L.is_null(arg.value, negated=True), _valid_simple(arg)])
223
+ return L.Cell(slot, L.case(valid, label))
224
+
225
+
226
+ def mint(prefix: str, namespace: str, step: str, call: str, bound: Tuple[str, ...]) -> E.Call:
227
+ """A created element's IRI, made per row (`mint_cell`): `prefix` the store's minted prefix, `namespace`
228
+ the store's id, `step` the write step's key, `call` the element's place in the query (its clause and
229
+ pattern position), `bound` the columns of the variables the query bound before it."""
230
+ return E.Call("MINT", (E.Const(call), E.Const(step), E.Const(namespace), E.Const(prefix))
231
+ + tuple(E.Col(c) for c in bound), E.SPARQL)
232
+
233
+
234
+ def mint_iri(prefix: str, namespace: str, step: str, call: str, key: str = "|", ordinal: int = 1) -> str:
235
+ """`mint_cell`'s IRI in Python, for a caller that mints one element itself (`Store.mint`)."""
236
+ import hashlib
237
+ text = f"{namespace}:{step}:{call}:{key}:{ordinal}"
238
+ return prefix + hashlib.sha256(text.encode("utf-8")).hexdigest()
239
+
240
+
241
+ @home("store-mint", "A created element's minted IRI, one per row, the same on a retry",
242
+ terms=("mint", "minted IRI", "CREATE", "SHA-256", "digest", "write step key", "created node IRI"))
243
+ def mint_cell(e: E.Call, cells: Any) -> Any:
244
+ """`{prefix}{SHA-256 of store : step key : call : the row's key : its ordinal}` (one-plan 2.10, design 66).
245
+ The row's key is what the query itself bound before the CREATE, and nothing a
246
+ plan adds (a property or label it read, which follows the store's names): each bound variable's term
247
+ as text (`lower.lexical`) or value, length-prefixed, NULL `~`; the ordinal is its number among rows of
248
+ equal key (ROW_NUMBER). So `UNWIND [1, 1, 2] AS x CREATE (:N {v: x})` makes three nodes, and a retried
249
+ step mints the same three whatever order the rows come in and whatever the store holds since. The
250
+ per-solution hash of the fresh values, with the step key for the nonce and SHA-256 for MD5."""
251
+ from prograph.plan.ir import lower as L
252
+ from prograph.plan.ir.slot import Bound, Slot
253
+ from prograph.schema.source_map import IRI
254
+ call, step, namespace, prefix = (a.value for a in e.args[:4])
255
+ pieces = []
256
+ for col in e.args[4:]:
257
+ cell = cells[col.name]
258
+ value = L.lexical(cell) if cell.slot.terms else cell.value
259
+ pieces += [L.fn("FRESH_PIECE", value), L.text("|")]
260
+ key = L.concat([L.text("|")] + pieces)
261
+ digest = L.fn("SHA256", L.concat([L.text(f"{namespace}:{step}:{call}:"), key, L.text(":"),
262
+ L.fn("CAST_STRING", L.fn("ROW_ORDINAL", key))]))
263
+ return L.Cell(Slot(kinds=frozenset({IRI}), bound=Bound.ALWAYS), L.concat([L.text(prefix), digest]))
264
+
265
+
266
+ def key_iri_cell(e: E.Call, cells: Any) -> Any:
267
+ """`KEY_IRI(prefix, namespace, what, v1, ...)`: the IRI a MERGE's key gives an element (rule store-mint):
268
+ `{prefix}` + SHA-256 of the store id, what it is (a label's, a relationship's) and each value as text,
269
+ length-prefixed, NULL `~`. No step key and no row: two writers merging one key meet."""
270
+ from prograph.plan.ir import lower as L
271
+ from prograph.plan.ir.slot import LIST, Bound, Slot
272
+ from prograph.schema.source_map import IRI
273
+ prefix, namespace, what = (a.value for a in e.args[:3])
274
+ pieces = []
275
+ for arg in e.args[3:]:
276
+ cell = L.expr_cell(arg, cells)
277
+ value = L.lexical(cell) if cell.slot.terms else cell.value
278
+ # The value's type beside its text: 1, 1.0 and '1' never give one IRI; a list's its elements' type
279
+ # and its stored text (`cypher_write.list_text`), so [1] and '[1]' never meet either.
280
+ kind = "iri" if cell.slot.terms else ",".join(sorted(cell.slot.datatypes)) or "null"
281
+ if cell.slot.kinds == {LIST}:
282
+ from prograph.plan.ir.cypher_write import list_text
283
+ value, kind = list_text(cell), "list:" + kind
284
+ elif len(cell.slot.datatypes) == 1 and not cell.slot.terms:
285
+ from prograph.plan.ir.cypher_temporal import stored_kind
286
+ if stored_kind(cell.slot.datatype) is not None: # a temporal: its stored text (all its parts)
287
+ from prograph.plan.ir.cypher_write import temporal_text
288
+ value = temporal_text(cell.slot.datatype, cell.value)
289
+ pieces += [L.text(kind + "="), L.fn("FRESH_PIECE", value), L.text("|")]
290
+ digest = L.fn("SHA256", L.concat([L.text(f"{namespace}:key:{what}:|")] + pieces))
291
+ return L.Cell(Slot(kinds=frozenset({IRI}), bound=Bound.ALWAYS), L.concat([L.text(prefix), digest]))