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,501 @@
1
+ """PostgreSQL SQL Serializer.
2
+
3
+ Subclasses ``SparkSQLSerializer`` to emit PostgreSQL-compatible SQL.
4
+ About 80% of the serialization logic is shared; this module overrides
5
+ the ~6 methods that differ between Spark SQL and PostgreSQL.
6
+
7
+ Key differences:
8
+
9
+ - Identifier quoting: double-quotes instead of backticks
10
+ - No ``LEFT ANTI JOIN``: use ``LEFT JOIN ... WHERE x IS NULL``
11
+ - No ``LEFT SEMI JOIN``, use ``WHERE EXISTS (SELECT 1 ...)``
12
+ - No ``LATERAL VIEW EXPLODE``, use ``CROSS JOIN LATERAL unnest()``
13
+ - No ``/*+ BROADCAST(...) */`` hints
14
+ - Different function names and type keywords
15
+
16
+ Architecture:
17
+
18
+ RelNode tree → Optimizer → PostgreSQLSerializer → PostgreSQL SQL string
19
+ """
20
+
21
+ from __future__ import annotations
22
+
23
+ import re
24
+ from typing import List, Optional
25
+
26
+ from .rel_algebra import (
27
+ AntiJoin,
28
+ ColumnRef,
29
+ ColExpr,
30
+ Expr,
31
+ FuncExpr,
32
+ LitExpr,
33
+ LateralExplode,
34
+ RelNode,
35
+ Scan,
36
+ SemiJoin,
37
+ SetOperation,
38
+ SortKey,
39
+ SortDirection,
40
+ NullsOrder,
41
+ WithClause,
42
+ )
43
+ from .sql_serializer import (
44
+ ExprSerializer,
45
+ QueryFrame,
46
+ SparkSQLSerializer,
47
+ _CAST_FUNCTIONS,
48
+ )
49
+ from .dialect import POSTGRESQL_DIALECT, safe_alias, unquoted_name
50
+
51
+
52
+ # =========================================================================
53
+ # PostgreSQL CAST type mappings
54
+ # =========================================================================
55
+
56
+ _PG_CAST_FUNCTIONS = {
57
+ 'CAST_INT': 'INTEGER',
58
+ 'CAST_DOUBLE': 'DOUBLE PRECISION',
59
+ 'CAST_STRING': 'VARCHAR',
60
+ 'CAST_LONG': 'BIGINT',
61
+ 'CAST_WHOLE_DECIMAL': 'NUMERIC(38,0)',
62
+ 'CAST_PATH_STRING': 'VARCHAR',
63
+ 'CAST_BOOLEAN': 'BOOLEAN',
64
+ 'CAST_TIMESTAMP': 'TIMESTAMP',
65
+ 'CAST_DATE': 'DATE',
66
+ }
67
+
68
+
69
+ class PostgreSQLExprSerializer(ExprSerializer):
70
+ """Serialize Expr nodes to PostgreSQL SQL strings.
71
+
72
+ Overrides ``_func_expr`` to translate Spark-centric IR function names
73
+ to their PostgreSQL equivalents.
74
+
75
+ ``is_duckdb`` selects DuckDB-specific spellings where DuckDB is strictly
76
+ more capable than PostgreSQL (currently: named struct literals).
77
+ """
78
+
79
+ def __init__(self, is_duckdb: bool = False, dialect=None):
80
+ from .dialect import get_dialect_instance
81
+ super().__init__(dialect or get_dialect_instance('duckdb' if is_duckdb else 'postgresql'))
82
+ self._is_duckdb = is_duckdb
83
+
84
+ def _func_expr(self, expr: FuncExpr) -> str:
85
+ name = expr.name
86
+ args = expr.args
87
+
88
+ # ---- PostgreSQL CAST types ----
89
+ if name in _PG_CAST_FUNCTIONS:
90
+ target_type = _PG_CAST_FUNCTIONS[name]
91
+ inner = self.serialize(args[0])
92
+ return f"CAST({inner} AS {target_type})"
93
+
94
+ # ---- COLLECT_LIST → array_agg ----
95
+ # Cypher collect() drops NULL inputs; Postgres/DuckDB array_agg keeps
96
+ # them, so filter explicitly. (Spark collect_list skips NULLs natively,
97
+ # so the base serializer needs no filter.)
98
+ if name == 'COLLECT_LIST':
99
+ inner = self.serialize(args[0])
100
+ return f"array_agg({inner}) FILTER (WHERE {self._operand(args[0])} IS NOT NULL)"
101
+
102
+ # ---- COLLECT_SET → array_agg(DISTINCT ...) ----
103
+ if name == 'COLLECT_SET':
104
+ inner = self.serialize(args[0])
105
+ return f"array_agg(DISTINCT {inner}) FILTER (WHERE {self._operand(args[0])} IS NOT NULL)"
106
+
107
+ # ---- Struct field access: (base)."field" on DuckDB ----
108
+ # PostgreSQL's ROW has no field names to read back; its dialect map
109
+ # refuses '.' before this is reached.
110
+ if name == '.' and len(args) == 2 and self._is_duckdb:
111
+ base = self.serialize(args[0])
112
+ field = args[1].sql if isinstance(args[1], LitExpr) else self.serialize(args[1])
113
+ return f"({base}).{_backtick_to_dquote_escaped(field)}"
114
+
115
+ # ---- NAMED_STRUCT → ROW (Postgres) / struct literal (DuckDB) ----
116
+ if name == 'NAMED_STRUCT':
117
+ if self._is_duckdb:
118
+ # DuckDB has named struct literals: {'k1': v1, 'k2': v2}.
119
+ # Preserve the field names so a map literal round-trips as a
120
+ # dict (fetchall returns a Python dict), not a positional tuple.
121
+ if not args:
122
+ # `{}` does not parse and a struct has no zero-field
123
+ # form; the empty map is DuckDB's empty MAP.
124
+ return "MAP {}"
125
+ pairs = [
126
+ f"{self.serialize(args[i])}: {self.serialize(args[i + 1])}"
127
+ for i in range(0, len(args) - 1, 2)
128
+ ]
129
+ return f"{{{', '.join(pairs)}}}"
130
+ # PostgreSQL: a jsonb object keeps the field names (an anonymous
131
+ # ROW lost them and came back as a tuple); the ADBC driver returns
132
+ # it as JSON text (decision D8).
133
+ return f"jsonb_build_object({', '.join(self.serialize(a) for a in args)})"
134
+
135
+ # ---- ELEMENT_AT → arr[n] ----
136
+ if name == 'ELEMENT_AT':
137
+ arr = self.serialize(args[0])
138
+ idx = self.serialize(args[1])
139
+ return f"{arr}[{idx}]"
140
+
141
+ # ---- SIZE → array_length(arr, 1) ----
142
+ if name == 'SIZE':
143
+ arr = self.serialize(args[0])
144
+ if self._is_duckdb:
145
+ return f"array_length({arr}, 1)"
146
+ # PostgreSQL's array_length of an empty array is NULL; size([])
147
+ # is 0. cardinality() is 0 there and NULL for a NULL array; it is
148
+ # an int4, and an integer is a BIGINT, as on every other engine.
149
+ return f"CAST(cardinality({arr}) AS BIGINT)"
150
+
151
+ # ---- MONTHS_BETWEEN → EXTRACT-based ----
152
+ if name == 'MONTHS_BETWEEN':
153
+ end = self.serialize(args[0])
154
+ start = self.serialize(args[1])
155
+ return (
156
+ f"(EXTRACT(YEAR FROM age({end}::timestamp, {start}::timestamp)) * 12"
157
+ f" + EXTRACT(MONTH FROM age({end}::timestamp, {start}::timestamp)))"
158
+ )
159
+
160
+ # ---- DATEDIFF → date subtraction ----
161
+ if name == 'DATEDIFF':
162
+ end = self.serialize(args[0])
163
+ start = self.serialize(args[1])
164
+ return f"({end}::date - {start}::date)"
165
+
166
+ # ---- ADD_MONTHS(date, n) → date + n months ----
167
+ # (Spark has a native add_months; Postgres/DuckDB use interval math.)
168
+ if name == 'ADD_MONTHS':
169
+ d = self.serialize(args[0])
170
+ n = self.serialize(args[1])
171
+ return f"(({d})::date + ({n}) * INTERVAL '1 month')"
172
+
173
+ # ---- CURRENT_DATE() → CURRENT_DATE (no parens), CURRENT_TIMESTAMP too:
174
+ # DuckDB has no current_timestamp() function (SPARQL NOW()) ----
175
+ if name in ('CURRENT_DATE', 'CURRENT_TIMESTAMP') and len(args) == 0:
176
+ return name
177
+
178
+ # ---- ARRAY(a, b, c) → ARRAY[a, b, c] ----
179
+ if name == 'ARRAY':
180
+ if not args and not self._is_duckdb:
181
+ # PostgreSQL gives `ARRAY[]` no type and refuses it ("cannot
182
+ # determine type of empty array"). Beside a list of a known
183
+ # element type the translator casts it to that type
184
+ # (ExprTranslator._typed_list); alone it is a list of text,
185
+ # which is what PostgreSQL makes of ARRAY[NULL].
186
+ return "CAST(ARRAY[] AS TEXT[])"
187
+ rendered = ', '.join(self.serialize(a) for a in args)
188
+ return f"ARRAY[{rendered}]"
189
+
190
+ # ---- DISTINCT aggregates ----
191
+ if name.startswith('DISTINCT_'):
192
+ real_name = name[len('DISTINCT_'):]
193
+ inner = self.serialize(args[0])
194
+ return f"{real_name}(DISTINCT {inner})"
195
+
196
+ # ---- Arithmetic operators (inherited logic) ----
197
+ from .sql_serializer import _ARITHMETIC_OPS
198
+ if name in _ARITHMETIC_OPS and len(args) == 2:
199
+ left = self.serialize(args[0])
200
+ right = self.serialize(args[1])
201
+ return f"({left} {name} {right})"
202
+
203
+ # ---- CASE (inherited) ----
204
+ if name == 'CASE':
205
+ return self._case_expr(args)
206
+ if name == 'CASE_SIMPLE':
207
+ return self._case_expr(args, simple=True)
208
+
209
+ # ---- Default: standard function call ----
210
+ rendered_args = ', '.join(self.serialize(a) for a in args)
211
+ return f"{name}({rendered_args})"
212
+
213
+ def serialize(self, expr: Expr) -> str:
214
+ """Override to convert backticks → double-quotes."""
215
+ from .rel_algebra import ColExpr
216
+
217
+ # ColExpr: replace backticks in the raw SQL expression
218
+ if isinstance(expr, ColExpr):
219
+ return _backtick_to_dquote(expr.ref.sql)
220
+
221
+ return super().serialize(expr)
222
+
223
+
224
+ class PostgreSQLSerializer(SparkSQLSerializer):
225
+ """Serialize a RelNode tree to PostgreSQL SQL.
226
+
227
+ Subclasses ``SparkSQLSerializer`` and overrides the methods that
228
+ differ between Spark SQL and PostgreSQL.
229
+ """
230
+
231
+ _alias_dialect = 'postgresql'
232
+
233
+ def __init__(self, is_duckdb: bool = False):
234
+ self._expr = PostgreSQLExprSerializer(is_duckdb=is_duckdb)
235
+ self._dialect = POSTGRESQL_DIALECT
236
+
237
+ # -----------------------------------------------------------------
238
+ # Column rendering, double-quote quoting
239
+ # -----------------------------------------------------------------
240
+
241
+ def _render_column(self, col: ColumnRef) -> str:
242
+ """Render a ColumnRef with double-quote quoting."""
243
+ expr_node = col.metadata.get('expr') if col.metadata else None
244
+ if expr_node is not None:
245
+ sql = self._value_sql(self._expr.as_value(expr_node))
246
+ else:
247
+ sql = _backtick_to_dquote(col.sql)
248
+ if col.alias:
249
+ return f'{sql} AS {self._quote_alias(col.alias)}'
250
+ return sql
251
+
252
+ def _render_sort_key(self, key: SortKey, beside=None) -> str:
253
+ """Render a SortKey with double-quote quoting; by its position
254
+ beside a select list where its name is one of two that differ by
255
+ case alone (the base class's `_render_sort_key`)."""
256
+ col = key.column
257
+ position = self._position_beside(col, beside)
258
+ expr_node = col.metadata.get('expr') if col.metadata else None
259
+ if position is not None:
260
+ ref = str(position)
261
+ elif expr_node is not None and not isinstance(expr_node, ColExpr):
262
+ ref = self._expr.serialize(expr_node)
263
+ elif self._named_by_itself(col):
264
+ ref = self._quote_alias(col.alias)
265
+ elif col.sql and col.sql != '<sort_expr>':
266
+ ref = _backtick_to_dquote(col.sql)
267
+ elif col.alias:
268
+ ref = self._quote_alias(col.alias)
269
+ else:
270
+ ref = _backtick_to_dquote(col.sql)
271
+ ref = self._by_code_point(key, ref, position)
272
+
273
+ direction = 'ASC' if key.direction == SortDirection.ASC else 'DESC'
274
+ return f"{ref} {direction}{self._nulls_suffix(key)}"
275
+
276
+ # -----------------------------------------------------------------
277
+ # Anti-join → LEFT JOIN ... WHERE IS NULL
278
+ # -----------------------------------------------------------------
279
+
280
+ def _collect_anti_join(self, node: AntiJoin, frame: QueryFrame) -> None:
281
+ """PostgreSQL doesn't support LEFT ANTI JOIN.
282
+
283
+ Emits LEFT JOIN + WHERE ... IS NULL instead.
284
+ """
285
+ self._collect_from(node.child, frame)
286
+
287
+ right_clause = self._render_from_node(node.right)
288
+ conditions = ' AND '.join(
289
+ self._expr.serialize(c) for c in node.on
290
+ )
291
+ frame.joins.append(
292
+ f"LEFT JOIN {right_clause} ON {conditions}"
293
+ )
294
+ if node.null_check:
295
+ frame.where_conditions.append(
296
+ self._expr.serialize(node.null_check)
297
+ )
298
+
299
+ if node.second_right:
300
+ right2_clause = self._render_from_node(node.second_right)
301
+ conditions2 = ' AND '.join(
302
+ self._expr.serialize(c) for c in node.second_on
303
+ )
304
+ frame.joins.append(
305
+ f"LEFT JOIN {right2_clause} ON {conditions2}"
306
+ )
307
+ if node.second_null_check:
308
+ frame.where_conditions.append(
309
+ self._expr.serialize(node.second_null_check)
310
+ )
311
+
312
+ # -----------------------------------------------------------------
313
+ # Semi-join → WHERE EXISTS (SELECT 1 ...)
314
+ # -----------------------------------------------------------------
315
+
316
+ def _collect_semi_join(self, node: SemiJoin, frame: QueryFrame) -> None:
317
+ """PostgreSQL doesn't support LEFT SEMI JOIN.
318
+
319
+ Emits WHERE EXISTS (SELECT 1 FROM ... WHERE ...) instead.
320
+ """
321
+ self._collect_from(node.child, frame)
322
+
323
+ right_clause = self._render_from_node(node.right)
324
+ conditions = ' AND '.join(
325
+ self._expr.serialize(c) for c in node.on
326
+ )
327
+ frame.where_conditions.append(
328
+ f"EXISTS (SELECT 1 FROM {right_clause} WHERE {conditions})"
329
+ )
330
+
331
+ # -----------------------------------------------------------------
332
+ # Lateral explode → CROSS JOIN LATERAL unnest()
333
+ # -----------------------------------------------------------------
334
+
335
+ def _collect_lateral_explode(
336
+ self, node: LateralExplode, frame: QueryFrame
337
+ ) -> None:
338
+ """PostgreSQL uses CROSS JOIN LATERAL unnest() instead of LATERAL VIEW."""
339
+ self._collect_from(node.child, frame)
340
+
341
+ list_sql = self._expr.serialize(self._expr.as_value(node.list_expr))
342
+ alias = node.element_alias
343
+ if node.more:
344
+ # The list and its parts' arrays exploded in step (an array of nodes, with the arrays of their ids,
345
+ # labels and properties), each element's position beside them.
346
+ arrays = [list_sql] + [self._expr.serialize(self._expr.as_value(e)) for e, _ in node.more]
347
+ names = [alias] + [a for _, a in node.more] + ([node.ordinal_alias] if node.ordinal_alias else [])
348
+ frame.joins.append(
349
+ f'CROSS JOIN LATERAL unnest({", ".join(arrays)}) WITH ORDINALITY AS "{alias}__u"'
350
+ f'({", ".join(chr(34) + n + chr(34) for n in names)})')
351
+ return
352
+ source = self._from_alias(frame.from_clause) if getattr(self._expr, '_is_duckdb', False) and not frame.joins else None
353
+ if source is not None:
354
+ # DuckDB decorrelates a LATERAL unnest into a join that
355
+ # materializes its whole input first, list and all, so a LIMIT
356
+ # cannot stop it: C160's two UNWINDs over each person's forums
357
+ # ran out of memory. An unnest in the select list streams (0.8 s).
358
+ # The same rows either way: a NULL or empty list gives none, a
359
+ # NULL element is kept. The subquery keeps the source's alias, so
360
+ # references to it still resolve.
361
+ frame.from_clause = (f'(SELECT {source}.*, unnest({list_sql}) AS "{alias}" '
362
+ f'FROM {frame.from_clause}) AS {source}')
363
+ return
364
+ # Name both the correlation AND its column. With only a table alias
365
+ # (`AS "x"`), DuckDB exposes the unnested column under the function name
366
+ # (`unnest`), so `SELECT "x"` yields the whole {unnest: v} struct instead
367
+ # of the scalar. `AS "x"("x")` names the column too and works for both
368
+ # PostgreSQL and DuckDB.
369
+ frame.joins.append(
370
+ f'CROSS JOIN LATERAL unnest({list_sql}) AS "{alias}"("{alias}")'
371
+ )
372
+
373
+ @staticmethod
374
+ def _from_alias(from_clause: Optional[str]) -> Optional[str]:
375
+ """The name a FROM item is referenced by: its alias, or a bare
376
+ CTE or table name. None when that is not plain to see."""
377
+ if not from_clause:
378
+ return None
379
+ m = re.search(r'\s+AS\s+("[^"]+"|\w+)\s*$', from_clause, re.I)
380
+ if m:
381
+ return m.group(1)
382
+ return from_clause if re.fullmatch(r'"[^"]+"|\w+', from_clause.strip()) else None
383
+
384
+ # -----------------------------------------------------------------
385
+ # GROUP BY quoting
386
+ # -----------------------------------------------------------------
387
+
388
+ def _group_by_column(self, sql: str) -> str:
389
+ return _backtick_to_dquote(sql)
390
+
391
+ # -----------------------------------------------------------------
392
+ # WITH RECURSIVE for recursive CTEs
393
+ # -----------------------------------------------------------------
394
+
395
+ def _cte_suffix(self, cte) -> str:
396
+ """After a CTE's definition: PostgreSQL 14's CYCLE clause, when the
397
+ CTE asks for one."""
398
+ cycle_cols = getattr(cte, 'cycle_columns', None)
399
+ if cycle_cols:
400
+ cols = ', '.join(f'"{c}"' for c in cycle_cols)
401
+ return f' CYCLE {cols} SET "is_cycle" USING "_path"'
402
+ return ""
403
+
404
+ def _cte_column_list(self, cte) -> str:
405
+ """A CTE's column list; none here. Oracle needs one on a recursive
406
+ CTE."""
407
+ return ""
408
+
409
+ def _serialize_with(self, node: WithClause) -> str:
410
+ """Serialize WITH clause, using WITH RECURSIVE when needed.
411
+
412
+ Appends CYCLE clause for CTEs with cycle_columns (PostgreSQL 14+).
413
+ """
414
+ has_recursive = any(
415
+ getattr(cte, 'recursive', False) for cte in node.ctes
416
+ )
417
+ keyword = self._recursive_with if has_recursive else "WITH"
418
+
419
+ cte_strs = []
420
+ for cte in node.ctes:
421
+ with self._kept_frame() as kept:
422
+ cte_sql = self._cte_body(cte, self._below_the_result(
423
+ self.serialize, cte.definition), has_recursive)
424
+ cte_strs.extend(kept)
425
+ cte_part = (f"{cte.name}{self._cte_column_list(cte)} AS "
426
+ f"{self._before_a_cte(cte)}({cte_sql})")
427
+ cte_part += self._cte_suffix(cte)
428
+ cte_strs.append(cte_part)
429
+
430
+ with self._kept_frame() as kept:
431
+ body_sql = self.serialize(node.body)
432
+ cte_strs.extend(kept)
433
+ cte_preamble = f"{keyword} {', '.join(cte_strs)}"
434
+ return f"{cte_preamble}\n{body_sql}"
435
+
436
+ # -----------------------------------------------------------------
437
+ # FROM node rendering, double-quote quoting for subquery aliases
438
+ # -----------------------------------------------------------------
439
+
440
+ def _render_from_node(self, node: RelNode) -> str:
441
+ """Render a node as a FROM/JOIN target with double-quote quoting."""
442
+ if isinstance(node, Scan):
443
+ return self._scan_ref(node)
444
+
445
+ from .rel_algebra import CteRef
446
+ if isinstance(node, CteRef):
447
+ return node.cte_name
448
+
449
+ if isinstance(node, SetOperation):
450
+ sub_sql = self._serialize_set_op(node)
451
+ alias = node.alias or '_sub'
452
+ return f'({sub_sql}) AS "{safe_alias(alias)}"'
453
+
454
+ raise NotImplementedError(f"one-plan: {type(node).__name__} as a FROM target")
455
+
456
+ # -----------------------------------------------------------------
457
+ # SetOperation subquery wrapping, double-quote alias
458
+ # -----------------------------------------------------------------
459
+
460
+ def _collect_from(
461
+ self, node: RelNode, frame: QueryFrame, *, top_level: bool = False,
462
+ ) -> None:
463
+ """Walk the remaining tree, override to use double-quote aliases."""
464
+ if isinstance(node, SetOperation):
465
+ sub_sql = self._serialize_set_op(node)
466
+ alias = node.alias or '_sub'
467
+ frame.from_clause = f'({sub_sql}) AS "{safe_alias(alias)}"'
468
+ else:
469
+ super()._collect_from(node, frame, top_level=top_level)
470
+
471
+
472
+ # =========================================================================
473
+ # Utility
474
+ # =========================================================================
475
+
476
+ def _backtick_to_dquote_escaped(identifier: str) -> str:
477
+ """One backtick-quoted identifier (Spark's doubled-backtick escape) as a
478
+ double-quoted one, a double quote inside doubled."""
479
+ return '"' + unquoted_name(identifier).replace('"', '""') + '"'
480
+
481
+
482
+ # A string literal (a quote inside doubled) or one identifier in the
483
+ # interpreter's backtick form (a backtick inside doubled, `internal_name`).
484
+ _LITERAL_OR_BACKTICK_NAME = re.compile(r"'(?:[^']|'')*'|`(?:[^`]|``)*`")
485
+
486
+
487
+ def _backtick_to_dquote(sql: str) -> str:
488
+ """Replace backtick-quoted identifiers with double-quote quoted ones.
489
+
490
+ The IR tree bakes backtick quoting into ColumnRef.sql values from tree
491
+ construction (~146 occurrences). Rather than refactoring all those sites,
492
+ the PostgreSQL serializer rewrites them at render time, each one whole:
493
+ a doubled backtick inside is one backtick and a double quote inside is
494
+ doubled (docs/architecture/rules.md, SQL identifiers). Swapping the
495
+ characters one for one wrote a property named `a"b` as `p."a"b"`, a
496
+ parser error, and ``p.`order` % 2``, a column named by its text, as a
497
+ name that ended at its second quote. A string literal
498
+ is left as it is."""
499
+ return _LITERAL_OR_BACKTICK_NAME.sub(
500
+ lambda m: m.group(0) if m.group(0)[0] == "'" else _backtick_to_dquote_escaped(m.group(0)),
501
+ sql)