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,1419 @@
1
+ """SQL Serializer: RelNode tree → SQL string.
2
+
3
+ Converts a relational algebra tree (produced by TreeBuilder) into a Spark SQL
4
+ string. This is a read-only tree walk, no mutation, no state accumulation.
5
+
6
+ Architecture:
7
+
8
+ RelNode tree
9
+ │
10
+ ▼
11
+ SparkSQLSerializer.serialize(tree)
12
+ │
13
+ ├── WithClause → WITH preamble + recurse CTE defs + body
14
+ ├── SetOperation → recurse branches, join with UNION ALL
15
+ └── Otherwise → _serialize_query(tree)
16
+ │
17
+ ├── Peel spine top-down: Limit → Sort → Project → Aggregate → child
18
+ ├── Collect: limit, offset, sort_keys, select_cols, distinct, group_by
19
+ ├── _collect_from(child, frame)
20
+ │ ├── Scan → FROM table AS alias
21
+ │ ├── CteRef → FROM cte_name
22
+ │ ├── Values → FROM (SELECT 1) AS _base
23
+ │ ├── Filter → recurse child, add WHERE
24
+ │ ├── Join → recurse left, add JOIN right
25
+ │ ├── AntiJoin → LEFT ANTI JOIN
26
+ │ ├── SemiJoin → LEFT SEMI JOIN
27
+ │ ├── LateralExplode → LATERAL VIEW explode(...)
28
+ │ └── Other → wrap as subquery fallback
29
+ └── QueryFrame.to_sql() → assemble final SQL
30
+ """
31
+
32
+ from __future__ import annotations
33
+
34
+ from contextlib import contextmanager
35
+ import re
36
+ from dataclasses import dataclass, field, replace
37
+ from typing import Any, Dict, List, Optional
38
+
39
+ from .dialect import internal_name, scope_name, standard_string, unquoted_name
40
+ from .rel_algebra import (
41
+ RelNode,
42
+ Scan,
43
+ Values,
44
+ CteRef,
45
+ Filter,
46
+ Project,
47
+ Aggregate,
48
+ Sort,
49
+ Limit,
50
+ LateralExplode,
51
+ Join,
52
+ AntiJoin,
53
+ SemiJoin,
54
+ SetOperation,
55
+ WithClause,
56
+ CTEDef,
57
+ ColumnRef,
58
+ ColumnId,
59
+ JoinType,
60
+ SortDirection,
61
+ SortKey,
62
+ NullsOrder,
63
+ SetOp,
64
+ Expr,
65
+ ColExpr,
66
+ LitExpr,
67
+ CompareExpr,
68
+ AndExpr,
69
+ OrExpr,
70
+ NotExpr,
71
+ IsNullExpr,
72
+ FuncExpr,
73
+ ExistsExpr,
74
+ holds_a_subquery_expression,
75
+ SQLSerializer,
76
+ )
77
+ from prograph.rules import module_home
78
+
79
+ module_home("sql-from-tree", "SQL text from the tree",
80
+ terms=("serializer", "SQL text", "tree", "dialect serializer"))
81
+
82
+
83
+ # =============================================================================
84
+ # Expression Serializer
85
+ # =============================================================================
86
+
87
+ # Arithmetic operators emitted as infix binary expressions
88
+ _ARITHMETIC_OPS = {'+', '-', '*', '/', '%'}
89
+
90
+
91
+ # CAST special functions: name → target type
92
+ _CAST_FUNCTIONS = {
93
+ 'CAST_INT': 'INT',
94
+ 'CAST_DOUBLE': 'DOUBLE',
95
+ 'CAST_STRING': 'STRING',
96
+ 'CAST_LONG': 'LONG',
97
+ 'CAST_WHOLE_DECIMAL': 'DECIMAL(38,0)',
98
+ 'CAST_PATH_STRING': 'PATH_STRING',
99
+ 'CAST_BOOLEAN': 'BOOLEAN',
100
+ 'CAST_TIMESTAMP': 'TIMESTAMP',
101
+ 'CAST_DATE': 'DATE',
102
+ }
103
+
104
+
105
+ _INT32_RANGE = range(-2**31, 2**31)
106
+
107
+ # Functions whose value is one of their arguments' (`_integer_of_literals`):
108
+ # every argument, or for a CASE its results.
109
+ _A_VALUE_OF_ITS_ARGUMENTS = {
110
+ 'COALESCE', 'GREATEST', 'LEAST', 'IFNULL', 'NVL', 'MAX', 'MIN', 'ANY_VALUE',
111
+ 'FIRST', 'LAST', 'FIRST_VALUE', 'LAST_VALUE', 'ABS',
112
+ } | (_ARITHMETIC_OPS - {'/'})
113
+
114
+
115
+ def _a_null(expr: Expr) -> bool:
116
+ return isinstance(expr, LitExpr) and expr.value is None and expr.sql.upper() == 'NULL'
117
+
118
+
119
+ def _integers_of_literals(values) -> bool:
120
+ """Whether the values are integers of literals or NULL, one at least
121
+ an integer."""
122
+ integers = [v for v in values if not _a_null(v)]
123
+ return bool(integers) and all(_integer_of_literals(v) for v in integers)
124
+
125
+
126
+ def _integer_of_literals(expr: Expr) -> bool:
127
+ """Whether `expr` is a SQL integer only because of the literals in it:
128
+ a 32-bit integer literal; arithmetic, a CASE, a COALESCE or a MAX whose
129
+ values are such integers or NULL, at least one an integer; or an
130
+ element of a list of them. A column's value has its column's type and
131
+ is not one."""
132
+ if isinstance(expr, LitExpr):
133
+ value = expr.value
134
+ return (type(value) is int and value in _INT32_RANGE
135
+ and expr.sql == str(value))
136
+ if not isinstance(expr, FuncExpr):
137
+ return False
138
+ name = expr.name.upper()
139
+ if name in ('CASE', 'CASE_SIMPLE'):
140
+ args = expr.args[1:] if name == 'CASE_SIMPLE' else expr.args
141
+ return _integers_of_literals(list(args[1::2]) + ([args[-1]] if len(args) % 2 else []))
142
+ if name in _A_VALUE_OF_ITS_ARGUMENTS:
143
+ return _integers_of_literals(expr.args)
144
+ if name == 'LIST_GET' and expr.args:
145
+ listed = expr.args[0]
146
+ return (isinstance(listed, FuncExpr) and listed.name == 'ARRAY'
147
+ and _integers_of_literals(listed.args))
148
+ return False
149
+
150
+
151
+ def _condition(sql: str) -> str:
152
+ """A WHERE or HAVING condition as every dialect accepts it: an unknown
153
+ one, a bare NULL (a SPARQL FILTER that is a type error), keeps no row,
154
+ as `1 = 0`. Spark and Databricks refuse `WHERE NULL`, a filter of type
155
+ VOID (DATATYPE_MISMATCH.FILTER_NOT_BOOLEAN), and SQL Server and Oracle
156
+ have no boolean literal."""
157
+ return '1 = 0' if sql.strip().upper() == 'NULL' else sql
158
+
159
+ def end_of_input(pattern: str) -> str:
160
+ """`pattern` with every unescaped `$` outside a character class as `\\z` (Java regex: the end
161
+ of the input, where `$` also matches before a final line terminator)."""
162
+ out, i, in_class = [], 0, False
163
+ while i < len(pattern):
164
+ c = pattern[i]
165
+ if c == "\\" and i + 1 < len(pattern):
166
+ out.append(pattern[i:i + 2]); i += 2; continue
167
+ if c == "[" and not in_class:
168
+ in_class = True
169
+ elif c == "]" and in_class:
170
+ in_class = False
171
+ out.append("\\z" if c == "$" and not in_class else c)
172
+ i += 1
173
+ return "".join(out)
174
+
175
+
176
+ class ExprSerializer:
177
+ """Converts Expr nodes to SQL strings.
178
+
179
+ Given a ``Dialect``, a function the dialect's ``function_map`` names is
180
+ rendered by the dialect before any special case here or in a subclass,
181
+ so dialect-specific names live in one place.
182
+ """
183
+
184
+ def __init__(self, dialect=None):
185
+ self._dialect_obj = dialect
186
+
187
+ def as_value(self, expr: Expr) -> Expr:
188
+ """`expr` as a column of a SELECT's output or an unwound list, its
189
+ integers 64-bit (docs/architecture/rules.md, "An integer constant
190
+ is 64-bit").
191
+
192
+ A Cypher integer and a SPARQL xsd:integer are 64-bit, as a mapped
193
+ integer column is, but a SQL integer literal is a 32-bit INT on
194
+ DuckDB, Spark, Databricks, PostgreSQL and SQL Server: `RETURN 7`,
195
+ `BIND(7 AS ?k)` and `VALUES ?k {7}` came back int32 where the Python
196
+ path gives int64 (the float literal's rule in
197
+ `serialize` does the same for doubles). A value made of such
198
+ literals alone is cast whole, so the expression inside keeps the
199
+ text a GROUP BY or an ORDER BY writes it with; a list or a map of
200
+ constants has each element typed. Only a value is typed: a literal
201
+ a function reads (`round(x, 2)`, `lpad(s, 3, 'x')`, DuckDB's date
202
+ + 1) keeps the type those need, and so does one compared with a
203
+ column."""
204
+ if _integer_of_literals(expr):
205
+ return FuncExpr(name='CAST_LONG', args=(expr,))
206
+ if not isinstance(expr, FuncExpr):
207
+ return expr
208
+ name = expr.name.upper()
209
+ if name in ('COLLECT_LIST', 'COLLECT_SET') and expr.args:
210
+ # An aggregate's argument, which no GROUP BY writes.
211
+ return replace(expr, args=(self.as_value(expr.args[0]),) + tuple(expr.args[1:]))
212
+ # A list or a map has each element typed, beside a column too
213
+ # (`{a: p.v, b: 1}`, `[x IN [1, 2] WHERE x > p.v]`): a grouping key
214
+ # is written in the GROUP BY through this as well (`_value_sql` of
215
+ # a key), so the two texts stay one.
216
+ if name in ('LIST_TRANSFORM', 'LIST_FILTER') and len(expr.args) == 3:
217
+ # A comprehension: its list's elements, and what the body
218
+ # makes of each.
219
+ listed, variable, body = expr.args
220
+ if name == 'LIST_TRANSFORM':
221
+ body = self.as_value(body)
222
+ return replace(expr, args=(self.as_value(listed), variable, body))
223
+ if name in ('ARRAY', 'LIST_CONCAT'):
224
+ return replace(expr, args=tuple(self.as_value(a) for a in expr.args))
225
+ if name in ('SLICE', 'LIST_REVERSE') and expr.args:
226
+ # The list's elements; a slice's bounds are positions.
227
+ return replace(expr, args=(self.as_value(expr.args[0]),) + tuple(expr.args[1:]))
228
+ if name == 'NAMED_STRUCT':
229
+ return replace(expr, args=tuple(
230
+ self.as_value(a) if i % 2 else a for i, a in enumerate(expr.args)))
231
+ if expr.columns_referenced():
232
+ # A value that reads a column is the database's own type.
233
+ return expr
234
+ if name in _A_VALUE_OF_ITS_ARGUMENTS and name not in _ARITHMETIC_OPS:
235
+ return replace(expr, args=tuple(self.as_value(a) for a in expr.args))
236
+ return expr
237
+
238
+ def _operand(self, expr: Expr) -> str:
239
+ """An operand of a comparison or IS NULL, parenthesised when it is
240
+ itself a boolean expression. Unparenthesised, `(a AND b) = (b AND a)`
241
+ rendered as `a AND b = b AND a`, which SQL reads as
242
+ `a AND (b = b) AND a`, and `false = true IS NULL` changed meaning
243
+ the same way. `EXISTS (...) IS NOT NULL` does not
244
+ parse on Spark or Databricks."""
245
+ predicate = isinstance(expr, (AndExpr, OrExpr, NotExpr, CompareExpr, IsNullExpr,
246
+ ExistsExpr))
247
+ if predicate and not self._predicates_are_values:
248
+ from prograph.utils.exceptions import SQLGenerationError
249
+ raise SQLGenerationError(
250
+ "a predicate compared as a value has no rendering in this dialect",
251
+ reason="boolean_value_comparison")
252
+ sql = self.serialize(expr)
253
+ return f"({sql})" if predicate else sql
254
+
255
+ # Whether a predicate is a value that can be compared (`(a AND b) = c`,
256
+ # `(a = b) IS NULL`). SQL Server and Oracle have no boolean type.
257
+ _predicates_are_values = True
258
+
259
+ def serialize(self, expr: Expr) -> str:
260
+ """Convert an Expr node to a SQL string."""
261
+ if isinstance(expr, ColExpr):
262
+ return expr.ref.sql
263
+
264
+ if isinstance(expr, LitExpr):
265
+ # A string literal is quoted when the tree is built, the
266
+ # standard way; re-escape it the way the target reads it (Spark
267
+ # took 'O''Neil' as two literals). Other
268
+ # LitExprs with string values (identifiers, keywords) keep
269
+ # their SQL.
270
+ value = expr.value
271
+ if (isinstance(value, str) and self._dialect_obj is not None
272
+ and expr.sql == standard_string(value)):
273
+ return self._dialect_obj.render_string(value)
274
+ if isinstance(value, float) and not isinstance(value, bool) \
275
+ and expr.sql == str(value) and value == value and abs(value) != float('inf'):
276
+ # A Cypher float is a SQL double, not the DECIMAL a bare 2.0 is.
277
+ if self._dialect_obj is not None and self._dialect_obj.maps_function('FLOAT_LITERAL'):
278
+ return self._dialect_obj.render_function('FLOAT_LITERAL', [expr.sql])
279
+ return f"{expr.sql}D"
280
+ return expr.sql
281
+
282
+ if isinstance(expr, CompareExpr):
283
+ left = self._operand(expr.left)
284
+ right = self._operand(expr.right)
285
+ if expr.op == 'RLIKE':
286
+ # A regex search: the pattern matches some part of the
287
+ # string. A dialect that maps 'REGEX_SEARCH' writes it
288
+ # (DuckDB's `~` is a full match; Spark and
289
+ # Databricks turn `.` off for a line break).
290
+ if self._dialect_obj is not None and self._dialect_obj.name in ('spark', 'databricks_sql') \
291
+ and isinstance(expr.right, LitExpr) and isinstance(expr.right.value, str):
292
+ # Java's `$` also matches before a final line terminator ("42\r" passed an
293
+ # integer's form, M2 review B3); `\z` is the end of the input, as `$` is in
294
+ # RE2 and PostgreSQL's ARE.
295
+ right = self._dialect_obj.render_string(end_of_input(expr.right.value))
296
+ if self._dialect_obj is not None and self._dialect_obj.maps_function('REGEX_SEARCH'):
297
+ return self._dialect_obj.render_function('REGEX_SEARCH', [left, right])
298
+ return f"{left} RLIKE {right}"
299
+ return f"{left} {expr.op} {right}"
300
+
301
+ if isinstance(expr, AndExpr):
302
+ if not expr.children:
303
+ return 'TRUE'
304
+ parts = [self.serialize(c) for c in expr.children]
305
+ return ' AND '.join(parts)
306
+
307
+ if isinstance(expr, OrExpr):
308
+ if not expr.children:
309
+ return 'FALSE'
310
+ parts = [self.serialize(c) for c in expr.children]
311
+ return f"({' OR '.join(parts)})"
312
+
313
+ if isinstance(expr, NotExpr):
314
+ inner = self.serialize(expr.child)
315
+ return f"NOT ({inner})"
316
+
317
+ if isinstance(expr, IsNullExpr):
318
+ inner = self._operand(expr.child)
319
+ if expr.negated:
320
+ return f"{inner} IS NOT NULL"
321
+ return f"{inner} IS NULL"
322
+
323
+ if isinstance(expr, FuncExpr):
324
+ dialect = getattr(self, '_dialect_obj', None)
325
+ if expr.name == 'NAMED_STRUCT' and not expr.args and dialect is not None \
326
+ and dialect.name in ('spark', 'databricks_sql'):
327
+ # An empty map ({}): a Databricks SQL warehouse refuses a struct holding a constant empty
328
+ # struct (`NAMED_STRUCT('a', NAMED_STRUCT())`, its serializer's BoundReference assertion,
329
+ # DBSQL 2026.44/45), where a parsed one passes; local Spark takes both. One form for both:
330
+ # the same type, struct<>.
331
+ return "from_json('{}', 'struct<>')"
332
+ if dialect is not None and dialect.maps_function(expr.name):
333
+ return dialect.render_function(
334
+ expr.name, [self.serialize(a) for a in expr.args])
335
+ if dialect is not None and dialect.refuses_unmapped(expr.name):
336
+ from prograph.utils.exceptions import SQLGenerationError
337
+ raise SQLGenerationError(f"{expr.name}() has no equivalent in {dialect.name}",
338
+ reason=f"unsupported_function:{expr.name}")
339
+ return self._func_expr(expr)
340
+
341
+ if isinstance(expr, ExistsExpr):
342
+ # The CTE and alias quoted as a column reference is, so each
343
+ # dialect's quoting applies (Oracle needs `_sub_0` quoted).
344
+ source = self.serialize(ColExpr(ColumnRef(sql=f"{internal_name(expr.cte_name)} {scope_name(internal_name(expr.alias))}")))
345
+ where = (f" WHERE {_condition(self.serialize(expr.condition))}"
346
+ if expr.condition is not None else "")
347
+ return f"EXISTS (SELECT 1 FROM {source}{where})"
348
+
349
+ return str(expr)
350
+
351
+ def _func_expr(self, expr: FuncExpr) -> str:
352
+ """Serialize a FuncExpr with special-case handling."""
353
+ name = expr.name
354
+ args = expr.args
355
+
356
+ # CAST functions
357
+ if name in _CAST_FUNCTIONS:
358
+ target_type = _CAST_FUNCTIONS[name]
359
+ # The dialect's name for the type: MySQL casts to CHAR and
360
+ # SIGNED, not STRING and BIGINT.
361
+ dialect = getattr(self, '_dialect_obj', None)
362
+ if target_type == 'PATH_STRING':
363
+ # A recursive CTE's column takes the anchor's type, so the
364
+ # path seed needs room for the whole path; MySQL's CHAR is
365
+ # one character there.
366
+ type_map = dialect.config.type_map if dialect is not None else {}
367
+ target_type = type_map.get('PATH_STRING', type_map.get('STRING', 'STRING'))
368
+ elif dialect is not None:
369
+ target_type = dialect.config.type_map.get(target_type, target_type)
370
+ elif target_type == 'LONG':
371
+ target_type = 'BIGINT'
372
+ inner = self.serialize(args[0])
373
+ return f"CAST({inner} AS {target_type})"
374
+
375
+ # DISTINCT aggregates (e.g., DISTINCT_COUNT → COUNT(DISTINCT ...))
376
+ if name.startswith('DISTINCT_'):
377
+ real_name = name[len('DISTINCT_'):]
378
+ inner = self.serialize(args[0])
379
+ return f"{real_name}(DISTINCT {inner})"
380
+
381
+ # Arithmetic operators as infix
382
+ if name in _ARITHMETIC_OPS and len(args) == 2:
383
+ left = self.serialize(args[0])
384
+ right = self.serialize(args[1])
385
+ return f"({left} {name} {right})"
386
+
387
+ # Struct field access: base.`field`
388
+ if name == '.' and len(args) == 2:
389
+ base_sql = self.serialize(args[0])
390
+ field = args[1].sql if isinstance(args[1], LitExpr) else self.serialize(args[1])
391
+ return f"{base_sql}.{field}"
392
+
393
+ # CASE expression
394
+ if name == 'CASE':
395
+ return self._case_expr(args)
396
+ if name == 'CASE_SIMPLE':
397
+ return self._case_expr(args, simple=True)
398
+
399
+ # Standard function call
400
+ rendered_args = ', '.join(self.serialize(a) for a in args)
401
+ return f"{name}({rendered_args})"
402
+
403
+ def _case_expr(self, args: tuple, simple: bool = False) -> str:
404
+ """Serialize a CASE expression.
405
+
406
+ The form is explicit (ExprTranslator._case_expression): `CASE` is
407
+ searched, [when1, then1, ..., else?]; `CASE_SIMPLE` has the operand
408
+ first, [operand, when1, then1, ..., else?].
409
+ """
410
+ if not args:
411
+ return 'NULL'
412
+
413
+ idx = 0
414
+ parts = ['CASE']
415
+ if simple:
416
+ parts.append(self.serialize(args[0]))
417
+ idx = 1
418
+
419
+ # Process WHEN/THEN pairs
420
+ while idx + 1 < len(args):
421
+ when_expr = self.serialize(args[idx])
422
+ then_expr = self.serialize(args[idx + 1])
423
+ parts.append(f"WHEN {when_expr} THEN {then_expr}")
424
+ idx += 2
425
+
426
+ # Remaining single arg is ELSE
427
+ if idx < len(args):
428
+ else_expr = self.serialize(args[idx])
429
+ parts.append(f"ELSE {else_expr}")
430
+
431
+ parts.append('END')
432
+ return ' '.join(parts)
433
+
434
+
435
+ # =============================================================================
436
+ # Query Frame
437
+ # =============================================================================
438
+
439
+ @dataclass
440
+ class QueryFrame:
441
+ """Flat SQL clause accumulator, assembled into a SQL string.
442
+
443
+ Collects the clauses of one SELECT and writes them out in order with
444
+ ``to_sql()``. (The SQLState class this once mirrored no longer exists.)
445
+ """
446
+ select_columns: List[str] = field(default_factory=list)
447
+ """Rendered 'sql AS `alias`' strings."""
448
+
449
+ distinct: bool = False
450
+
451
+ from_clause: Optional[str] = None
452
+ """'table AS alias' or 'cte_name'."""
453
+
454
+ from_alias: Optional[str] = None
455
+ """The name the rest of the SELECT reads the FROM table by, where it is
456
+ a table: the name a subquery around it and its LATERAL VIEWs keeps."""
457
+
458
+ joins: List[str] = field(default_factory=list)
459
+ """Rendered JOIN clauses."""
460
+
461
+ lateral_views: List[str] = field(default_factory=list)
462
+ """LATERAL VIEW clauses."""
463
+
464
+ lateral_view_joins: List[int] = field(default_factory=list)
465
+ """For each LATERAL VIEW, the number of JOINs collected before it: the
466
+ joins of the rows it explodes beside. Written by `add_lateral_view`; a
467
+ view with none recorded stands before every join."""
468
+
469
+ where_conditions: List[str] = field(default_factory=list)
470
+ group_by_columns: List[str] = field(default_factory=list)
471
+ having_conditions: List[str] = field(default_factory=list)
472
+ order_by_columns: List[str] = field(default_factory=list)
473
+
474
+ limit: Optional[int] = None
475
+ offset: Optional[int] = None
476
+ limit_style: str = 'standard'
477
+ """'standard' → LIMIT N, 'fetch' → FETCH FIRST N ROWS ONLY."""
478
+
479
+ aggregated: bool = False
480
+ """The SELECT groups or aggregates: the order of the rows it reads is
481
+ nothing to it."""
482
+
483
+ is_result: bool = False
484
+ """The SELECT whose rows are the statement's answer."""
485
+
486
+ def add_lateral_view(self, clause: str) -> None:
487
+ """Add a LATERAL VIEW over the rows collected so far: it stands
488
+ after the JOINs already collected and before any collected later."""
489
+ self.lateral_view_joins.extend(
490
+ [0] * (len(self.lateral_views) - len(self.lateral_view_joins)))
491
+ self.lateral_views.append(clause)
492
+ self.lateral_view_joins.append(len(self.joins))
493
+
494
+ def to_sql(self) -> str:
495
+ """Assemble the SQL string from collected clauses.
496
+
497
+ The parts, in order:
498
+ - LATERAL VIEW + JOIN subquery wrapping
499
+ - Parts joined with newlines
500
+ """
501
+ parts: List[str] = []
502
+
503
+ # SELECT
504
+ distinct_kw = "DISTINCT " if self.distinct else ""
505
+
506
+ if self.select_columns:
507
+ cols = ', '.join(self.select_columns)
508
+ parts.append(f"SELECT {distinct_kw}{cols}")
509
+ else:
510
+ parts.append(f"SELECT {distinct_kw}*")
511
+
512
+ # FROM + JOINs + LATERAL VIEWs. Spark's FROM ends with its lateral
513
+ # views, after every join: a LATERAL VIEW over the rows of joins
514
+ # (an UNWIND after a MATCH of several tables) is written there, where
515
+ # its list can read every table of them. Wrapped with the FROM table
516
+ # alone, `UNWIND [a, b]` read b, and the joins read a, outside the
517
+ # subquery that held them (UNRESOLVED_COLUMN).
518
+ joined = len(self.joins)
519
+ # A view with no recorded place stands before every join (index 0),
520
+ # so none is ever dropped.
521
+ places = list(self.lateral_view_joins[:len(self.lateral_views)])
522
+ places += [0] * (len(self.lateral_views) - len(places))
523
+ early = [lv for lv, k in zip(self.lateral_views, places) if k < joined]
524
+ late = [lv for lv, k in zip(self.lateral_views, places) if k >= joined]
525
+ if early:
526
+ # Spark SQL doesn't allow JOINs after LATERAL VIEW in same scope.
527
+ # Wrap FROM + LATERAL VIEWs as a subquery first, under the FROM
528
+ # table's own name: the joins and the select list read its
529
+ # columns by it (`n.model` after `UNWIND [n] AS q MATCH ...`),
530
+ # and `_lv` hid it (UNRESOLVED_COLUMN).
531
+ lv_parts = "\n".join(early)
532
+ name = self.from_alias
533
+ if not name or not (self.from_clause == name or self.from_clause.endswith(f" AS {name}")):
534
+ name = '_lv'
535
+ subquery = f"(SELECT * FROM {self.from_clause}\n{lv_parts}) AS {name}"
536
+ parts.append(f"FROM {subquery}")
537
+ elif self.from_clause:
538
+ parts.append(f"FROM {self.from_clause}")
539
+ for join in self.joins:
540
+ parts.append(join)
541
+ for lv in late:
542
+ parts.append(lv)
543
+
544
+ # WHERE
545
+ if self.where_conditions:
546
+ parts.append(f"WHERE {' AND '.join(_condition(c) for c in self.where_conditions)}")
547
+
548
+ # GROUP BY
549
+ if self.group_by_columns:
550
+ parts.append(f"GROUP BY {', '.join(self.group_by_columns)}")
551
+
552
+ # HAVING
553
+ if self.having_conditions:
554
+ parts.append(f"HAVING {' AND '.join(_condition(c) for c in self.having_conditions)}")
555
+
556
+ # ORDER BY
557
+ if self.order_by_columns:
558
+ parts.append(f"ORDER BY {', '.join(self.order_by_columns)}")
559
+
560
+ # LIMIT / OFFSET. The standard's OFFSET ... FETCH puts OFFSET first;
561
+ # it was written after FETCH, which Oracle rejects.
562
+ # MySQL has no OFFSET without a LIMIT, so 'limit_required' supplies
563
+ # its documented largest one.
564
+ if self.limit_style == 'fetch':
565
+ if self.offset is not None:
566
+ parts.append(f"OFFSET {self.offset} ROWS")
567
+ if self.limit is not None:
568
+ parts.append(f"FETCH NEXT {self.limit} ROWS ONLY")
569
+ else:
570
+ if self.limit is not None:
571
+ parts.append(f"LIMIT {self.limit}")
572
+ elif self.offset is not None and self.limit_style == 'limit_required':
573
+ parts.append("LIMIT 18446744073709551615")
574
+ if self.offset is not None:
575
+ parts.append(f"OFFSET {self.offset}")
576
+
577
+ return '\n'.join(parts)
578
+
579
+
580
+ # =============================================================================
581
+ # Spark SQL Serializer
582
+ # =============================================================================
583
+
584
+ # One quoted name in any dialect's quoting, the quote character doubled
585
+ # inside it (`Dialect.quote`, `internal_name`): `a``b`, "a""b", [a]]b].
586
+ _QUOTED_NAME = r'`(?:[^`]|``)+`|"(?:[^"]|"")+"|\[(?:[^\]]|\]\])+\]'
587
+
588
+
589
+ class SparkSQLSerializer(SQLSerializer):
590
+ """Serialize a RelNode tree to a Spark SQL string.
591
+
592
+ Top-level dispatch:
593
+ - WithClause → WITH preamble + recurse body
594
+ - SetOperation → recurse branches, join with UNION ALL / DISTINCT
595
+ - Otherwise → _serialize_query() spine walker
596
+ """
597
+
598
+ def __init__(self, dialect: str = 'spark'):
599
+ from .dialect import get_dialect_instance
600
+ self._expr = ExprSerializer(get_dialect_instance(dialect))
601
+
602
+ _limit_style: str = 'standard'
603
+
604
+ _one_row_source: str = "(SELECT 1 AS _dummy) AS _base"
605
+ """The one row a query with no table starts from; Oracle before 23ai
606
+ names a table in every SELECT."""
607
+
608
+ _recursive_with: str = "WITH RECURSIVE"
609
+ """How a recursive CTE is introduced: SQL Server and Oracle take a
610
+ plain WITH and reject RECURSIVE."""
611
+ """Override in subclasses: 'standard' → LIMIT, 'fetch' → FETCH FIRST."""
612
+
613
+ _recursion_level_clause: str = " MAX RECURSION LEVEL 2147483647"
614
+ """Written after a recursive CTE's name. Spark and Databricks stop a
615
+ recursive CTE at 100 levels (RECURSION_LEVEL_LIMIT_EXCEEDED) unless the
616
+ CTE names its own limit; a walk ends by itself, so the limit is lifted
617
+ to the largest figure the clause takes. Their limit on rows
618
+ from a recursion is left on. Empty for every other dialect."""
619
+
620
+ _recursive_statement_suffix: str = ""
621
+ """Written at the end of a statement holding a recursive CTE: SQL
622
+ Server's OPTION (MAXRECURSION 0)."""
623
+
624
+ def _table_ref(self, table: str, alias: str) -> str:
625
+ """Format a table reference with alias: ``table AS alias``, the
626
+ alias written by `scope_name`."""
627
+ return f"{table} AS {scope_name(alias)}"
628
+
629
+ def write_select(self, table: str, alias: str, columns: List[str],
630
+ where: List[str] = (), group_by: List[str] = (),
631
+ having: List[str] = (), limit: Optional[int] = None) -> str:
632
+ """A SELECT the engine runs outside a plan's tree (the key check's
633
+ duplicate scan, `node_keys.SQLSource.duplicate`), written as every
634
+ statement is: `table` (a name as the dialect reads it) with its
635
+ alias by `_table_ref` (Oracle takes no AS, MySQL quotes the name),
636
+ and the row limit by `_assemble_sql` (SQL Server's TOP, Oracle's
637
+ FETCH)."""
638
+ frame = QueryFrame(select_columns=list(columns),
639
+ from_clause=self._table_ref(table, alias),
640
+ where_conditions=list(where), group_by_columns=list(group_by),
641
+ having_conditions=list(having), limit=limit,
642
+ limit_style=self._limit_style, aggregated=bool(group_by))
643
+ return self._assemble_sql(frame)
644
+
645
+ def _scan_ref(self, node: Scan) -> str:
646
+ """A Scan as a FROM or JOIN target: its table, named as the dialect
647
+ reads it (a reserved word quoted, ``Dialect.table_name``), with its alias. Every serializer writes a scan here."""
648
+ dialect = getattr(self._expr, '_dialect_obj', None)
649
+ from prograph.plan.ir.key_checks import pinned_name
650
+ written = dialect.table_name(node.table) if dialect is not None else node.table
651
+ table = pinned_name(node.table, written)
652
+ if node.alias and table is not written and scope_name(node.alias) == node.table:
653
+ # A pinned read (``t VERSION AS OF n``) is no name to read the
654
+ # scan by: it keeps the table's own as its alias.
655
+ return self._table_ref(table, node.alias)
656
+ if node.alias and scope_name(node.alias) != node.table:
657
+ return self._table_ref(table, node.alias)
658
+ return table
659
+
660
+ def serialize(self, tree: RelNode) -> str:
661
+ """Convert a relational algebra tree to a SQL string."""
662
+ if getattr(self, '_kept', None):
663
+ return self._serialize_node(tree)
664
+ # The outermost call: the statement. A CTE a dialect keeps
665
+ # is written into the WITH of the statement it stands in; a WithClause takes its own
666
+ # (`_kept_frame` in `_serialize_with`), and a statement with no
667
+ # WITH is given one here.
668
+ self._kept, self._kept_count = [[]], 0
669
+ self._result = tree.body if isinstance(tree, WithClause) else tree
670
+ # A sorted slice is kept from its readers only in a statement
671
+ # that holds a subquery expression (`_over_a_sorted_slice`): the
672
+ # statement whole, its CTEs and a UNION's branches together.
673
+ self._holds_a_subquery_expression = holds_a_subquery_expression(tree)
674
+ try:
675
+ sql = self._serialize_node(tree)
676
+ kept = self._kept[0]
677
+ finally:
678
+ self._kept = None
679
+ self._holds_a_subquery_expression = False
680
+ return f"WITH {', '.join(kept)}\n{sql}" if kept else sql
681
+
682
+ def _serialize_node(self, tree: RelNode) -> str:
683
+ if isinstance(tree, WithClause):
684
+ return self._serialize_with(tree)
685
+ if isinstance(tree, SetOperation):
686
+ return self._serialize_set_op(tree)
687
+ return self._serialize_query(tree)
688
+
689
+ @contextmanager
690
+ def _kept_frame(self):
691
+ """The CTEs that sliced subqueries written inside the block ask
692
+ for, to stand in the WITH being written, before what reads them."""
693
+ frames = getattr(self, '_kept', None)
694
+ if frames is None:
695
+ yield []
696
+ return
697
+ frames.append([])
698
+ try:
699
+ yield frames[-1]
700
+ finally:
701
+ frames.pop()
702
+
703
+ # -----------------------------------------------------------------
704
+ # Top-level dispatchers
705
+ # -----------------------------------------------------------------
706
+
707
+ def _serialize_with(self, node: WithClause) -> str:
708
+ """Serialize WITH ... AS (...) body."""
709
+ has_recursive = any(getattr(cte, 'recursive', False) for cte in node.ctes)
710
+ cte_strs = []
711
+ for cte in node.ctes:
712
+ with self._kept_frame() as kept:
713
+ cte_sql = self._cte_body(cte, self._below_the_result(
714
+ self.serialize, cte.definition), has_recursive)
715
+ cte_strs.extend(kept)
716
+ level = self._recursion_level_clause if getattr(cte, 'recursive', False) else ""
717
+ # A sorted slice the dialect keeps from its readers is written
718
+ # under a name of its own, and the CTE's name is the dialect's
719
+ # SELECT over it: no reader's text moves.
720
+ name = cte.name
721
+ over = self._over_a_sorted_slice(cte.definition, f"{cte.name}_s")
722
+ if over:
723
+ name = f"{cte.name}_s"
724
+ cte_strs.append(f"{name}{level} AS {self._before_a_cte(cte)}({cte_sql})")
725
+ if over:
726
+ cte_strs.append(f"{cte.name} AS ({over})")
727
+
728
+ with self._kept_frame() as kept:
729
+ body_sql = self.serialize(node.body)
730
+ cte_strs.extend(kept)
731
+ keyword = self._recursive_with if has_recursive else "WITH"
732
+ cte_preamble = f"{keyword} {', '.join(cte_strs)}"
733
+ suffix = self._recursive_statement_suffix if has_recursive else ""
734
+ return f"{cte_preamble}\n{body_sql}{suffix}"
735
+
736
+ def _serialize_set_op(self, node: SetOperation) -> str:
737
+ """Serialize UNION ALL / UNION DISTINCT."""
738
+ op_str = 'UNION ALL' if node.op == SetOp.UNION_ALL else 'UNION'
739
+ parts = []
740
+ for i, branch in enumerate(node.branches):
741
+ branch_sql = self.serialize(branch)
742
+ parts.append(branch_sql)
743
+ return f"\n{op_str}\n".join(parts)
744
+
745
+ @staticmethod
746
+ def _slices(node: RelNode) -> bool:
747
+ """Whether the SELECT written for `node` keeps rows by its own
748
+ LIMIT or OFFSET: a Limit on the spine `_serialize_query` peels
749
+ into that SELECT."""
750
+ while isinstance(node, (Project, Limit, Sort)):
751
+ if isinstance(node, Limit):
752
+ return True
753
+ node = node.child
754
+ return False
755
+
756
+ def _over_a_sorted_slice(self, node: RelNode, source: str) -> str:
757
+ """The dialect's SELECT to stand over `node`, read from `source`,
758
+ where the SELECT written for `node` is a sorted slice (a Sort and
759
+ a Limit on the spine `_serialize_query` peels into it); '' where
760
+ it is none, the dialect needs nothing there, or the statement
761
+ being written holds no subquery expression
762
+ (`rel_algebra.holds_a_subquery_expression`, asked once of the
763
+ whole statement in `serialize`): what the dialect keeps a slice
764
+ from is a projection that holds one, pushed under the slice, and
765
+ which SELECT of a statement comes to hold it is the database's
766
+ to say (it inlines a chain of CTEs), so a statement that holds
767
+ one has every sorted slice kept and a statement that holds none
768
+ is written as it always was."""
769
+ if not getattr(self, '_holds_a_subquery_expression', False):
770
+ return ""
771
+ sorted_, limit, spine = False, None, node
772
+ while isinstance(spine, (Project, Limit, Sort)):
773
+ if isinstance(spine, Limit):
774
+ limit = spine
775
+ elif isinstance(spine, Sort):
776
+ sorted_ = True
777
+ spine = spine.child
778
+ if limit is None or not sorted_:
779
+ return ""
780
+ return self._expr._dialect_obj.over_a_sorted_slice(source)
781
+
782
+ def _cte_body(self, cte, sql: str, in_a_recursive_with: bool) -> str:
783
+ """A CTE's SELECT as written inside its parentheses: `sql`, or,
784
+ where the dialect binds a union CTE of a WITH RECURSIVE as
785
+ recursive (`Dialect.binds_a_union_cte_as_recursive`, DuckDB), a
786
+ SELECT over the UNION of a CTE that does not recurse, so its
787
+ columns take the type its branches share."""
788
+ if (in_a_recursive_with and not getattr(cte, 'recursive', False)
789
+ and isinstance(cte.definition, SetOperation)
790
+ and self._expr._dialect_obj.binds_a_union_cte_as_recursive()):
791
+ return f"SELECT * FROM ({sql}) AS {cte.name}_u"
792
+ return sql
793
+
794
+ def _before_a_cte(self, cte) -> str:
795
+ """What the dialect writes between `AS` and a CTE's parenthesis:
796
+ its word for a CTE that holds a slice, and nothing for any other
797
+ (docs/architecture/rules.md, "A CTE that holds a slice")."""
798
+ return self._expr._dialect_obj.before_a_sliced_cte() if self._slices(cte.definition) else ""
799
+
800
+ # -----------------------------------------------------------------
801
+ # Query spine walker
802
+ # -----------------------------------------------------------------
803
+
804
+ def _serialize_query(self, tree: RelNode) -> str:
805
+ """Peel the spine into a flat QueryFrame, then assemble SQL."""
806
+ frame = QueryFrame()
807
+ frame.is_result = tree is getattr(self, '_result', None)
808
+ current = self._peel_spine(tree, frame)
809
+
810
+ # Collect FROM, JOINs, WHERE from remaining tree
811
+ self._collect_from(current, frame, top_level=True)
812
+
813
+ return self._assemble_sql(frame)
814
+
815
+ def _peel_spine(self, tree: RelNode, frame: QueryFrame) -> RelNode:
816
+ """The Limit, Sort, Project and Aggregate on top of `tree` as the
817
+ clauses of one SELECT in `frame`; returns what is left, the FROM.
818
+
819
+ One SELECT applies its clauses in SQL's order: DISTINCT, ORDER BY,
820
+ then LIMIT. So a Limit is peeled into the SELECT only where that is
821
+ its place in the tree:
822
+
823
+ - Limit over Sort over Project (a RETURN and its own ORDER BY and
824
+ LIMIT), and Limit over Project over Sort (a SPARQL query: ORDER
825
+ BY, the projection, DISTINCT, then the slice): the Limit is on
826
+ top, after the DISTINCT, as SQL applies it.
827
+ - A Limit UNDER a Project that is not DISTINCT: the projection
828
+ keeps every row, and the slice before it is the same rows.
829
+ - A Limit under a DISTINCT Project is NOT this SELECT's: it is an
830
+ earlier clause's slice (`WITH p LIMIT 3 RETURN DISTINCT p.g`),
831
+ which cuts the rows before the DISTINCT. Peeled, the LIMIT
832
+ counted distinct rows, after the RETURN's ORDER BY (a a b under
833
+ `RETURN DISTINCT g` answered a, b, c). It stays under the SELECT,
834
+ a subquery with its own ORDER BY, on every dialect.
835
+ - A Limit under a Project that has a Limit over it is NOT this
836
+ SELECT's either: one SELECT has one slice (`WITH p LIMIT 6 RETURN
837
+ p.name AS n SKIP 1`: the SKIP is the SELECT's, and the LIMIT 6
838
+ took its place and lost it where the SKIP had no count).
839
+
840
+ A Sort under the Project is not built: the plan writes its ORDER BY
841
+ over the select list (`lower.emit`, `lower.to_tree`).
842
+
843
+ The one peel for every statement: the body of a WITH clause that
844
+ hints a bounded CTE had a copy with no step under the Project.
845
+ """
846
+ current = tree
847
+
848
+ # Peel Limit
849
+ sliced = isinstance(current, Limit)
850
+ if isinstance(current, Limit):
851
+ frame.limit = current.count
852
+ frame.limit_style = self._limit_style
853
+ frame.offset = current.offset
854
+ current = current.child
855
+
856
+ # Peel Sort
857
+ if isinstance(current, Sort):
858
+ beside = current.child.columns if isinstance(current.child, Project) else None
859
+ for key in self._keys_that_order(current.keys):
860
+ key = self._read_by_its_own_select_alias(key, current.child)
861
+ frame.order_by_columns.append(self._render_sort_key(key, beside))
862
+ current = current.child
863
+
864
+ # Peel Project
865
+ if isinstance(current, Project):
866
+ frame.distinct = current.distinct
867
+ for col in current.columns:
868
+ frame.select_columns.append(self._render_column(col))
869
+ current = current.child
870
+
871
+ # A Limit under the Project is this SELECT's where the Project
872
+ # keeps every row and the SELECT has no slice yet; under a DISTINCT,
873
+ # or under a slice already taken, it is an earlier clause's and
874
+ # stays a subquery (the docstring).
875
+ if isinstance(current, Limit) and not sliced and not frame.distinct:
876
+ frame.limit = current.count
877
+ frame.limit_style = self._limit_style
878
+ frame.offset = current.offset
879
+ current = current.child
880
+
881
+ if isinstance(current, Sort) and not frame.order_by_columns:
882
+ # The plan writes an ORDER BY over its select list, never under it (`lower.emit`,
883
+ # `lower.to_tree`), so a Sort here has no SELECT of its own to name its keys.
884
+ raise NotImplementedError("one-plan: a sort under the select list")
885
+
886
+ # Peel Aggregate
887
+ if isinstance(current, Aggregate):
888
+ self._peel_aggregate(current, frame)
889
+ current = current.child
890
+
891
+ return current
892
+
893
+ def _written(self, column: ColumnRef) -> str:
894
+ """The text a column's value is written as: its expression's, or
895
+ its own."""
896
+ expr_node = column.metadata.get('expr') if column.metadata else None
897
+ if expr_node is not None and not isinstance(expr_node, ColExpr):
898
+ return self._expr.serialize(expr_node)
899
+ return column.sql
900
+
901
+ def _read_by_its_own_select_alias(self, key: SortKey, project) -> SortKey:
902
+ """A sort key of the SELECT of `project`, on a database that cannot
903
+ sort by a column read by its source's name where the select list
904
+ projects it under that same name
905
+ (`Dialect.sorts_by_a_column_its_select_list_names_by_itself`: Spark
906
+ and Databricks), with each such read written as the alias:
907
+ `SELECT _sub_7.o AS o ... ORDER BY CASE WHEN _sub_7.o IS NULL ...
908
+ END, o` is PLAN_VALIDATION_FAILED on Spark 4.1 over some UNION ALLs,
909
+ and so is Cypher's `MATCH (x) RETURN x.name AS name ORDER BY
910
+ toLower(x.name)` over two tables; `ORDER BY CASE
911
+ WHEN o IS NULL ... END, o` plans. The alias is the column's value, and Spark reads a select
912
+ alias inside an ORDER BY expression, so the order is the same. A
913
+ plain key is the alias itself; an expression key has the read
914
+ replaced by the optimizer's `_substitute_expr`, which leaves every
915
+ other column it reads as it was (the `__iri__o` marker the list
916
+ does not hold). Not where another select alias differs from the
917
+ name by case alone: Spark reads the two as one, ambiguous."""
918
+ dialect = getattr(self._expr, '_dialect_obj', None)
919
+ if dialect is None or dialect.sorts_by_a_column_its_select_list_names_by_itself() \
920
+ or not isinstance(project, Project):
921
+ return key
922
+ from .names import differ_by_case_alone
923
+ aliases = [col.alias for col in project.columns if col.alias]
924
+ own: Dict[ColumnId, str] = {}
925
+ for col in project.columns:
926
+ if not col.alias or self._written(col) != col.sql:
927
+ continue
928
+ read = col.identity()
929
+ if read.scope is None or read.name != col.alias \
930
+ or any(differ_by_case_alone(col.alias, other) for other in aliases):
931
+ continue
932
+ own.setdefault(read, col.alias)
933
+ if not own:
934
+ return key
935
+ column = key.column
936
+ expr_node = column.metadata.get('expr') if column.metadata else None
937
+ if expr_node is None or isinstance(expr_node, ColExpr):
938
+ alias = own.get((expr_node.ref if expr_node is not None else column).identity())
939
+ if alias is None:
940
+ return key
941
+ return replace(key, column=ColumnRef(sql=internal_name(alias), alias=alias))
942
+ from .names import substitute_expr as _substitute_expr
943
+ changed = expr_node
944
+ for read, alias in own.items():
945
+ changed = _substitute_expr(
946
+ changed, read, ColumnRef(sql=internal_name(alias), alias=alias))
947
+ if changed == expr_node:
948
+ return key
949
+ return replace(key, column=replace(column, metadata={**column.metadata, 'expr': changed}))
950
+
951
+ def _group_by_column(self, sql: str) -> str:
952
+ """A plain column's text in GROUP BY, in this dialect's quoting."""
953
+ return sql
954
+
955
+ def _predicate_value(self, sql: str) -> str:
956
+ """A predicate as a value in this dialect: itself where the database
957
+ has a boolean type. A dialect without one (Oracle, SQL Server)
958
+ renders 1, 0, or NULL where it is unknown."""
959
+ return sql
960
+
961
+ def _value_sql(self, expr_node) -> str:
962
+ """An expression as a value: a predicate in its dialect's value form
963
+ (``_predicate_value``), in the select list and in GROUP BY alike, so
964
+ the two agree."""
965
+ from .sqlserver_serializer import _is_predicate
966
+ sql = self._expr.serialize(expr_node)
967
+ return self._predicate_value(sql) if _is_predicate(expr_node) else sql
968
+
969
+ def _peel_aggregate(self, node: Aggregate, frame: QueryFrame) -> None:
970
+ """Extract aggregate clauses into the query frame.
971
+
972
+ Separated from _serialize_query so subclasses can override
973
+ group-by rendering (e.g., for different quoting).
974
+ """
975
+ grouped = len(frame.group_by_columns)
976
+ for col in node.group_by:
977
+ rendered = self._render_column(col)
978
+ if self._is_its_own_name(col) and not self._names_reach_result:
979
+ # Written by its name alone, here or where the Project over
980
+ # the Aggregate already put it in the select list. Not where
981
+ # the name reaches the result: DuckDB names an unaliased
982
+ # column by the table's own spelling (`nm` for a mapping's
983
+ # `NM`), so there the alias keeps the result's name.
984
+ as_named = rendered
985
+ rendered = self._render_column(replace(col, alias=None))
986
+ frame.select_columns[:] = [rendered if c == as_named else c
987
+ for c in frame.select_columns]
988
+ if rendered not in frame.select_columns:
989
+ frame.select_columns.append(rendered)
990
+ # GROUP BY uses the column expression (not the alias).
991
+ # For complex expressions (FuncExpr etc.) the sql field
992
+ # may just be the class name, use metadata['expr'] instead.
993
+ expr_node = col.metadata.get('expr') if col.metadata else None
994
+ keys = col.metadata.get('group_keys') if col.metadata else None
995
+ if isinstance(expr_node, LitExpr):
996
+ # A literal is the same in every row and splits no group. In
997
+ # GROUP BY an integer is read as a column's position
998
+ # (`GROUP BY 1` grouped by the first column, an aggregate or
999
+ # none at all), and PostgreSQL and SQL Server refuse any
1000
+ # other constant there.
1001
+ continue
1002
+ if keys:
1003
+ # A whole node or relationship: grouped by its columns.
1004
+ for key in keys:
1005
+ rendered_key = self._expr.serialize(key)
1006
+ if rendered_key not in frame.group_by_columns:
1007
+ frame.group_by_columns.append(rendered_key)
1008
+ elif expr_node is not None and not isinstance(expr_node, ColExpr):
1009
+ # Typed as the select list writes it (`as_value`).
1010
+ frame.group_by_columns.append(self._value_sql(self._expr.as_value(expr_node)))
1011
+ else:
1012
+ frame.group_by_columns.append(self._group_by_column(col.sql))
1013
+ # Aggregation columns go to SELECT
1014
+ for col in node.aggregations:
1015
+ rendered = self._render_column(col)
1016
+ if rendered not in frame.select_columns:
1017
+ frame.select_columns.append(rendered)
1018
+ if node.group_by and len(frame.group_by_columns) == grouped:
1019
+ # Every key is a literal. Grouped rows are none where there are
1020
+ # no rows, where an aggregate with no key answers one row.
1021
+ frame.having_conditions.append("COUNT(*) > 0")
1022
+ # HAVING
1023
+ if node.having:
1024
+ frame.having_conditions.append(
1025
+ self._expr.serialize(node.having)
1026
+ )
1027
+
1028
+ # -----------------------------------------------------------------
1029
+ # FROM clause collector
1030
+ # -----------------------------------------------------------------
1031
+
1032
+ def _collect_from(
1033
+ self, node: RelNode, frame: QueryFrame, *, top_level: bool = False,
1034
+ ) -> None:
1035
+ """Walk the remaining tree to populate FROM, JOINs, WHERE, etc.
1036
+
1037
+ Args:
1038
+ top_level: When True, the frame's select/order/group-by columns
1039
+ all reference tables within *node*. The subquery fallback
1040
+ can safely rewrite them to use ``_sub``. When False (the
1041
+ default, used by recursive calls from _collect_join etc.),
1042
+ the frame may already contain column references from JOIN
1043
+ siblings that must NOT be rewritten.
1044
+ """
1045
+ if node is None:
1046
+ # A projection with no source (`RETURN 7 / 2`): no FROM. The
1047
+ # fallback below wrapped None as a subquery of itself and
1048
+ # recursed until the interpreter gave up.
1049
+ return
1050
+ if isinstance(node, Scan):
1051
+ self._collect_scan(node, frame)
1052
+
1053
+ elif isinstance(node, CteRef):
1054
+ frame.from_clause = node.cte_name
1055
+
1056
+ elif isinstance(node, Values):
1057
+ # Dummy base for standalone UNWIND
1058
+ frame.from_clause = self._one_row_source
1059
+
1060
+ elif isinstance(node, Filter):
1061
+ # Recurse child, add WHERE condition. A filter on nothing (a
1062
+ # SPARQL group with no pattern) tests the one row a standalone
1063
+ # UNWIND starts from.
1064
+ if node.child is None:
1065
+ frame.from_clause = self._one_row_source
1066
+ self._collect_from(node.child, frame, top_level=top_level)
1067
+ frame.where_conditions.append(
1068
+ self._expr.serialize(node.predicate)
1069
+ )
1070
+
1071
+ elif isinstance(node, Join):
1072
+ self._collect_join(node, frame)
1073
+
1074
+ elif isinstance(node, AntiJoin):
1075
+ self._collect_anti_join(node, frame)
1076
+
1077
+ elif isinstance(node, SemiJoin):
1078
+ self._collect_semi_join(node, frame)
1079
+
1080
+ elif isinstance(node, LateralExplode):
1081
+ self._collect_lateral_explode(node, frame)
1082
+
1083
+ elif isinstance(node, SetOperation):
1084
+ sub_sql = self._below_the_result(self._serialize_set_op, node)
1085
+ alias = node.alias or '_sub'
1086
+ frame.from_clause = f"({sub_sql}) AS {scope_name(internal_name(alias))}"
1087
+
1088
+ else:
1089
+ # A subselect, a union or a slice is a CTE in the plan (`lower.to_tree`),
1090
+ # never a node under a FROM.
1091
+ raise NotImplementedError(f"one-plan: {type(node).__name__} under a FROM")
1092
+
1093
+ def _collect_scan(self, node: Scan, frame: QueryFrame) -> None:
1094
+ """Populate FROM clause from a Scan node."""
1095
+ frame.from_clause = self._scan_ref(node)
1096
+ frame.from_alias = scope_name(node.alias) if node.alias else frame.from_clause
1097
+
1098
+ def _collect_join(self, node: Join, frame: QueryFrame) -> None:
1099
+ """Collect JOIN clause. Left side becomes FROM, right side becomes JOIN.
1100
+
1101
+ After predicate pushdown, the right child of a Join may be
1102
+ ``Filter(pred, Scan)`` or ``Filter(pred, CteRef)``. For INNER
1103
+ and CROSS joins we unwrap the Filter chain and merge predicates
1104
+ into the ON clause so they appear as ``JOIN t ON ... AND pred``
1105
+ instead of requiring a subquery. For LEFT joins the extra
1106
+ predicates go to WHERE to preserve null-extension semantics.
1107
+
1108
+ Hub node elimination may produce ``Join(left=None, right=Scan)``.
1109
+ In that case the right side becomes the FROM clause directly.
1110
+ """
1111
+ if node.left is None:
1112
+ # Hub node eliminated: right side is the FROM source
1113
+ self._collect_from(node.right, frame)
1114
+ return
1115
+
1116
+ # Recurse left side for FROM + any nested JOINs
1117
+ self._collect_from(node.left, frame)
1118
+
1119
+ # Unwrap Filter chains on the right side of the join
1120
+ right = node.right
1121
+ extra_preds: list[str] = []
1122
+ while isinstance(right, Filter):
1123
+ extra_preds.append(self._expr.serialize(right.predicate))
1124
+ right = right.child
1125
+
1126
+ # Only inline if the unwrapped node is a simple table/CTE reference
1127
+ if isinstance(right, (Scan, CteRef)):
1128
+ right_clause = self._render_from_node(right)
1129
+ else:
1130
+ # Complex right side, fall back to subquery for the
1131
+ # original (un-unwrapped) node
1132
+ right_clause = self._render_from_node(node.right)
1133
+ extra_preds = [] # subquery already contains the filters
1134
+
1135
+ # Join type
1136
+ if node.join_type == JoinType.CROSS:
1137
+ if extra_preds:
1138
+ # CROSS JOIN with extra predicates becomes INNER JOIN
1139
+ # since the predicates impose a condition
1140
+ all_conditions = extra_preds
1141
+ frame.joins.append(
1142
+ f"INNER JOIN {right_clause} ON "
1143
+ + ' AND '.join(all_conditions)
1144
+ )
1145
+ else:
1146
+ frame.joins.append(f"CROSS JOIN {right_clause}")
1147
+ elif node.join_type == JoinType.LEFT:
1148
+ conditions = ' AND '.join(
1149
+ self._expr.serialize(c) for c in node.on
1150
+ )
1151
+ frame.joins.append(
1152
+ f"LEFT JOIN {right_clause} ON {conditions}"
1153
+ )
1154
+ # For LEFT JOIN, pushed predicates go to WHERE, not ON
1155
+ for pred_sql in extra_preds:
1156
+ frame.where_conditions.append(pred_sql)
1157
+ else:
1158
+ # INNER, merge extra predicates into ON clause
1159
+ all_conds = [self._expr.serialize(c) for c in node.on]
1160
+ all_conds.extend(extra_preds)
1161
+ conditions = ' AND '.join(all_conds)
1162
+ frame.joins.append(
1163
+ f"INNER JOIN {right_clause} ON {conditions}"
1164
+ )
1165
+
1166
+ def _collect_anti_join(self, node: AntiJoin, frame: QueryFrame) -> None:
1167
+ """Collect LEFT ANTI JOIN for anti-join pattern.
1168
+
1169
+ Uses native Spark LEFT ANTI JOIN syntax which produces a direct
1170
+ LeftAnti physical join (BroadcastHash or SortMerge) without
1171
+ materializing right-side columns. This replaces the previous
1172
+ LEFT JOIN + IS NULL pattern which required a full LEFT OUTER JOIN
1173
+ followed by a post-filter.
1174
+ """
1175
+ # Recurse child for FROM
1176
+ self._collect_from(node.child, frame)
1177
+
1178
+ # First anti-join leg
1179
+ right_clause = self._render_from_node(node.right)
1180
+ conditions = ' AND '.join(
1181
+ self._expr.serialize(c) for c in node.on
1182
+ )
1183
+ frame.joins.append(
1184
+ f"LEFT ANTI JOIN {right_clause} ON {conditions}"
1185
+ )
1186
+ # null_check is implicit in LEFT ANTI JOIN semantics
1187
+
1188
+ # Second anti-join leg (undirected relationships)
1189
+ # Rows surviving the first ANTI have no match in direction 1.
1190
+ # The second ANTI removes rows that match in direction 2.
1191
+ # Only rows with NO match in either direction survive.
1192
+ if node.second_right:
1193
+ right2_clause = self._render_from_node(node.second_right)
1194
+ conditions2 = ' AND '.join(
1195
+ self._expr.serialize(c) for c in node.second_on
1196
+ )
1197
+ frame.joins.append(
1198
+ f"LEFT ANTI JOIN {right2_clause} ON {conditions2}"
1199
+ )
1200
+
1201
+ def _collect_semi_join(self, node: SemiJoin, frame: QueryFrame) -> None:
1202
+ """Collect LEFT SEMI JOIN for existence-check patterns.
1203
+
1204
+ Uses native Spark LEFT SEMI JOIN syntax which produces a direct
1205
+ LeftSemi physical join (BroadcastHash or SortMerge) without
1206
+ materializing right-side columns. Created by the JoinElimination
1207
+ optimization when an endpoint node table's columns are unused
1208
+ downstream.
1209
+ """
1210
+ # Recurse child for FROM
1211
+ self._collect_from(node.child, frame)
1212
+
1213
+ right_clause = self._render_from_node(node.right)
1214
+ conditions = ' AND '.join(
1215
+ self._expr.serialize(c) for c in node.on
1216
+ )
1217
+ frame.joins.append(
1218
+ f"LEFT SEMI JOIN {right_clause} ON {conditions}"
1219
+ )
1220
+
1221
+ def _collect_lateral_explode(
1222
+ self, node: LateralExplode, frame: QueryFrame
1223
+ ) -> None:
1224
+ """Collect LATERAL VIEW explode(...)."""
1225
+ # Recurse child for FROM
1226
+ self._collect_from(node.child, frame)
1227
+
1228
+ list_sql = self._expr.serialize(self._expr.as_value(node.list_expr))
1229
+ frame.add_lateral_view(
1230
+ f"LATERAL VIEW explode({list_sql}) AS {internal_name(node.element_alias)}"
1231
+ )
1232
+
1233
+ # -----------------------------------------------------------------
1234
+ # Rendering helpers
1235
+ # -----------------------------------------------------------------
1236
+
1237
+ def _render_from_node(self, node: RelNode) -> str:
1238
+ """Render a node as a FROM/JOIN target (table ref or subquery)."""
1239
+ if isinstance(node, Scan):
1240
+ return self._scan_ref(node)
1241
+
1242
+ if isinstance(node, CteRef):
1243
+ return node.cte_name
1244
+
1245
+ if isinstance(node, SetOperation):
1246
+ sub_sql = self._below_the_result(self._serialize_set_op, node)
1247
+ alias = node.alias or '_sub'
1248
+ return f"({sub_sql}) AS {scope_name(internal_name(alias))}"
1249
+
1250
+ raise NotImplementedError(f"one-plan: {type(node).__name__} as a FROM target")
1251
+
1252
+ _alias_dialect: str = 'spark'
1253
+ """The dialect whose quoting writes a column alias (`_quote_alias`)."""
1254
+
1255
+ _names_reach_result: bool = True
1256
+ """Whether the SELECT being written names the statement's result
1257
+ columns: the outermost query, its WITH body and each branch of an
1258
+ outermost UNION. False inside a CTE's definition and inside a subquery
1259
+ (`_below_the_result`)."""
1260
+
1261
+ def _below_the_result(self, serialize, node):
1262
+ """`serialize(node)` for a query whose column names do not reach the
1263
+ statement's result: a CTE's definition or a subquery."""
1264
+ reach, self._names_reach_result = self._names_reach_result, False
1265
+ try:
1266
+ return serialize(node)
1267
+ finally:
1268
+ self._names_reach_result = reach
1269
+
1270
+ def _quote_alias(self, alias: str) -> str:
1271
+ """A column alias as the database reads it: the dialect's own
1272
+ quoting, its quote character doubled (an unaliased column is named by
1273
+ the query's text, which holds quotes: `p.nm + "y"`)."""
1274
+ from .dialect import get_dialect_instance
1275
+ return get_dialect_instance(self._alias_dialect).quote_exact(alias)
1276
+
1277
+ @staticmethod
1278
+ def _is_its_own_name(col: ColumnRef) -> bool:
1279
+ """A column whose SQL is a name, bare or qualified by its table, and
1280
+ whose alias is that name: `p__id AS p__id`, `p.id AS id`. Below the
1281
+ result (a CTE's definition, a subquery) a grouped column is written
1282
+ as the name alone: on Databricks a grouping column aliased to its own
1283
+ name, with a HAVING that holds a correlated subquery over it, under an
1284
+ outer query, failed in the optimizer (INTERNAL_ERROR XX000, DBSQL
1285
+ 2026.39). There the column is read by references
1286
+ that every database resolves without regard to case. Where the name
1287
+ reaches the result the alias stays: DuckDB names an unaliased column
1288
+ by the table's own spelling, which a mapping may spell otherwise."""
1289
+ expr_node = col.metadata.get('expr') if col.metadata else None
1290
+ if not col.alias or (expr_node is not None and not isinstance(expr_node, ColExpr)):
1291
+ return False
1292
+ m = re.fullmatch(r'(?:[A-Za-z_]\w*\.)?(' + _QUOTED_NAME + r'|[A-Za-z_]\w*)', (col.sql or '').strip())
1293
+ if m is None:
1294
+ return False
1295
+ return unquoted_name(m.group(1)) == col.alias
1296
+
1297
+ def _render_column(self, col: ColumnRef) -> str:
1298
+ """Render a ColumnRef as 'sql AS `alias`'.
1299
+
1300
+ Checks metadata['expr'] first (set by tree handlers for aggregation
1301
+ columns), then falls back to col.sql.
1302
+ """
1303
+ expr_node = col.metadata.get('expr') if col.metadata else None
1304
+ if expr_node is not None:
1305
+ sql = self._value_sql(self._expr.as_value(expr_node))
1306
+ else:
1307
+ sql = col.sql
1308
+ if col.alias:
1309
+ return f"{sql} AS {self._quote_alias(col.alias)}"
1310
+ return sql
1311
+
1312
+ @staticmethod
1313
+ def _keys_that_order(keys) -> List[SortKey]:
1314
+ """The sort keys without the literals. A literal is the same in every
1315
+ row and orders nothing; in ORDER BY an integer is read as a column's
1316
+ position (`ORDER BY 1` sorted by the first column, silently), and
1317
+ some databases refuse any other constant there. The same rule as a
1318
+ literal grouping key in `_peel_aggregate`."""
1319
+ def literal(key):
1320
+ col = key.column
1321
+ expr = col.metadata.get('expr') if col.metadata else None
1322
+ return isinstance(expr, LitExpr)
1323
+ return [key for key in keys if not literal(key)]
1324
+
1325
+ @staticmethod
1326
+ def _named_by_itself(col: ColumnRef) -> bool:
1327
+ """Whether a sort key is a column of the select list named by
1328
+ itself (`` `name` `` under the alias `name`). It is then quoted as
1329
+ the select list quotes it, the quote character inside it doubled:
1330
+ a column with no alias is named by its text, `coalesce(n.g, "zz")`,
1331
+ and the per-dialect rewrite of the backtick form does not double
1332
+ (docs/architecture/rules.md, SQL identifiers)."""
1333
+ return bool(col.alias) and col.sql == internal_name(col.alias)
1334
+
1335
+ def _render_sort_key(self, key: SortKey, beside: Optional[list] = None) -> str:
1336
+ """Render a SortKey as 'col ASC NULLS LAST'.
1337
+
1338
+ `beside` is the select list the key is written beside, where it
1339
+ is one. A key that names one of its columns, where another of
1340
+ them differs from that name by case alone, is written by its
1341
+ POSITION in the list: `SELECT ... AS "N", ... AS "n" ORDER BY "N"`
1342
+ is either column to DuckDB and an ambiguous reference to Spark and
1343
+ Databricks, and the answer's columns are the names that cannot be
1344
+ changed (docs/architecture/rules.md, "A name of the query is its
1345
+ own column"). Spark and Databricks read an
1346
+ ordinal while `spark.sql.orderByOrdinal` is true, their default.
1347
+ """
1348
+ col = key.column
1349
+ position = self._position_beside(col, beside)
1350
+ # Check metadata for complex expression (e.g. postCount - friendCount)
1351
+ expr_node = col.metadata.get('expr') if col.metadata else None
1352
+ if position is not None:
1353
+ ref = str(position)
1354
+ elif expr_node is not None and not isinstance(expr_node, ColExpr):
1355
+ ref = self._expr.serialize(expr_node)
1356
+ elif self._named_by_itself(col):
1357
+ ref = self._quote_alias(col.alias)
1358
+ elif col.sql and col.sql != '<sort_expr>':
1359
+ # Prefer the actual SQL expression (e.g. person.`birthday`) over
1360
+ # the alias (e.g. `person__birthday`); the alias is a synthetic
1361
+ # name for CTE columns that doesn't exist in the underlying table.
1362
+ ref = col.sql
1363
+ elif col.alias:
1364
+ ref = self._quote_alias(col.alias)
1365
+ else:
1366
+ ref = col.sql
1367
+
1368
+ ref = self._by_code_point(key, ref, position)
1369
+ direction = 'ASC' if key.direction == SortDirection.ASC else 'DESC'
1370
+ return f"{ref} {direction}{self._nulls_suffix(key)}"
1371
+
1372
+ def _by_code_point(self, key: SortKey, ref: str, position=None) -> str:
1373
+ """`ref` in the dialect's binary collation where the key is a text ordered by code point
1374
+ (`SortKey.codepoint`, rule codepoint-string-order); every dialect's sort key goes here.
1375
+ A key written by its position stays as it is (a collated ordinal is a constant)."""
1376
+ if not getattr(key, 'codepoint', False) or position is not None:
1377
+ return ref
1378
+ dialect = getattr(self._expr, '_dialect_obj', None)
1379
+ template = dialect.config.function_map.get('CODEPOINT_TEXT') if dialect is not None else None
1380
+ return template.format(ref) if template and template != '{0}' else ref
1381
+
1382
+ @staticmethod
1383
+ def _position_beside(col: ColumnRef, beside: Optional[list]) -> Optional[int]:
1384
+ """The 1-based position of `col` in the select list `beside`,
1385
+ where `col` names one of its columns and another of them differs
1386
+ from that name by case alone; else None."""
1387
+ if not beside or not col.alias or (col.metadata or {}).get('expr') is not None:
1388
+ return None
1389
+ from .names import differ_by_case_alone
1390
+ if col.sql != internal_name(col.alias):
1391
+ return None
1392
+ names = [c.alias for c in beside]
1393
+ if names.count(col.alias) != 1 or not any(
1394
+ name and differ_by_case_alone(name, col.alias) for name in names):
1395
+ return None
1396
+ return names.index(col.alias) + 1
1397
+
1398
+ @staticmethod
1399
+ def _nulls_suffix(key: SortKey) -> str:
1400
+ """Explicit ' NULLS FIRST'/' NULLS LAST' suffix pinning Cypher ordering.
1401
+
1402
+ Cypher treats null as larger than any value, so nulls sort LAST in ASC
1403
+ and FIRST in DESC. The dialect default disagrees and varies; DuckDB is
1404
+ nulls-last in both directions (DESC wrong); Spark is nulls-first ASC /
1405
+ nulls-last DESC (wrong on both), so we always emit an explicit clause to
1406
+ match the pandas/memory engines. Shared by every dialect serializer.
1407
+ """
1408
+ nulls = key.nulls
1409
+ if nulls is None:
1410
+ nulls = NullsOrder.LAST if key.direction == SortDirection.ASC else NullsOrder.FIRST
1411
+ return ' NULLS FIRST' if nulls == NullsOrder.FIRST else ' NULLS LAST'
1412
+
1413
+ def _assemble_sql(self, frame: QueryFrame) -> str:
1414
+ """Assemble a QueryFrame into a SQL string.
1415
+
1416
+ Override in subclasses for dialect-specific assembly (e.g.,
1417
+ SQL Server TOP/FETCH rewriting).
1418
+ """
1419
+ return frame.to_sql()