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,717 @@
1
+ """APOC Core's functions in Cypher, as SQL (rule cypher-apoc; design 239-apoc-functions): a table from
2
+ each function's name to its lowering, each built from the Cypher list home (`cypher_lists`: the engine's
3
+ arrays, their filters and transforms, typed empty lists) and Cypher's equality (`lower.cypher_compare`).
4
+ Nothing is evaluated row by row in Python: a function of literal lists is the same SQL as one of a column.
5
+
6
+ APOC's own behaviour is the standard (its manual, then Neo4j 5 with APOC Core where the manual is silent;
7
+ the recorded answers are tests/cypher/apoc/answers.json). Built: apoc.coll.* (toSet, contains, containsAll,
8
+ indexOf, flatten, union, intersection, subtract, sort, sum, avg, min, max, pairs, partition, zip) on DuckDB,
9
+ Spark and Databricks. Any other apoc.* function, and these on another engine, raise `ApocFunctionError`
10
+ naming the function (and the engine).
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import itertools
16
+ from dataclasses import dataclass
17
+ from typing import TYPE_CHECKING, Callable, Dict, List, Mapping, Optional, Tuple
18
+
19
+ from prograph.plan.ir import expr as E
20
+ from prograph.plan.ir.facts import NotBuilt, expr_slot
21
+ from prograph.plan.ir.slot import LIST, NOTHING, Bound, Slot, list_slot, value_slot
22
+ from prograph.plan.sql import rel_algebra as R
23
+ from prograph.rules import module_home
24
+ from prograph.schema import xsd
25
+
26
+ if TYPE_CHECKING:
27
+ from prograph.plan.ir import lower as L
28
+
29
+ module_home("cypher-apoc", "APOC Core's functions in Cypher, in SQL",
30
+ terms=("apoc", "APOC", "apoc.coll", "toSet", "containsAll", "indexOf", "flatten", "union",
31
+ "intersection", "subtract", "pairs", "partition", "zip", "APOC function"))
32
+
33
+ ENGINES = ("duckdb", "spark", "databricks_sql")
34
+ """The engines the APOC functions are built and checked on."""
35
+ _ENGINE_NAMES = {"duckdb": "DuckDB", "spark": "Spark", "databricks_sql": "Databricks", "postgresql": "PostgreSQL", "postgres": "PostgreSQL", "sqlserver": "SQL Server",
36
+ "mysql": "MySQL", "oracle": "Oracle"}
37
+
38
+
39
+ class ApocFunctionError(NotBuilt):
40
+ """An APOC function ProGraph does not translate: not built yet, or not on this engine."""
41
+
42
+ def __init__(self, function: str, why: str, engine: Optional[str] = None) -> None:
43
+ self.function, self.engine = function, engine
44
+ on = f" on {_ENGINE_NAMES.get(engine, engine)}" if engine else ""
45
+ super().__init__(f"{function}(){on}: {why}")
46
+
47
+
48
+ @dataclass(frozen=True)
49
+ class _Function:
50
+ name: str # APOC's spelling
51
+ arity: Tuple[int, ...]
52
+ slot: Callable
53
+ cell: Callable
54
+ exprs: bool = False # slot and cell also take the call's argument expressions (constants read there)
55
+ note: Optional[str] = None # why it is refused on an engine of no arrays or no such function
56
+ rewrite: Optional[Callable] = None # apoc.map.*: the call worked out into the map and list homes' calls
57
+
58
+
59
+ _INTEGERS = frozenset({xsd.INTEGER}) | xsd.INTEGER_DATATYPES
60
+ _FLOATS = frozenset({xsd.DOUBLE, xsd.FLOAT})
61
+ _NAMES = itertools.count()
62
+
63
+
64
+ # --- slots and the pieces every lowering is built from ------------------------------------------------
65
+
66
+ def _list_arg(s: Slot, fn: str) -> None:
67
+ if s.present is not Bound.NEVER and s.kinds != {LIST}:
68
+ raise ApocFunctionError(fn, "an argument that is not a list")
69
+
70
+
71
+ def _element(s: Slot) -> Optional[str]:
72
+ """A list's element type; None for null or a list of no element type (`[]`)."""
73
+ return s.datatype if s.present is not Bound.NEVER and s.datatypes else None
74
+
75
+
76
+ def _untyped(s: Slot) -> bool:
77
+ """A list of no element type: `[]` (a literal of nulls only is refused where it matters)."""
78
+ return s.present is not Bound.NEVER and s.kinds == {LIST} and not s.datatypes
79
+
80
+
81
+ def _null_of(*slots: Slot) -> Bound:
82
+ """The result's null-ness where it is null exactly when one of `slots` is."""
83
+ if any(s.present is Bound.NEVER for s in slots):
84
+ return Bound.ALWAYS
85
+ return Bound.NEVER if all(s.present is Bound.ALWAYS for s in slots) else Bound.MAYBE
86
+
87
+
88
+ def _var() -> R.LitExpr:
89
+ name = f"_ap{next(_NAMES)}"
90
+ return R.LitExpr(value=name, sql=name)
91
+
92
+
93
+ def _element_cell(lst: "L.Cell", value: R.Expr) -> "L.Cell":
94
+ from prograph.plan.ir import lower as L
95
+ from prograph.plan.ir.cypher_lists import element_slot
96
+ return L.Cell(element_slot(lst.slot), value)
97
+
98
+
99
+ def _at(lst: R.Expr, i: R.Expr) -> R.Expr:
100
+ """The element at the 1-based position `i`, known to be in the list."""
101
+ from prograph.plan.ir import lower as L
102
+ return L.fn("CYPHER_ELEMENT_AT", lst, i)
103
+
104
+
105
+ def _positions(lst: R.Expr) -> R.Expr:
106
+ """[1, ..., size(lst)]."""
107
+ from prograph.plan.ir import lower as L
108
+ return L.fn("CYPHER_RANGE", L.integer(1), L.fn("SIZE", lst), L.integer(1))
109
+
110
+
111
+ def _some(lst: "L.Cell", test: Callable[["L.Cell"], R.Expr]) -> R.Expr:
112
+ """Whether an element makes `test` true (false for none; null for a null list)."""
113
+ from prograph.plan.ir import lower as L
114
+ v = _var()
115
+ hits = L.fn("LIST_FILTER", lst.value, v, L.fn("COALESCE", test(_element_cell(lst, v)), L.FALSE))
116
+ return R.CompareExpr(left=L.fn("SIZE", hits), op=">", right=L.integer(0))
117
+
118
+
119
+ def _equal(a: "L.Cell", b: "L.Cell") -> R.Expr:
120
+ """Cypher's `=` (cypher-equality), unknown as false: what contains() and indexOf() match by, so a null
121
+ matches nothing (APOC's manual: "always false when matching on a null value")."""
122
+ from prograph.plan.ir import lower as L
123
+ return L.fn("COALESCE", L.cypher_compare("=", a, b), L.FALSE)
124
+
125
+
126
+ def _distinct(lst: "L.Cell") -> R.Expr:
127
+ """The list's elements, each once (equal by value, nulls one), in the order they first appear: the
128
+ dialects' `CYPHER_LIST_DISTINCT`, which reads its list once (an expression passed to it is computed
129
+ once, never per element). Spark's set functions keep -0.0 apart from 0.0, so a list of floats there
130
+ takes `CYPHER_LIST_DISTINCT_FLOAT` (each element where its value first appears)."""
131
+ from prograph.plan.ir import lower as L
132
+ floats = _element(lst.slot) in _FLOATS
133
+ return L.fn("CYPHER_LIST_DISTINCT_FLOAT" if floats else "CYPHER_LIST_DISTINCT", lst.value)
134
+
135
+
136
+ def _set_operation(a: "L.Cell", b: "L.Cell", keep: bool) -> R.Expr:
137
+ """intersection (keep) or subtract: a's elements that are (are not) in b, each once, in a's order: the
138
+ dialects' `CYPHER_LIST_INTERSECT` / `CYPHER_LIST_EXCEPT` (each argument read once; hash sets on
139
+ Spark). Floats, or integers against floats (equal by value, a's elements kept), take the `_FLOAT`
140
+ forms: Spark's hash sets keep -0.0 apart from 0.0 and do not compare an integer with a float, so there
141
+ each element is looked for by value."""
142
+ from prograph.plan.ir import lower as L
143
+ name = "CYPHER_LIST_INTERSECT" if keep else "CYPHER_LIST_EXCEPT"
144
+ if _element(a.slot) != _element(b.slot) or _element(a.slot) in _FLOATS:
145
+ name += "_FLOAT"
146
+ return L.fn(name, a.value, b.value)
147
+
148
+
149
+ _DOUBLE = "double"
150
+
151
+
152
+ _SCALAR_CASTS = {xsd.STRING: "CAST_STRING", xsd.INTEGER: "CAST_LONG", xsd.BOOLEAN: "CAST_BOOLEAN"}
153
+
154
+
155
+ def _raising(bad: R.Expr, message: str, value: R.Expr, of) -> R.Expr:
156
+ """`value`, or an error where `bad` is true (APOC raises there). The error is a value of the result's
157
+ type, so an engine that folds `value` to a constant keeps the two branches apart (Spark drops a CASE
158
+ whose branches are one null). `of`: `_DOUBLE`; ("scalar", a string, integer or boolean type); a list's
159
+ element type, or ("list", element type), for a list of them."""
160
+ from prograph.plan.ir import lower as L
161
+ from prograph.plan.ir.cypher_lists import typed_null
162
+ error = L.fn("DATA_ERROR", L.text(f"ProGraph: {message}"), L.text(""))
163
+ if of == _DOUBLE:
164
+ raised = L.fn("CAST_DOUBLE", error)
165
+ elif isinstance(of, tuple) and of[0] == "scalar":
166
+ raised = L.fn(_SCALAR_CASTS[of[1]], error)
167
+ else: # a one-element list of the type, filtered by the error: the error, as such a list
168
+ element = of[1] if isinstance(of, tuple) else of
169
+ raised = L.fn("LIST_FILTER", L.fn("ARRAY", typed_null(element, L)), _var(), L.fn("CAST_BOOLEAN", error))
170
+ return L.case(bad, raised, value)
171
+
172
+
173
+ def _holds_null(lst: R.Expr) -> R.Expr:
174
+ from prograph.plan.ir import lower as L
175
+ v = _var()
176
+ return R.CompareExpr(left=L.fn("SIZE", L.fn("LIST_FILTER", lst, v, L.is_null(v))), op=">",
177
+ right=L.integer(0))
178
+
179
+
180
+ def _empty(element: Optional[str]) -> R.Expr:
181
+ """[] typed as a list of `element` (the cypher-lists home's), the engine's own [] for no type."""
182
+ from prograph.plan.ir import lower as L
183
+ from prograph.plan.ir.cypher_lists import typed_empty
184
+ return L.fn("ARRAY") if element is None else typed_empty(element, L)
185
+
186
+
187
+ def _nesting(element: Optional[str]) -> None:
188
+ from prograph.plan.ir.cypher_lists import native_nesting
189
+ native_nesting(element)
190
+
191
+
192
+ def _plain_kind(element: Optional[str], fn: str) -> str:
193
+ """"number", "float", "string" or "boolean": the element kinds sort, min and max order (cypher-order:
194
+ numbers by value, strings by code point, false before true)."""
195
+ if element in _FLOATS:
196
+ return "float"
197
+ if element in _INTEGERS:
198
+ return "number"
199
+ if element == xsd.STRING:
200
+ return "string"
201
+ if element == xsd.BOOLEAN:
202
+ return "boolean"
203
+ from prograph.plan.ir.cypher_lists import nested
204
+ from prograph.plan.ir.cypher_maps import is_map_type
205
+ if nested(element) or is_map_type(element):
206
+ raise ApocFunctionError(fn, "a list of lists or maps (ordering lists is not built; APOC's sort() "
207
+ "raises for one)")
208
+ raise ApocFunctionError(fn, "a list of temporal values (not built yet)")
209
+
210
+
211
+ # --- the functions ------------------------------------------------------------------------------------
212
+
213
+ def _to_set_slot(args: List[Slot]) -> Slot:
214
+ (lst,) = args
215
+ _list_arg(lst, "apoc.coll.toSet")
216
+ return NOTHING if lst.present is Bound.NEVER else list_slot(_element(lst), _null_of(lst))
217
+
218
+
219
+ def _to_set(args, L) -> R.Expr:
220
+ """toSet(l): l's elements once each, first appearance first; null for null."""
221
+ (lst,) = args
222
+ if _untyped(lst.slot):
223
+ return lst.value
224
+ return L.case(L.is_null(lst.value), L.NULL, _distinct(lst))
225
+
226
+
227
+ def _contains_slot(args: List[Slot]) -> Slot:
228
+ _list_arg(args[0], "apoc.coll.contains")
229
+ return value_slot(xsd.BOOLEAN, Bound.NEVER)
230
+
231
+
232
+ def _contains(args, L) -> R.Expr:
233
+ """contains(l, x): whether an element equals x; false for a null list, a null x, or []."""
234
+ lst, x = args
235
+ if lst.slot.present is Bound.NEVER or x.slot.present is Bound.NEVER or _untyped(lst.slot):
236
+ return L.FALSE
237
+ return L.fn("COALESCE", _some(lst, lambda e: _equal(e, x)), L.FALSE)
238
+
239
+
240
+ def _contains_all_slot(args: List[Slot]) -> Slot:
241
+ for a in args:
242
+ _list_arg(a, "apoc.coll.containsAll")
243
+ return value_slot(xsd.BOOLEAN, Bound.NEVER)
244
+
245
+
246
+ def _contains_all(args, L) -> R.Expr:
247
+ """containsAll(a, b): whether every element of b is in a (contains()); false where either list is
248
+ null or a is empty (so containsAll([], []) is false and containsAll([1], []) true, as Neo4j answers)."""
249
+ a, b = args
250
+ if any(s.slot.present is Bound.NEVER for s in args) or _untyped(a.slot):
251
+ return L.FALSE
252
+ nonempty = R.CompareExpr(left=L.fn("SIZE", a.value), op=">", right=L.integer(0))
253
+ if _untyped(b.slot):
254
+ return L.fn("COALESCE", nonempty, L.FALSE)
255
+ missing = _some(b, lambda y: R.NotExpr(child=L.fn("COALESCE", _some(a, lambda e: _equal(e, y)), L.FALSE)))
256
+ return L.fn("COALESCE", L.all_of([nonempty, R.NotExpr(child=missing)]), L.FALSE)
257
+
258
+
259
+ def _index_of_slot(args: List[Slot]) -> Slot:
260
+ _list_arg(args[0], "apoc.coll.indexOf")
261
+ return value_slot(xsd.INTEGER, Bound.NEVER)
262
+
263
+
264
+ def _index_of(args, L) -> R.Expr:
265
+ """indexOf(l, x): the 0-based position of the first element equal to x, else -1 (a null list or x
266
+ included)."""
267
+ lst, x = args
268
+ if lst.slot.present is Bound.NEVER or x.slot.present is Bound.NEVER or _untyped(lst.slot):
269
+ return L.integer(-1)
270
+ i = _var()
271
+ found = L.fn("LIST_FILTER", _positions(lst.value), i, _equal(_element_cell(lst, _at(lst.value, i)), x))
272
+ none = R.CompareExpr(left=L.fn("SIZE", found), op="=", right=L.integer(0))
273
+ return L.case(L.is_null(lst.value), L.integer(-1), none, L.integer(-1),
274
+ L.fn("-", _at(found, L.integer(1)), L.integer(1)))
275
+
276
+
277
+ def _recursive(e_args: Tuple[E.Expr, ...]) -> bool:
278
+ if len(e_args) < 2:
279
+ return False
280
+ flag = e_args[1]
281
+ if not (isinstance(flag, E.Const) and isinstance(flag.value, bool)):
282
+ raise ApocFunctionError("apoc.coll.flatten", "a recursive flag that is not true or false written in "
283
+ "the query (a null one is an error in APOC)")
284
+ return flag.value
285
+
286
+
287
+ def _flatten_levels(element: Optional[str], recursive: bool) -> List[Optional[str]]:
288
+ """The element types the list's levels flatten through, outermost first."""
289
+ from prograph.plan.ir.cypher_lists import element_of, nested
290
+ levels = []
291
+ while nested(element):
292
+ levels.append(element)
293
+ element = element_of(element)
294
+ if not recursive:
295
+ break
296
+ return levels
297
+
298
+
299
+ def _flatten_slot(args: List[Slot], e_args=()) -> Slot:
300
+ from prograph.plan.ir.cypher_lists import element_of
301
+ lst = args[0]
302
+ _list_arg(lst, "apoc.coll.flatten")
303
+ levels = _flatten_levels(_element(lst), _recursive(e_args))
304
+ element = element_of(levels[-1]) if levels else _element(lst)
305
+ return list_slot(element, Bound.NEVER)
306
+
307
+
308
+ def _flatten(args, L, e_args=()) -> R.Expr:
309
+ """flatten(l[, recursive]): the elements of l's lists in order (with recursive, of their lists too, to
310
+ the plain values); a list of plain values as it is; [] for null; an error where l holds a null list
311
+ (APOC raises)."""
312
+ from prograph.plan.ir.cypher_lists import element_of
313
+ lst = args[0]
314
+ if lst.slot.present is Bound.NEVER or _untyped(lst.slot):
315
+ return L.fn("ARRAY")
316
+ levels = _flatten_levels(_element(lst.slot), _recursive(e_args))
317
+ out = lst.value
318
+ for level in levels:
319
+ _nesting(level)
320
+ out = _raising(_holds_null(out), "apoc.coll.flatten() of a list holding null (APOC raises)",
321
+ L.fn("CYPHER_LIST_FLATTEN", out), element_of(level))
322
+ element = element_of(levels[-1]) if levels else _element(lst.slot)
323
+ return L.case(L.is_null(lst.value), _empty(element), out)
324
+
325
+
326
+ def _two_lists(args: List[Slot], fn: str) -> Optional[str]:
327
+ from prograph.plan.ir.cypher_lists import joined
328
+ for a in args:
329
+ _list_arg(a, fn)
330
+ types = [t for t in (_element(a) for a in args) if t is not None]
331
+ if len(types) == 2 and joined(*types) is None:
332
+ raise ApocFunctionError(fn, "two lists of different element types (the answer is a mixed list)")
333
+ return joined(*types) if len(types) == 2 else (types[0] if types else None)
334
+
335
+
336
+ def _union_slot(args: List[Slot]) -> Slot:
337
+ a, b = args
338
+ element = _two_lists(args, "apoc.coll.union")
339
+ if a.present is Bound.NEVER and b.present is Bound.NEVER:
340
+ return NOTHING
341
+ both_null = Bound.NEVER if Bound.ALWAYS in (a.present, b.present) else Bound.MAYBE
342
+ return list_slot(element, both_null)
343
+
344
+
345
+ def _union(args, L) -> R.Expr:
346
+ """union(a, b): the elements of a then b, each once; a null list gives the other list as it is
347
+ (duplicates kept, as Neo4j answers), null where both are null. Neo4j's order is its hash set's,
348
+ which APOC's manual leaves unsaid; ProGraph keeps first appearance (tests compare these as sets)."""
349
+ a, b = args
350
+ if a.slot.present is Bound.NEVER:
351
+ return b.value
352
+ if b.slot.present is Bound.NEVER:
353
+ return a.value
354
+ typed = [c for c in (a, b) if not _untyped(c.slot)]
355
+ if not typed:
356
+ return L.fn("ARRAY")
357
+ slot = list_slot(_two_lists([a.slot, b.slot], "apoc.coll.union"), Bound.NEVER)
358
+ joined = typed[0].value if len(typed) == 1 else L.fn("LIST_CONCAT", a.value, b.value)
359
+ both = _distinct(L.Cell(slot, joined)) # the concatenation computed once, in the template
360
+ return L.case(L.is_null(a.value), b.value, L.is_null(b.value), a.value, both)
361
+
362
+
363
+ def _intersection_slot(args: List[Slot]) -> Slot:
364
+ for a in args:
365
+ _list_arg(a, "apoc.coll.intersection")
366
+ return list_slot(_element(args[0]), Bound.NEVER)
367
+
368
+
369
+ def _intersection(args, L) -> R.Expr:
370
+ """intersection(a, b): a's elements in b, each once (null with null), first appearance first; [] where
371
+ either is null."""
372
+ a, b = args
373
+ element = _element(a.slot)
374
+ if any(c.slot.present is Bound.NEVER or _untyped(c.slot) for c in args):
375
+ return _empty(element)
376
+ return L.case(L.any_of([L.is_null(a.value), L.is_null(b.value)]), _empty(element),
377
+ _set_operation(a, b, keep=True))
378
+
379
+
380
+ def _subtract_slot(args: List[Slot]) -> Slot:
381
+ a, b = args
382
+ for x in args:
383
+ _list_arg(x, "apoc.coll.subtract")
384
+ return NOTHING if a.present is Bound.NEVER else list_slot(_element(a), _null_of(a))
385
+
386
+
387
+ def _subtract(args, L) -> R.Expr:
388
+ """subtract(a, b): a's elements not in b (null with null), each once, first appearance first; null for
389
+ a null a; a as it is for a null b (duplicates kept, as Neo4j answers)."""
390
+ a, b = args
391
+ if _untyped(a.slot):
392
+ return a.value
393
+ if b.slot.present is Bound.NEVER:
394
+ return a.value
395
+ if _untyped(b.slot):
396
+ return L.case(L.is_null(a.value), L.NULL, _distinct(a))
397
+ return L.case(L.is_null(a.value), L.NULL, L.is_null(b.value), a.value, _set_operation(a, b, keep=False))
398
+
399
+
400
+ def _sort_slot(args: List[Slot]) -> Slot:
401
+ (lst,) = args
402
+ _list_arg(lst, "apoc.coll.sort")
403
+ if _element(lst) is not None:
404
+ _plain_kind(_element(lst), "apoc.coll.sort")
405
+ return list_slot(_element(lst), Bound.NEVER)
406
+
407
+
408
+ def _sort(args, L) -> R.Expr:
409
+ """sort(l): l ascending (numbers by value, NaN last; strings by code point; false before true); [] for
410
+ null; an error where l holds a null (APOC raises)."""
411
+ (lst,) = args
412
+ if lst.slot.present is Bound.NEVER or _untyped(lst.slot):
413
+ return L.fn("ARRAY")
414
+ sorted_ = _raising(_holds_null(lst.value), "apoc.coll.sort() of a list holding null (APOC raises)",
415
+ _sorted(lst.value, _element(lst.slot)), _element(lst.slot))
416
+ return L.case(L.is_null(lst.value), _empty(_element(lst.slot)), sorted_)
417
+
418
+
419
+ def _sorted(lst: R.Expr, element: Optional[str]) -> R.Expr:
420
+ """The dialects' `CYPHER_LIST_SORT` of a list with no null; strings compared by code point
421
+ (codepoint-string-order: each element as `lower.codepoint` writes it)."""
422
+ from prograph.plan.ir import lower as L
423
+ if element == xsd.STRING:
424
+ v = _var()
425
+ lst = L.fn("LIST_TRANSFORM", lst, v, L.codepoint(v))
426
+ return L.fn("CYPHER_LIST_SORT", lst)
427
+
428
+
429
+ def _numbers(lst: Slot, fn: str) -> None:
430
+ _list_arg(lst, fn)
431
+ element = _element(lst)
432
+ if element is not None and element not in _INTEGERS | _FLOATS:
433
+ raise ApocFunctionError(fn, "a list that is not of numbers (an error in Neo4j)")
434
+
435
+
436
+ def _sum_slot(args: List[Slot], fn: str = "apoc.coll.sum") -> Slot:
437
+ (lst,) = args
438
+ _numbers(lst, fn)
439
+ return NOTHING if lst.present is Bound.NEVER or _untyped(lst) else value_slot(xsd.DOUBLE, Bound.MAYBE)
440
+
441
+
442
+ def _sum(args, L, average: bool = False) -> R.Expr:
443
+ """sum(l): the elements added as doubles, left to right (Java's); avg(l): that over the size. Null for
444
+ a null or empty list; an error where l holds a null (APOC raises)."""
445
+ (lst,) = args
446
+ if lst.slot.present is Bound.NEVER or _untyped(lst.slot):
447
+ return L.NULL
448
+ fn = "avg" if average else "sum"
449
+ total = L.fn("CYPHER_LIST_SUM", lst.value)
450
+ if average:
451
+ total = L.fn("/", total, L.fn("CAST_DOUBLE", L.fn("SIZE", lst.value)))
452
+ out = _raising(_holds_null(lst.value), f"apoc.coll.{fn}() of a list holding null (APOC raises)", total,
453
+ _DOUBLE)
454
+ empty = R.CompareExpr(left=L.fn("SIZE", lst.value), op="=", right=L.integer(0))
455
+ return L.case(L.any_of([L.is_null(lst.value), empty]), L.fn("CAST_DOUBLE", L.NULL), out)
456
+
457
+
458
+ def _extreme_slot(args: List[Slot], fn: str) -> Slot:
459
+ from prograph.plan.ir.cypher_lists import element_slot
460
+ (lst,) = args
461
+ _list_arg(lst, fn)
462
+ if lst.present is Bound.NEVER or _untyped(lst):
463
+ return NOTHING
464
+ _plain_kind(_element(lst), fn)
465
+ return element_slot(lst)
466
+
467
+
468
+ def _extreme(args, L, largest: bool) -> R.Expr:
469
+ """min(l), max(l): the least or greatest non-null element (cypher-order's kinds), null for a null or
470
+ empty list or one of nulls only. A NaN never wins a comparison, so it is the answer only where it is the
471
+ first non-null element (Neo4j's answers: max([NaN, 1.0]) is NaN, max([1.0, NaN]) 1.0)."""
472
+ (lst,) = args
473
+ if lst.slot.present is Bound.NEVER or _untyped(lst.slot):
474
+ return L.NULL
475
+ kind = _plain_kind(_element(lst.slot), "apoc.coll.max" if largest else "apoc.coll.min")
476
+ v = _var()
477
+ present = L.fn("LIST_FILTER", lst.value, v, L.is_null(v, negated=True))
478
+ w = _var()
479
+ ordered = _sorted(present if kind != "float" else
480
+ L.fn("LIST_FILTER", present, w, R.NotExpr(child=L.fn("IS_NAN", w))), _element(lst.slot))
481
+ n = L.fn("SIZE", ordered)
482
+ pick = L.case(R.CompareExpr(left=n, op="=", right=L.integer(0)), L.NULL,
483
+ _at(ordered, n if largest else L.integer(1)))
484
+ if kind == "float":
485
+ first = _at(present, L.integer(1))
486
+ has_first = R.CompareExpr(left=L.fn("SIZE", present), op=">", right=L.integer(0))
487
+ pick = L.case(L.all_of([has_first, L.fn("IS_NAN", first)]), first, pick)
488
+ return L.case(L.is_null(lst.value), L.NULL, pick)
489
+
490
+
491
+ def _pairs_slot(args: List[Slot]) -> Slot:
492
+ from prograph.plan.ir.cypher_lists import list_type
493
+ (lst,) = args
494
+ _list_arg(lst, "apoc.coll.pairs")
495
+ if lst.present is Bound.NEVER:
496
+ return NOTHING
497
+ return list_slot(list_type(_element(lst)) if _element(lst) else None, _null_of(lst))
498
+
499
+
500
+ def _pairs(args, L) -> R.Expr:
501
+ """pairs(l): [l[i], l[i + 1]] for each element, the last paired with null; [] for a list of one
502
+ element or none (as Neo4j answers); null for null."""
503
+ from prograph.plan.ir.cypher_lists import list_type
504
+ (lst,) = args
505
+ if _untyped(lst.slot):
506
+ return lst.value
507
+ element = list_type(_element(lst.slot))
508
+ _nesting(element)
509
+ i = _var()
510
+ n = L.fn("SIZE", lst.value)
511
+ after = L.case(R.CompareExpr(left=i, op="<", right=n), _at(lst.value, L.fn("+", i, L.integer(1))))
512
+ pairs = L.fn("LIST_TRANSFORM", _positions(lst.value), i, L.fn("ARRAY", _at(lst.value, i), after))
513
+ return L.case(L.is_null(lst.value), L.NULL, R.CompareExpr(left=n, op="<=", right=L.integer(1)),
514
+ _empty(element), pairs)
515
+
516
+
517
+ def _partition_slot(args: List[Slot]) -> Slot:
518
+ from prograph.plan.ir.cypher_lists import list_type
519
+ lst, size = args
520
+ _list_arg(lst, "apoc.coll.partition")
521
+ if size.present is Bound.NEVER:
522
+ raise ApocFunctionError("apoc.coll.partition", "a null batch size (an error in APOC)")
523
+ if not (size.kinds and len(size.datatypes) == 1 and size.datatype in _INTEGERS):
524
+ raise ApocFunctionError("apoc.coll.partition", "a batch size that is not an integer")
525
+ return list_slot(list_type(_element(lst)) if _element(lst) else None, Bound.NEVER)
526
+
527
+
528
+ def _partition(args, L) -> R.Expr:
529
+ """partition(l, n): l in consecutive lists of n elements, the last possibly shorter; [] for a null or
530
+ empty list or a negative n; an error for a null n, or n = 0 with elements (APOC raises)."""
531
+ from prograph.plan.ir.cypher_lists import list_type
532
+ lst, size = args
533
+ if lst.slot.present is Bound.NEVER or _untyped(lst.slot):
534
+ return L.fn("ARRAY")
535
+ element = list_type(_element(lst.slot))
536
+ _nesting(element)
537
+ s = _var()
538
+ n = size.value
539
+ chunks = L.fn("LIST_TRANSFORM", L.fn("CYPHER_RANGE", L.integer(1), L.fn("SIZE", lst.value), n), s,
540
+ L.fn("SLICE", lst.value, s, n))
541
+ # A zero size raises only for a list with elements (Neo4j: partition([], 0) and partition(null, 0) are []).
542
+ nonempty = R.CompareExpr(left=L.fn("COALESCE", L.fn("SIZE", lst.value), L.integer(0)), op=">", right=L.integer(0))
543
+ bad = L.any_of([L.is_null(n), L.all_of([R.CompareExpr(left=n, op="=", right=L.integer(0)), nonempty])])
544
+ out = L.case(L.is_null(lst.value), _empty(element), R.CompareExpr(left=n, op="<=", right=L.integer(0)),
545
+ _empty(element), chunks)
546
+ return _raising(bad, "apoc.coll.partition() of a null or zero batch size (APOC raises)", out, element)
547
+
548
+
549
+ def _zip_slot(args: List[Slot]) -> Slot:
550
+ from prograph.plan.ir.cypher_lists import list_type
551
+ element = _two_lists(args, "apoc.coll.zip")
552
+ if any(a.present is Bound.NEVER for a in args):
553
+ return NOTHING
554
+ return list_slot(list_type(element) if element else None, _null_of(*args))
555
+
556
+
557
+ def _zip(args, L) -> R.Expr:
558
+ """zip(a, b): [a[i], b[i]] for each element of a, b's missing ones null; [] where either is empty;
559
+ null where either is null."""
560
+ from prograph.plan.ir.cypher_lists import list_type
561
+ a, b = args
562
+ element = _two_lists([a.slot, b.slot], "apoc.coll.zip")
563
+ either_null = L.any_of([L.is_null(a.value), L.is_null(b.value)])
564
+ if element is None: # [] and [] (or a list of no type): [] unless one is null
565
+ return L.case(either_null, L.NULL, L.fn("ARRAY"))
566
+ pair = list_type(element)
567
+ _nesting(pair)
568
+ if _untyped(a.slot) or _untyped(b.slot):
569
+ return L.case(either_null, L.NULL, _empty(pair))
570
+ i = _var()
571
+ from_b = L.case(R.CompareExpr(left=i, op="<=", right=L.fn("SIZE", b.value)), _at(b.value, i))
572
+ zipped = L.fn("LIST_TRANSFORM", _positions(a.value), i, L.fn("ARRAY", _at(a.value, i), from_b))
573
+ empty_b = R.CompareExpr(left=L.fn("SIZE", b.value), op="=", right=L.integer(0))
574
+ return L.case(either_null, L.NULL, empty_b, _empty(pair), zipped)
575
+
576
+
577
+ TABLE: Dict[str, _Function] = {f.name.lower(): f for f in (
578
+ _Function("apoc.coll.toSet", (1,), _to_set_slot, _to_set),
579
+ _Function("apoc.coll.contains", (2,), _contains_slot, _contains),
580
+ _Function("apoc.coll.containsAll", (2,), _contains_all_slot, _contains_all),
581
+ _Function("apoc.coll.indexOf", (2,), _index_of_slot, _index_of),
582
+ _Function("apoc.coll.flatten", (1, 2), _flatten_slot, _flatten),
583
+ _Function("apoc.coll.union", (2,), _union_slot, _union),
584
+ _Function("apoc.coll.intersection", (2,), _intersection_slot, _intersection),
585
+ _Function("apoc.coll.subtract", (2,), _subtract_slot, _subtract),
586
+ _Function("apoc.coll.sort", (1,), _sort_slot, _sort),
587
+ _Function("apoc.coll.sum", (1,), _sum_slot, _sum),
588
+ _Function("apoc.coll.avg", (1,), lambda a: _sum_slot(a, "apoc.coll.avg"),
589
+ lambda a, L: _sum(a, L, average=True)),
590
+ _Function("apoc.coll.min", (1,), lambda a: _extreme_slot(a, "apoc.coll.min"),
591
+ lambda a, L: _extreme(a, L, largest=False)),
592
+ _Function("apoc.coll.max", (1,), lambda a: _extreme_slot(a, "apoc.coll.max"),
593
+ lambda a, L: _extreme(a, L, largest=True)),
594
+ _Function("apoc.coll.pairs", (1,), _pairs_slot, _pairs),
595
+ _Function("apoc.coll.partition", (2,), _partition_slot, _partition),
596
+ _Function("apoc.coll.zip", (2,), _zip_slot, _zip),
597
+ )}
598
+ """Each built APOC function by its name in lower case (Cypher's function names are case-insensitive)."""
599
+
600
+ _GONE = {"apoc.coll.reverse": "not in APOC Core 5 (Neo4j 5 answers 'Unknown function'); Cypher's reverse() "
601
+ "replaced it"}
602
+ _CALL = "APOC:"
603
+
604
+
605
+ def call(name: str, args: Tuple[E.Expr, ...]) -> E.Expr:
606
+ """The front end's call of the APOC function `name` (in lower case): a plan call the table lowers, or
607
+ `ApocFunctionError` for a function not built."""
608
+ _with_text()
609
+ f = TABLE.get(name)
610
+ if f is None:
611
+ why = _GONE.get(name, "not built yet (built: apoc.coll.*, apoc.text.* and apoc.map.* on DuckDB, Spark and Databricks; "
612
+ "see docs/reference/apoc-functions.md)")
613
+ raise ApocFunctionError(name, why)
614
+ if len(args) not in f.arity:
615
+ raise ApocFunctionError(f.name, f"takes {' or '.join(map(str, f.arity))} arguments, not {len(args)}")
616
+ return E.Call(_CALL + name, args, E.CYPHER)
617
+
618
+
619
+ def is_apoc(e: E.Call) -> bool:
620
+ return e.name.startswith(_CALL)
621
+
622
+
623
+ def _function(e: E.Call) -> _Function:
624
+ _with_text()
625
+ return TABLE[e.name[len(_CALL):]]
626
+
627
+
628
+ def _nulls_literal(x: E.Expr) -> bool:
629
+ return isinstance(x, E.Call) and x.name == "LIST" and bool(x.args)
630
+
631
+
632
+ def _known(slots: List[Slot]) -> Optional[str]:
633
+ """The element type of the call's first list argument that has one."""
634
+ return next((_element(s) for s in slots if s.kinds == {LIST} and _element(s) is not None), None)
635
+
636
+
637
+ def _typed(f: _Function, e: E.Call, slots: List[Slot]) -> List[Slot]:
638
+ """The arguments' slots, a list literal of nulls only (`[null]`) typed as the other list's elements
639
+ (as `+` types one, cypher-lists); refused where no argument gives a type."""
640
+ from prograph.plan.ir.cypher_mixed import holds_mixed
641
+ if any(holds_mixed(s) for s in slots):
642
+ # APOC's own equality and order across types (apoc.coll.toSet treats 1 and 1.0 as one value) is
643
+ # not the engine's over the tagged structs: a list of several element types is not built here.
644
+ raise ApocFunctionError(f.name, "a list or value of several types")
645
+ known = _known(slots)
646
+ out = []
647
+ for x, s in zip(e.args, slots):
648
+ if _untyped(s) and _nulls_literal(x):
649
+ if known is None:
650
+ if f.exprs: # apoc.text.*: a list of nulls read as nulls (format's parameters)
651
+ out.append(s)
652
+ continue
653
+ raise ApocFunctionError(f.name, "a list of nulls only (its element type is unknown)")
654
+ s = list_slot(known, Bound.NEVER)
655
+ out.append(s)
656
+ return out
657
+
658
+
659
+ def _slot_of(f: _Function, e: E.Call, slots: List[Slot]) -> Slot:
660
+ if f.exprs:
661
+ return f.slot(slots, e.args)
662
+ if f.slot is _flatten_slot:
663
+ return _flatten_slot(slots, e.args)
664
+ return f.slot(slots)
665
+
666
+
667
+ def apoc_slot(e: E.Call, slots: Mapping[str, Slot]) -> Slot:
668
+ f = _function(e)
669
+ if f.rewrite is not None:
670
+ return expr_slot(f.rewrite(list(e.args), lambda x: expr_slot(x, slots)), slots)
671
+ from prograph.plan.ir.cypher_apoc_convert import CELLS
672
+ if f.name.lower() in CELLS: # a string in every row, whatever the arguments' types
673
+ return f.slot([], e.args)
674
+ return _slot_of(f, e, _typed(f, e, [expr_slot(a, slots) for a in e.args]))
675
+
676
+
677
+ def apoc_cell(e: E.Call, cells: Dict[str, "L.Cell"]) -> "L.Cell":
678
+ from prograph.plan.ir import lower as L
679
+ from prograph.plan.ir.cypher_lists import typed_null
680
+ f = _function(e)
681
+ engine = L.DIALECT.get()
682
+ if engine is not None and engine not in ENGINES:
683
+ raise ApocFunctionError(f.name, f.note if f.note and engine in ("postgresql", "postgres") else
684
+ "not built on this engine yet (built on DuckDB, Spark and Databricks)", engine)
685
+ if f.rewrite is not None:
686
+ slots = {n: c.slot for n, c in cells.items()}
687
+ return L.expr_cell(f.rewrite(list(e.args), lambda x: expr_slot(x, slots)), cells)
688
+ from prograph.plan.ir.cypher_apoc_convert import CELLS
689
+ if f.name.lower() in CELLS: # lowered from the call's expressions (toJson of a literal of several types)
690
+ return CELLS[f.name.lower()](list(e.args), cells, L)
691
+ args = [L.expr_cell(a, cells) for a in e.args]
692
+ typed = _typed(f, e, [c.slot for c in args])
693
+ for k, (x, c, s) in enumerate(zip(e.args, args, typed)):
694
+ if s is not c.slot: # [null, ...] as the other list's elements
695
+ args[k] = L.Cell(s, L.fn("ARRAY", *(typed_null(s.datatype, L) for _ in x.args)))
696
+ slot = _slot_of(f, e, typed)
697
+ if slot.present is Bound.NEVER:
698
+ return L.nothing()
699
+ if f.exprs:
700
+ return L.Cell(slot, f.cell(args, L, e.args))
701
+ if f.cell is _flatten:
702
+ return L.Cell(slot, _flatten(args, L, e.args))
703
+ return L.Cell(slot, f.cell(args, L))
704
+
705
+
706
+
707
+ def _with_text() -> None:
708
+ """The apoc.text.* and apoc.map.* rows (cypher_apoc_text, cypher_apoc_map, which build on this module),
709
+ added on first use."""
710
+ if "apoc.text.join" not in TABLE:
711
+ from prograph.plan.ir import cypher_apoc_convert as convert
712
+ from prograph.plan.ir import cypher_apoc_date as dates
713
+ from prograph.plan.ir import cypher_apoc_map as maps
714
+ from prograph.plan.ir import cypher_apoc_text as text
715
+ TABLE.update({f.name.lower(): f for f in text.FUNCTIONS + maps.FUNCTIONS + dates.FUNCTIONS
716
+ + convert.FUNCTIONS})
717
+ _GONE.update({**text.GONE, **dates.GONE, **convert.GONE})