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
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