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,370 @@
1
+ """Cypher's maps on the one plan (rule cypher-maps): a map whose keys are known at planning (a map
2
+ literal) is a struct (DuckDB, Spark, Databricks) or a jsonb object (PostgreSQL), as a node's value is;
3
+ its slot records each key's value type (`map_slot`). `m.k` reads a key, null where the map has no such
4
+ key or is null; on a map literal it is the key's own expression. `keys(m)` is the literal's keys. `keys(n)` and `properties(n)` of a node or relationship are the keys it holds
5
+ (null properties do not exist) and a map of its property keys, null for a null element. A map
6
+ holds lists and maps of plain values; two maps are equal key by key (`map_equality`). A map holding a
7
+ node or a temporal value, and maps of keys known only at run time are not built yet.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ from typing import TYPE_CHECKING, Dict, List, Mapping, Optional, Tuple
13
+
14
+ from prograph.plan.ir import expr as E
15
+ from prograph.plan.ir.facts import NotBuilt, expr_slot
16
+ from prograph.plan.ir.slot import MAP, NOTHING, UNKNOWN, VALUE, Bound, Slot, list_slot, value_slot
17
+ from prograph.rules import module_home
18
+ from prograph.schema import xsd
19
+
20
+ if TYPE_CHECKING:
21
+ from prograph.plan.ir import lower as L
22
+
23
+ module_home("cypher-maps", "Cypher's maps, in SQL",
24
+ terms=("map", "map literal", "m.k", "keys()", "properties()", "struct field", "Cypher map"))
25
+
26
+ MAP_CALLS = frozenset({"MAP", "FIELD", "KEYS", "PROPERTIES"})
27
+ _SEP = "\x00"
28
+ _INTEGERS = frozenset({xsd.INTEGER}) | xsd.INTEGER_DATATYPES
29
+
30
+
31
+ def map_slot(fields: Dict[str, Optional[str]], null: Bound, digits=None) -> Slot:
32
+ """A map of these keys, each its value's type (None: null in every row). `digits`: the DECIMAL(p, s) of each
33
+ decimal field, in key order (a map literal's, which PostgreSQL's answer types its decimals by)."""
34
+ return Slot(kinds=frozenset({MAP}), datatypes=frozenset(f"{k}{_SEP}{t or ''}" for k, t in fields.items()),
35
+ bound=Bound.NEVER, null=null, digits=digits)
36
+
37
+
38
+ MAP_OF = "urn:prograph:cypher:map:"
39
+ """A list's element type when its elements are maps: this prefix and their keys' types."""
40
+
41
+
42
+ def map_type(fields: Dict[str, Optional[str]]) -> str:
43
+ """The element type of a list whose elements are maps of these keys and value types: each key and
44
+ type length-prefixed (`3:key5:type`), so a map type nested in a field's type is kept whole and the
45
+ text grows with the depth, not with an escape per level."""
46
+ return MAP_OF + "".join(f"{len(k)}:{k}{len(t or '')}:{t or ''}" for k, t in sorted(fields.items()))
47
+
48
+
49
+ def is_map_type(datatype: Optional[str]) -> bool:
50
+ return datatype is not None and datatype.startswith(MAP_OF)
51
+
52
+
53
+ def type_fields(datatype: str) -> Dict[str, Optional[str]]:
54
+ """The keys and value types a `map_type` names."""
55
+ rest, i, parts = datatype, len(MAP_OF), []
56
+ while i < len(rest):
57
+ colon = rest.index(":", i)
58
+ n = int(rest[i:colon])
59
+ parts.append(rest[colon + 1:colon + 1 + n])
60
+ i = colon + 1 + n
61
+ return {k: t or None for k, t in zip(parts[0::2], parts[1::2])}
62
+
63
+
64
+ def fields_of(slot: Slot) -> Dict[str, Optional[str]]:
65
+ return _fields(slot.datatypes)
66
+
67
+
68
+ def _fields(items) -> Dict[str, Optional[str]]:
69
+ out = {}
70
+ for d in items:
71
+ k, _, t = d.partition(_SEP)
72
+ out[k] = t or None
73
+ return out
74
+
75
+
76
+ def _field_type(s: Slot) -> Optional[str]:
77
+ if s.present is Bound.NEVER:
78
+ return None
79
+ from prograph.plan.ir.cypher_lists import value_type
80
+ t = value_type(s) # a list's is its `list_type`
81
+ from prograph.plan.ir.cypher_mixed import has_mixed
82
+ if has_mixed(t):
83
+ raise NotBuilt("a map holding values of several types (a mixed list or value)")
84
+ if t is None:
85
+ raise NotBuilt("a map holding a value that is not one plain type (a map, node or mixed)")
86
+ if not _holdable(t):
87
+ raise NotBuilt("a map holding a temporal value, a node or a relationship")
88
+ return t
89
+
90
+
91
+ def _holdable(t: Optional[str]) -> bool:
92
+ """Whether a map holds values of type `t` as a struct field: plain values, and lists and maps of them."""
93
+ from prograph.plan.ir.cypher_lists import element_of, nested
94
+ if t is None:
95
+ return True
96
+ if nested(t):
97
+ return _holdable(element_of(t))
98
+ if is_map_type(t):
99
+ return all(_holdable(f) for f in type_fields(t).values())
100
+ return not t.startswith("urn:prograph:cypher:")
101
+
102
+
103
+ def _literal_slot(keys: List[str], values: List[Slot]) -> Slot:
104
+ """A map literal's slot from its keys and its values' slots."""
105
+ if len(set(keys)) != len(keys):
106
+ raise NotBuilt("a map literal with a key twice")
107
+ if len({k.lower() for k in keys}) != len(keys):
108
+ # Struct field names are case-insensitive on DuckDB and Spark; Cypher's keys are not.
109
+ raise NotBuilt("a map of two keys that differ only in case")
110
+ fields = {k: _field_type(v) for k, v in zip(keys, values)}
111
+ digits = tuple(v.digits for k, v in sorted(zip(keys, values), key=lambda kv: kv[0])
112
+ if fields[k] == xsd.DECIMAL) or None
113
+ return map_slot(fields, Bound.NEVER, digits)
114
+
115
+
116
+ def map_call_slot(e: E.Call, slots: Mapping[str, Slot]) -> Slot:
117
+ if e.name == "MAP":
118
+ keys = [k.value for k in e.args[0::2]]
119
+ return _literal_slot(keys, [expr_slot(v, slots) for v in e.args[1::2]])
120
+ direct = _direct(e)
121
+ if direct is not None:
122
+ return expr_slot(direct, slots)
123
+ if _element(e):
124
+ return _element_slot(e, slots)
125
+ literal = _literal_key(e)
126
+ if literal is not None:
127
+ return expr_slot(literal, slots)
128
+ base = expr_slot(e.args[0], slots)
129
+ if base.present is Bound.NEVER:
130
+ return NOTHING
131
+ if e.name == "PROPERTIES": # properties(m) of a map is the map (Neo4j)
132
+ if base.kinds != {MAP}:
133
+ raise NotBuilt("properties() of a value that is not a node, a relationship or a map")
134
+ return base
135
+ from prograph.plan.ir.cypher_temporal import TEMPORAL, _FIELDS, field_of
136
+ if e.name == "FIELD" and isinstance(e.args[0], E.Const) and base.kinds == {VALUE} and base.datatype in TEMPORAL:
137
+ from prograph.plan.ir.facts import const_slot
138
+ value = field_of(e.args[0].value, e.args[1].value) # a literal's field, at planning
139
+ return NOTHING if value is None else const_slot(value)
140
+ if e.name == "FIELD" and base.kinds == {VALUE} and base.datatype in TEMPORAL:
141
+ from prograph.plan.ir.cypher_temporal import CYPHER_LOCALDATETIME, CYPHER_LOCALTIME, _TIME_FIELDS
142
+ from prograph.plan.ir.cypher_temporal import CYPHER_DURATION, CYPHER_TIME, _DURATION_FIELDS
143
+ if base.datatype == CYPHER_DURATION:
144
+ return value_slot(xsd.INTEGER, Bound.MAYBE) if e.args[1].value in _DURATION_FIELDS else NOTHING
145
+ if base.datatype == CYPHER_TIME and e.args[1].value in _TIME_FIELDS:
146
+ return value_slot(xsd.INTEGER, Bound.MAYBE)
147
+ from prograph.plan.ir.cypher_temporal import CYPHER_DATETIME
148
+ if base.datatype in (CYPHER_TIME, CYPHER_DATETIME) and e.args[1].value in ("offset", "timezone"):
149
+ return value_slot(xsd.STRING, Bound.MAYBE)
150
+ if base.datatype == CYPHER_TIME:
151
+ return value_slot(xsd.INTEGER, Bound.MAYBE) if e.args[1].value in ("offsetSeconds", "offsetMinutes") \
152
+ else NOTHING
153
+ keys = _TIME_FIELDS if base.datatype == CYPHER_LOCALTIME else \
154
+ {**_FIELDS, **_TIME_FIELDS} if base.datatype == CYPHER_LOCALDATETIME else \
155
+ {**_FIELDS, **_TIME_FIELDS, "offsetSeconds": 0, "offsetMinutes": 0, "epochSeconds": 0, "epochMillis": 0} \
156
+ if base.datatype == CYPHER_DATETIME else _FIELDS
157
+ return value_slot(xsd.INTEGER, Bound.MAYBE) if e.args[1].value in keys else NOTHING
158
+ from prograph.plan.ir.cypher_answer import element_base, property_slot
159
+ if e.name == "FIELD" and base.kinds == {VALUE} and element_base(base.datatype) is not None:
160
+ return property_slot(base.datatype, e.args[1].value) # a node or relationship held as a value
161
+ if base.kinds != {MAP}:
162
+ what = 'a key lookup' if e.name == 'FIELD' else 'keys()'
163
+ from prograph.plan.ir.cypher_runtime_errors import RuntimeTypeError, known_kind
164
+ if known_kind(base):
165
+ raise RuntimeTypeError(0, "InvalidArgumentType", f"{what} on a value that is not a map")
166
+ raise NotBuilt(f"{what} on a value that is not a map")
167
+ fields = fields_of(base)
168
+ if e.name == "KEYS":
169
+ return list_slot(xsd.STRING, Bound.NEVER if base.present is Bound.ALWAYS else Bound.MAYBE)
170
+ t = fields.get(e.args[1].value)
171
+ from prograph.plan.ir.cypher_lists import element_of, nested
172
+ if nested(t):
173
+ return list_slot(element_of(t), Bound.MAYBE)
174
+ if is_map_type(t):
175
+ return map_slot(type_fields(t), Bound.MAYBE)
176
+ return NOTHING if t is None else value_slot(t, Bound.MAYBE)
177
+
178
+
179
+ def _element(e: E.Call) -> bool:
180
+ """keys(x) or properties(x) of a node or relationship of the pattern (the front end's `NODE(...)` or
181
+ `REL(...)` value)."""
182
+ return e.name in ("KEYS", "PROPERTIES") and isinstance(e.args[0], E.Call) and e.args[0].name in ("NODE", "REL")
183
+
184
+
185
+ def _element_properties(x: E.Call):
186
+ """The (key, value expression) of the properties a `NODE(...)` or `REL(...)` lists, in name order."""
187
+ rest = x.args[1:] if x.name == "NODE" else x.args[4:]
188
+ return sorted(((k.value, v) for k, v in zip(rest[0::2], rest[1::2]) if not k.value.startswith("label:")),
189
+ key=lambda kv: kv[0])
190
+
191
+
192
+ def _direct(e: E.Call) -> Optional[E.Expr]:
193
+ """`properties(n).k` is n's property k, and `keys(properties(n))` is keys(n): read from the element's
194
+ own columns, not from the map `properties(n)` builds."""
195
+ if e.name not in ("FIELD", "KEYS") or not (isinstance(e.args[0], E.Call) and e.args[0].name == "PROPERTIES"
196
+ and _element(e.args[0])):
197
+ return None
198
+ element = e.args[0].args[0]
199
+ if e.name == "KEYS":
200
+ return E.Call("KEYS", (element,), E.CYPHER)
201
+ for k, v in _element_properties(element):
202
+ if k == e.args[1].value:
203
+ return v
204
+ return E.Const(None)
205
+
206
+
207
+ def _literal_key(e: E.Call) -> Optional[E.Expr]:
208
+ """`m.k` of a map literal: the key's own expression, null where the literal has no such key (keys are
209
+ case-sensitive: `{name: 1, Name: 2}.Name` is 2), read without building the map (whose struct field names
210
+ could not hold two keys that differ only in case)."""
211
+ base = e.args[0] if e.name == "FIELD" else None
212
+ if not (isinstance(base, E.Call) and base.name == "MAP"):
213
+ return None
214
+ names = [k.value for k in base.args[0::2]]
215
+ if len(set(names)) != len(names):
216
+ raise NotBuilt("a map literal with a key twice")
217
+ for k, v in zip(base.args[0::2], base.args[1::2]):
218
+ if k.value == e.args[1].value:
219
+ return v
220
+ return E.Const(None)
221
+
222
+
223
+ def _element_slot(e: E.Call, slots: Mapping[str, Slot]) -> Slot:
224
+ """properties(n) is a map of the keys n has (a null element's is null); keys(n) a list of text."""
225
+ if e.name == "KEYS":
226
+ return list_slot(xsd.STRING, Bound.MAYBE)
227
+ from prograph.plan.ir.cypher_answer import PROPS_TYPE, element_type, props_slot
228
+ # Its keys and their types, which PostgreSQL's answer is laid out from (rule cypher-result-values).
229
+ values = {k: expr_slot(v, slots) for k, v in _element_properties(e.args[0])}
230
+ return props_slot(element_type(PROPS_TYPE, list(values.items())))
231
+
232
+
233
+ def _element_cell(e: E.Call, cells: Dict[str, "L.Cell"]) -> "L.Cell":
234
+ """properties(n): a map of the keys n has (`cypher_answer.properties_map`); keys(n): the keys
235
+ n holds (a Cypher element has no null property: a null field is a key it lacks), in name order. Both
236
+ null for a null element (an OPTIONAL MATCH that found none)."""
237
+ from prograph.plan.ir import lower as L
238
+ from prograph.plan.sql import rel_algebra as R
239
+ x = e.args[0]
240
+ identity = L.expr_cell(x.args[0], cells)
241
+ props = _element_properties(x)
242
+ values = {k: L.expr_cell(v, cells) for k, v in props}
243
+ slot = _element_slot(e, {n: c.slot for n, c in cells.items()})
244
+ if e.name == "KEYS":
245
+ from prograph.plan.ir.cypher_answer import _keys
246
+ _keys([k for k, _ in props], "node" if x.name == "NODE" else "relationship")
247
+ held = [L.case(L.is_null(values[k].value, negated=True), L.text(k))
248
+ for k, _ in props if values[k].slot.present is not Bound.NEVER]
249
+ listed = L.fn("ARRAY", *held)
250
+ if held:
251
+ var = R.LitExpr(value="_key", sql="_key") # the lambda variable
252
+ listed = L.fn("LIST_FILTER", listed, var, L.is_null(var, negated=True))
253
+ return L.Cell(slot, L.case(L.is_null(identity.value), L.NULL, listed))
254
+ from prograph.plan.ir.cypher_answer import _id_part, _property_values, element_shape, properties_map
255
+ cell = L.Cell(slot, L.case(L.is_null(identity.value), L.NULL,
256
+ properties_map([(k, values[k]) for k, _ in props], "node" if x.name == "NODE" else
257
+ "relationship", L)))
258
+ shape = element_shape(slot, L)
259
+ if shape is None:
260
+ return cell
261
+ from dataclasses import replace
262
+ return replace(cell, parts=(_id_part(identity, L),) + _property_values(shape, values, L))
263
+
264
+
265
+ _FIELD_FN = {"long": "CYPHER_FIELD_LONG", "double": "CYPHER_FIELD_DOUBLE", "string": "CYPHER_FIELD_STRING",
266
+ "boolean": "CYPHER_FIELD_BOOLEAN"}
267
+
268
+
269
+ def map_call_cell(e: E.Call, cells: Dict[str, "L.Cell"]) -> "L.Cell":
270
+ from prograph.plan.ir import lower as L
271
+ if e.name == "MAP":
272
+ # Each value lowered once and the map's slot from theirs (a slot worked out again at each level
273
+ # of a nested literal is exponential in its depth).
274
+ keys = [k.value for k in e.args[0::2]]
275
+ values = {k: L.expr_cell(v, cells) for k, v in zip(keys, e.args[1::2])}
276
+ slot = _literal_slot(keys, [values[k].slot for k in keys])
277
+ parts: List["R.Expr"] = []
278
+ # Keys in name order: maps of the same keys are one struct type (an array's elements).
279
+ for k in sorted(keys):
280
+ cell = values[k]
281
+ parts += [L.text(k), cell.value if cell.slot.present is not Bound.NEVER else L.NULL]
282
+ from prograph.plan.ir.cypher_answer import element_shape, map_value_parts
283
+ shape = element_shape(slot, L) # PostgreSQL: the map's columns, beside the jsonb value
284
+ columns = map_value_parts(shape, values, L) if shape is not None else ()
285
+ return L.Cell(slot, L.fn("NAMED_STRUCT", *parts), parts=columns)
286
+ direct = _direct(e)
287
+ if direct is not None:
288
+ return L.expr_cell(direct, cells)
289
+ if _element(e):
290
+ return _element_cell(e, cells)
291
+ literal = _literal_key(e)
292
+ if literal is not None:
293
+ return L.expr_cell(literal, cells)
294
+ slot = map_call_slot(e, {n: c.slot for n, c in cells.items()})
295
+ if slot.present is Bound.NEVER:
296
+ return L.nothing()
297
+ base = e.args[0]
298
+ if e.name == "PROPERTIES":
299
+ return L.expr_cell(base, cells)
300
+ if e.name == "KEYS":
301
+ keys = sorted(fields_of(L.expr_cell(base, cells).slot))
302
+ value = L.fn("ARRAY", *(L.text(k) for k in keys)) if keys else L.fn("ARRAY")
303
+ return L.Cell(slot, L.case(L.is_null(L.expr_cell(base, cells).value), L.NULL, value))
304
+ key = e.args[1].value
305
+ from prograph.plan.ir.cypher_temporal import (TEMPORAL, CypherDate, CypherDateTime, CypherDuration,
306
+ CypherLocalDateTime, CypherLocalTime, CypherTime, field_cell, field_of)
307
+ if isinstance(base, E.Const) and isinstance(base.value, (CypherDate, CypherLocalTime, CypherLocalDateTime,
308
+ CypherTime, CypherDateTime, CypherDuration)):
309
+ return L.const_cell(field_of(base.value, key))
310
+ if L.expr_cell(base, cells).slot.datatype in TEMPORAL:
311
+ return field_cell(key, L.expr_cell(base, cells))
312
+ from prograph.plan.ir.cypher_answer import element_base, property_cell
313
+ if element_base(L.expr_cell(base, cells).slot.datatype) is not None:
314
+ return property_cell(L.expr_cell(base, cells), key)
315
+ return _read(L.expr_cell(base, cells), key, slot)
316
+
317
+
318
+ def _read(cell: "L.Cell", key: str, slot: Slot) -> "L.Cell":
319
+ """A map value's key, typed as its slot records it."""
320
+ from prograph.plan.ir import lower as L
321
+ t = fields_of(cell.slot)[key]
322
+ from prograph.plan.ir.cypher_lists import nested
323
+ if nested(t) or is_map_type(t):
324
+ from prograph.plan.ir.strings import _dialect_has
325
+ if not _dialect_has("CYPHER_FIELD_VALUE"):
326
+ raise NotBuilt("a map's list or map read back on PostgreSQL (a jsonb value)")
327
+ return L.Cell(slot, L.fn("CYPHER_FIELD_VALUE", cell.value, L.text(key)))
328
+ kind = "long" if t in _INTEGERS else "double" if t in (xsd.DOUBLE, xsd.FLOAT) else \
329
+ "string" if t == xsd.STRING else "boolean" if t == xsd.BOOLEAN else None
330
+ if kind is None:
331
+ raise NotBuilt(f"a map's {t} value read back")
332
+ return L.Cell(slot, L.fn(_FIELD_FN[kind], cell.value, L.text(key)))
333
+
334
+
335
+ def map_equality(op: str, a: "L.Cell", b: "L.Cell") -> "R.Expr":
336
+ """`=` and `<>` of two maps (openCypher 9 equality): null where a map is null; false for two key sets;
337
+ else false where a key's values are unequal, else null where a key's equality is null (a null value
338
+ among them), else true. A map against a value of another kind: `=` false, `<>` true. Maps are not
339
+ ordered (`<`, `>` null)."""
340
+ from prograph.plan.ir import lower as L
341
+ from prograph.plan.sql import rel_algebra as R
342
+ if a.slot.present is Bound.NEVER or b.slot.present is Bound.NEVER:
343
+ return L.NULL_BOOLEAN
344
+ nulls = L.any_of([L.is_null(c.value) for c in (a, b)])
345
+ if a.slot.kinds != {MAP} or b.slot.kinds != {MAP} or op not in ("=", "!="):
346
+ differ = {"=": L.FALSE, "!=": L.TRUE}.get(op, L.NULL_BOOLEAN) \
347
+ if a.slot.kinds != {MAP} or b.slot.kinds != {MAP} else L.NULL_BOOLEAN
348
+ return L.case(nulls, L.NULL_BOOLEAN, differ)
349
+ fa, fb = fields_of(a.slot), fields_of(b.slot)
350
+ if set(fa) != set(fb):
351
+ eq = L.case(nulls, L.NULL_BOOLEAN, L.FALSE)
352
+ else:
353
+ pairs = []
354
+ for k in sorted(fa):
355
+ x = _value(a, k, fa[k])
356
+ y = _value(b, k, fb[k])
357
+ pairs.append(L.cypher_compare("=", x, y))
358
+ unequal = [L.fn("COALESCE", R.NotExpr(child=p), L.FALSE) for p in pairs]
359
+ unknown = [L.is_null(p) for p in pairs]
360
+ eq = L.case(nulls, L.NULL_BOOLEAN, *([L.any_of(unequal), L.FALSE] if pairs else []),
361
+ *([L.any_of(unknown), L.NULL_BOOLEAN] if pairs else []), L.TRUE)
362
+ return eq if op == "=" else R.NotExpr(child=eq)
363
+
364
+
365
+ def _value(cell: "L.Cell", key: str, t: Optional[str]) -> "L.Cell":
366
+ from prograph.plan.ir import lower as L
367
+ from prograph.plan.ir.cypher_lists import typed_slot
368
+ if t is None:
369
+ return L.nothing()
370
+ return _read(cell, key, typed_slot(t, Bound.MAYBE))