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,1081 @@
1
+ """A Cypher answer's whole elements (one-plan section 6; the answer shape of the Cypher inventory), made in the statement: a node is
2
+
3
+ {id: string, labels: list<string>, properties: map<string, V>}
4
+
5
+ an Arrow struct on DuckDB, Spark and Databricks. On PostgreSQL the statement writes the struct's parts as
6
+ flat typed columns (`Shape`, `element_parts`) and the reader assembles the same Arrow struct
7
+ (`postgresql_graph.Numerics`), never through jsonb. `id` is the node's identity as text; `labels`
8
+ the labels of the maps that give it, in name order; `properties` (`properties_map`, also `properties(n)`
9
+ and a relationship's) a map holding the keys the node has: a Cypher node has no null property, so a key
10
+ it lacks is absent, not null. V is the one plain type where every key holds one type, else Arrow's dense
11
+ union of integer, float, string and boolean (rule cypher-mixed-values). A null identity (an OPTIONAL
12
+ MATCH that found none) is a null node.
13
+ """
14
+
15
+ from __future__ import annotations
16
+
17
+ from dataclasses import dataclass, replace
18
+ from typing import Any, Dict, List, Optional, Tuple
19
+
20
+ from prograph.plan.ir import expr as E
21
+ from prograph.plan.ir.facts import NotBuilt
22
+ from prograph.plan.ir.slot import LIST, MAP, MIXED, VALUE, Bound, Slot
23
+ from prograph.plan.sql import rel_algebra as R
24
+ from prograph.rules import home
25
+ from prograph.schema import xsd
26
+
27
+ NODE_TYPE = "urn:prograph:cypher:node" # the slot datatype of a node value
28
+
29
+ # The fields of each element's answer struct, in order: the one definition DuckDB's struct (`node_cell`,
30
+ # `rel_cell`, `path_cell`) and the PostgreSQL reader's assembly (`postgresql_graph.Numerics`) are both
31
+ # written from, so they cannot drift.
32
+ NODE_FIELDS = ("id", "labels", "properties")
33
+ REL_FIELDS = ("id", "type", "start", "end", "properties")
34
+ PATH_FIELDS = ("nodes", "relationships")
35
+ LABEL_ITEM = "l" # the element name of a labels list's Arrow type, as DuckDB gives it (list<l: string>)
36
+
37
+
38
+ def named_struct(L, fields, values) -> "R.Expr":
39
+ """`NAMED_STRUCT(field, value, ...)` over `fields` and their `values`."""
40
+ return L.fn("NAMED_STRUCT", *[x for f, v in zip(fields, values) for x in (L.text(f), v)])
41
+
42
+
43
+ PROPS_TYPE = "urn:prograph:cypher:properties" # the slot datatype of `properties(n)`: a map of the present keys
44
+
45
+
46
+ def props_slot(datatype: str = PROPS_TYPE) -> Slot:
47
+ """`properties(n)`'s slot: `datatype` PROPS_TYPE, or on PostgreSQL its `element_type` (the keys and their
48
+ types, which the answer's columns are laid out from)."""
49
+ return Slot(kinds=frozenset({VALUE}), datatypes=frozenset({datatype}), bound=Bound.NEVER,
50
+ null=Bound.MAYBE, native=datatype)
51
+
52
+
53
+ def node_slot(datatype: str = NODE_TYPE) -> Slot:
54
+ """A node value's slot: `datatype` NODE_TYPE, or its `element_type` where its properties' types are
55
+ known."""
56
+ return Slot(kinds=frozenset({VALUE}), datatypes=frozenset({datatype}), bound=Bound.NEVER,
57
+ null=Bound.MAYBE, native=datatype)
58
+
59
+
60
+ @home("cypher-result-values", "A Cypher answer's whole nodes, as one value each",
61
+ terms=("RETURN n", "whole node", "answer shape", "id labels properties", "node struct"))
62
+ def node_cell(e: E.Call, cells: Dict[str, "L.Cell"]) -> "L.Cell":
63
+ """`NODE(identity, 'k1', value1, ..., 'label:A', flagA, ...)` (the front end's) as the node's value
64
+ (see the module)."""
65
+ from prograph.plan.ir import lower as L
66
+ identity = L.expr_cell(e.args[0], cells)
67
+ properties, labels = [], []
68
+ rest = e.args[1:]
69
+ for key, part in zip(rest[0::2], rest[1::2]):
70
+ name = key.value
71
+ if name.startswith("label:"):
72
+ flag = L.expr_cell(part, cells)
73
+ labels.append(L.case(L.is_null(flag.value, negated=True), L.text(name[len("label:"):])))
74
+ else:
75
+ properties.append((name, L.expr_cell(part, cells)))
76
+ slots = L.fn("ARRAY", *labels)
77
+ listed = slots
78
+ if labels:
79
+ var = R.LitExpr(value="_lbl", sql="_lbl") # the lambda variable
80
+ listed = L.fn("LIST_FILTER", listed, var, L.is_null(var, negated=True))
81
+ node = named_struct(L, NODE_FIELDS, [L.fn("CAST_STRING", L.lexical(identity)), listed,
82
+ properties_map(properties, "node", L)])
83
+ slot = node_slot(element_type(NODE_TYPE, [(k, c.slot) for k, c in properties]))
84
+ cell = L.Cell(slot, L.case(L.is_null(identity.value), L.NULL, node))
85
+ shape = element_shape(slot, L)
86
+ if shape is None:
87
+ return cell
88
+ values = _property_values(shape, dict(properties), L)
89
+ if not labels: # no label to ask of: `listed` and `slots` typed as text arrays, `slots` one null wide
90
+ from prograph.plan.ir.cypher_lists import typed_empty, typed_null
91
+ listed, slots = typed_empty(xsd.STRING, L), L.fn("ARRAY", typed_null(xsd.STRING, L))
92
+ return replace(cell, parts=(_id_part(identity, L), listed, slots) + values)
93
+
94
+
95
+ REL_TYPE = "urn:prograph:cypher:relationship" # the slot datatype of a relationship value
96
+
97
+
98
+ def rel_slot(datatype: str = REL_TYPE) -> Slot:
99
+ return Slot(kinds=frozenset({VALUE}), datatypes=frozenset({datatype}), bound=Bound.NEVER,
100
+ null=Bound.MAYBE, native=datatype)
101
+
102
+
103
+ def rel_cell(e: E.Call, cells: Dict[str, "L.Cell"]) -> "L.Cell":
104
+ """`REL(identity, type, start, end, 'k1', value1, ...)` (the front end's) as the relationship's value:
105
+ {id, type, start, end, properties}, `start` and `end` its end nodes' ids in its own direction, `id`
106
+ its identity's text (`lpg_view.relationship_identity`); a null identity a null relationship. Part of
107
+ rule cypher-result-values."""
108
+ from prograph.plan.ir import lower as L
109
+ identity, rtype, start, end = (L.expr_cell(a, cells) for a in e.args[:4])
110
+ rest = e.args[4:]
111
+ properties = [(key.value, L.expr_cell(part, cells)) for key, part in zip(rest[0::2], rest[1::2])]
112
+ rel = named_struct(L, REL_FIELDS, [L.fn("CAST_STRING", L.lexical(identity)), L.fn("CAST_STRING", rtype.value),
113
+ L.fn("CAST_STRING", L.lexical(start)), L.fn("CAST_STRING", L.lexical(end)),
114
+ properties_map(properties, "relationship", L)])
115
+ slot = rel_slot(element_type(REL_TYPE, [(k, c.slot) for k, c in properties]))
116
+ cell = L.Cell(slot, L.case(L.is_null(identity.value), L.NULL, rel))
117
+ shape = element_shape(slot, L)
118
+ if shape is None:
119
+ return cell
120
+ values = _property_values(shape, dict(properties), L)
121
+ return replace(cell, parts=(_id_part(identity, L), L.fn("CAST_STRING", rtype.value),
122
+ L.fn("CAST_STRING", L.lexical(start)), L.fn("CAST_STRING", L.lexical(end))) + values)
123
+
124
+
125
+ def properties_map(named, what: str, L) -> "R.Expr":
126
+ """The properties of a node or relationship (`named`: (key, cell) per key the pattern reads) as one
127
+ map of the keys it has: a key whose value is null in a row is not in that row's map. DuckDB's MAP,
128
+ Spark's and Databricks' `map_from_arrays`, over the keys and values left after dropping the nulls;
129
+ PostgreSQL's jsonb object with its nulls stripped. Where the values are of one type the map's values
130
+ are that type; of several, each value is a tagged struct (`cypher_mixed.wrap_value`), which the
131
+ answer's conversion makes Arrow's dense union (`unwrap_table`). No key the pattern reads: the empty map."""
132
+ from prograph.plan.ir.cypher_mixed import wrap_value
133
+ from prograph.plan.ir.lower import DIALECT, TAGGED_PROPERTIES
134
+ _keys([k for k, _ in named], what)
135
+ present = sorted(((k, c) for k, c in named if c.slot.present is not Bound.NEVER), key=lambda kv: kv[0])
136
+ for k, c in present:
137
+ _property(k, c, what)
138
+ if not present:
139
+ return L.fn("NAMED_STRUCT")
140
+ values = [(k, _answered(c, L), c) for k, c in present]
141
+ if DIALECT.get() in ("postgresql", "postgres"):
142
+ pairs = []
143
+ for k, v, _ in values:
144
+ pairs += [L.text(k), v]
145
+ return L.fn("CYPHER_STRIP_NULLS", L.fn("NAMED_STRUCT", *pairs))
146
+ if map_form([(k, c.slot) for k, c in present], what).startswith("t"):
147
+ from prograph.plan.ir.cypher_lists import list_type, value_type
148
+ from prograph.plan.ir.cypher_temporal import TEMPORAL
149
+ like = next((v for k, v, c in values if c.slot.kinds == {VALUE} and c.slot.datatype == xsd.DECIMAL), None)
150
+ list_like = next((v for k, v, c in values if c.slot.kinds == {LIST}), None)
151
+ values = [(k, v if c.slot.kinds == {MIXED} else
152
+ wrap_value(v, (list_type(xsd.STRING) if c.slot.datatype in TEMPORAL else value_type(c.slot))
153
+ if c.slot.kinds == {LIST} else
154
+ xsd.STRING if c.slot.datatype in TEMPORAL else c.slot.datatype, L,
155
+ decimal_like=like, list_like=list_like),
156
+ None) for k, v, c in values]
157
+ TAGGED_PROPERTIES.set(True)
158
+ names = [L.case(L.is_null(v, negated=True), L.text(k)) for k, v, _ in values]
159
+ var = R.LitExpr(value="_p", sql="_p") # the lambda variable
160
+ keep = L.is_null(var, negated=True)
161
+ return L.fn("CYPHER_MAP", L.fn("LIST_FILTER", L.fn("ARRAY", *names), var, keep),
162
+ L.fn("LIST_FILTER", L.fn("ARRAY", *(v for _, v, _ in values)), var, keep))
163
+
164
+
165
+ def _answered(cell: "L.Cell", L) -> "R.Expr":
166
+ """A property's value as the answer gives it: a temporal one (a source DATE column's among them) as
167
+ its ISO 8601 text, as a column of it answers (rule cypher-temporal); any other as it is."""
168
+ from prograph.plan.ir.cypher_temporal import TEMPORAL, text
169
+ if cell.slot.kinds == {VALUE} and len(cell.slot.datatypes) == 1 and cell.slot.datatype in TEMPORAL:
170
+ return text(cell.slot.datatype, cell.value, L)
171
+ from prograph.plan.ir.cypher_temporal import innermost, list_text
172
+ if cell.slot.kinds == {LIST} and len(cell.slot.datatypes) == 1 and innermost(cell.slot.datatype) in TEMPORAL:
173
+ return list_text(cell.slot.datatype, cell.value, L) # a list of temporals: a list of their texts
174
+ return cell.value
175
+
176
+
177
+ def _property(name: str, cell: "L.Cell", what: str) -> None:
178
+ """A property a whole node or relationship lists: of one plain type over every map (a union of an
179
+ integer and a text column is text on the engines)."""
180
+ s = cell.slot
181
+ if s.present is Bound.NEVER:
182
+ return
183
+ from prograph.plan.ir.cypher_lists import value_type
184
+ if s.kinds == {LIST} and value_type(s) is not None:
185
+ return # a list column of one element type
186
+ if s.kinds == {MIXED}:
187
+ return # a property its maps give in several plain types (`cypher_front.scan`): the tagged struct
188
+ if s.kinds != {VALUE} or len(s.datatypes) != 1:
189
+ raise NotBuilt(f"a whole {what} whose property {name} is of several types over its maps")
190
+
191
+
192
+ def _keys(keys, what: str) -> None:
193
+ lowered = [k.lower() for k in keys]
194
+ if len(set(lowered)) != len(lowered):
195
+ # Struct field names are case-insensitive on DuckDB and Spark.
196
+ raise NotBuilt(f"a whole {what} with property keys that differ only in case")
197
+
198
+
199
+
200
+ PATH_TYPE = "urn:prograph:cypher:path" # the slot datatype of a path value
201
+
202
+
203
+ def path_slot(datatype: str = PATH_TYPE) -> Slot:
204
+ return Slot(kinds=frozenset({VALUE}), datatypes=frozenset({datatype}), bound=Bound.NEVER,
205
+ null=Bound.MAYBE, native=datatype)
206
+
207
+
208
+ def path_type(nodes: Slot, rels: Slot) -> str:
209
+ """A path value's slot datatype from its lists' slots: `PATH_TYPE|<n>:<node type><relationship type>`,
210
+ its nodes' and relationships' element types (`element_type`; empty where a list has none), so
211
+ `nodes(p)` of a path held as a value is a list of them."""
212
+ n = nodes.datatype if nodes.datatypes else ""
213
+ r = rels.datatype if rels.datatypes else ""
214
+ return f"{PATH_TYPE}|{len(n)}:{n}{r}"
215
+
216
+
217
+ def path_parts(datatype: Optional[str]):
218
+ """(node type, relationship type) of a `path_type` (None where a list has no element type); None for
219
+ any other datatype, or a bare PATH_TYPE."""
220
+ if datatype is None or not datatype.startswith(PATH_TYPE + "|"):
221
+ return None
222
+ body = datatype[len(PATH_TYPE) + 1:]
223
+ colon = body.index(":")
224
+ n = int(body[:colon])
225
+ nodes, rels = body[colon + 1:colon + 1 + n], body[colon + 1 + n:]
226
+ return nodes or None, rels or None
227
+
228
+
229
+ def joined_paths(a: str, b: str) -> Optional[str]:
230
+ """Two path types as one list's: their node and relationship types joined (`joined_elements`)."""
231
+ pa, pb = path_parts(a), path_parts(b)
232
+ if pa is None or pb is None:
233
+ return None
234
+ out = []
235
+ for x, y in zip(pa, pb):
236
+ if x is None or y is None:
237
+ out.append(x or y)
238
+ continue
239
+ j = joined_elements(x, y)
240
+ if j is None:
241
+ return None
242
+ out.append(j)
243
+ n, r = out[0] or "", out[1] or ""
244
+ return f"{PATH_TYPE}|{len(n)}:{n}{r}"
245
+
246
+
247
+ def path_part_slot(e: E.Call, slots) -> Slot:
248
+ """`nodes(p)`, `relationships(p)` of a path held as a value (`PATH_PART(p, 'nodes')`): the list of
249
+ its elements, null for a null path."""
250
+ from prograph.plan.ir.facts import expr_slot
251
+ from prograph.plan.ir.slot import NOTHING, list_slot
252
+ base = expr_slot(e.args[0], slots)
253
+ if base.present is Bound.NEVER:
254
+ return NOTHING
255
+ parts = path_parts(base.datatype) if base.kinds == {VALUE} else None
256
+ if parts is None:
257
+ raise NotBuilt("nodes(), relationships() or length() of a value that is not a path")
258
+ return list_slot(parts[0 if e.args[1].value == "nodes" else 1], Bound.MAYBE)
259
+
260
+
261
+ def path_part_cell(e: E.Call, cells) -> "L.Cell":
262
+ from prograph.plan.ir import lower as L
263
+ slot = path_part_slot(e, {n: c.slot for n, c in cells.items()})
264
+ if slot.present is Bound.NEVER:
265
+ return L.nothing()
266
+ if L.DIALECT.get() in ("postgresql", "postgres"):
267
+ raise NotBuilt("nodes() or relationships() of a path held as a value, on PostgreSQL")
268
+ path = L.expr_cell(e.args[0], cells)
269
+ return L.Cell(slot, L.fn("CYPHER_FIELD_VALUE", path.value, L.text(e.args[1].value)))
270
+
271
+
272
+ def path_cell(e: E.Call, cells: Dict[str, "L.Cell"]) -> "L.Cell":
273
+ """`PATH(LIST(nodes), LIST(relationships))` (the front end's) as the path's value: {nodes,
274
+ relationships}, each the list of its elements' values in the path's order; a path with a null element
275
+ is null. Part of rule cypher-result-values."""
276
+ from prograph.plan.ir import lower as L
277
+ nodes, rels = (L.expr_cell(a, cells) for a in e.args)
278
+ value = named_struct(L, PATH_FIELDS, [nodes.value, rels.value])
279
+ # A path with a null element (an OPTIONAL MATCH that found none) is null: each node's or
280
+ # relationship's identity, through the lists and their concatenations; a variable-length segment's
281
+ # columns (`#seg_nodes`, `#seg_rels`) are null where its OPTIONAL MATCH found no trail.
282
+ def elements(x):
283
+ if isinstance(x, E.Call) and x.name in ("NODE", "REL"):
284
+ return [x.args[0]]
285
+ if isinstance(x, E.Col) and x.name.endswith(("#seg_nodes", "#seg_rels")):
286
+ return [x]
287
+ if isinstance(x, E.Call) and x.name in ("LIST", "+"):
288
+ return [y for a in x.args for y in elements(a)]
289
+ return []
290
+ found = elements(e.args[0]) + elements(e.args[1])
291
+ null = L.any_of([L.is_null(L.expr_cell(x, cells).value) for x in found])
292
+ slot = path_slot(path_type(nodes.slot, rels.slot))
293
+ cell = L.Cell(slot, L.case(null, L.NULL, value))
294
+ shape = element_shape(slot, L)
295
+ if shape is None:
296
+ return cell
297
+ empty = shape.inner[1].kind == "empty"
298
+ if not (nodes.parts and (rels.parts or empty)):
299
+ return cell # a list of this path holds no parts: refused where answered
300
+ parts = nodes.parts + ((L.integer(1),) if empty else rels.parts)
301
+ return replace(cell, parts=tuple(L.case(null, L.NULL, x) for x in parts)) # a path with a null element is null
302
+
303
+
304
+ # -- a node or relationship held as a value (in a list, carried through WITH) ------------------------
305
+ #
306
+ # A node's or relationship's value is the struct above; where it sits in a list (`nodes(p)`, `[a, b]`) its
307
+ # properties are read back from that struct, so its slot's datatype records how they are held: the type
308
+ # of the properties map's values (`_held`: one plain type, a list type, the tagged struct of several, or
309
+ # none) and each present key's type. Two elements whose maps hold values of one SQL type are one element
310
+ # type (their keys together, a key of the same type in both); others are refused as a list of several
311
+ # types, never coerced by the engine.
312
+
313
+ def element_type(base: str, named) -> str:
314
+ """The slot datatype of a node (`base` NODE_TYPE) or relationship (REL_TYPE) whose properties are
315
+ `named` ((key, slot) per key read): `base|held|keys`, or `base` alone where a property's type is not
316
+ one (the value is still answered whole where `properties_map` builds it; a key is not read back). A
317
+ property its maps give in several plain types is recorded as its mixed type (`cypher_mixed.mixed_type`)."""
318
+ from prograph.plan.ir.cypher_lists import value_type
319
+ from prograph.plan.ir.cypher_mixed import mixed_type, slot_tags
320
+ present = sorted(((k, s) for k, s in named if s.present is not Bound.NEVER), key=lambda kv: kv[0])
321
+ fields = {}
322
+ for k, s in present:
323
+ if s.kinds == {MIXED}:
324
+ fields[k] = mixed_type(slot_tags(s))
325
+ continue
326
+ t = value_type(s)
327
+ if t is None or (s.kinds != {LIST} and (s.kinds != {VALUE} or len(s.datatypes) != 1)):
328
+ return base
329
+ fields[k] = decimal_type(t, s.digits)
330
+ held = _held(present)
331
+ if held is None:
332
+ return base
333
+ return f"{base}|{held}|" + "".join(f"{len(k)}:{k}{len(t)}:{t}" for k, t in sorted(fields.items()))
334
+
335
+
336
+ def map_form(present, what: str) -> str:
337
+ """How a whole node's or relationship's properties map holds its values, from the slots of its present
338
+ keys ((key, slot), in key order): `0` no key (an empty struct), `v<type>` every value of one type (a
339
+ temporal one as its text, a list type), `t` each value a tagged struct (`cypher_mixed.wrap_value`: values
340
+ of several plain types, or a property its maps give in several), `td` the same with the decimal field.
341
+ NotBuilt where it refuses (a list beside values of other types, a type with no tagged member, a decimal
342
+ beside a property of several types). The one rule `properties_map` builds by and `_held` records."""
343
+ from prograph.plan.ir.cypher_lists import list_type
344
+ from prograph.plan.ir.cypher_mixed import family
345
+ from prograph.plan.ir.cypher_temporal import TEMPORAL
346
+ if not present:
347
+ return "0"
348
+ kinds = set()
349
+ mixed = False
350
+ for _, s in present:
351
+ if s.kinds == {MIXED}:
352
+ mixed = True # a property its maps give in several types: always the tagged form
353
+ elif s.kinds == {LIST}: # a list of temporals as a list of their texts (`_answered`)
354
+ kinds.add(list_type((xsd.STRING if s.datatype in TEMPORAL else s.datatype) if s.datatypes else None))
355
+ else:
356
+ kinds.add(xsd.STRING if s.datatype in TEMPORAL else s.datatype)
357
+ if len(kinds) == 1 and not mixed:
358
+ return "v" + next(iter(kinds))
359
+ decimal = any(s.kinds == {VALUE} and s.datatype == xsd.DECIMAL for _, s in present)
360
+ lists = {(xsd.STRING if s.datatype in TEMPORAL else s.datatype) if s.datatypes else None
361
+ for _, s in present if s.kinds == {LIST}}
362
+ if len(lists) > 1:
363
+ raise NotBuilt(f"a whole {what} with lists of two element types among its properties")
364
+ if lists:
365
+ from prograph.plan.ir.cypher_mixed import family as _family
366
+ element = next(iter(lists))
367
+ if element is None or _family(element) is None:
368
+ raise NotBuilt(f"a whole {what} with a list property of lists, maps or no element type beside "
369
+ "properties of other types")
370
+ if mixed:
371
+ raise NotBuilt(f"a whole {what} with a list property beside a property of several types")
372
+ for k, s in present:
373
+ if s.kinds == {LIST}:
374
+ continue
375
+ if s.kinds == {MIXED}:
376
+ if decimal:
377
+ raise NotBuilt(f"a whole {what} with a decimal property beside one of several types")
378
+ continue
379
+ d = xsd.STRING if s.datatype in TEMPORAL else s.datatype
380
+ if family(d) is None and d != xsd.DECIMAL:
381
+ raise NotBuilt(f"a whole {what} whose property {k} is a {d} beside properties of other types")
382
+ return ("td" if decimal else "t") + ("l" + list_type(next(iter(lists))) if lists else "")
383
+
384
+
385
+ def _held(present) -> Optional[str]:
386
+ """How `properties_map` holds the map's values (`map_form`); None where it refuses."""
387
+ try:
388
+ return map_form(present, "node")
389
+ except NotBuilt:
390
+ return None
391
+
392
+
393
+ def element_base(datatype: Optional[str]) -> Optional[str]:
394
+ """NODE_TYPE or REL_TYPE where `datatype` is a node's or relationship's value type, else None."""
395
+ if datatype is None:
396
+ return None
397
+ for base in (NODE_TYPE, REL_TYPE):
398
+ if datatype == base or datatype.startswith(base + "|"):
399
+ return base
400
+ return None
401
+
402
+
403
+ def _shape(datatype: str):
404
+ """(held, {key: type}) of an `element_type`; None for a bare NODE_TYPE or REL_TYPE."""
405
+ parts = datatype.split("|", 2)
406
+ if len(parts) < 3:
407
+ return None
408
+ held, body, fields, i = parts[1], parts[2], {}, 0
409
+ while i < len(body):
410
+ colon = body.index(":", i)
411
+ n = int(body[i:colon])
412
+ key = body[colon + 1:colon + 1 + n]
413
+ i = colon + 1 + n
414
+ colon = body.index(":", i)
415
+ n = int(body[i:colon])
416
+ fields[key] = body[colon + 1:colon + 1 + n]
417
+ i = colon + 1 + n
418
+ return held, fields
419
+
420
+
421
+ def joined_elements(a: str, b: str) -> Optional[str]:
422
+ """Two element types as one list's (`cypher_lists.joined`): one where both maps hold values of one SQL
423
+ type and a key both have is of one type, their keys together; a bare type where either is bare (its
424
+ keys are not read back); None otherwise (a node beside a relationship among them)."""
425
+ base = element_base(a)
426
+ if base is None or element_base(b) != base:
427
+ return None
428
+ if a == b:
429
+ return a
430
+ sa, sb = _shape(a), _shape(b)
431
+ if sa is None or sb is None:
432
+ return base
433
+ (ha, fa), (hb, fb) = sa, sb
434
+ if ha != hb:
435
+ return None
436
+ fields = {**fa, **fb}
437
+ for k in fa.keys() & fb.keys():
438
+ if fa[k] == fb[k]:
439
+ continue
440
+ (ta, da), (tb, db) = split_decimal(fa[k]), split_decimal(fb[k])
441
+ if ta != tb or ta != xsd.DECIMAL:
442
+ return None
443
+ fields[k] = decimal_type(ta, common_digits(da, db)) # decimals of two precisions: the one they fit
444
+ return f"{base}|{ha}|" + "".join(f"{len(k)}:{k}{len(t)}:{t}" for k, t in sorted(fields.items()))
445
+
446
+
447
+ def holds_elements(slot: Slot) -> bool:
448
+ """Whether a slot's values are nodes or relationships held as values, or lists of them."""
449
+ return slot.kinds <= {VALUE, LIST} and any(element_base(d) is not None for d in slot.datatypes)
450
+
451
+
452
+ def element_slot(datatype: str, null: Bound) -> Slot:
453
+ """The slot of a node or relationship value of this element type (a list's element)."""
454
+ slot = node_slot(datatype) if element_base(datatype) == NODE_TYPE else rel_slot(datatype)
455
+ from dataclasses import replace
456
+ return replace(slot, null=null)
457
+
458
+
459
+ def property_slot(datatype: str, key: str) -> Slot:
460
+ """`x.k` of a node or relationship value held as a value (a list's element): its property k typed as
461
+ its maps hold it, null where it has none."""
462
+ from prograph.plan.ir.cypher_lists import typed_slot
463
+ from prograph.plan.ir.cypher_temporal import TEMPORAL
464
+ from prograph.plan.ir.slot import NOTHING
465
+ shape = _shape(datatype)
466
+ what = "node" if element_base(datatype) == NODE_TYPE else "relationship"
467
+ if shape is None:
468
+ raise NotBuilt(f"a property of a {what} held as a value whose properties are of several types")
469
+ t = shape[1].get(key)
470
+ if t is None:
471
+ return NOTHING
472
+ t = split_decimal(t)[0]
473
+ if t in TEMPORAL or t == xsd.DECIMAL:
474
+ raise NotBuilt(f"a {'temporal' if t in TEMPORAL else 'decimal'} property of a {what} held as a value "
475
+ "(a list's element)")
476
+ return typed_slot(t, Bound.MAYBE)
477
+
478
+
479
+ def property_cell(element: "L.Cell", key: str) -> "L.Cell":
480
+ """`x.k` of a node or relationship value (rule cypher-result-values): the value its `properties` map
481
+ holds under k, read as its type (the tagged struct's member for it, where the map holds several
482
+ types); null where the map lacks k or the element is null. On PostgreSQL the jsonb object's key, cast."""
483
+ from prograph.plan.ir import lower as L
484
+ from prograph.plan.ir.cypher_lists import nested
485
+ from prograph.plan.ir.cypher_mixed import BOOL, FLOAT, INT, LIST_FIELD, STR, family
486
+ datatype = element.slot.datatype
487
+ slot = property_slot(datatype, key)
488
+ if slot.present is Bound.NEVER:
489
+ return L.nothing()
490
+ held, fields = _shape(datatype)
491
+ t = fields[key]
492
+ kind = "long" if family(t) == "i" else "double" if family(t) == "f" else "string" if family(t) == "s" \
493
+ else "boolean" if family(t) == "b" else None
494
+ from prograph.plan.ir.cypher_mixed import is_mixed
495
+ if is_mixed(t): # a property of several types over its maps: the map's tagged struct (jsonb on PostgreSQL)
496
+ if L.DIALECT.get() in ("postgresql", "postgres"):
497
+ props = L.fn("CYPHER_JSON_GET", element.value, L.text("properties"))
498
+ return L.Cell(slot, L.fn("CYPHER_JSON_GET", props, L.text(key)))
499
+ return L.Cell(slot, L.fn("CYPHER_MAP_VALUE", L.fn("CYPHER_FIELD_VALUE", element.value, L.text("properties")),
500
+ L.text(key)))
501
+ if L.DIALECT.get() in ("postgresql", "postgres"):
502
+ if kind is None:
503
+ raise NotBuilt("a list or map property of a node or relationship held as a value, on PostgreSQL")
504
+ props = L.fn("CYPHER_JSON_GET", element.value, L.text("properties"))
505
+ return L.Cell(slot, L.fn(f"CYPHER_FIELD_{kind.upper()}", props, L.text(key)))
506
+ value = L.fn("CYPHER_MAP_VALUE", L.fn("CYPHER_FIELD_VALUE", element.value, L.text("properties")), L.text(key))
507
+ if held.startswith("t") and nested(t):
508
+ value = L.fn("CYPHER_FIELD_VALUE", value, L.text(LIST_FIELD))
509
+ elif held.startswith("t"):
510
+ member = {"long": INT, "double": FLOAT, "string": STR, "boolean": BOOL}[kind]
511
+ value = L.fn(f"CYPHER_FIELD_{kind.upper()}", value, L.text(member))
512
+ elif kind is None and not nested(t):
513
+ raise NotBuilt(f"a {t} property of a node or relationship held as a value")
514
+ return L.Cell(slot, value)
515
+
516
+
517
+ def held_kind(slot: Slot) -> Optional[str]:
518
+ """NODE_TYPE, REL_TYPE or PATH_TYPE where `slot` is one value of that kind, else None."""
519
+ if slot.kinds != {VALUE} or len(slot.datatypes) != 1:
520
+ return None
521
+ t = slot.datatype
522
+ if t == PATH_TYPE or t.startswith(PATH_TYPE + "|"):
523
+ return PATH_TYPE
524
+ return element_base(t)
525
+
526
+
527
+ def identity_text(cell: "L.Cell", L) -> Optional["R.Expr"]:
528
+ """A node's or relationship's identity as text, whether a pattern's variable (its identity term, an IRI or
529
+ blank node: `CAST_STRING` of its lexical form) or held as a value (its `id` field, `node_cell` and `rel_cell`
530
+ write the same text); None for any other value. The one form both sides of an element's equality and a
531
+ node value's match against a pattern node (`cypher_values.element_id`) read."""
532
+ from prograph.schema.source_map import BLANK, IRI
533
+ kind = held_kind(cell.slot)
534
+ if kind in (NODE_TYPE, REL_TYPE):
535
+ return L.fn("CYPHER_FIELD_STRING", cell.value, L.text("id"))
536
+ if cell.slot.kinds and cell.slot.kinds <= {IRI, BLANK}:
537
+ return L.fn("CAST_STRING", L.lexical(cell))
538
+ return None
539
+
540
+
541
+ def held_equality(op: str, a: "L.Cell", b: "L.Cell") -> "R.Expr":
542
+ """`a = b`, `a <> b` of two nodes, relationships or paths, at least one held as a value (openCypher 9
543
+ equality; TCK Comparison1 [14]): a node or relationship equals another by identity (`identity_text`), a
544
+ pattern's variable against a value too (`l[0] = x`); a path another path of the same nodes and
545
+ relationships in the same order, by their ids, whatever direction each relationship was traversed in.
546
+ A node and a relationship differ (a relationship's identity is never a node's). Values of two kinds are
547
+ unequal; null where either is null; `<` and the like null (not ordered). Part of rule cypher-equality; a
548
+ path's ids are read on DuckDB, Spark and Databricks (PostgreSQL's jsonb path is refused)."""
549
+ from prograph.plan.ir import lower as L
550
+ ka = held_kind(a.slot) or ("element" if identity_text(a, L) is not None else None)
551
+ kb = held_kind(b.slot) or ("element" if identity_text(b, L) is not None else None)
552
+ ta, tb = identity_text(a, L), identity_text(b, L)
553
+ null = L.any_of([L.is_null(ta if ta is not None else a.value), L.is_null(tb if tb is not None else b.value)])
554
+ if op not in ("=", "!="):
555
+ return L.NULL_BOOLEAN
556
+ elements = {NODE_TYPE, REL_TYPE, "element"}
557
+ if ka != kb and not (ka in elements and kb in elements and "element" in (ka, kb)):
558
+ return L.case(null, L.NULL_BOOLEAN, L.FALSE if op == "=" else L.TRUE)
559
+ if ka == PATH_TYPE:
560
+ if L.DIALECT.get() in ("postgresql", "postgres"):
561
+ raise NotBuilt("equality of paths held as values, on PostgreSQL")
562
+
563
+ def ids(path, part):
564
+ var = R.LitExpr(value="_pe", sql="_pe")
565
+ return L.fn("LIST_TRANSFORM", L.fn("CYPHER_FIELD_VALUE", path, L.text(part)), var,
566
+ L.fn("CYPHER_FIELD_STRING", var, L.text("id")))
567
+ same = L.all_of([R.CompareExpr(left=ids(a.value, p), op="=", right=ids(b.value, p))
568
+ for p in ("nodes", "relationships")])
569
+ else:
570
+ same = R.CompareExpr(left=ta, op="=", right=tb)
571
+ return L.case(null, L.NULL_BOOLEAN, same if op == "=" else R.NotExpr(child=same))
572
+
573
+
574
+ # -- an element's parts as flat columns, for PostgreSQL's answer ------------------------------------------
575
+ #
576
+ # A statement on PostgreSQL does not build an element's struct (its jsonb would lose the types: a float 1.0
577
+ # reads back as 1, a NaN as text, a NUMERIC 1.50 as 1.5). It writes the struct's parts as flat typed
578
+ # columns, `<column>__e<i>`, and the reader makes the Arrow struct DuckDB gives of them, column-wise
579
+ # (`postgresql_graph.Numerics`). A `Shape` is that layout, worked out from a slot (the slot's datatype
580
+ # records each element's property keys and types, `element_type`), so the statement's writer and the
581
+ # reader share one definition. The jsonb value stays the cell's `value` for the plan's own reads of an
582
+ # element held as a value (`x.name`, equality); the parts are what the answer reads.
583
+ #
584
+ # a node id text, labels text[], slots text[] (each candidate label or null: what an aggregate
585
+ # flattens), then one column per property key, in its SQL type (a decimal's as text, made
586
+ # a decimal by the reader);
587
+ # a relationship id, type, start, end, then the properties;
588
+ # a list of either parallel arrays, one per part (`ids` text[], every element's labels in order as one
589
+ # flat text[] with an int[] of label counts, each property's values as an array of its
590
+ # type, null where the element lacks it), all from ONE aggregation with ONE ORDER, so
591
+ # element i is element i in every array;
592
+ # a path its node list's parts, then its relationship list's;
593
+ # a map literal one column per field.
594
+ # A property that is null is a key the element lacks: the reader's map holds the keys of non-null values.
595
+
596
+ PG_DIALECTS = ("postgresql", "postgres")
597
+
598
+
599
+ class PartsRefused(NotBuilt):
600
+ """A whole element, path, map or list of them that PostgreSQL's parts do not lay out (named). A statement that
601
+ does not answer one is lowered without parts (`entry`), as it always was; one that does is refused with this."""
602
+
603
+
604
+ def answers_elements(slot: Slot) -> bool:
605
+ """Whether an answer column of this slot holds a node, relationship, path or map, or a list of them: what the
606
+ reader must make a struct of, so parts it cannot write are refused rather than answered as jsonb."""
607
+ if slot.present is Bound.NEVER:
608
+ return False
609
+ try:
610
+ if slot_shape(slot) is not None:
611
+ return True
612
+ except PartsRefused:
613
+ return True
614
+ return slot.kinds == {MAP} or held_kind(slot) is not None or (
615
+ slot.kinds == {LIST} and any(element_base(d) is not None or d.startswith(PATH_TYPE) for d in slot.datatypes))
616
+
617
+
618
+ @dataclass(frozen=True)
619
+ class Part:
620
+ """One flat column of an element's layout: its role (`id`, `labels`, `slots`, `type`, `start`, `end`,
621
+ `ids`, `counts`, `types`, `starts`, `ends`, `prop`, `field`), and for a property or a field its key and
622
+ datatype."""
623
+ role: str
624
+ key: Any = None
625
+ datatype: Optional[str] = None
626
+ depth: int = 0 # the lists a map's column sits inside: 0 a value per row, more an array per row of every instance
627
+
628
+
629
+ @dataclass(frozen=True)
630
+ class Shape:
631
+ """The layout of a node, relationship, path, property map or map literal (`kind`: node, rel, path,
632
+ props, map; `mixed` a value of several types, its one tagged text column, `cypher_mixed.answer_text`), one value or, `many`, a list of them as parallel arrays. `held` is how a node's properties
633
+ map holds its values (`map_form`), `fields` its property keys, sorted, with their types, `inner` a
634
+ path's node and relationship lists."""
635
+ kind: str
636
+ many: bool = False
637
+ held: str = ""
638
+ fields: Tuple[Tuple[str, str], ...] = ()
639
+ inner: Tuple["Shape", ...] = ()
640
+
641
+ def parts(self, carried: bool = True) -> Tuple[Part, ...]:
642
+ """The columns, in order. `carried`: those a plan's CTE carries (a node's `slots` too); the answer
643
+ reads the rest."""
644
+ if self.kind == "path":
645
+ nodes, rels = (s.parts(carried) for s in self.inner)
646
+ if self.many: # a list of paths: each path's node and relationship counts, then the elements of all
647
+ return (Part("pcounts"),) + nodes + (Part("rcounts"),) + rels
648
+ return nodes + rels
649
+ if self.kind == "map":
650
+ level = 1 if self.many else 0 # a list of maps: every column an array
651
+ return (Part("marker", None, None, level),) + map_columns(self.fields, level)
652
+ if self.kind in ("empty", "mixed"):
653
+ return (Part("marker" if self.kind == "empty" else "mixed"),)
654
+ head = {("node", False): ("id", "labels") + (("slots",) if carried else ()),
655
+ ("node", True): ("ids", "labels", "counts"),
656
+ ("rel", False): ("id", "type", "start", "end"),
657
+ ("rel", True): ("ids", "types", "starts", "ends"),
658
+ ("props", False): ("id",), ("props", True): ("ids",)}[(self.kind, self.many)]
659
+ role = "prop"
660
+ return tuple(Part(r) for r in head) + tuple(Part(role, k, t) for k, t in self.fields)
661
+
662
+ def flat(self) -> "Shape":
663
+ """The shape of one element of a list's shape."""
664
+ return Shape(self.kind, False, self.held, self.fields, self.inner)
665
+
666
+ def listed(self) -> "Shape":
667
+ return Shape(self.kind, True, self.held, self.fields, self.inner)
668
+
669
+
670
+ @dataclass(frozen=True)
671
+ class ElementColumns:
672
+ """What `lower.ANSWER_DIGITS` holds at an answer column written as an element's parts: the shape, and
673
+ the DECIMAL(p, s) of each part the answer reads (None where it is no decimal)."""
674
+ shape: Shape
675
+ digits: Tuple[Optional[Tuple[int, int]], ...]
676
+
677
+
678
+ DECIMAL_DIGITS = "(" # a decimal property's type, then its digits: `xsd:decimal(5,2)`
679
+
680
+
681
+ def decimal_type(datatype: str, digits: Optional[Tuple[int, int]]) -> str:
682
+ """A property's type as an element's datatype records it: a decimal's with its SQL digits, where known."""
683
+ if datatype == xsd.DECIMAL and digits is not None:
684
+ return f"{datatype}{DECIMAL_DIGITS}{digits[0]},{digits[1]})"
685
+ return datatype
686
+
687
+
688
+ def split_decimal(datatype: str) -> Tuple[str, Optional[Tuple[int, int]]]:
689
+ """(the type, its decimal digits or None) of a property type `decimal_type` wrote."""
690
+ if not datatype.startswith(xsd.DECIMAL + DECIMAL_DIGITS):
691
+ return datatype, None
692
+ base, mark, digits = datatype.partition(DECIMAL_DIGITS)
693
+ p, s = digits.rstrip(")").split(",")
694
+ return base, (int(p), int(s))
695
+
696
+
697
+ def common_digits(a: Optional[Tuple[int, int]], b: Optional[Tuple[int, int]]) -> Optional[Tuple[int, int]]:
698
+ """The DECIMAL a column of both is held as (the engines': the larger whole part and the larger scale,
699
+ at most 38 digits); None where either is not known."""
700
+ if a is None or b is None:
701
+ return None
702
+ scale = max(a[1], b[1])
703
+ return min(max(a[0] - a[1], b[0] - b[1]) + scale, 38), scale
704
+
705
+
706
+ def element_shape(slot: Slot, L=None) -> Optional[Shape]:
707
+ """The layout of a slot's value as parts, on PostgreSQL; None on any other engine or for a value that is
708
+ no element, path or list of them. NotBuilt (named) where it is one this layout does not hold."""
709
+ if L is None:
710
+ from prograph.plan.ir import lower as L
711
+ if L.DIALECT.get() not in PG_DIALECTS or not L.ELEMENT_PARTS.get():
712
+ return None
713
+ return slot_shape(slot)
714
+
715
+
716
+ def slot_shape(slot: Slot) -> Optional[Shape]:
717
+ if slot.present is Bound.NEVER:
718
+ return None
719
+ if slot.kinds == {VALUE} and len(slot.datatypes) == 1:
720
+ d = slot.datatype
721
+ base = element_base(d)
722
+ if base is not None:
723
+ return _element_shape(d, base, False)
724
+ if d == PROPS_TYPE or d.startswith(PROPS_TYPE + "|"):
725
+ shape = _shape(d)
726
+ if shape is None:
727
+ raise PartsRefused("properties() of a node or relationship whose properties are of several types, "
728
+ "or of no one type, on PostgreSQL")
729
+ return Shape("props", False, shape[0], tuple(sorted(shape[1].items())))
730
+ if d == PATH_TYPE or d.startswith(PATH_TYPE + "|"):
731
+ parts = path_parts(d)
732
+ if parts is None or parts[0] is None:
733
+ raise PartsRefused("a whole path whose nodes are of no one type, on PostgreSQL")
734
+ # No relationship type: the path is only its start (a zero-length one), its relationships `[]`.
735
+ rels = Shape("empty", many=True) if parts[1] is None else _element_shape(parts[1], REL_TYPE, True)
736
+ return Shape("path", inner=(_element_shape(parts[0], NODE_TYPE, True), rels))
737
+ return None
738
+ if slot.kinds == {LIST} and len(slot.datatypes) == 1 and element_base(slot.datatype) is not None:
739
+ return _element_shape(slot.datatype, element_base(slot.datatype), True)
740
+ if slot.kinds == {LIST} and len(slot.datatypes) == 1 and (
741
+ slot.datatype == PATH_TYPE or slot.datatype.startswith(PATH_TYPE + "|")):
742
+ parts = path_parts(slot.datatype)
743
+ if parts is None or None in parts:
744
+ raise PartsRefused("a list of paths whose nodes or relationships are of no one type, on PostgreSQL")
745
+ return Shape("path", True, inner=(_element_shape(parts[0], NODE_TYPE, True),
746
+ _element_shape(parts[1], REL_TYPE, True)))
747
+ from prograph.plan.ir.cypher_maps import MAP_OF
748
+ if slot.kinds == {LIST} and len(slot.datatypes) == 1 and slot.datatype.startswith(MAP_OF):
749
+ return _maps_shape(slot.datatype)
750
+ if slot.kinds == {LIST} and len(slot.datatypes) == 1 and slot.datatype.startswith(PROPS_TYPE + "|"):
751
+ return replace(slot_shape(props_slot(slot.datatype)), many=True)
752
+ if slot.kinds == {MAP}:
753
+ return _map_shape(slot)
754
+ return None
755
+
756
+
757
+ def _sound(t: Optional[str]) -> bool:
758
+ """Whether a map's field of type `t` has a layout: null, a plain scalar, a list of plain scalars or of maps whose
759
+ fields are sound, a map of sound fields. Not a decimal (its digits are not known below the top), a list of
760
+ lists, a value of several types, a temporal value."""
761
+ from prograph.plan.ir.cypher_lists import element_of, nested
762
+ from prograph.plan.ir.cypher_maps import is_map_type, type_fields
763
+ from prograph.plan.ir.cypher_mixed import family
764
+ if t is None:
765
+ return True
766
+ if is_map_type(t):
767
+ return all(_sound(f) for f in type_fields(t).values())
768
+ if nested(t):
769
+ inner = element_of(t)
770
+ return inner is None or family(inner) is not None or (is_map_type(inner) and _sound(inner))
771
+ return family(t) is not None
772
+
773
+
774
+ def _maps_shape(datatype: str) -> Optional[Shape]:
775
+ """The layout of a list of maps: every column an array (a marker array for the count). None where a field has
776
+ none (`_sound`): that list is refused as an answer."""
777
+ from prograph.plan.ir.cypher_maps import type_fields
778
+ fields = type_fields(datatype)
779
+ if not all(_sound(t) for t in fields.values()):
780
+ return None
781
+ return Shape("map", True, fields=tuple(sorted(fields.items())))
782
+
783
+
784
+ def map_columns(fields, depth: int = 0) -> Tuple[Part, ...]:
785
+ """The columns of a map's fields (`fields`: (key, type) sorted), in the order `cypher_maps.map_call_cell` writes
786
+ them: a field's own column (a null field's too), a nested map's marker then its fields', a list field its
787
+ count then its items, a list of maps' items the map's fields one level deeper (an array each). A column's
788
+ key is the path of keys to it."""
789
+ from prograph.plan.ir.cypher_lists import element_of, nested
790
+ from prograph.plan.ir.cypher_maps import is_map_type, type_fields
791
+ return _columns(fields, depth, ())
792
+
793
+
794
+ def _columns(fields, depth: int, path: tuple) -> Tuple[Part, ...]:
795
+ from prograph.plan.ir.cypher_lists import element_of, nested
796
+ from prograph.plan.ir.cypher_maps import is_map_type, type_fields
797
+ out: List[Part] = []
798
+ for k, t in fields:
799
+ at = path + (k,)
800
+ if t is None:
801
+ out.append(Part("null", at, None, depth))
802
+ elif is_map_type(t):
803
+ out.append(Part("map", at, t, depth))
804
+ out += _columns(tuple(sorted(type_fields(t).items())), depth, at)
805
+ elif nested(t):
806
+ inner = element_of(t)
807
+ out.append(Part("lcount", at, t, depth))
808
+ if inner is not None and is_map_type(inner):
809
+ out += _columns(tuple(sorted(type_fields(inner).items())), depth + 1, at)
810
+ else:
811
+ out.append(Part("litems", at, inner, depth + 1))
812
+ else:
813
+ out.append(Part("field", at, t, depth))
814
+ return tuple(out)
815
+
816
+
817
+ def _map_shape(slot: Slot) -> Optional[Shape]:
818
+ """A map literal's layout (`map_columns`). None for a map holding a value of several types, a list of lists, a
819
+ temporal value or a decimal whose digits the slot does not know (the slot's `digits` are those of the
820
+ top-level decimal fields, in key order): its jsonb stays its value, and answering it is refused
821
+ (`lower.answer`)."""
822
+ from prograph.plan.ir.cypher_maps import fields_of
823
+ fields = fields_of(slot)
824
+ digits = list(slot.digits or ())
825
+ out = []
826
+ for k, t in sorted(fields.items()):
827
+ if t == xsd.DECIMAL:
828
+ d = digits.pop(0) if digits else None
829
+ if d is None:
830
+ return None
831
+ t = decimal_type(t, d)
832
+ elif not _sound(t):
833
+ return None
834
+ out.append((k, t))
835
+ return Shape("map", fields=tuple(out))
836
+
837
+
838
+ def map_value_parts(shape: Shape, values: Dict[str, "L.Cell"], L) -> Tuple["R.Expr", ...]:
839
+ """The columns of a map literal (`shape`, `map_columns`) from its fields' cells `values` by key: a marker, a
840
+ field's value, a null field's null, a nested map's own parts, a list's count (null for a null list) and its items
841
+ (a plain list's array, a list of maps' parts below its marker). () where a nested value holds no parts."""
842
+ from prograph.plan.ir.cypher_lists import element_of, nested
843
+ from prograph.plan.ir.cypher_maps import is_map_type, type_fields
844
+ out: List["R.Expr"] = [L.integer(1)]
845
+
846
+ def count(cell, array):
847
+ return L.case(L.is_null(cell.value), L.NULL, L.fn("CYPHER_CARDINALITY", array))
848
+
849
+ for k, t in shape.fields:
850
+ cell = values[k]
851
+ if t is None:
852
+ out.append(L.fn("CAST_LONG", L.NULL))
853
+ elif is_map_type(t):
854
+ if len(cell.parts) != 1 + len(map_columns(tuple(sorted(type_fields(t).items())))):
855
+ return ()
856
+ out += cell.parts
857
+ elif nested(t):
858
+ inner = element_of(t)
859
+ if inner is not None and is_map_type(inner):
860
+ want = 1 + len(map_columns(tuple(sorted(type_fields(inner).items())), 1))
861
+ if len(cell.parts) != want:
862
+ return ()
863
+ out += [count(cell, cell.parts[0])] + list(cell.parts[1:])
864
+ else:
865
+ out += [count(cell, cell.value), cell.value]
866
+ else:
867
+ out.append(cell.value if cell.slot.present is not Bound.NEVER else L.fn("CAST_LONG", L.NULL))
868
+ return tuple(out)
869
+
870
+
871
+ def _element_shape(datatype: str, base: str, many: bool) -> Shape:
872
+ what = "node" if base == NODE_TYPE else "relationship"
873
+ shape = _shape(datatype)
874
+ if shape is None:
875
+ raise PartsRefused(f"a whole {what} whose properties are of several types, or of no one type, on PostgreSQL")
876
+ held, fields = shape
877
+ from prograph.plan.ir.cypher_lists import nested
878
+ if many and any(nested(split_decimal(t)[0]) for t in fields.values()):
879
+ raise PartsRefused(f"a {what} with a list property in a list of {what}s, on PostgreSQL")
880
+ return Shape("node" if base == NODE_TYPE else "rel", many, held, tuple(sorted(fields.items())))
881
+
882
+
883
+ def _id_part(identity: "L.Cell", L) -> "R.Expr":
884
+ """The `id` part: the identity's text, null where the element is."""
885
+ return L.case(L.is_null(identity.value), L.NULL, L.fn("CAST_STRING", L.lexical(identity)))
886
+
887
+
888
+ def _property_values(shape: Shape, props: Dict[str, "L.Cell"], L) -> Tuple["R.Expr", ...]:
889
+ """Each property's column: its answered value, a property of several types its tagged text
890
+ (`cypher_mixed.answer_text`)."""
891
+ from prograph.plan.ir.cypher_mixed import answer_text
892
+ return tuple(answer_text(props[k].value, L) if props[k].slot.kinds == {MIXED} else _answered(props[k], L)
893
+ for k, _ in shape.fields)
894
+
895
+
896
+ def answer_parts(cell: "L.Cell", shape: Shape) -> Tuple["R.Expr", ...]:
897
+ """The columns the answer reads of an element cell (`Shape.parts(carried=False)`), as `answer` writes them."""
898
+ carried = shape.parts(True)
899
+ if len(cell.parts) != len(carried):
900
+ raise PartsRefused("a whole node, relationship, path or list of them made by a step that writes no parts "
901
+ "(a union, a conditional, a list function), on PostgreSQL")
902
+ return tuple(x for p, x in zip(carried, cell.parts) if p.role != "slots")
903
+
904
+
905
+ def element_columns(shape: Shape) -> ElementColumns:
906
+ return ElementColumns(shape, tuple(split_decimal(p.datatype)[1] if p.datatype is not None else None
907
+ for p in shape.parts(False)))
908
+
909
+
910
+ def list_parts(elements: List["L.Cell"], shape: Shape, L) -> Tuple["R.Expr", ...]:
911
+ """The parts of a list literal of elements that each hold their own parts (`shape` the list's): each
912
+ part an array of the elements' values, labels in the offsets form."""
913
+ flat = shape.flat().parts(True)
914
+ at = {(p.role, p.key): i for i, p in enumerate(flat)}
915
+ out = []
916
+ for p in shape.parts(True):
917
+ one = {"ids": "id", "types": "type", "starts": "start", "ends": "end"}.get(p.role, p.role)
918
+ if p.role == "labels":
919
+ labels = [c.parts[at[("labels", None)]] for c in elements]
920
+ joined = labels[0]
921
+ for x in labels[1:]:
922
+ joined = L.fn("LIST_CONCAT", joined, x)
923
+ out.append(joined)
924
+ elif p.role == "counts":
925
+ out.append(L.fn("ARRAY", *(L.fn("CYPHER_CARDINALITY", c.parts[at[("labels", None)]]) for c in elements)))
926
+ elif split_decimal(p.datatype or "")[1] is not None:
927
+ # a decimal column's array is NUMERIC without its digits, so a recursive CTE's two terms agree
928
+ out.append(L.fn("ARRAY", *(L.fn("CYPHER_NUMERIC", c.parts[at[(one, p.key)]]) for c in elements)))
929
+ else:
930
+ out.append(L.fn("ARRAY", *(c.parts[at[(one, p.key)]] for c in elements)))
931
+ return tuple(out)
932
+
933
+
934
+ def concat_parts(sides: List[Tuple["R.Expr", ...]], L) -> Tuple["R.Expr", ...]:
935
+ """The parts of lists joined (`+`): each part of the sides joined, in order."""
936
+ out = []
937
+ for column in zip(*sides):
938
+ joined = column[0]
939
+ for x in column[1:]:
940
+ joined = L.fn("LIST_CONCAT", joined, x)
941
+ out.append(joined)
942
+ return tuple(out)
943
+
944
+
945
+ def collected_parts(arg: "L.Cell", keys: List["R.Expr"], descending: List[bool], L) -> Tuple["R.Expr", ...]:
946
+ """collect() of an element that holds its own parts: each part one aggregate, `array_agg` of it in the
947
+ ONE order (`keys`, the element's id last: what a tie falls to), the elements with no id left out. The
948
+ same keys and directions as the jsonb value's collect (`cypher_lists.collect_value`), so a list held
949
+ as a value and answered is in one order."""
950
+ from prograph.plan.ir.cypher_lists import typed_empty
951
+ shape = element_shape(arg.slot, L)
952
+ if shape is None or shape.many or not arg.parts:
953
+ raise PartsRefused("collect() of nodes or relationships held as values, on PostgreSQL")
954
+ if shape.kind == "path":
955
+ return _collected_paths(arg, shape, keys, descending, L)
956
+ flat = shape.parts(True)
957
+ at = {(p.role, p.key): i for i, p in enumerate(flat)}
958
+ from prograph.plan.sql.dialect import COLLECT_PART, COLLECT_PART_LABELS
959
+ directions = "".join("D" if d else "A" for d in descending)
960
+ ident = arg.parts[0]
961
+ out = []
962
+ for p in shape.listed().parts(True):
963
+ one = {"ids": "id", "types": "type", "starts": "start", "ends": "end"}.get(p.role, p.role)
964
+ if p.role == "labels":
965
+ out.append(L.fn(COLLECT_PART_LABELS + directions, arg.parts[at[("slots", None)]], ident, *keys))
966
+ continue
967
+ value = L.fn("CYPHER_CARDINALITY", arg.parts[at[("labels", None)]]) if p.role == "counts" \
968
+ else arg.parts[at[(one, p.key)]]
969
+ listed = L.fn(COLLECT_PART + directions, value, ident, *keys)
970
+ if p.role in ("ids", "marker"): # what says a list is there: empty, never null
971
+ listed = L.fn("COALESCE", listed, typed_empty(xsd.STRING if p.role == "ids" else xsd.INTEGER, L))
972
+ out.append(listed)
973
+ return tuple(out)
974
+
975
+
976
+ def empty_parts(shape: Shape, L) -> Tuple["R.Expr", ...]:
977
+ """The parts of an empty list (a zero-length trail's `[]`) in the layout of a list of elements: its `ids` an empty
978
+ text array (a null one would be a null list), the rest null, which a union takes the type of the other branches'."""
979
+ from prograph.plan.ir.cypher_lists import typed_empty
980
+ typed = {"ids": xsd.STRING, "pcounts": xsd.INTEGER, "marker": xsd.INTEGER} # what says a list is there
981
+ return tuple(typed_empty(typed[p.role], L) if p.role in typed else L.NULL for p in shape.parts(True))
982
+
983
+
984
+ def element_at(lst: "L.Cell", position: "R.Expr", L) -> Tuple["R.Expr", ...]:
985
+ """The parts of the element at the 1-based `position` of a list of elements that holds parts (`l[i]`, `head`,
986
+ `last`): each part's array at it, the element's labels sliced out of the flat labels by the counts; a position
987
+ outside the list gives null parts, so a null element. The layout is the list's element shape's."""
988
+ shape = element_shape(lst.slot, L)
989
+ flat = shape.flat()
990
+ many = shape.parts(True)
991
+ by = {(p.role, p.key): lst.parts[i] for i, p in enumerate(many)}
992
+ parts = []
993
+ for p in flat.parts(True):
994
+ if p.role == "labels":
995
+ parts.append(L.fn("CYPHER_LABELS_AT", by[("labels", None)], by[("counts", None)], position))
996
+ elif p.role == "slots":
997
+ from prograph.plan.ir.cypher_lists import typed_null
998
+ parts.append(L.fn("ARRAY", typed_null(xsd.STRING, L)))
999
+ else:
1000
+ many_role = {"id": "ids", "type": "types", "start": "starts", "end": "ends"}.get(p.role, p.role)
1001
+ parts.append(L.fn("CYPHER_ELEMENT_AT", by[(many_role, p.key)], position))
1002
+ return tuple(parts)
1003
+
1004
+
1005
+ def map_list_parts(elements: List["L.Cell"], shape: Shape, L) -> Tuple["R.Expr", ...]:
1006
+ """The parts of a list literal of maps (`shape` the list's): each element's column lifted one level, a
1007
+ value per row becoming an array of the elements' (null where an element lacks the column: its field is null),
1008
+ an array per row the elements' arrays joined; none where an element holds no parts."""
1009
+ shapes = [element_shape(c.slot, L) for c in elements]
1010
+ if any(h is None or not c.parts for h, c in zip(shapes, elements)):
1011
+ return ()
1012
+ own = [{(p.role, p.key): (p, c.parts[i]) for i, p in enumerate(h.parts(True))} for h, c in zip(shapes, elements)]
1013
+ out = []
1014
+ for part in shape.parts(True):
1015
+ lower = (part.role, part.key if part.role != "marker" else None)
1016
+ values, depth = [], part.depth - 1
1017
+ for table in own:
1018
+ hit = table.get(lower)
1019
+ values.append(hit[1] if hit is not None else L.NULL)
1020
+ if depth <= 0:
1021
+ out.append(L.fn("ARRAY", *values))
1022
+ else:
1023
+ joined = values[0]
1024
+ for x in values[1:]:
1025
+ joined = L.fn("LIST_CONCAT", joined, x)
1026
+ out.append(joined)
1027
+ return tuple(out)
1028
+
1029
+
1030
+
1031
+ def _collected_width() -> int:
1032
+ from prograph.plan.ir import lower
1033
+ return lower.PATH_DEPTH.get() + 1
1034
+
1035
+
1036
+ def _collected_paths(arg: "L.Cell", shape: Shape, keys: List["R.Expr"], descending: List[bool], L) -> Tuple["R.Expr", ...]:
1037
+ """collect() of paths that hold their parts: ragged arrays cannot be aggregated, so each path's arrays are
1038
+ padded to one width (the path_depth bound, labels eight to a node) and aggregated into one rectangular array,
1039
+ which the elements are read back out of in order, a pad being a null (`dialect.COLLECT_FLAT`). Each path's
1040
+ node and relationship counts say where one path ends. A path longer than the width is an error the statement
1041
+ raises, never a short path."""
1042
+ from prograph.plan.ir.cypher_lists import typed_empty
1043
+ from prograph.plan.sql.dialect import COLLECT_FLAT, COLLECT_FLAT_LABELS, COLLECT_PART
1044
+ width, label_width = _collected_width(), _collected_width() * 8
1045
+ nodes, rels = shape.inner
1046
+ cut = len(nodes.parts(True))
1047
+ node_parts, rel_parts = arg.parts[:cut], arg.parts[cut:]
1048
+ directions = "".join("D" if d else "A" for d in descending)
1049
+ ident = node_parts[0]
1050
+
1051
+ def padded(x, w=width):
1052
+ return L.fn("CYPHER_PAD", x, L.integer(w))
1053
+
1054
+ def counted(ids, labels=None):
1055
+ card = L.fn("CYPHER_CARDINALITY", ids)
1056
+ over = R.CompareExpr(left=card, op=">", right=L.integer(width))
1057
+ if labels is not None:
1058
+ over = L.any_of([over, R.CompareExpr(left=L.fn("CYPHER_CARDINALITY", labels), op=">",
1059
+ right=L.integer(label_width))])
1060
+ message = L.text(f"ProGraph: a path in a collected list longer than {width - 1} relationships (or with "
1061
+ "more labels than eight to a node); the query hint path_depth sets how long. Length: ")
1062
+ return L.fn("COALESCE", L.fn(COLLECT_PART + directions, L.case(over, L.fn("CAST_LONG", L.fn("DATA_ERROR", message, card)), card),
1063
+ ident, *keys), typed_empty(xsd.INTEGER, L))
1064
+
1065
+ out = [counted(node_parts[0], node_parts[1])]
1066
+ for p, x in zip(nodes.parts(True), node_parts):
1067
+ if p.role == "labels":
1068
+ out.append(L.fn(COLLECT_FLAT_LABELS + directions, padded(x, label_width), ident, *keys))
1069
+ elif p.role == "ids":
1070
+ out.append(L.fn("COALESCE", L.fn(COLLECT_FLAT + directions, padded(x), padded(node_parts[0]), ident, *keys),
1071
+ typed_empty(xsd.STRING, L)))
1072
+ else:
1073
+ out.append(L.fn(COLLECT_FLAT + directions, padded(x), padded(node_parts[0]), ident, *keys))
1074
+ out.append(counted(rel_parts[0]))
1075
+ for p, x in zip(rels.parts(True), rel_parts):
1076
+ if p.role == "ids":
1077
+ out.append(L.fn("COALESCE", L.fn(COLLECT_FLAT + directions, padded(x), padded(rel_parts[0]), ident, *keys),
1078
+ typed_empty(xsd.STRING, L)))
1079
+ else:
1080
+ out.append(L.fn(COLLECT_FLAT + directions, padded(x), padded(rel_parts[0]), ident, *keys))
1081
+ return tuple(out)