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,234 @@
1
+ """Cost hints: query shapes that are expensive by nature, read off the plan with no data (agreed 2026-11-11).
2
+
3
+ Four shapes and a note:
4
+
5
+ - `unpinned-join`: an aggregate over a join at a node both sides hold many rows of, by their declared
6
+ keys, grouped by that node or what it determines (`fan_out`: friends and posts counted per person,
7
+ every friend-post pair built before the counts). Shown by `explain` only; it warns once statistics give
8
+ it a number (step 2).
9
+ - `unseeded-closure`: a property path's closure with no seed, every pair of the step relation walked.
10
+ - `whole-graph`: a variable predicate over whole tables (`?s ?p ?o` with nothing narrowing it), every
11
+ row of every mapped table.
12
+ - `whole-iri-merge`: a Cypher node pattern over a map whose node ids are a column's whole values.
13
+ - `sameas-expansion`: under owl:sameAs (all aliases), a triple pattern whose positions expand to every
14
+ member of their components, up to largest^n rows per triple for n positions, past `EXPANSION_HINT`.
15
+ - The note `keys-not-declared`, once per query: a join under a reduction over tables that declare no key,
16
+ so nothing tells whether it multiplies rows. Shown by `explain`, never warned or refused.
17
+
18
+ `explain` lists every hint. The last two warn by default (`ProGraphCostWarning`). A query is refused
19
+ before any SQL runs (`QueryTooExpensiveError`) only where the engine's `refuse_costly` or the query's
20
+ `refuse` hint names its shape (opt-in). No statistics are read here: Brice's decision of 2026-11-11 lets
21
+ statistics rank proven-equivalent plans in an opt-in mode, never decide what a rule may do.
22
+ """
23
+
24
+ from __future__ import annotations
25
+
26
+ import warnings
27
+ from dataclasses import dataclass
28
+ from typing import Dict, Iterable, List, Optional
29
+
30
+ from prograph.plan.ir import ops as O
31
+ from prograph.rules import home
32
+
33
+ UNPINNED_JOIN, UNSEEDED_CLOSURE, WHOLE_GRAPH = "unpinned-join", "unseeded-closure", "whole-graph"
34
+ WHOLE_IRI_MERGE, KEYS_NOT_DECLARED = "whole-iri-merge", "keys-not-declared"
35
+ SAMEAS_EXPANSION = "sameas-expansion"
36
+ TOP_PROPERTY = "top-property"
37
+ SHAPES = (UNPINNED_JOIN, UNSEEDED_CLOSURE, WHOLE_GRAPH, WHOLE_IRI_MERGE, SAMEAS_EXPANSION, TOP_PROPERTY)
38
+ NOTES = (KEYS_NOT_DECLARED,)
39
+ WARNED_BY_DEFAULT = frozenset({UNSEEDED_CLOSURE, WHOLE_GRAPH, WHOLE_IRI_MERGE, TOP_PROPERTY})
40
+
41
+ SUGGESTIONS = {
42
+ UNPINNED_JOIN: "Aggregate each side per node in a sub-select and join the results, or pin the node down "
43
+ "(a constant, or a VALUES of a few).",
44
+ KEYS_NOT_DECLARED: "Declare their keys (a PRIMARY KEY or UNIQUE constraint the database enforces, a "
45
+ "Databricks primary key with RELY, or `keys: trusted` on the mapping).",
46
+ UNSEEDED_CLOSURE: "Seed the path from a constant or a bound variable at one end (<x> ex:p+ ?y).",
47
+ WHOLE_GRAPH: "Add a constant subject, predicate or object, or name the predicates you need.",
48
+ WHOLE_IRI_MERGE: "If that mapping's nodes are never another mapping's, say so: `identity: distinct` on it.",
49
+ TOP_PROPERTY: "Bind one end to a constant, or name the property you mean: owl:topObjectProperty relates "
50
+ "every individual to every individual.",
51
+ SAMEAS_EXPANSION: "Bind the entity by a constant, or answer one row per entity: sameas=\"representative\"; "
52
+ "engine.explain_identity(a, b) shows why the component is large.",
53
+ }
54
+
55
+
56
+ class ProGraphCostWarning(UserWarning):
57
+ """A query of a shape that reads every row of a large relation (`cost_hints`)."""
58
+
59
+
60
+ @dataclass(frozen=True)
61
+ class CostHint:
62
+ shape: str
63
+ where: str
64
+ suggestion: str
65
+
66
+ def __str__(self) -> str:
67
+ return f"{self.shape}: {self.where}. {self.suggestion}"
68
+
69
+
70
+ def _walk(op: O.Op, under: bool = False, seen: Optional[set] = None):
71
+ """Each (operator, whether under a reducing one) of a plan once. A plan is a DAG whose subtrees are
72
+ shared (a recursive walk's steps, each reading the one before): a walk that revisited a shared node
73
+ by every path would take time exponential in the depth, so a node is read once per `under`."""
74
+ seen = set() if seen is None else seen
75
+ if (id(op), under) in seen:
76
+ return
77
+ seen.add((id(op), under))
78
+ yield op, under
79
+ reduces = under or isinstance(op, (O.Aggregate, O.Distinct, O.Order))
80
+ for child in op.children():
81
+ yield from _walk(child, reduces, seen)
82
+
83
+
84
+ ONE, MANY = "one", "many"
85
+ _THROUGH = (O.Filter, O.Extend, O.Project)
86
+
87
+
88
+ def _side(side: O.Op, shared: frozenset):
89
+ """ONE where the facts prove at most one row per value of `shared`; else the tables under `side`
90
+ with no trusted key (a tuple, nonempty: nothing is known); else MANY (keys declared, none within)."""
91
+ from prograph.plan.ir.facts import facts
92
+ f = facts(side)
93
+ if f.unique(shared) or (f.rows[1] is not None and f.rows[1] <= 1):
94
+ return ONE
95
+ bare = tuple(sorted({x.map.source.table for x, _ in _walk(side)
96
+ if isinstance(x, O.MapScan) and not x.unique_keys}))
97
+ return bare or MANY
98
+
99
+
100
+ def _operands(op: O.Op):
101
+ """A join tree's operands (a filter, extend or projection over a join is looked through)."""
102
+ inner = op
103
+ while isinstance(inner, _THROUGH):
104
+ inner = inner.input
105
+ if isinstance(inner, O.Join):
106
+ yield from _operands(inner.left)
107
+ yield from _operands(inner.right)
108
+ else:
109
+ yield op
110
+
111
+
112
+ def _joins(op: O.Op):
113
+ while isinstance(op, _THROUGH):
114
+ op = op.input
115
+ if isinstance(op, O.Join):
116
+ yield op
117
+ yield from _joins(op.left)
118
+ yield from _joins(op.right)
119
+
120
+
121
+ @home("fan-out", "An aggregate over a join at a node both sides hold many rows of",
122
+ terms=("fan-out", "fan out", "multi-valued sides", "eager aggregation", "count per node", "R11"))
123
+ def fan_out(agg: O.Aggregate) -> str:
124
+ """The node (a column name) where `agg` aggregates over a join whose two sides each hold many rows
125
+ per node by their declared keys (neither side's keys lie within the node), every grouping column
126
+ being the node or a column of a part of the join keyed on it: friends and posts counted per person.
127
+ Every pair through the node is built before the aggregate; eager aggregation computes each side
128
+ per node first. '' where there is none, or a side's tables declare no key (nothing is known)."""
129
+ from prograph.plan.ir.facts import facts
130
+ for j in _joins(agg.input):
131
+ node = frozenset(j.shared)
132
+ if len(node) != 1 or _side(j.left, node) != MANY or _side(j.right, node) != MANY:
133
+ continue
134
+ parts = [x for x in _operands(j) if facts(x).unique(node)]
135
+ if all(g in node or any(g in x.columns for x in parts) for g in agg.group):
136
+ return next(iter(node))
137
+ return ""
138
+
139
+
140
+ def _whole_graph(op: O.Union) -> bool:
141
+ """A variable predicate's union over whole tables: every input binds a constant (the predicate,
142
+ the front end's Extend over each branch), and no branch read as a map's pattern has a condition
143
+ narrowing its rows (a constant subject or object would be one)."""
144
+ from prograph.plan.ir import expr as E
145
+ from prograph.plan.ir.rewrite import _groups_of
146
+ if len(op.inputs) < 2 or not all(isinstance(x, O.Extend) and isinstance(x.expr, E.Const) for x in op.inputs):
147
+ return False
148
+ members = [m for g in (_groups_of(op) or []) if g[0] for m in g[0]]
149
+ return len(members) >= 2 and not any(p.conditions for _, p, _, _ in members)
150
+
151
+
152
+ def _whole_iri(op: O.Aggregate) -> str:
153
+ """A Cypher node pattern's merge (its maps' union grouped by the node, `cypher-node-scan`) where one
154
+ of the maps has subjects with no fixed prefix (`{uri}`, a column), which meets every other: its name,
155
+ else ''."""
156
+ from prograph.plan.ir.cypher_front import MERGED
157
+ if not any(name.endswith(MERGED) for name, _ in op.aggregates):
158
+ return "" # not a Cypher node merge (the front end marks its own)
159
+ scans = [x for x, _ in _walk(op.input) if isinstance(x, O.MapScan) and hasattr(x.map, "subject")]
160
+ whole = [x for x in scans if not x.map.subject.prefix()]
161
+ if whole and len({x.map.id for x in scans}) > 1:
162
+ return f"the mapping of {whole[0].map.source.table}"
163
+ return ""
164
+
165
+
166
+ def _expansion(scan: O.MapScan):
167
+ """(positions, largest component) of an owl:sameAs expansion's alias scan (`identity._expanded`) whose
168
+ rows a triple may reach `identity.EXPANSION_HINT`; None for any other scan."""
169
+ import re
170
+ from prograph.plan.ir.identity import ALIAS_MAP, EXPANSION_HINT
171
+ found = re.search(r"-expand(\d+)-k(\d+)$", scan.map.id) if scan.map.id.startswith(ALIAS_MAP) else None
172
+ if found is None:
173
+ return None
174
+ n, k = int(found.group(1)), int(found.group(2))
175
+ return (n, k) if k ** n >= EXPANSION_HINT else None
176
+
177
+
178
+ @home("cost-warnings", "Query shapes expensive by nature: hints, default warnings, opt-in refusal",
179
+ terms=("cost", "expensive query", "QueryTooExpensiveError", "refuse_costly", "unseeded closure",
180
+ "whole graph", "unpinned join", "ProGraphCostWarning"))
181
+ def cost_hints(plan: O.Op) -> List[CostHint]:
182
+ """The cost hints of a planned query, each shape once, then the notes (`NOTES`)."""
183
+ found = {}
184
+ suggestion: Dict[str, str] = {}
185
+ bare = set()
186
+ for op, under in _walk(plan):
187
+ if isinstance(op, O.Closure) and op.seed is None and UNSEEDED_CLOSURE not in found:
188
+ found[UNSEEDED_CLOSURE] = (
189
+ "a variable-length relationship walked from every node (one row per trail)" if op.mode == O.CYPHER
190
+ else "a property path walked from every node of its step")
191
+ if op.mode == O.CYPHER:
192
+ suggestion[UNSEEDED_CLOSURE] = (f"Set {op.bound_by} or bind its start." if op.bound_by
193
+ else "Bound the path length (*1..n) or bind its start.")
194
+ elif isinstance(op, O.Aggregate) and WHOLE_IRI_MERGE not in found and _whole_iri(op):
195
+ found[WHOLE_IRI_MERGE] = (f"a node pattern also reads {_whole_iri(op)}, whose node ids are a column's "
196
+ "whole values (`iri_template: \"{uri}\"`), so its nodes may be any "
197
+ "label's: every row is merged by node id")
198
+ elif isinstance(op, O.Union) and WHOLE_GRAPH not in found and _whole_graph(op):
199
+ found[WHOLE_GRAPH] = "a variable predicate over every row of its tables"
200
+ elif isinstance(op, O.MapScan) and SAMEAS_EXPANSION not in found and _expansion(op):
201
+ n, k = _expansion(op)
202
+ found[SAMEAS_EXPANSION] = (f"a triple pattern's {n} position{'s' if n > 1 else ''} expand to every IRI of "
203
+ f"their owl:sameAs components, the largest of {k}: up to {k ** n} rows a "
204
+ f"triple")
205
+ if op.__dict__.get("_top_property") and TOP_PROPERTY not in found:
206
+ found[TOP_PROPERTY] = "owl:topObjectProperty between two unbound ends: every pair of named individuals"
207
+ if isinstance(op, O.Aggregate) and UNPINNED_JOIN not in found and fan_out(op):
208
+ found[UNPINNED_JOIN] = (f"an aggregate over a join at ?{fan_out(op)}, whose two sides each hold "
209
+ f"many rows per ?{fan_out(op)}: every pair is built before the aggregate")
210
+ if under and isinstance(op, O.Join) and op.shared:
211
+ shared = frozenset(op.shared)
212
+ sides = (_side(op.left, shared), _side(op.right, shared))
213
+ if ONE not in sides:
214
+ bare.update(t for x in sides if x != MANY for t in x)
215
+ if bare:
216
+ found[KEYS_NOT_DECLARED] = (f"{', '.join(sorted(bare))} declare{'s' if len(bare) == 1 else ''} no key, "
217
+ f"so whether a join under an aggregate, DISTINCT or ORDER BY multiplies "
218
+ f"rows is not known")
219
+ return [CostHint(s, found[s], suggestion.get(s, SUGGESTIONS[s])) for s in SHAPES + NOTES if s in found]
220
+
221
+
222
+ def check(plan: O.Op, refuse: Iterable[str] = ()) -> List[CostHint]:
223
+ """Warn of the default shapes, and refuse a shape `refuse` names (`all`: every shape), before any
224
+ SQL runs."""
225
+ from prograph.utils.exceptions import QueryTooExpensiveError
226
+ hints = cost_hints(plan)
227
+ refused = set(SHAPES) if "all" in set(refuse) else set(refuse)
228
+ for h in hints:
229
+ if h.shape in refused:
230
+ raise QueryTooExpensiveError(h.shape, str(h))
231
+ for h in hints:
232
+ if h.shape in WARNED_BY_DEFAULT:
233
+ warnings.warn(f"ProGraph cost: {h}", ProGraphCostWarning, stacklevel=4)
234
+ return hints