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/writes.py
ADDED
|
@@ -0,0 +1,369 @@
|
|
|
1
|
+
"""Writing properties to nodes named by identity, and the rows a mapping
|
|
2
|
+
owns.
|
|
3
|
+
|
|
4
|
+
``engine.set_properties(label, identities, values)`` sets the same values
|
|
5
|
+
on a set of nodes, each named by its key or its IRI. It is the write an
|
|
6
|
+
action layer needs (ProAct): it holds the identities of the entities a
|
|
7
|
+
decision is about, not a Cypher pattern that finds them. It is the one
|
|
8
|
+
write ProGraph makes to a table it maps, and only to a mapping marked
|
|
9
|
+
``mutable`` (decided 2026-11-04, opt-in writes); every other write to a
|
|
10
|
+
user's table is refused (``prograph.read_only``).
|
|
11
|
+
|
|
12
|
+
Which rows such a write may touch is one rule:
|
|
13
|
+
|
|
14
|
+
- the rows whose key is one of the identities, every part of a composite
|
|
15
|
+
key compared;
|
|
16
|
+
- that the label's mapping owns: on a table several labels share, a
|
|
17
|
+
mapping's ``filter_predicate`` picks its rows, and another label's row
|
|
18
|
+
with the same key value is not this node;
|
|
19
|
+
- that are asserted: a row a reasoner materialized (``_inferred``) is a
|
|
20
|
+
consequence of other rows, not a fact to edit.
|
|
21
|
+
|
|
22
|
+
:func:`row_conditions` states the rule in SQL, for a SQL database and for
|
|
23
|
+
Spark; :func:`row_mask` states it for a pandas DataFrame. Reads use the
|
|
24
|
+
same rows: :func:`owned_conditions`, :func:`own_asserted_conditions`,
|
|
25
|
+
:func:`own_rows_sql`, :func:`is_inferred`; whether text a caller
|
|
26
|
+
hands over is one query: :func:`require_one_query`.
|
|
27
|
+
"""
|
|
28
|
+
|
|
29
|
+
from __future__ import annotations
|
|
30
|
+
|
|
31
|
+
import re
|
|
32
|
+
from typing import Any, Dict, List, Mapping, NamedTuple, Optional, Sequence, Tuple
|
|
33
|
+
from prograph.rules import home
|
|
34
|
+
|
|
35
|
+
INFERRED_COLUMN = "_inferred"
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
@home("inferred-rows", "Whether a row is inferred",
|
|
39
|
+
terms=("_inferred", "is_inferred", "inferred_mask", "asserted"))
|
|
40
|
+
def is_inferred(flag: Any) -> bool:
|
|
41
|
+
"""Whether one row's `_inferred` value says a reasoner materialized the
|
|
42
|
+
row. The flag is a boolean in some tables and 1/0 in others; a missing
|
|
43
|
+
one (NULL, NaN, no such column) is an asserted row. The one reading of
|
|
44
|
+
the flag for code that holds a row; SQL states it in
|
|
45
|
+
:func:`own_asserted_conditions`."""
|
|
46
|
+
from prograph.schema.types import is_missing
|
|
47
|
+
|
|
48
|
+
return not is_missing(flag) and bool(flag)
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def inferred_mask(frame: Any) -> Any:
|
|
52
|
+
""":func:`is_inferred` over a pandas DataFrame that has the column, as
|
|
53
|
+
one column operation: a write runs it over the whole frame."""
|
|
54
|
+
flag = frame[INFERRED_COLUMN]
|
|
55
|
+
return (flag.notna() & flag.ne(0)).fillna(False).astype(bool)
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
def _key_parts(mapping: Any, key: Any) -> Tuple[Any, ...]:
|
|
59
|
+
"""A key as a tuple in ``id_columns`` order; ValueError when it is not
|
|
60
|
+
one of this mapping's keys."""
|
|
61
|
+
from prograph.schema.types import is_missing
|
|
62
|
+
|
|
63
|
+
parts = tuple(key) if isinstance(key, (tuple, list)) else (key,)
|
|
64
|
+
if len(parts) != len(mapping.id_columns):
|
|
65
|
+
raise ValueError(
|
|
66
|
+
f"{mapping.label} is keyed by {', '.join(mapping.id_columns)}: "
|
|
67
|
+
f"a key has {len(mapping.id_columns)} part(s), got {key!r}")
|
|
68
|
+
if any(is_missing(part) for part in parts):
|
|
69
|
+
raise ValueError(f"{key!r} is no key of {mapping.label}: a part of it is missing")
|
|
70
|
+
return parts
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
@home("write-rows", "Rows a write by identity may touch",
|
|
74
|
+
terms=("set_properties", "row_mask", "row_conditions", "owned_values", "update_sql"))
|
|
75
|
+
def row_conditions(mapping: Any, keys: Sequence[Any], dialect: Any, has_inferred: bool) -> List[str]:
|
|
76
|
+
"""The SQL conditions, to be joined with AND, selecting the rows a write
|
|
77
|
+
to these keys of `mapping` may touch. `dialect` quotes the names and
|
|
78
|
+
writes the literals, the one way either enters SQL."""
|
|
79
|
+
q, lit = dialect.quote, dialect.literal
|
|
80
|
+
columns = list(mapping.id_columns)
|
|
81
|
+
rows = [_key_parts(mapping, key) for key in keys]
|
|
82
|
+
if not rows:
|
|
83
|
+
return ["1 = 0"]
|
|
84
|
+
if len(columns) == 1:
|
|
85
|
+
conditions = [f"{q(columns[0])} IN ({', '.join(lit(row[0]) for row in rows)})"]
|
|
86
|
+
else:
|
|
87
|
+
# Written out: SQL Server has no row-value IN.
|
|
88
|
+
conditions = ["(" + " OR ".join(
|
|
89
|
+
"(" + " AND ".join(f"{q(c)} = {lit(v)}" for c, v in zip(columns, row)) + ")"
|
|
90
|
+
for row in rows) + ")"]
|
|
91
|
+
return conditions + own_asserted_conditions(mapping, dialect, has_inferred)
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
from prograph.schema.rows import column_condition, owned_conditions, owned_values # noqa: E402,F401
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
class SQLQuoting(NamedTuple):
|
|
98
|
+
"""How a dialect writes a name and a string (`Dialect.quote`,
|
|
99
|
+
`Dialect.render_string`), as patterns that read them back: `ident` a
|
|
100
|
+
name in its quotes, `literal` a value. A backtick dialect (Spark,
|
|
101
|
+
Databricks, MySQL) escapes a backslash and may escape a quote with one;
|
|
102
|
+
the double-quote dialects double a quote and keep a backslash as it is
|
|
103
|
+
(`kind = 'x\\y'` is the three characters)."""
|
|
104
|
+
quote: str
|
|
105
|
+
ident: str
|
|
106
|
+
literal: str
|
|
107
|
+
|
|
108
|
+
def name(self, text: str) -> str:
|
|
109
|
+
"""A name as `ident` matched it, its quotes removed."""
|
|
110
|
+
return text[1:-1].replace(self.quote * 2, self.quote)
|
|
111
|
+
|
|
112
|
+
def names(self, text: str) -> str:
|
|
113
|
+
"""A dotted name, each part read by `name`."""
|
|
114
|
+
return ".".join(self.name(part) for part in re.findall(self.ident, text))
|
|
115
|
+
|
|
116
|
+
def value(self, text: Optional[str]) -> Any:
|
|
117
|
+
"""A literal as `literal` matched it, as its Python value."""
|
|
118
|
+
if text is None:
|
|
119
|
+
return None
|
|
120
|
+
upper = text.upper()
|
|
121
|
+
if upper in ("TRUE", "FALSE"):
|
|
122
|
+
return upper == "TRUE"
|
|
123
|
+
if text[:2] in ("E'", "e'"): # PostgreSQL's escape string: '' a quote, a backslash escapes
|
|
124
|
+
return re.sub(r"\\(.)", r"\1", text[2:-1].replace("''", "'"))
|
|
125
|
+
if text.startswith("'"):
|
|
126
|
+
body = text[1:-1].replace("''", "'")
|
|
127
|
+
return re.sub(r"\\(.)", r"\1", body) if self.quote == "`" else body
|
|
128
|
+
return float(text) if "." in text else int(text)
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
_NUMBER_OR_BOOLEAN = r"-?\d+(?:\.\d+)?|TRUE|FALSE"
|
|
132
|
+
SQL_QUOTINGS = (
|
|
133
|
+
SQLQuoting('"', r'"(?:[^"]|"")+"', rf"(?:[Ee]'(?:[^'\\]|''|\\.)*'|'(?:[^']|'')*'|{_NUMBER_OR_BOOLEAN})"),
|
|
134
|
+
SQLQuoting('`', r'`(?:[^`]|``)+`', rf"(?:'(?:[^'\\]|''|\\.)*'|{_NUMBER_OR_BOOLEAN})"),
|
|
135
|
+
)
|
|
136
|
+
|
|
137
|
+
|
|
138
|
+
def owned_query(sql: str) -> Optional[Tuple[str, Dict[str, Any]]]:
|
|
139
|
+
"""The table and the column values of a query that keeps one mapping's
|
|
140
|
+
rows of a shared table: `SELECT * FROM <table> WHERE <col> = <value>
|
|
141
|
+
[AND ...]`, each condition as :func:`column_condition` writes it (`IS
|
|
142
|
+
NULL` for a None), every name quoted, in one dialect's quoting
|
|
143
|
+
(`SQL_QUOTINGS`). The reading back of :func:`owned_conditions` (an
|
|
144
|
+
R2RML export writes a filtered label so):
|
|
145
|
+
the table and its `filter_predicate`, the same rows. None for any other
|
|
146
|
+
query: a name written bare (`FROM Things`, `main.things`) is read by
|
|
147
|
+
the database's own rules, which a frame's name does not follow, so such
|
|
148
|
+
a query stays a query."""
|
|
149
|
+
if not sql:
|
|
150
|
+
return None
|
|
151
|
+
for quoting in SQL_QUOTINGS:
|
|
152
|
+
condition = rf"({quoting.ident})\s*(?:=\s*({quoting.literal})|IS\s+NULL)"
|
|
153
|
+
match = re.fullmatch(
|
|
154
|
+
rf"\s*SELECT\s+\*\s+FROM\s+({quoting.ident}(?:\.{quoting.ident})*)\s+WHERE\s+"
|
|
155
|
+
rf"({condition}(?:\s+AND\s+{condition})*)\s*;?\s*", sql, flags=re.IGNORECASE | re.DOTALL)
|
|
156
|
+
if match is None:
|
|
157
|
+
continue
|
|
158
|
+
values: Dict[str, Any] = {}
|
|
159
|
+
for column, literal in re.findall(condition, match.group(2), flags=re.IGNORECASE):
|
|
160
|
+
name = quoting.name(column)
|
|
161
|
+
if name in values:
|
|
162
|
+
return None
|
|
163
|
+
values[name] = quoting.value(literal or None)
|
|
164
|
+
return quoting.names(match.group(1)), values
|
|
165
|
+
return None
|
|
166
|
+
|
|
167
|
+
|
|
168
|
+
def own_asserted_conditions(mapping: Any, dialect: Any, has_inferred: bool) -> List[str]:
|
|
169
|
+
"""The SQL conditions for "a row this mapping owns, and asserted": the
|
|
170
|
+
part of the rule that does not name keys, for a write that chooses its
|
|
171
|
+
rows another way (a Cypher MATCH's key list)."""
|
|
172
|
+
conditions = owned_conditions(mapping, dialect)
|
|
173
|
+
if has_inferred:
|
|
174
|
+
flag = dialect.quote(INFERRED_COLUMN)
|
|
175
|
+
# The flag is a boolean in some tables and 1/0 in others.
|
|
176
|
+
conditions.append(f"({flag} IS NULL OR CAST({flag} AS {dialect.type_name('INTEGER')}) = 0)")
|
|
177
|
+
return conditions
|
|
178
|
+
|
|
179
|
+
|
|
180
|
+
def own_rows_sql(mapping: Any, dialect: Any, has_inferred: bool,
|
|
181
|
+
columns: Optional[Sequence[str]] = None) -> str:
|
|
182
|
+
"""A SELECT of the rows a write by identity may touch, whatever their
|
|
183
|
+
keys: the mapping's table, the rows it owns, asserted. The
|
|
184
|
+
relation a caller's own SQL joins against to stay on a label's nodes `columns` defaults to the mapping's key columns."""
|
|
185
|
+
table = dialect.quote_qualified(mapping.qualified_source_table)
|
|
186
|
+
selected = ", ".join(dialect.quote(c) for c in (columns or mapping.id_columns))
|
|
187
|
+
conditions = own_asserted_conditions(mapping, dialect, has_inferred)
|
|
188
|
+
where = f" WHERE {' AND '.join(conditions)}" if conditions else ""
|
|
189
|
+
return f"SELECT {selected} FROM {table}{where}"
|
|
190
|
+
|
|
191
|
+
|
|
192
|
+
class NotAQueryError(ValueError):
|
|
193
|
+
"""SQL text that had to be one query and is not: a write, a statement
|
|
194
|
+
of another kind, or more than one statement."""
|
|
195
|
+
|
|
196
|
+
|
|
197
|
+
def require_one_query(duckdb_connection: Any, sql: str) -> None:
|
|
198
|
+
"""Refuse `sql` unless DuckDB's own parser finds exactly one statement
|
|
199
|
+
in it, a SELECT. No text is inspected here: a query that closes a
|
|
200
|
+
parenthesis and carries a DELETE after a semicolon is two statements to
|
|
201
|
+
the parser, whatever it was wrapped in (PA-0012's review)."""
|
|
202
|
+
try:
|
|
203
|
+
statements = duckdb_connection.extract_statements(sql)
|
|
204
|
+
except Exception as error: # noqa: BLE001 - DuckDB's own parser error
|
|
205
|
+
raise NotAQueryError(f"read-only SQL must be one query; DuckDB cannot parse this: "
|
|
206
|
+
f"{str(error).splitlines()[0]}") from error
|
|
207
|
+
kinds = [str(statement.type).rsplit(".", 1)[-1] for statement in statements]
|
|
208
|
+
if kinds != ["SELECT"]:
|
|
209
|
+
raise NotAQueryError(
|
|
210
|
+
f"read-only SQL must be one query; this is {len(kinds)} statement(s): "
|
|
211
|
+
f"{', '.join(kinds) or 'none'}")
|
|
212
|
+
|
|
213
|
+
|
|
214
|
+
|
|
215
|
+
|
|
216
|
+
def update_sql(mapping: Any, keys: Sequence[Any], columns: Mapping[str, Any],
|
|
217
|
+
dialect: Any, has_inferred: bool) -> str:
|
|
218
|
+
"""One UPDATE setting `columns` (column name to value) on the rows
|
|
219
|
+
:func:`row_conditions` selects."""
|
|
220
|
+
table = dialect.quote_qualified(mapping.qualified_source_table)
|
|
221
|
+
assignments = ", ".join(
|
|
222
|
+
f"{dialect.quote(column)} = {dialect.literal(value)}" for column, value in columns.items())
|
|
223
|
+
where = " AND ".join(row_conditions(mapping, keys, dialect, has_inferred))
|
|
224
|
+
return f"UPDATE {table} SET {assignments} WHERE {where}"
|
|
225
|
+
|
|
226
|
+
|
|
227
|
+
def row_mask(frame: Any, mapping: Any, keys: Sequence[Any]) -> Any:
|
|
228
|
+
"""The rule as a boolean mask over a pandas DataFrame."""
|
|
229
|
+
import pandas as pd
|
|
230
|
+
|
|
231
|
+
columns = list(mapping.id_columns)
|
|
232
|
+
rows = [_key_parts(mapping, key) for key in keys]
|
|
233
|
+
if len(columns) == 1:
|
|
234
|
+
mask = frame[columns[0]].isin([row[0] for row in rows])
|
|
235
|
+
else:
|
|
236
|
+
mask = pd.Series(pd.MultiIndex.from_frame(frame[columns]).isin(rows), index=frame.index)
|
|
237
|
+
mask &= _owned_mask(frame, mapping)
|
|
238
|
+
if INFERRED_COLUMN in frame.columns:
|
|
239
|
+
mask &= ~inferred_mask(frame)
|
|
240
|
+
return mask
|
|
241
|
+
|
|
242
|
+
|
|
243
|
+
def _owned_mask(frame: Any, mapping: Any) -> Any:
|
|
244
|
+
"""The rows of `frame` the mapping owns, as a mask: every discriminator
|
|
245
|
+
column the frame has, a None value being a missing one."""
|
|
246
|
+
import pandas as pd
|
|
247
|
+
from prograph.schema.rows import owned_column_mask
|
|
248
|
+
|
|
249
|
+
mask = pd.Series(True, index=frame.index)
|
|
250
|
+
for column, value in owned_values(mapping).items():
|
|
251
|
+
if column in frame.columns:
|
|
252
|
+
mask &= owned_column_mask(frame[column], value)
|
|
253
|
+
return mask
|
|
254
|
+
|
|
255
|
+
|
|
256
|
+
def _columns_to_set(schema: Any, mapping: Any, values: Mapping[str, Any]) -> Dict[str, Any]:
|
|
257
|
+
"""Property names to the columns they are stored in. A name must be a
|
|
258
|
+
property of the label (``schema.require_name``); the key and the
|
|
259
|
+
columns that make the row this label's are not properties to set."""
|
|
260
|
+
if not values:
|
|
261
|
+
raise ValueError("set_properties needs at least one property to set")
|
|
262
|
+
fixed = set(mapping.id_columns) | set(mapping.filter_predicate or {})
|
|
263
|
+
columns: Dict[str, Any] = {}
|
|
264
|
+
for name, value in values.items():
|
|
265
|
+
schema.require_name('property', name, mapping.label, write=True)
|
|
266
|
+
column = (mapping.property_columns or {}).get(name, name)
|
|
267
|
+
if column in fixed:
|
|
268
|
+
raise ValueError(
|
|
269
|
+
f"{name!r} is stored in {column!r}, which is part of what makes a row "
|
|
270
|
+
f"this {mapping.label}: setting it would change the node's identity")
|
|
271
|
+
if value is not None and not isinstance(value, (bool, int, float, str)):
|
|
272
|
+
raise ValueError(
|
|
273
|
+
f"set_properties writes literal values; {name!r} is a {type(value).__name__}")
|
|
274
|
+
columns[column] = value
|
|
275
|
+
return columns
|
|
276
|
+
|
|
277
|
+
|
|
278
|
+
def _keys(engine: Any, mapping: Any, identities: Sequence[Any], by: str) -> List[Any]:
|
|
279
|
+
"""The identities as keys. An IRI is read back to its node, so one that
|
|
280
|
+
names no node of this label contributes no key."""
|
|
281
|
+
if by == "key":
|
|
282
|
+
return [parts if len(parts) > 1 else parts[0]
|
|
283
|
+
for parts in (_key_parts(mapping, identity) for identity in identities)]
|
|
284
|
+
if by != "iri":
|
|
285
|
+
raise ValueError(f"by must be 'key' or 'iri', got {by!r}")
|
|
286
|
+
from prograph.schema.iri import require_key_template
|
|
287
|
+
|
|
288
|
+
require_key_template(mapping)
|
|
289
|
+
keys = []
|
|
290
|
+
for iri in identities:
|
|
291
|
+
if not isinstance(iri, str):
|
|
292
|
+
raise ValueError(f"an IRI is text, got {iri!r}")
|
|
293
|
+
found = engine.resolve_iri(iri)
|
|
294
|
+
if found is not None and mapping.label in found["labels"]:
|
|
295
|
+
keys.append(found["id"])
|
|
296
|
+
return keys
|
|
297
|
+
|
|
298
|
+
|
|
299
|
+
def set_properties(engine: Any, label: str, identities: Sequence[Any],
|
|
300
|
+
values: Mapping[str, Any], by: str = "key") -> int:
|
|
301
|
+
"""See :meth:`prograph.engine.ProGraph.set_properties`."""
|
|
302
|
+
from prograph import read_only
|
|
303
|
+
from prograph.graph.pandas_graph import _set_cells
|
|
304
|
+
from prograph.utils.exceptions import ReadOnlyGraphError
|
|
305
|
+
|
|
306
|
+
schema = engine._schema
|
|
307
|
+
if schema is None:
|
|
308
|
+
raise ValueError("set_properties needs a schema")
|
|
309
|
+
mapping = schema.get_node_mapping(schema.require_name('label', label))
|
|
310
|
+
if not mapping.mutable:
|
|
311
|
+
read_only.refuse_not_mutable(label)
|
|
312
|
+
columns = _columns_to_set(schema, mapping, values)
|
|
313
|
+
keys = list(dict.fromkeys(_keys(engine, mapping, list(identities), by)))
|
|
314
|
+
if not keys:
|
|
315
|
+
return 0
|
|
316
|
+
graph = getattr(engine.executor, 'graph', None)
|
|
317
|
+
|
|
318
|
+
if hasattr(graph, '_execute_mutation_sql'): # Spark: a Delta UPDATE
|
|
319
|
+
from prograph.plan.sql.dialect import get_dialect_instance
|
|
320
|
+
frame = graph.dataframes[mapping.source_table]
|
|
321
|
+
has_inferred = INFERRED_COLUMN in frame.columns
|
|
322
|
+
dialect = get_dialect_instance("spark")
|
|
323
|
+
where = " AND ".join(row_conditions(mapping, keys, dialect, has_inferred))
|
|
324
|
+
written = frame.sparkSession.sql(
|
|
325
|
+
f"SELECT COUNT(*) AS n FROM {dialect.quote_qualified(mapping.qualified_source_table)} "
|
|
326
|
+
f"WHERE {where}").collect()[0]["n"]
|
|
327
|
+
if written:
|
|
328
|
+
graph._execute_mutation_sql(update_sql(mapping, keys, columns, dialect, has_inferred), mapping)
|
|
329
|
+
return int(written)
|
|
330
|
+
|
|
331
|
+
if getattr(engine, '_frame_backed', False): # pandas, DuckDB over DataFrames
|
|
332
|
+
frame = graph.dataframes.get(mapping.source_table)
|
|
333
|
+
if frame is None:
|
|
334
|
+
raise ReadOnlyGraphError(f"DataFrame not found for table '{mapping.source_table}'")
|
|
335
|
+
mask = row_mask(frame, mapping, keys)
|
|
336
|
+
for column, value in columns.items():
|
|
337
|
+
_set_cells(frame, mask, column, value)
|
|
338
|
+
return int(mask.sum())
|
|
339
|
+
|
|
340
|
+
# A SQL database: one UPDATE on its own connection.
|
|
341
|
+
from prograph.plan.sql.dialect import get_dialect_instance
|
|
342
|
+
from prograph.utils.exceptions import SQLRuntimeError
|
|
343
|
+
|
|
344
|
+
dialect = get_dialect_instance(graph._dialect)
|
|
345
|
+
table = dialect.quote_qualified(mapping.qualified_source_table)
|
|
346
|
+
|
|
347
|
+
def run(sql: str) -> List[Dict[str, Any]]:
|
|
348
|
+
try:
|
|
349
|
+
return graph._execute_sql(sql)
|
|
350
|
+
except Exception as exc: # noqa: BLE001 - the driver's own error types
|
|
351
|
+
raise SQLRuntimeError(f"SQL execution failed: {exc}",
|
|
352
|
+
reason="execution_error", sql=sql) from exc
|
|
353
|
+
|
|
354
|
+
try:
|
|
355
|
+
present = graph._execute_sql_arrow(f"SELECT * FROM {table} WHERE 1 = 0").column_names
|
|
356
|
+
except Exception as exc: # noqa: BLE001 - the driver's own error types
|
|
357
|
+
raise SQLRuntimeError(f"SQL execution failed: {exc}", reason="execution_error") from exc
|
|
358
|
+
has_inferred = INFERRED_COLUMN in present
|
|
359
|
+
where = " AND ".join(row_conditions(mapping, keys, dialect, has_inferred))
|
|
360
|
+
rows = run(f"SELECT COUNT(*) AS n FROM {table} WHERE {where}")
|
|
361
|
+
written = int(list(rows[0].values())[0]) if rows else 0
|
|
362
|
+
if written:
|
|
363
|
+
run(update_sql(mapping, keys, columns, dialect, has_inferred))
|
|
364
|
+
return written
|
|
365
|
+
|
|
366
|
+
|
|
367
|
+
__all__ = ["INFERRED_COLUMN", "NotAQueryError", "column_condition", "own_asserted_conditions",
|
|
368
|
+
"own_rows_sql", "owned_conditions", "require_one_query", "row_conditions", "row_mask",
|
|
369
|
+
"set_properties", "update_sql"]
|
|
@@ -0,0 +1,281 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: prograph
|
|
3
|
+
Version: 1.3.3
|
|
4
|
+
Summary: A multi-language graph query engine for Python with multiple execution backends
|
|
5
|
+
License-Expression: Apache-2.0
|
|
6
|
+
Project-URL: Homepage, https://gitlab.com/briceg/prograph
|
|
7
|
+
Project-URL: Documentation, https://gitlab.com/briceg/prograph/-/blob/stable/1.3/docs/README.md
|
|
8
|
+
Project-URL: Source, https://gitlab.com/briceg/prograph
|
|
9
|
+
Project-URL: Issues, https://gitlab.com/briceg/prograph/-/issues
|
|
10
|
+
Project-URL: Changelog, https://gitlab.com/briceg/prograph/-/blob/stable/1.3/docs/changelog.md
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Operating System :: OS Independent
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
17
|
+
Classifier: Topic :: Database
|
|
18
|
+
Requires-Python: >=3.11
|
|
19
|
+
Description-Content-Type: text/markdown
|
|
20
|
+
License-File: LICENSE
|
|
21
|
+
License-File: NOTICE
|
|
22
|
+
Requires-Dist: antlr4-python3-runtime>=4.13.0
|
|
23
|
+
Requires-Dist: structlog>=24.0.0
|
|
24
|
+
Requires-Dist: pyyaml>=6.0.0
|
|
25
|
+
Requires-Dist: pyarrow>=20
|
|
26
|
+
Requires-Dist: rdflib>=7.0.0
|
|
27
|
+
Provides-Extra: dev
|
|
28
|
+
Requires-Dist: pytest==9.0.3; extra == "dev"
|
|
29
|
+
Requires-Dist: pytest-bdd==8.1.0; extra == "dev"
|
|
30
|
+
Requires-Dist: pytest-cov==7.1.0; extra == "dev"
|
|
31
|
+
Requires-Dist: pytest-xdist==3.8.0; extra == "dev"
|
|
32
|
+
Requires-Dist: duckdb==1.5.6; extra == "dev"
|
|
33
|
+
Requires-Dist: pyarrow==24.0.0; extra == "dev"
|
|
34
|
+
Requires-Dist: pandas==2.3.3; extra == "dev"
|
|
35
|
+
Requires-Dist: pyspark==4.1.3; extra == "dev"
|
|
36
|
+
Requires-Dist: numpy==2.4.5; extra == "dev"
|
|
37
|
+
Requires-Dist: mcp==1.27.1; extra == "dev"
|
|
38
|
+
Requires-Dist: rdflib==7.6.0; extra == "dev"
|
|
39
|
+
Requires-Dist: pyoxigraph==0.5.13; extra == "dev"
|
|
40
|
+
Requires-Dist: pyshacl==0.31.0; extra == "dev"
|
|
41
|
+
Requires-Dist: owlrl==7.1.4; extra == "dev"
|
|
42
|
+
Requires-Dist: antlr4-python3-runtime==4.13.2; extra == "dev"
|
|
43
|
+
Requires-Dist: structlog==25.5.0; extra == "dev"
|
|
44
|
+
Requires-Dist: pyyaml==6.0.3; extra == "dev"
|
|
45
|
+
Requires-Dist: adbc-driver-postgresql==1.12.0; extra == "dev"
|
|
46
|
+
Requires-Dist: adbc-driver-manager==1.12.0; extra == "dev"
|
|
47
|
+
Requires-Dist: oracledb==26.0.1; extra == "dev"
|
|
48
|
+
Requires-Dist: pyodbc==5.3.0; extra == "dev"
|
|
49
|
+
Requires-Dist: mysql-connector-python==9.7.0; extra == "dev"
|
|
50
|
+
Requires-Dist: databricks-sql-connector==4.2.6; extra == "dev"
|
|
51
|
+
Requires-Dist: graphql-core==3.2.13; extra == "dev"
|
|
52
|
+
Requires-Dist: black>=23.0.0; extra == "dev"
|
|
53
|
+
Requires-Dist: isort>=5.12.0; extra == "dev"
|
|
54
|
+
Requires-Dist: mypy>=1.0.0; extra == "dev"
|
|
55
|
+
Requires-Dist: flake8>=6.0.0; extra == "dev"
|
|
56
|
+
Requires-Dist: sqlglot==28.7.0; extra == "dev"
|
|
57
|
+
Requires-Dist: fastapi==0.136.1; extra == "dev"
|
|
58
|
+
Requires-Dist: uvicorn==0.47.0; extra == "dev"
|
|
59
|
+
Requires-Dist: python-multipart==0.0.29; extra == "dev"
|
|
60
|
+
Requires-Dist: httpx==0.28.1; extra == "dev"
|
|
61
|
+
Provides-Extra: pandas
|
|
62
|
+
Requires-Dist: pandas<3,>=2.0.0; extra == "pandas"
|
|
63
|
+
Provides-Extra: duckdb
|
|
64
|
+
Requires-Dist: duckdb<3,>=1.5.3; extra == "duckdb"
|
|
65
|
+
Requires-Dist: pandas<3,>=2.0.0; extra == "duckdb"
|
|
66
|
+
Provides-Extra: postgresql
|
|
67
|
+
Requires-Dist: adbc-driver-postgresql>=1.12; extra == "postgresql"
|
|
68
|
+
Provides-Extra: oracle
|
|
69
|
+
Requires-Dist: oracledb>=26.0.1; extra == "oracle"
|
|
70
|
+
Provides-Extra: spark
|
|
71
|
+
Requires-Dist: pyspark>=4.1.0; extra == "spark"
|
|
72
|
+
Provides-Extra: ontology
|
|
73
|
+
Provides-Extra: shacl
|
|
74
|
+
Requires-Dist: pyshacl>=0.31.0; extra == "shacl"
|
|
75
|
+
Provides-Extra: r2rml
|
|
76
|
+
Provides-Extra: logging
|
|
77
|
+
Requires-Dist: structlog>=24.0.0; extra == "logging"
|
|
78
|
+
Provides-Extra: nlp
|
|
79
|
+
Requires-Dist: openai>=1.0.0; extra == "nlp"
|
|
80
|
+
Provides-Extra: nlp-databricks
|
|
81
|
+
Requires-Dist: openai>=1.0.0; extra == "nlp-databricks"
|
|
82
|
+
Requires-Dist: databricks-sdk>=0.20.0; extra == "nlp-databricks"
|
|
83
|
+
Provides-Extra: nlp-langchain
|
|
84
|
+
Requires-Dist: openai>=1.0.0; extra == "nlp-langchain"
|
|
85
|
+
Requires-Dist: databricks-langchain>=0.1.0; extra == "nlp-langchain"
|
|
86
|
+
Requires-Dist: langchain>=0.1.0; extra == "nlp-langchain"
|
|
87
|
+
Provides-Extra: ui
|
|
88
|
+
Requires-Dist: fastapi>=0.109.0; extra == "ui"
|
|
89
|
+
Requires-Dist: jinja2>=3.1.0; extra == "ui"
|
|
90
|
+
Requires-Dist: uvicorn>=0.27.0; extra == "ui"
|
|
91
|
+
Requires-Dist: python-multipart>=0.0.6; extra == "ui"
|
|
92
|
+
Provides-Extra: endpoint
|
|
93
|
+
Requires-Dist: fastapi>=0.109.0; extra == "endpoint"
|
|
94
|
+
Requires-Dist: uvicorn>=0.27.0; extra == "endpoint"
|
|
95
|
+
Requires-Dist: python-multipart>=0.0.6; extra == "endpoint"
|
|
96
|
+
Requires-Dist: duckdb<3,>=1.5.3; extra == "endpoint"
|
|
97
|
+
Requires-Dist: pandas<3,>=2.0.0; extra == "endpoint"
|
|
98
|
+
Provides-Extra: databricks
|
|
99
|
+
Requires-Dist: databricks-sql-connector>=4.9; extra == "databricks"
|
|
100
|
+
Requires-Dist: databricks-sdk>=0.40.0; extra == "databricks"
|
|
101
|
+
Provides-Extra: databricks-rt
|
|
102
|
+
Requires-Dist: databricks-sql-connector[kernel]>=4.9.0; extra == "databricks-rt"
|
|
103
|
+
Requires-Dist: databricks-sdk>=0.40.0; extra == "databricks-rt"
|
|
104
|
+
Provides-Extra: cli
|
|
105
|
+
Requires-Dist: pandas<3,>=2.0.0; extra == "cli"
|
|
106
|
+
Provides-Extra: graphql
|
|
107
|
+
Requires-Dist: graphql-core<3.3,>=3.2; extra == "graphql"
|
|
108
|
+
Provides-Extra: mcp
|
|
109
|
+
Requires-Dist: mcp<2,>=1.27; extra == "mcp"
|
|
110
|
+
Requires-Dist: duckdb<3,>=1.5.3; extra == "mcp"
|
|
111
|
+
Requires-Dist: pandas<3,>=2.0.0; extra == "mcp"
|
|
112
|
+
Requires-Dist: openai>=1.0.0; extra == "mcp"
|
|
113
|
+
Provides-Extra: genie
|
|
114
|
+
Requires-Dist: databricks-sdk>=0.40.0; extra == "genie"
|
|
115
|
+
Requires-Dist: databricks-sql-connector>=3.0.0; extra == "genie"
|
|
116
|
+
Requires-Dist: rdflib>=7.0.0; extra == "genie"
|
|
117
|
+
Requires-Dist: pandas<3,>=2.0.0; extra == "genie"
|
|
118
|
+
Requires-Dist: pyyaml>=6.0; extra == "genie"
|
|
119
|
+
Provides-Extra: test-sql
|
|
120
|
+
Requires-Dist: adbc-driver-postgresql>=1.12; extra == "test-sql"
|
|
121
|
+
Requires-Dist: mysql-connector-python>=8.0; extra == "test-sql"
|
|
122
|
+
Requires-Dist: oracledb>=26.0.1; extra == "test-sql"
|
|
123
|
+
Requires-Dist: pyodbc>=5.0; extra == "test-sql"
|
|
124
|
+
Dynamic: license-file
|
|
125
|
+
|
|
126
|
+
# ProGraph
|
|
127
|
+
|
|
128
|
+
ProGraph answers SPARQL 1.1 queries over tables you already have. You give it
|
|
129
|
+
a mapping (R2RML or YAML) from tables to RDF terms; each query is translated
|
|
130
|
+
to one SQL statement that your database runs. Nothing is copied or loaded:
|
|
131
|
+
the data stays where it is, and ProGraph does not write to your tables.
|
|
132
|
+
|
|
133
|
+
## Install
|
|
134
|
+
|
|
135
|
+
Python 3.11 or later:
|
|
136
|
+
|
|
137
|
+
```bash
|
|
138
|
+
pip install "prograph[duckdb]"
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
Extras, from `pyproject.toml`; install the ones you use.
|
|
142
|
+
|
|
143
|
+
| Extra | Adds |
|
|
144
|
+
|---|---|
|
|
145
|
+
| `duckdb` | DuckDB and pandas: the default engine over DataFrames, and DuckDB databases |
|
|
146
|
+
| `pandas` | pandas 2 |
|
|
147
|
+
| `postgresql` | the ADBC PostgreSQL driver |
|
|
148
|
+
| `oracle` | `oracledb` |
|
|
149
|
+
| `spark` | PySpark 4.1 or later |
|
|
150
|
+
| `databricks` | the Databricks SQL connector and SDK |
|
|
151
|
+
| `databricks-rt` | the connector's kernel path, for Lakehouse RT warehouses |
|
|
152
|
+
| `shacl` | pyshacl, for `engine.validate_shapes()` |
|
|
153
|
+
| `endpoint` | the SPARQL Protocol server, `prograph serve` |
|
|
154
|
+
| `mcp` | the MCP server and the model client its `ask` tool uses |
|
|
155
|
+
| `cli` | `prograph load-ttl` and `prograph infer-schema` |
|
|
156
|
+
| `nlp`, `nlp-databricks`, `nlp-langchain` | the natural-language interface |
|
|
157
|
+
| `genie` | the Databricks Genie integration |
|
|
158
|
+
| `logging`, `ui`, `graphql` | structlog; the web UI; GraphQL (experimental) |
|
|
159
|
+
|
|
160
|
+
MySQL and SQL Server have no extra: install `mysql-connector-python` or
|
|
161
|
+
`pyodbc` yourself (SQL Server also needs the ODBC Driver 18).
|
|
162
|
+
|
|
163
|
+
## Quickstart
|
|
164
|
+
|
|
165
|
+
A DuckDB table, a YAML mapping and one query:
|
|
166
|
+
|
|
167
|
+
```python
|
|
168
|
+
import duckdb
|
|
169
|
+
from prograph import ProGraph
|
|
170
|
+
from prograph.config import load_config
|
|
171
|
+
|
|
172
|
+
con = duckdb.connect()
|
|
173
|
+
con.execute("CREATE TABLE people (id INTEGER, name VARCHAR, age INTEGER)")
|
|
174
|
+
con.execute("INSERT INTO people VALUES (1, 'Alice', 30), (2, 'Bob', 25)")
|
|
175
|
+
|
|
176
|
+
open("graph.yaml", "w").write("""
|
|
177
|
+
version: "1.0"
|
|
178
|
+
graph: {name: people}
|
|
179
|
+
sources:
|
|
180
|
+
people: {table: people}
|
|
181
|
+
nodes:
|
|
182
|
+
- label: Person
|
|
183
|
+
source: people
|
|
184
|
+
id_column: id
|
|
185
|
+
iri_template: "http://example.org/person/{id}"
|
|
186
|
+
class_iri: "http://example.org/Person"
|
|
187
|
+
properties: {name: name, age: age}
|
|
188
|
+
rdf: {vocab_iri: "http://example.org/", auto_generate: true}
|
|
189
|
+
""")
|
|
190
|
+
engine = ProGraph(schema=load_config("graph.yaml").to_schema(), connection=con)
|
|
191
|
+
|
|
192
|
+
engine.execute("""
|
|
193
|
+
PREFIX ex: <http://example.org/>
|
|
194
|
+
SELECT ?name ?age WHERE { ?p a ex:Person ; ex:name ?name ; ex:age ?age . FILTER(?age > 26) }
|
|
195
|
+
""", language="sparql", return_type="list")
|
|
196
|
+
# [{'name': 'Alice', 'age': 30}]
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
`ProGraph.from_r2rml(path, connection=con)` reads an R2RML mapping instead.
|
|
200
|
+
More: [quickstart](https://gitlab.com/briceg/prograph/-/blob/stable/1.3/docs/sparql/quickstart.md), [map your tables](https://gitlab.com/briceg/prograph/-/blob/stable/1.3/docs/sparql/mapping.md),
|
|
201
|
+
[R2RML tutorial](https://gitlab.com/briceg/prograph/-/blob/stable/1.3/docs/start/r2rml-tutorial.md).
|
|
202
|
+
|
|
203
|
+
## Reasoning
|
|
204
|
+
|
|
205
|
+
Pass an ontology (`ontology=`) and reasoning is on. The RDFS core is always on
|
|
206
|
+
with an ontology. `profile="ql"`, the default, answers OWL 2 QL by rewriting the
|
|
207
|
+
query: nothing is stored. `profile="rl"` with an owned store (`store=`)
|
|
208
|
+
materializes OWL 2 RL facts into ProGraph's own tables, never yours; a query
|
|
209
|
+
reads them only where every mapped table is provably unchanged since the run
|
|
210
|
+
that made them. An ontology and data that contradict each other raise
|
|
211
|
+
`InconsistentOntologyError` unless `inconsistency="report"`. `owl:imports`
|
|
212
|
+
is read from local files only. See [OWL and ontology](https://gitlab.com/briceg/prograph/-/blob/stable/1.3/docs/guides/owl-and-ontology.md)
|
|
213
|
+
and [OWL 2 RL](https://gitlab.com/briceg/prograph/-/blob/stable/1.3/docs/reference/owl-rl.md).
|
|
214
|
+
|
|
215
|
+
## Backends
|
|
216
|
+
|
|
217
|
+
| Backend | Install | SPARQL | Owned store, `profile="rl"` |
|
|
218
|
+
|---|---|---|---|
|
|
219
|
+
| DuckDB, over pandas DataFrames or a DuckDB database | `duckdb` | yes | yes |
|
|
220
|
+
| PostgreSQL (also Lakebase, over ADBC) | `postgresql` | yes | yes |
|
|
221
|
+
| Spark (a SparkSession) | `spark` | yes | yes, with Delta Lake |
|
|
222
|
+
| Databricks SQL warehouse | `databricks` | yes | yes |
|
|
223
|
+
| Oracle | `oracle` | yes | no |
|
|
224
|
+
| MySQL 8.0+ | `mysql-connector-python` | yes | no |
|
|
225
|
+
| SQL Server | `pyodbc` | yes | no |
|
|
226
|
+
|
|
227
|
+
PostgreSQL, MySQL, SQL Server and Oracle are checked behind DuckDB,
|
|
228
|
+
Databricks and Spark: a fault found only on one of them waits for a later
|
|
229
|
+
pass. What differs per backend: [backends](https://gitlab.com/briceg/prograph/-/blob/stable/1.3/docs/guides/backends.md),
|
|
230
|
+
[what differs by backend](https://gitlab.com/briceg/prograph/-/blob/stable/1.3/docs/reference/backend-differences.md).
|
|
231
|
+
|
|
232
|
+
## Cypher
|
|
233
|
+
|
|
234
|
+
Cypher queries run on every engine, with no option: `engine.execute(query, language="cypher")`.
|
|
235
|
+
|
|
236
|
+
- **Mapping.** Cypher needs a YAML mapping: an R2RML mapping has no property-graph
|
|
237
|
+
view and raises `PropertyGraphViewError`; query it with SPARQL.
|
|
238
|
+
- **Ontology.** Cypher applies the ontology's class and property hierarchies only
|
|
239
|
+
(subclass, sub-property, equivalent class and property). The first Cypher query on an
|
|
240
|
+
engine whose ontology states other axioms (domain and range, inverses, symmetric and
|
|
241
|
+
transitive properties, `owl:sameAs`, RL facts, individuals) warns once
|
|
242
|
+
(`CypherOntologyWarning`); SPARQL applies them.
|
|
243
|
+
- **Writes.** `CREATE`, `SET`, `REMOVE`, `DELETE` and `MERGE` write into the owned store
|
|
244
|
+
(`store=`), never a mapped table; with no store they raise `CypherWriteRefusedError`. A
|
|
245
|
+
label a table maps, or an inferred superclass of one, or a label the ontology makes a
|
|
246
|
+
subclass of another, is refused.
|
|
247
|
+
- **Nodes.** A node is the map `{id, labels, properties}`; its `id` is its IRI, and so are
|
|
248
|
+
`id(n)` and `elementId(n)`. A node mapping's key columns are properties under their column
|
|
249
|
+
names (`n.id`). A property no mapping declares is null.
|
|
250
|
+
- **Speed.** A Cypher plan runs as translated, without the rewrites SPARQL plans get. A
|
|
251
|
+
pattern that a second `MATCH` joins back to nodes the first bound (`MATCH (a)-[:KNOWS]->(b)
|
|
252
|
+
MATCH (a)-[:LIKES]->(p)<-[:LIKES]-(b)`) can take minutes on large tables: its joins run
|
|
253
|
+
in the order written, over every type a relationship's table gives. On LDBC SF1, 3 of 200
|
|
254
|
+
Cypher queries ran past 2 minutes on DuckDB; one of them, written in SPARQL, took half a
|
|
255
|
+
second. Write such a query in SPARQL until this is fixed.
|
|
256
|
+
- **Checked.** The openCypher TCK gave 0 wrong answers across the scenarios run for 1.3.0:
|
|
257
|
+
2,880 on DuckDB and on Spark; 2,658 on PostgreSQL, where 222 more are refused by name
|
|
258
|
+
(values of several types in one column, lists of lists, paths held as values); 2,849 of the
|
|
259
|
+
2,880 on a Databricks SQL warehouse, where the other 31 hold values it has no type for (TIME,
|
|
260
|
+
TIME WITH TIME ZONE, nanoseconds). Of the TCK's 3,897 scenarios,
|
|
261
|
+
314 are not built (refused by name) and the rest expect an error or a setup the test
|
|
262
|
+
harness cannot load. MySQL, SQL Server and Oracle run Cypher unchecked.
|
|
263
|
+
- Natural-language `ask` writes SPARQL by default, or Cypher (`language="cypher"`); it never writes data.
|
|
264
|
+
|
|
265
|
+
See [Choosing a language](https://gitlab.com/briceg/prograph/-/blob/stable/1.3/docs/start/choosing-a-language.md) and the
|
|
266
|
+
[conformance choices](https://gitlab.com/briceg/prograph/-/blob/stable/1.3/docs/conformance/choices.md).
|
|
267
|
+
|
|
268
|
+
## Endpoint, MCP and ask
|
|
269
|
+
|
|
270
|
+
`prograph serve --config graph.yaml` serves the SPARQL 1.1 Protocol; with
|
|
271
|
+
`--mcp` it also serves MCP tools at `/mcp`, including `ask`, which turns a
|
|
272
|
+
question into SPARQL (or Cypher) with a model, runs it, and retries with the error if it
|
|
273
|
+
fails. See [the endpoint](https://gitlab.com/briceg/prograph/-/blob/stable/1.3/docs/guides/sparql-endpoint.md) and
|
|
274
|
+
[agents](https://gitlab.com/briceg/prograph/-/blob/stable/1.3/docs/guides/agents.md).
|
|
275
|
+
|
|
276
|
+
## More
|
|
277
|
+
|
|
278
|
+
- [Documentation](https://gitlab.com/briceg/prograph/-/blob/stable/1.3/docs/README.md), and the [primer](https://gitlab.com/briceg/prograph/-/blob/stable/1.3/docs/primer.md)
|
|
279
|
+
- [llms.txt](https://gitlab.com/briceg/prograph/-/blob/stable/1.3/llms.txt), a reference for LLMs and agents
|
|
280
|
+
- [Changelog](https://gitlab.com/briceg/prograph/-/blob/stable/1.3/docs/changelog.md)
|
|
281
|
+
- [Licence](https://gitlab.com/briceg/prograph/-/blob/stable/1.3/LICENSE): Apache-2.0
|