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.
- prograph/__init__.py +36 -0
- prograph/__main__.py +5 -0
- prograph/_version.py +375 -0
- prograph/cli/__init__.py +1 -0
- prograph/cli/_iri_utils.py +124 -0
- prograph/cli/emit_genie_space.py +107 -0
- prograph/cli/generate_views.py +140 -0
- prograph/cli/main.py +420 -0
- prograph/cli/schema_inferrer.py +746 -0
- prograph/cli/ttl_loader.py +289 -0
- prograph/cli/upload_genie_space.py +84 -0
- prograph/config/__init__.py +27 -0
- prograph/config/yaml_config.py +848 -0
- prograph/demos/__init__.py +14 -0
- prograph/demos/turbofan/README.md +74 -0
- prograph/demos/turbofan/SCENARIO.md +209 -0
- prograph/demos/turbofan/__init__.py +75 -0
- prograph/demos/turbofan/create_tables.sql +206 -0
- prograph/demos/turbofan/data/engine-instances.ttl +1123 -0
- prograph/demos/turbofan/data/sensor-timeseries.csv +90 -0
- prograph/demos/turbofan/demo.py +162 -0
- prograph/demos/turbofan/genie_qa_notebook.py +434 -0
- prograph/demos/turbofan/graph.yaml +1098 -0
- prograph/demos/turbofan/instance_graph_demo.py +32 -0
- prograph/demos/turbofan/load.py +223 -0
- prograph/demos/turbofan/mapping.r2rml.ttl +991 -0
- prograph/demos/turbofan/ontology/engine-maintenance.ttl +606 -0
- prograph/demos/turbofan/payload-shapes.ttl +33 -0
- prograph/demos/turbofan/queries/example-queries.sparql +215 -0
- prograph/demos/turbofan/shapes.ttl +75 -0
- prograph/demos/turbofan/tables.py +106 -0
- prograph/demos/turbofan/turbofan_schema.py +393 -0
- prograph/demos/turbofan/validation_demo.py +153 -0
- prograph/describe.py +231 -0
- prograph/endpoint/__init__.py +12 -0
- prograph/endpoint/app.py +722 -0
- prograph/endpoint/cli.py +280 -0
- prograph/endpoint/credentials.py +240 -0
- prograph/endpoint/engines.py +418 -0
- prograph/endpoint/negotiate.py +101 -0
- prograph/endpoint/results.py +181 -0
- prograph/endpoint/service.py +31 -0
- prograph/engine.py +2718 -0
- prograph/execution.py +455 -0
- prograph/executors/__init__.py +6 -0
- prograph/executors/base.py +11 -0
- prograph/executors/databricks_sql_executor.py +51 -0
- prograph/executors/duckdb_executor.py +24 -0
- prograph/executors/mysql_executor.py +20 -0
- prograph/executors/oracle_executor.py +24 -0
- prograph/executors/pandas_executor.py +72 -0
- prograph/executors/postgresql_executor.py +35 -0
- prograph/executors/spark_executor.py +88 -0
- prograph/executors/sqlserver_executor.py +35 -0
- prograph/extras/__init__.py +1 -0
- prograph/extras/graphql/__init__.py +33 -0
- prograph/extras/graphql/execute.py +25 -0
- prograph/extras/graphql/schema.py +314 -0
- prograph/extras/instance_graph.py +559 -0
- prograph/genie/__init__.py +83 -0
- prograph/genie/databricks_uploader.py +306 -0
- prograph/genie/deploy.py +393 -0
- prograph/genie/formats.py +414 -0
- prograph/genie/instruction_generator.py +375 -0
- prograph/genie/sample_query_generator.py +256 -0
- prograph/genie/shacl_views.py +318 -0
- prograph/genie/space_emitter.py +329 -0
- prograph/genie/view_generator.py +628 -0
- prograph/genie/view_writer.py +172 -0
- prograph/graph/__init__.py +1 -0
- prograph/graph/ansi_session.py +348 -0
- prograph/graph/databricks_sql_graph.py +300 -0
- prograph/graph/drivers.py +143 -0
- prograph/graph/duckdb_graph.py +68 -0
- prograph/graph/mysql_graph.py +38 -0
- prograph/graph/oracle_graph.py +285 -0
- prograph/graph/pandas_graph.py +343 -0
- prograph/graph/postgresql_graph.py +644 -0
- prograph/graph/spark_graph.py +556 -0
- prograph/graph/sql_graph.py +83 -0
- prograph/graph/sqlserver_graph.py +72 -0
- prograph/hints.py +95 -0
- prograph/logging.py +550 -0
- prograph/mcp/__init__.py +29 -0
- prograph/mcp/__main__.py +180 -0
- prograph/mcp/bootstrap.py +98 -0
- prograph/mcp/server.py +601 -0
- prograph/mcp/sparql.py +397 -0
- prograph/mcp/tools.py +504 -0
- prograph/nlp/__init__.py +79 -0
- prograph/nlp/client.py +305 -0
- prograph/nlp/databricks_tools.py +369 -0
- prograph/nlp/graph_context.py +313 -0
- prograph/nlp/interface.py +652 -0
- prograph/nlp/prompts/__init__.py +19 -0
- prograph/nlp/prompts/examples.py +258 -0
- prograph/nlp/prompts/system.py +239 -0
- prograph/nlp/providers/__init__.py +14 -0
- prograph/nlp/providers/anthropic.py +274 -0
- prograph/nlp/providers/databricks.py +312 -0
- prograph/nlp/providers/openai.py +203 -0
- prograph/nlp/schema_context.py +78 -0
- prograph/ontology/__init__.py +53 -0
- prograph/ontology/alignment.py +542 -0
- prograph/ontology/hierarchy.py +310 -0
- prograph/ontology/imports.py +587 -0
- prograph/ontology/layer.py +991 -0
- prograph/ontology/skos.py +61 -0
- prograph/owl/__init__.py +27 -0
- prograph/owl/defined_classes.py +323 -0
- prograph/parameters.py +242 -0
- prograph/parser/__init__.py +1 -0
- prograph/parser/cypher/CypherLexer.py +836 -0
- prograph/parser/cypher/CypherListener.py +966 -0
- prograph/parser/cypher/CypherParser.py +10854 -0
- prograph/parser/cypher/CypherVisitor.py +543 -0
- prograph/parser/cypher/__init__.py +1 -0
- prograph/parser/sparql/SparqlLexer.py +801 -0
- prograph/parser/sparql/SparqlParser.py +10146 -0
- prograph/parser/sparql/SparqlParserListener.py +1056 -0
- prograph/parser/sparql/SparqlParserVisitor.py +593 -0
- prograph/parser/sparql/__init__.py +8 -0
- prograph/plan/__init__.py +3 -0
- prograph/plan/ir/__init__.py +1 -0
- prograph/plan/ir/casts.py +338 -0
- prograph/plan/ir/consistency.py +397 -0
- prograph/plan/ir/construct.py +90 -0
- prograph/plan/ir/cost.py +234 -0
- prograph/plan/ir/cypher_answer.py +1081 -0
- prograph/plan/ir/cypher_apoc.py +717 -0
- prograph/plan/ir/cypher_apoc_convert.py +505 -0
- prograph/plan/ir/cypher_apoc_date.py +845 -0
- prograph/plan/ir/cypher_apoc_map.py +496 -0
- prograph/plan/ir/cypher_apoc_meta.py +384 -0
- prograph/plan/ir/cypher_apoc_path.py +597 -0
- prograph/plan/ir/cypher_apoc_procedures.py +163 -0
- prograph/plan/ir/cypher_apoc_text.py +785 -0
- prograph/plan/ir/cypher_front.py +5474 -0
- prograph/plan/ir/cypher_functions.py +565 -0
- prograph/plan/ir/cypher_lists.py +935 -0
- prograph/plan/ir/cypher_maps.py +370 -0
- prograph/plan/ir/cypher_mixed.py +604 -0
- prograph/plan/ir/cypher_ontology.py +226 -0
- prograph/plan/ir/cypher_procedures.py +191 -0
- prograph/plan/ir/cypher_runtime_errors.py +107 -0
- prograph/plan/ir/cypher_temporal.py +1357 -0
- prograph/plan/ir/cypher_temporal_arith.py +339 -0
- prograph/plan/ir/cypher_values.py +546 -0
- prograph/plan/ir/cypher_write.py +612 -0
- prograph/plan/ir/dataset.py +643 -0
- prograph/plan/ir/dates.py +102 -0
- prograph/plan/ir/entry.py +992 -0
- prograph/plan/ir/expr.py +260 -0
- prograph/plan/ir/facts.py +1171 -0
- prograph/plan/ir/fresh.py +291 -0
- prograph/plan/ir/freshness.py +625 -0
- prograph/plan/ir/identity.py +797 -0
- prograph/plan/ir/java_datetime.py +265 -0
- prograph/plan/ir/java_regex.py +391 -0
- prograph/plan/ir/join_order.py +39 -0
- prograph/plan/ir/key_checks.py +433 -0
- prograph/plan/ir/keys.py +454 -0
- prograph/plan/ir/lower.py +5323 -0
- prograph/plan/ir/ops.py +619 -0
- prograph/plan/ir/owl_rl.py +1119 -0
- prograph/plan/ir/owl_rl_rules.py +725 -0
- prograph/plan/ir/profiles.py +694 -0
- prograph/plan/ir/ql.py +987 -0
- prograph/plan/ir/rdfs.py +342 -0
- prograph/plan/ir/rewrite.py +1782 -0
- prograph/plan/ir/saturate.py +339 -0
- prograph/plan/ir/semantics.py +103 -0
- prograph/plan/ir/slot.py +509 -0
- prograph/plan/ir/sparql_front.py +3418 -0
- prograph/plan/ir/strings.py +534 -0
- prograph/plan/ir/term_functions.py +274 -0
- prograph/plan/ir/terms.py +84 -0
- prograph/plan/ir/xpath_regex.py +264 -0
- prograph/plan/run_record.py +65 -0
- prograph/plan/sql/__init__.py +21 -0
- prograph/plan/sql/dialect.py +3726 -0
- prograph/plan/sql/mysql_serializer.py +103 -0
- prograph/plan/sql/names.py +65 -0
- prograph/plan/sql/oracle_serializer.py +306 -0
- prograph/plan/sql/pg_serializer.py +501 -0
- prograph/plan/sql/rel_algebra.py +781 -0
- prograph/plan/sql/sql_serializer.py +1419 -0
- prograph/plan/sql/sqlserver_serializer.py +603 -0
- prograph/provenance.py +222 -0
- prograph/r2rml/__init__.py +48 -0
- prograph/r2rml/catalog.py +259 -0
- prograph/r2rml/compile.py +372 -0
- prograph/r2rml/direct.py +140 -0
- prograph/r2rml/export.py +495 -0
- prograph/r2rml/model.py +180 -0
- prograph/r2rml/parser.py +546 -0
- prograph/r2rml/schema.py +120 -0
- prograph/read_only.py +122 -0
- prograph/results.py +157 -0
- prograph/rules/__init__.py +168 -0
- prograph/rules/__main__.py +32 -0
- prograph/schema/__init__.py +60 -0
- prograph/schema/change_set.py +50 -0
- prograph/schema/collations.py +198 -0
- prograph/schema/compile_schema.py +388 -0
- prograph/schema/context.py +845 -0
- prograph/schema/examples.py +234 -0
- prograph/schema/iri.py +817 -0
- prograph/schema/literals.py +94 -0
- prograph/schema/lpg_view.py +617 -0
- prograph/schema/mapping.py +1803 -0
- prograph/schema/maps_schema.py +40 -0
- prograph/schema/naming.py +77 -0
- prograph/schema/query_sources.py +59 -0
- prograph/schema/rows.py +215 -0
- prograph/schema/source_map.py +1103 -0
- prograph/schema/store_view.py +459 -0
- prograph/schema/types.py +569 -0
- prograph/schema/xsd.py +569 -0
- prograph/shacl/__init__.py +30 -0
- prograph/shacl/dqv.py +58 -0
- prograph/shacl/generate.py +255 -0
- prograph/shacl/report.py +138 -0
- prograph/shacl/validator.py +164 -0
- prograph/store.py +1737 -0
- prograph/utils/__init__.py +6 -0
- prograph/utils/exceptions.py +308 -0
- prograph/utils/helpers.py +126 -0
- prograph/warnings.py +46 -0
- prograph/writes.py +369 -0
- prograph-1.3.3.dist-info/METADATA +281 -0
- prograph-1.3.3.dist-info/RECORD +237 -0
- prograph-1.3.3.dist-info/WHEEL +5 -0
- prograph-1.3.3.dist-info/entry_points.txt +3 -0
- prograph-1.3.3.dist-info/licenses/LICENSE +201 -0
- prograph-1.3.3.dist-info/licenses/NOTICE +10 -0
- prograph-1.3.3.dist-info/top_level.txt +1 -0
prograph/plan/ir/cost.py
ADDED
|
@@ -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
|