prograph 1.3.3__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (237) hide show
  1. prograph/__init__.py +36 -0
  2. prograph/__main__.py +5 -0
  3. prograph/_version.py +375 -0
  4. prograph/cli/__init__.py +1 -0
  5. prograph/cli/_iri_utils.py +124 -0
  6. prograph/cli/emit_genie_space.py +107 -0
  7. prograph/cli/generate_views.py +140 -0
  8. prograph/cli/main.py +420 -0
  9. prograph/cli/schema_inferrer.py +746 -0
  10. prograph/cli/ttl_loader.py +289 -0
  11. prograph/cli/upload_genie_space.py +84 -0
  12. prograph/config/__init__.py +27 -0
  13. prograph/config/yaml_config.py +848 -0
  14. prograph/demos/__init__.py +14 -0
  15. prograph/demos/turbofan/README.md +74 -0
  16. prograph/demos/turbofan/SCENARIO.md +209 -0
  17. prograph/demos/turbofan/__init__.py +75 -0
  18. prograph/demos/turbofan/create_tables.sql +206 -0
  19. prograph/demos/turbofan/data/engine-instances.ttl +1123 -0
  20. prograph/demos/turbofan/data/sensor-timeseries.csv +90 -0
  21. prograph/demos/turbofan/demo.py +162 -0
  22. prograph/demos/turbofan/genie_qa_notebook.py +434 -0
  23. prograph/demos/turbofan/graph.yaml +1098 -0
  24. prograph/demos/turbofan/instance_graph_demo.py +32 -0
  25. prograph/demos/turbofan/load.py +223 -0
  26. prograph/demos/turbofan/mapping.r2rml.ttl +991 -0
  27. prograph/demos/turbofan/ontology/engine-maintenance.ttl +606 -0
  28. prograph/demos/turbofan/payload-shapes.ttl +33 -0
  29. prograph/demos/turbofan/queries/example-queries.sparql +215 -0
  30. prograph/demos/turbofan/shapes.ttl +75 -0
  31. prograph/demos/turbofan/tables.py +106 -0
  32. prograph/demos/turbofan/turbofan_schema.py +393 -0
  33. prograph/demos/turbofan/validation_demo.py +153 -0
  34. prograph/describe.py +231 -0
  35. prograph/endpoint/__init__.py +12 -0
  36. prograph/endpoint/app.py +722 -0
  37. prograph/endpoint/cli.py +280 -0
  38. prograph/endpoint/credentials.py +240 -0
  39. prograph/endpoint/engines.py +418 -0
  40. prograph/endpoint/negotiate.py +101 -0
  41. prograph/endpoint/results.py +181 -0
  42. prograph/endpoint/service.py +31 -0
  43. prograph/engine.py +2718 -0
  44. prograph/execution.py +455 -0
  45. prograph/executors/__init__.py +6 -0
  46. prograph/executors/base.py +11 -0
  47. prograph/executors/databricks_sql_executor.py +51 -0
  48. prograph/executors/duckdb_executor.py +24 -0
  49. prograph/executors/mysql_executor.py +20 -0
  50. prograph/executors/oracle_executor.py +24 -0
  51. prograph/executors/pandas_executor.py +72 -0
  52. prograph/executors/postgresql_executor.py +35 -0
  53. prograph/executors/spark_executor.py +88 -0
  54. prograph/executors/sqlserver_executor.py +35 -0
  55. prograph/extras/__init__.py +1 -0
  56. prograph/extras/graphql/__init__.py +33 -0
  57. prograph/extras/graphql/execute.py +25 -0
  58. prograph/extras/graphql/schema.py +314 -0
  59. prograph/extras/instance_graph.py +559 -0
  60. prograph/genie/__init__.py +83 -0
  61. prograph/genie/databricks_uploader.py +306 -0
  62. prograph/genie/deploy.py +393 -0
  63. prograph/genie/formats.py +414 -0
  64. prograph/genie/instruction_generator.py +375 -0
  65. prograph/genie/sample_query_generator.py +256 -0
  66. prograph/genie/shacl_views.py +318 -0
  67. prograph/genie/space_emitter.py +329 -0
  68. prograph/genie/view_generator.py +628 -0
  69. prograph/genie/view_writer.py +172 -0
  70. prograph/graph/__init__.py +1 -0
  71. prograph/graph/ansi_session.py +348 -0
  72. prograph/graph/databricks_sql_graph.py +300 -0
  73. prograph/graph/drivers.py +143 -0
  74. prograph/graph/duckdb_graph.py +68 -0
  75. prograph/graph/mysql_graph.py +38 -0
  76. prograph/graph/oracle_graph.py +285 -0
  77. prograph/graph/pandas_graph.py +343 -0
  78. prograph/graph/postgresql_graph.py +644 -0
  79. prograph/graph/spark_graph.py +556 -0
  80. prograph/graph/sql_graph.py +83 -0
  81. prograph/graph/sqlserver_graph.py +72 -0
  82. prograph/hints.py +95 -0
  83. prograph/logging.py +550 -0
  84. prograph/mcp/__init__.py +29 -0
  85. prograph/mcp/__main__.py +180 -0
  86. prograph/mcp/bootstrap.py +98 -0
  87. prograph/mcp/server.py +601 -0
  88. prograph/mcp/sparql.py +397 -0
  89. prograph/mcp/tools.py +504 -0
  90. prograph/nlp/__init__.py +79 -0
  91. prograph/nlp/client.py +305 -0
  92. prograph/nlp/databricks_tools.py +369 -0
  93. prograph/nlp/graph_context.py +313 -0
  94. prograph/nlp/interface.py +652 -0
  95. prograph/nlp/prompts/__init__.py +19 -0
  96. prograph/nlp/prompts/examples.py +258 -0
  97. prograph/nlp/prompts/system.py +239 -0
  98. prograph/nlp/providers/__init__.py +14 -0
  99. prograph/nlp/providers/anthropic.py +274 -0
  100. prograph/nlp/providers/databricks.py +312 -0
  101. prograph/nlp/providers/openai.py +203 -0
  102. prograph/nlp/schema_context.py +78 -0
  103. prograph/ontology/__init__.py +53 -0
  104. prograph/ontology/alignment.py +542 -0
  105. prograph/ontology/hierarchy.py +310 -0
  106. prograph/ontology/imports.py +587 -0
  107. prograph/ontology/layer.py +991 -0
  108. prograph/ontology/skos.py +61 -0
  109. prograph/owl/__init__.py +27 -0
  110. prograph/owl/defined_classes.py +323 -0
  111. prograph/parameters.py +242 -0
  112. prograph/parser/__init__.py +1 -0
  113. prograph/parser/cypher/CypherLexer.py +836 -0
  114. prograph/parser/cypher/CypherListener.py +966 -0
  115. prograph/parser/cypher/CypherParser.py +10854 -0
  116. prograph/parser/cypher/CypherVisitor.py +543 -0
  117. prograph/parser/cypher/__init__.py +1 -0
  118. prograph/parser/sparql/SparqlLexer.py +801 -0
  119. prograph/parser/sparql/SparqlParser.py +10146 -0
  120. prograph/parser/sparql/SparqlParserListener.py +1056 -0
  121. prograph/parser/sparql/SparqlParserVisitor.py +593 -0
  122. prograph/parser/sparql/__init__.py +8 -0
  123. prograph/plan/__init__.py +3 -0
  124. prograph/plan/ir/__init__.py +1 -0
  125. prograph/plan/ir/casts.py +338 -0
  126. prograph/plan/ir/consistency.py +397 -0
  127. prograph/plan/ir/construct.py +90 -0
  128. prograph/plan/ir/cost.py +234 -0
  129. prograph/plan/ir/cypher_answer.py +1081 -0
  130. prograph/plan/ir/cypher_apoc.py +717 -0
  131. prograph/plan/ir/cypher_apoc_convert.py +505 -0
  132. prograph/plan/ir/cypher_apoc_date.py +845 -0
  133. prograph/plan/ir/cypher_apoc_map.py +496 -0
  134. prograph/plan/ir/cypher_apoc_meta.py +384 -0
  135. prograph/plan/ir/cypher_apoc_path.py +597 -0
  136. prograph/plan/ir/cypher_apoc_procedures.py +163 -0
  137. prograph/plan/ir/cypher_apoc_text.py +785 -0
  138. prograph/plan/ir/cypher_front.py +5474 -0
  139. prograph/plan/ir/cypher_functions.py +565 -0
  140. prograph/plan/ir/cypher_lists.py +935 -0
  141. prograph/plan/ir/cypher_maps.py +370 -0
  142. prograph/plan/ir/cypher_mixed.py +604 -0
  143. prograph/plan/ir/cypher_ontology.py +226 -0
  144. prograph/plan/ir/cypher_procedures.py +191 -0
  145. prograph/plan/ir/cypher_runtime_errors.py +107 -0
  146. prograph/plan/ir/cypher_temporal.py +1357 -0
  147. prograph/plan/ir/cypher_temporal_arith.py +339 -0
  148. prograph/plan/ir/cypher_values.py +546 -0
  149. prograph/plan/ir/cypher_write.py +612 -0
  150. prograph/plan/ir/dataset.py +643 -0
  151. prograph/plan/ir/dates.py +102 -0
  152. prograph/plan/ir/entry.py +992 -0
  153. prograph/plan/ir/expr.py +260 -0
  154. prograph/plan/ir/facts.py +1171 -0
  155. prograph/plan/ir/fresh.py +291 -0
  156. prograph/plan/ir/freshness.py +625 -0
  157. prograph/plan/ir/identity.py +797 -0
  158. prograph/plan/ir/java_datetime.py +265 -0
  159. prograph/plan/ir/java_regex.py +391 -0
  160. prograph/plan/ir/join_order.py +39 -0
  161. prograph/plan/ir/key_checks.py +433 -0
  162. prograph/plan/ir/keys.py +454 -0
  163. prograph/plan/ir/lower.py +5323 -0
  164. prograph/plan/ir/ops.py +619 -0
  165. prograph/plan/ir/owl_rl.py +1119 -0
  166. prograph/plan/ir/owl_rl_rules.py +725 -0
  167. prograph/plan/ir/profiles.py +694 -0
  168. prograph/plan/ir/ql.py +987 -0
  169. prograph/plan/ir/rdfs.py +342 -0
  170. prograph/plan/ir/rewrite.py +1782 -0
  171. prograph/plan/ir/saturate.py +339 -0
  172. prograph/plan/ir/semantics.py +103 -0
  173. prograph/plan/ir/slot.py +509 -0
  174. prograph/plan/ir/sparql_front.py +3418 -0
  175. prograph/plan/ir/strings.py +534 -0
  176. prograph/plan/ir/term_functions.py +274 -0
  177. prograph/plan/ir/terms.py +84 -0
  178. prograph/plan/ir/xpath_regex.py +264 -0
  179. prograph/plan/run_record.py +65 -0
  180. prograph/plan/sql/__init__.py +21 -0
  181. prograph/plan/sql/dialect.py +3726 -0
  182. prograph/plan/sql/mysql_serializer.py +103 -0
  183. prograph/plan/sql/names.py +65 -0
  184. prograph/plan/sql/oracle_serializer.py +306 -0
  185. prograph/plan/sql/pg_serializer.py +501 -0
  186. prograph/plan/sql/rel_algebra.py +781 -0
  187. prograph/plan/sql/sql_serializer.py +1419 -0
  188. prograph/plan/sql/sqlserver_serializer.py +603 -0
  189. prograph/provenance.py +222 -0
  190. prograph/r2rml/__init__.py +48 -0
  191. prograph/r2rml/catalog.py +259 -0
  192. prograph/r2rml/compile.py +372 -0
  193. prograph/r2rml/direct.py +140 -0
  194. prograph/r2rml/export.py +495 -0
  195. prograph/r2rml/model.py +180 -0
  196. prograph/r2rml/parser.py +546 -0
  197. prograph/r2rml/schema.py +120 -0
  198. prograph/read_only.py +122 -0
  199. prograph/results.py +157 -0
  200. prograph/rules/__init__.py +168 -0
  201. prograph/rules/__main__.py +32 -0
  202. prograph/schema/__init__.py +60 -0
  203. prograph/schema/change_set.py +50 -0
  204. prograph/schema/collations.py +198 -0
  205. prograph/schema/compile_schema.py +388 -0
  206. prograph/schema/context.py +845 -0
  207. prograph/schema/examples.py +234 -0
  208. prograph/schema/iri.py +817 -0
  209. prograph/schema/literals.py +94 -0
  210. prograph/schema/lpg_view.py +617 -0
  211. prograph/schema/mapping.py +1803 -0
  212. prograph/schema/maps_schema.py +40 -0
  213. prograph/schema/naming.py +77 -0
  214. prograph/schema/query_sources.py +59 -0
  215. prograph/schema/rows.py +215 -0
  216. prograph/schema/source_map.py +1103 -0
  217. prograph/schema/store_view.py +459 -0
  218. prograph/schema/types.py +569 -0
  219. prograph/schema/xsd.py +569 -0
  220. prograph/shacl/__init__.py +30 -0
  221. prograph/shacl/dqv.py +58 -0
  222. prograph/shacl/generate.py +255 -0
  223. prograph/shacl/report.py +138 -0
  224. prograph/shacl/validator.py +164 -0
  225. prograph/store.py +1737 -0
  226. prograph/utils/__init__.py +6 -0
  227. prograph/utils/exceptions.py +308 -0
  228. prograph/utils/helpers.py +126 -0
  229. prograph/warnings.py +46 -0
  230. prograph/writes.py +369 -0
  231. prograph-1.3.3.dist-info/METADATA +281 -0
  232. prograph-1.3.3.dist-info/RECORD +237 -0
  233. prograph-1.3.3.dist-info/WHEEL +5 -0
  234. prograph-1.3.3.dist-info/entry_points.txt +3 -0
  235. prograph-1.3.3.dist-info/licenses/LICENSE +201 -0
  236. prograph-1.3.3.dist-info/licenses/NOTICE +10 -0
  237. prograph-1.3.3.dist-info/top_level.txt +1 -0
@@ -0,0 +1,1803 @@
1
+ """Schema mapping for virtual graph layers.
2
+
3
+ This module maps external data sources (Pandas DataFrames, Spark tables)
4
+ to virtual graph structures. This will be implemented in Phase 3.
5
+ """
6
+
7
+ import itertools
8
+ import weakref
9
+ from dataclasses import dataclass
10
+ from enum import Enum
11
+ from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional, Sequence, Set, Tuple, Union
12
+
13
+ from prograph.schema.iri import DEFAULT_VOCAB_IRI
14
+ from prograph.schema.source_map import identity_table
15
+ from prograph.rules import home, module_home
16
+
17
+ module_home("language-column", "A language column",
18
+ terms=("language_column", "lang", "language tag", "LANG"))
19
+
20
+ if TYPE_CHECKING:
21
+ from prograph.schema.context import SchemaDescriptor
22
+ from prograph.schema.source_map import EdgeMap, NodeMap, SourceMaps
23
+
24
+
25
+ @dataclass
26
+ class TableStats:
27
+ """Statistics for a source table, used for broadcast join decisions.
28
+
29
+ Either field can be provided independently. The optimizer uses these
30
+ to decide whether to broadcast a table in join operations.
31
+
32
+ Example:
33
+ >>> stats = TableStats(row_count=1000, size_bytes=50_000)
34
+ """
35
+ row_count: Optional[int] = None
36
+ size_bytes: Optional[int] = None
37
+
38
+
39
+ class PredicateKind(Enum):
40
+ """The kind of RDF predicate - maps to LPG structure."""
41
+ DATATYPE = "datatype" # Datatype property → node property column
42
+ OBJECT = "object" # Object property → relationship
43
+
44
+
45
+ class PredicateMapping:
46
+ """Maps an RDF predicate IRI to LPG structure.
47
+
48
+ RDF predicates can be either:
49
+ - Datatype properties: Map to node property columns (e.g., :name → Person.name)
50
+ - Object properties: Map to relationships (e.g., :knows → KNOWS relationship)
51
+
52
+ This allows SPARQL queries with concrete predicates to execute against
53
+ a labeled property graph backend.
54
+
55
+ Example (datatype property):
56
+ >>> mapping = PredicateMapping(
57
+ ... predicate_iri="http://example.org/name",
58
+ ... kind=PredicateKind.DATATYPE,
59
+ ... node_label="Person",
60
+ ... property_name="name"
61
+ ... )
62
+
63
+ Example (object property):
64
+ >>> mapping = PredicateMapping(
65
+ ... predicate_iri="http://example.org/knows",
66
+ ... kind=PredicateKind.OBJECT,
67
+ ... relationship_type="KNOWS"
68
+ ... )
69
+ """
70
+
71
+ def __init__(
72
+ self,
73
+ predicate_iri: str,
74
+ kind: PredicateKind,
75
+ node_label: Optional[str] = None,
76
+ property_name: Optional[str] = None,
77
+ relationship_type: Optional[str] = None,
78
+ datatype: Optional[str] = None,
79
+ language: Optional[str] = None,
80
+ language_column: Optional[str] = None,
81
+ ):
82
+ """Create a predicate mapping.
83
+
84
+ Args:
85
+ predicate_iri: The full IRI of the RDF predicate
86
+ kind: Whether this is a datatype or object property
87
+ node_label: For datatype properties, the node label containing this property
88
+ property_name: For datatype properties, the property name on the node
89
+ relationship_type: For object properties, the relationship type
90
+ datatype: XSD datatype IRI for the emitted literal, e.g.
91
+ 'http://www.w3.org/2001/XMLSchema#date'. Without it the datatype
92
+ is inferred from the Python value, which is right for numbers and
93
+ wrong for anything a column stores as text, a date, a decimal
94
+ held as a string, and a shape's ``sh:datatype`` then fails
95
+ against a plain literal.
96
+ language: A fixed BCP-47 language tag for every value of this
97
+ property, e.g. 'fr'. Mutually exclusive with datatype: a
98
+ language-tagged literal is an rdf:langString by definition.
99
+ language_column: Column holding a per-row language tag, for the
100
+ usual shape of multilingual data, a label column beside a lang
101
+ column. Takes precedence over ``language`` when the row has a
102
+ value; rows with none fall back to ``language``.
103
+ """
104
+ self.predicate_iri = predicate_iri
105
+ self.kind = kind
106
+ self.node_label = node_label
107
+ self.property_name = property_name
108
+ self.relationship_type = relationship_type
109
+ self.datatype = datatype
110
+ self.language = language
111
+ self.language_column = language_column
112
+
113
+ # Validation
114
+ if kind == PredicateKind.DATATYPE:
115
+ if not property_name:
116
+ raise ValueError("Datatype predicates require property_name")
117
+ elif kind == PredicateKind.OBJECT:
118
+ if not relationship_type:
119
+ raise ValueError("Object predicates require relationship_type")
120
+
121
+ if datatype and (language or language_column):
122
+ raise ValueError(
123
+ "A literal carries either a datatype or a language tag, not "
124
+ "both: a language-tagged literal is an rdf:langString. "
125
+ f"Got datatype={datatype!r} with "
126
+ f"language={language or language_column!r}."
127
+ )
128
+ if (language or language_column) and kind != PredicateKind.DATATYPE:
129
+ raise ValueError("Language tags apply to datatype predicates only")
130
+
131
+
132
+ def _same_predicate_target(left: PredicateMapping, right: PredicateMapping) -> bool:
133
+ """Whether two mappings for one IRI say the same thing.
134
+
135
+ Re-registering an equivalent mapping is idempotent; only a genuinely
136
+ different target, another label, another property, is an addition.
137
+ """
138
+ return (
139
+ left.kind == right.kind
140
+ and left.node_label == right.node_label
141
+ and left.property_name == right.property_name
142
+ and left.relationship_type == right.relationship_type
143
+ )
144
+
145
+
146
+ # Gremlin results that carry an element's id and label (valueMap(true),
147
+ # elementMap()) key them as these strings, which are TinkerPop's accessor
148
+ # strings for T.id and T.label. The prefix is reserved so that no property can
149
+ # take the same key (docs/architecture/ row "Gremlin token keys").
150
+ RESERVED_PROPERTY_PREFIX = "~"
151
+ TOKEN_ID_KEY = RESERVED_PROPERTY_PREFIX + "id"
152
+ TOKEN_LABEL_KEY = RESERVED_PROPERTY_PREFIX + "label"
153
+ # The name a WITH carries a node's labels under where its row may carry
154
+ # several (`ExprTranslator.row_labels`): no property, by the prefix.
155
+ ROW_LABELS_KEY = RESERVED_PROPERTY_PREFIX + "labels"
156
+ # The name a node's language column is read under (a PredicateMapping's
157
+ # `language_column`, `NodeMapping.language_columns`): the column the tag of
158
+ # a literal comes from, whether or not property_columns lists it, and no
159
+ # property, by the prefix (docs/architecture/rules.md, "A language column").
160
+ LANGUAGE_COLUMN_PREFIX = RESERVED_PROPERTY_PREFIX + "lang:"
161
+
162
+
163
+ def _property_columns(value: Optional[Dict[str, str]]) -> Dict[str, str]:
164
+ """property_columns as given, refusing anything but a dict.
165
+
166
+ A list of column names would otherwise pass construction and fail at
167
+ query time with "'list' object has no attribute 'items'". A property name
168
+ that starts with the reserved prefix is refused as well: the rule is on the
169
+ property name, so a column called ``~id`` may still be read under the
170
+ property name ``id``.
171
+ """
172
+ if value is not None and not isinstance(value, dict):
173
+ raise TypeError(
174
+ "property_columns must be a dict of property name to column "
175
+ f"name, e.g. {{'name': 'name'}}; got {type(value).__name__} "
176
+ f"{value!r}")
177
+ for name in value or {}:
178
+ if isinstance(name, str) and name.startswith(RESERVED_PROPERTY_PREFIX):
179
+ raise ValueError(
180
+ f"property name {name!r} is refused: names starting with "
181
+ f"{RESERVED_PROPERTY_PREFIX!r} are reserved, because Gremlin "
182
+ f"results key an element's id and label as {TOKEN_ID_KEY!r} "
183
+ f"and {TOKEN_LABEL_KEY!r}. Map the column under another "
184
+ "property name")
185
+ return value or {}
186
+
187
+
188
+ def _filter_predicate(value: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
189
+ """filter_predicate as given, refusing anything but column -> value pairs.
190
+
191
+ Every reader applies it as ``column == value`` for each pair; a value of
192
+ None means the column IS NULL (the rows with no value there). A string
193
+ such as "kind = 'emp'" or a list would otherwise pass construction and
194
+ fail at query time with "'str' object has no attribute 'items'"; a value
195
+ that is a list or a dict would fail with a length mismatch or match no
196
+ rows, silently, and an array or a Series is compared row by row and
197
+ matches whichever rows happen to line up.
198
+ """
199
+ if value is None:
200
+ return None
201
+ if not isinstance(value, dict):
202
+ raise TypeError(
203
+ "filter_predicate must be a dict of column name to the value "
204
+ f"the column equals (None: the column has none), e.g. {{'kind': 'emp'}}; got "
205
+ f"{type(value).__name__} {value!r}. A SQL string or a list is not "
206
+ "accepted")
207
+ for column, expected in value.items():
208
+ if not isinstance(column, str):
209
+ raise TypeError(
210
+ "filter_predicate keys must be column names (str); got "
211
+ f"{type(column).__name__} {column!r}")
212
+ # Anything that holds values is not a value: a list, a set, a dict,
213
+ # and also a numpy array or a pandas Series, which compared with the
214
+ # column element by element and answered wrongly with no error.
215
+ if hasattr(expected, '__iter__') and not isinstance(expected, (str, bytes)):
216
+ raise TypeError(
217
+ f"filter_predicate[{column!r}] must be a single value the "
218
+ f"column equals (or None, for no value); got {type(expected).__name__} {expected!r}. "
219
+ "A set of allowed values is not supported")
220
+ return value
221
+
222
+
223
+ # Each mapping's version, a number no other change has, set whenever an
224
+ # attribute of the mapping is: `GraphSchema.source_maps` keys its cache on
225
+ # its mappings' versions, so that a change made to a mapping one schema
226
+ # shares with another (its `_schema` the other) is a new version of both.
227
+ # Kept beside the mappings, not on them, so that a mapping's attributes are
228
+ # its own (the round trip compares them, `compile_schema.project`).
229
+ _MAPPING_VERSIONS: 'weakref.WeakKeyDictionary[Any, int]' = weakref.WeakKeyDictionary()
230
+ _NEXT_VERSION = itertools.count(1)
231
+
232
+
233
+ @home("source-queries", "A mapping's source that is a SQL query",
234
+ terms=("source_query", "rr:sqlQuery", "R2RML view", "derived table", "logical table"))
235
+ class TableMapping:
236
+ """Base class for mappings that reference source tables.
237
+
238
+ Provides table name qualification support for Unity Catalog.
239
+ """
240
+
241
+ def __init__(self, source_table: str, source_query: Optional[str] = None):
242
+ self.source_table = source_table
243
+ # A logical table given by a SQL query rather than a table (R2RML
244
+ # 5.2, rr:sqlQuery): `source_table` is its name, the key of its
245
+ # frame on a DataFrame backend, and SQL reads the query itself as a
246
+ # derived table (`qualified_source_table`).
247
+ self.source_query = source_query
248
+ self._schema: Optional['GraphSchema'] = None # Set when added to schema
249
+
250
+ def __setattr__(self, name: str, value: Any) -> None:
251
+ # A mapping changed after it joined a schema (turbofan's iri_template,
252
+ # a YAML file's class_iri) is a new version of that schema: its
253
+ # source maps are compiled again (`GraphSchema.source_maps`).
254
+ object.__setattr__(self, name, value)
255
+ if name != '_schema':
256
+ _MAPPING_VERSIONS[self] = next(_NEXT_VERSION)
257
+ schema = self.__dict__.get('_schema')
258
+ if schema is not None and name != '_schema':
259
+ schema._schema_changed()
260
+
261
+ @property
262
+ def qualified_source_table(self) -> str:
263
+ """Get fully qualified table name for SQL generation.
264
+
265
+ Resolution order:
266
+ 0. A source query (``source_query``, an R2RML view): the query in
267
+ parentheses, a derived table every SQL reader of the source
268
+ writes where a table name stands (``Dialect.table_name`` keeps
269
+ it as it is)
270
+ 1. Explicit table_qualifications map (if table name is in map)
271
+ 2. Already qualified (contains dots) - return as-is
272
+ 3. default_catalog + default_schema prefix
273
+ 4. Return source_table unchanged
274
+
275
+ Returns:
276
+ Qualified table name for SQL generation.
277
+ """
278
+ if getattr(self, 'source_query', None):
279
+ return f"({self.source_query})"
280
+ # 1. Check explicit mapping first
281
+ if self._schema and self.source_table in self._schema.table_qualifications:
282
+ return self._schema.table_qualifications[self.source_table]
283
+ # 2. Already qualified - return as-is
284
+ if '.' in self.source_table:
285
+ return self.source_table
286
+ # 3. Use defaults
287
+ if self._schema and self._schema.default_catalog and self._schema.default_schema:
288
+ return f"{self._schema.default_catalog}.{self._schema.default_schema}.{self.source_table}"
289
+ # 4. Return unchanged
290
+ return self.source_table
291
+
292
+
293
+ class NodeMapping(TableMapping):
294
+ """Defines how a data source maps to graph nodes.
295
+
296
+ Example:
297
+ >>> mapping = NodeMapping(
298
+ ... source_table="movies",
299
+ ... label="Movie",
300
+ ... id_column="movie_id",
301
+ ... property_columns={"title": "title", "year": "released"}
302
+ ... )
303
+
304
+ Example with composite key (for tables like TPC-H lineitem):
305
+ >>> mapping = NodeMapping(
306
+ ... source_table="lineitem",
307
+ ... label="LineItem",
308
+ ... id_column=["l_orderkey", "l_linenumber"], # Composite key
309
+ ... property_columns={"quantity": "l_quantity", "price": "l_extendedprice"}
310
+ ... )
311
+
312
+ Example of a label an action layer writes (``engine.set_properties``):
313
+ >>> mapping = NodeMapping(
314
+ ... source_table="suppliers",
315
+ ... label="Supplier",
316
+ ... id_column="id",
317
+ ... property_columns={"status": "status"},
318
+ ... mutable=True,
319
+ ... )
320
+ """
321
+
322
+ def __init__(
323
+ self,
324
+ source_table: str,
325
+ label: str,
326
+ id_column: Union[str, List[str]],
327
+ property_columns: Optional[Dict[str, str]] = None,
328
+ graph_iri: Optional[str] = None,
329
+ filter_predicate: Optional[Dict[str, Any]] = None,
330
+ iri_template: Optional[str] = None,
331
+ class_iri: Optional[str] = None,
332
+ rdf_class: bool = True,
333
+ source_query: Optional[str] = None,
334
+ key_stated: bool = True,
335
+ mutable: bool = False,
336
+ on_duplicate: Optional[str] = None,
337
+ keys: Optional[str] = None,
338
+ identity: Optional[str] = None,
339
+ ):
340
+ """Create a node mapping.
341
+
342
+ Args:
343
+ source_table: Name of the source table
344
+ label: Graph label for nodes from this table
345
+ id_column: Column(s) that uniquely identify nodes. Can be a single
346
+ column name (str) or a list of column names for composite keys.
347
+ property_columns: Mapping of property names to column names
348
+ graph_iri: Static named graph IRI for this mapping. The only
349
+ supported named-graph mechanism, per-row dynamic graphs
350
+ (``graph_column``) and IRI templates (``graph_template``)
351
+ were removed in phase 0 of the W3C roadmap because they
352
+ were stored but never consumed by execution. Reintroduce
353
+ only when paired with a real downstream consumer.
354
+ filter_predicate: Optional dict of column=value pairs injected as
355
+ WHERE filters on reads. Enables mapping multiple graph labels
356
+ to the same base table using a discriminator column.
357
+ Example: {'type': 'Bearing'} → WHERE type = 'Bearing'.
358
+ A None value is the rows with no value: {'type': None} →
359
+ WHERE type IS NULL.
360
+ iri_template: R2RML-style template deciding this node's IRI in RDF,
361
+ with {column} placeholders resolved per row, e.g.
362
+ 'http://example.org/person/{person_id}'. When omitted the IRI is
363
+ synthesized as {base_iri}{source_table}/{id}. Consumed by
364
+ R2RML import/export and the SPARQL front-end
365
+ through prograph.schema.iri, so both agree on a node's
366
+ identity. Set this when the data has real IRIs (RDF-sourced, or
367
+ an R2RML mapping with its own subject map); otherwise those
368
+ IRIs are lost and the synthesized ones will not round-trip.
369
+ class_iri: The IRI of the RDF class these rows are typed with,
370
+ e.g. 'http://xmlns.com/foaf/0.1/Person'. Declare it to bind the
371
+ label to an externally-authored ontology's class; otherwise
372
+ '{vocab_iri}{label}' is synthesized, which no outside ontology
373
+ will recognize. The class counterpart of iri_template, resolved
374
+ through prograph.schema.iri like everything else.
375
+ rdf_class: Whether the label is an RDF class (default). False
376
+ for a label that only groups rows, such as one that holds
377
+ every subject of a loaded graph: its rows get no rdf:type
378
+ triple for it, and `?s a ?t` and `?s ?p ?o` do not list it.
379
+ source_query: A SQL query whose result is the source, an R2RML
380
+ view (rr:sqlQuery); `source_table` then names it.
381
+ key_stated: Whether `id_column` is a stated key, one row per
382
+ node (a YAML or Python schema's, the user's responsibility),
383
+ which an optimization may rely on; False for a key that is
384
+ only an R2RML subject template's columns, which states
385
+ identity, not uniqueness, so nothing is pruned or joined
386
+ exactly on it (docs/architecture/rules.md "Keys an
387
+ optimization relies on").
388
+ mutable: Whether ProGraph may write this label's table
389
+ (default False): ``engine.set_properties`` on the rows this
390
+ mapping owns, never an inferred row (``prograph.writes``). It opens nothing
391
+ else: a query's CREATE, SET or DELETE and a SPARQL Update
392
+ stay refused (``prograph.read_only``).
393
+ on_duplicate: Cypher's policy for a key the data breaks
394
+ (``'refuse'`` or ``'trust'``): accepted so a mapping that
395
+ states it loads, with a warning that 1.0 does not apply it
396
+ (``policy_name``; SPARQL reads ``keys: trusted`` or
397
+ ``keys: check``). Any other value raises ValueError.
398
+ keys: Whether a query plan may rely on the key being unique
399
+ (one-plan.md 2.4): ``'trusted'``, the user's assertion that
400
+ no two rows hold one key value (a broken key then gives
401
+ wrong answers, documented); ``'check'``, verified for the
402
+ data version (not built yet: until it is, the key is not
403
+ relied on); None (the default), relied on only where the
404
+ database enforces it or Databricks declares it RELY
405
+ (``prograph.node_keys.trusted_keys``). Any other value
406
+ raises ValueError.
407
+ """
408
+ super().__init__(source_table, source_query)
409
+ self.label = label
410
+ self.on_duplicate = on_duplicate
411
+ from prograph.plan.ir.keys import key_trust_name
412
+ self.keys = key_trust_name(keys, f"keys of the node mapping {label!r}")
413
+ # Which maps' subjects this one's may meet (docs/architecture/keys-and-identity.md, 4): a
414
+ # shared name (`{base_iri}{name}/{key}` where no iri_template is given), "global", or "distinct"
415
+ # (its subjects are never another map's: trusted as `keys: trusted` is; source_map.DISTINCT; with no
416
+ # iri_template, its IRIs are its table's own, `{base_iri}{table}/{key}`).
417
+ if identity is not None and (not isinstance(identity, str) or not identity
418
+ or not all(c.isalnum() or c in "-_." for c in identity)):
419
+ raise ValueError(f"identity of the node mapping {label!r}: {identity!r} is no name "
420
+ f"(letters, digits, '-', '_', '.') and not 'global'")
421
+ self.identity = identity
422
+ self.mutable = bool(mutable)
423
+ self._id_column = id_column
424
+ self.property_columns = _property_columns(property_columns)
425
+ self.graph_iri = graph_iri
426
+ self.filter_predicate = _filter_predicate(filter_predicate)
427
+ self.iri_template = iri_template
428
+ self.class_iri = class_iri
429
+ self.rdf_class = rdf_class
430
+ self.key_stated = key_stated
431
+
432
+ @property
433
+ def on_duplicate(self) -> Optional[str]:
434
+ """The policy for a key the data breaks, or None for the engine's
435
+ (``prograph.node_keys``)."""
436
+ return self._on_duplicate
437
+
438
+ @on_duplicate.setter
439
+ def on_duplicate(self, value: Optional[str]) -> None:
440
+ self._on_duplicate = policy_name(
441
+ value, f"on_duplicate of the node mapping {self.__dict__.get('label')!r}")
442
+
443
+ @property
444
+ def id_column(self) -> str:
445
+ """Get the ID column name.
446
+
447
+ For backward compatibility, returns the single ID column name.
448
+ Raises ValueError if this is a composite key with multiple columns.
449
+
450
+ Returns:
451
+ The ID column name
452
+
453
+ Raises:
454
+ ValueError: If this mapping has a composite key with multiple columns
455
+ """
456
+ if isinstance(self._id_column, list):
457
+ if len(self._id_column) == 1:
458
+ return self._id_column[0]
459
+ raise ValueError(
460
+ f"Cannot use id_column on composite key with {len(self._id_column)} columns. "
461
+ f"Use id_columns property instead."
462
+ )
463
+ return self._id_column
464
+
465
+ @id_column.setter
466
+ def id_column(self, value: Union[str, List[str]]) -> None:
467
+ """Set the ID column(s)."""
468
+ self._id_column = value
469
+
470
+ @property
471
+ def id_columns(self) -> List[str]:
472
+ """Get all ID columns as a list.
473
+
474
+ Always returns a list, whether this is a single-column or composite key.
475
+
476
+ Returns:
477
+ List of ID column names
478
+ """
479
+ if isinstance(self._id_column, list):
480
+ return self._id_column
481
+ return [self._id_column]
482
+
483
+ @property
484
+ def node_properties(self) -> Dict[str, str]:
485
+ """Property name -> column for every property a node has: the mapped
486
+ names, then the identity columns under their own names. The one list
487
+ both executors and every SQL scan of the node read."""
488
+ props = dict(self.property_columns or {})
489
+ mapped = set(props.values())
490
+ for col in self.identity_columns:
491
+ if col not in mapped and col not in props:
492
+ props[col] = col
493
+ return props
494
+
495
+ @property
496
+ def language_columns(self) -> Dict[str, str]:
497
+ """Read name -> column for each language column the schema's
498
+ PredicateMappings name for this label (a `language_column` on a
499
+ declaration for the label, or on one for no label whose property the
500
+ label has): the one place a
501
+ language column becomes readable, by every reader of a node's row,
502
+ whether or not property_columns lists it. The names carry the
503
+ reserved prefix, so a language column is no property of the node:
504
+ its map, its keys and ?s ?p ?o are as property_columns says
505
+ (1258)."""
506
+ schema = getattr(self, '_schema', None)
507
+ if schema is None:
508
+ return {}
509
+ found: Dict[str, str] = {}
510
+ for declared in schema._predicate_mappings_by_iri.values():
511
+ for pm in declared:
512
+ if pm.language_column and (pm.node_label == self.label or (
513
+ pm.node_label is None and pm.property_name in self.node_properties)):
514
+ found[LANGUAGE_COLUMN_PREFIX + pm.language_column] = pm.language_column
515
+ return found
516
+
517
+ @property
518
+ def identity_columns(self) -> List[str]:
519
+ """The key columns, then any other column the iri_template names.
520
+
521
+ A node's properties are its mapped names plus these columns under
522
+ their own names: its identity in the property graph and in RDF.
523
+ """
524
+ columns = list(self.id_columns)
525
+ template = getattr(self, 'iri_template', None)
526
+ if template:
527
+ from prograph.schema.iri import template_parts
528
+ for text, is_column in template_parts(template):
529
+ if is_column and text not in columns:
530
+ columns.append(text)
531
+ return columns
532
+
533
+ @property
534
+ def is_composite_key(self) -> bool:
535
+ """Check if this mapping uses a composite key.
536
+
537
+ Returns:
538
+ True if the key has multiple columns, False otherwise
539
+ """
540
+ return isinstance(self._id_column, list) and len(self._id_column) > 1
541
+
542
+
543
+ class RelationshipMapping(TableMapping):
544
+ """Defines how a data source maps to graph relationships.
545
+
546
+ Example:
547
+ >>> mapping = RelationshipMapping(
548
+ ... source_table="acted_in",
549
+ ... rel_type="ACTED_IN",
550
+ ... start_node_label="Person",
551
+ ... start_id_column="person_id",
552
+ ... end_node_label="Movie",
553
+ ... end_id_column="movie_id",
554
+ ... property_columns={"roles": "character_names"}
555
+ ... )
556
+
557
+ Example with composite key endpoint:
558
+ >>> mapping = RelationshipMapping(
559
+ ... source_table="lineitem",
560
+ ... rel_type="CONTAINS",
561
+ ... start_node_label="Order",
562
+ ... start_id_column="l_orderkey", # Single column
563
+ ... end_node_label="LineItem",
564
+ ... end_id_column=["l_orderkey", "l_linenumber"], # Composite key
565
+ ... )
566
+
567
+ Example with mutability (for Delta Lake):
568
+ >>> mapping = RelationshipMapping(
569
+ ... source_table="catalog.schema.knows",
570
+ ... rel_type="KNOWS",
571
+ ... start_node_label="Person",
572
+ ... start_id_column="person1_id",
573
+ ... end_node_label="Person",
574
+ ... end_id_column="person2_id",
575
+ ... )
576
+ """
577
+
578
+ def __init__(
579
+ self,
580
+ source_table: str,
581
+ rel_type: str,
582
+ start_node_label: str,
583
+ start_id_column: Union[str, List[str]],
584
+ end_node_label: str,
585
+ end_id_column: Union[str, List[str]],
586
+ property_columns: Optional[Dict[str, str]] = None,
587
+ graph_iri: Optional[str] = None,
588
+ filter_predicate: Optional[Dict[str, Any]] = None,
589
+ reify: Optional[bool] = None,
590
+ relation_class_iri: Optional[str] = None,
591
+ referential_integrity: bool = False,
592
+ source_query: Optional[str] = None,
593
+ mutable: bool = False,
594
+ keys: Optional[str] = None,
595
+ id_column: Optional[Union[str, List[str]]] = None,
596
+ start_node_identity: Optional[str] = None,
597
+ end_node_identity: Optional[str] = None,
598
+ ):
599
+ """Create a relationship mapping.
600
+
601
+ Args:
602
+ source_table: Name of the source table
603
+ rel_type: Relationship type in the graph
604
+ start_node_label: Label of start nodes
605
+ start_id_column: Column(s) for start node ID. Can be a single
606
+ column name or a list for composite keys.
607
+ end_node_label: Label of end nodes
608
+ end_id_column: Column(s) for end node ID. Can be a single
609
+ column name or a list for composite keys.
610
+ property_columns: Mapping of property names to column names
611
+ graph_iri: Static named graph IRI for this mapping. The only
612
+ supported named-graph mechanism. See ``NodeMapping`` for
613
+ rationale.
614
+ filter_predicate: Optional dict of column=value pairs injected
615
+ as WHERE clauses on reads. Enables multiple rel_types to
616
+ share a single table (a ``rel_type`` discriminator column).
617
+ reify: ``True`` asks for the edge's properties as a reified
618
+ ``rdf:Statement``, which is not built on the graph SPARQL
619
+ answers: it raises ``NotBuilt`` (reified statements return as
620
+ RDF 1.2 reifiers). ``None`` (default) and ``False`` load.
621
+ relation_class_iri: The class the reified statement node is typed
622
+ with, for a shape's ``sh:targetClass`` or an ontology's own
623
+ relation class. Defaults to ``{vocab}{PascalCaseRelType}``,
624
+ ``WORKS_AT`` → ``:WorksAt``.
625
+ referential_integrity: Declares that every start and end key in
626
+ this table has a row in its node mapping (no dangling foreign
627
+ keys). With it, SQL generation may drop a join to a node
628
+ table that is only there to connect two relationships, which
629
+ is a large saving on long chains. Without it the join stays,
630
+ because it is also an existence check: a path through an id
631
+ with no node row is not a path. Default False: correct on
632
+ any data.
633
+ source_query: A SQL query whose result is the source, an R2RML
634
+ view (rr:sqlQuery); `source_table` then names it.
635
+ mutable: Not read for a relationship mapping: ``set_properties``
636
+ writes nodes only, and a query's CREATE or DELETE stays
637
+ refused.
638
+ keys: ``'trusted'``, the user's assertion that no two rows hold
639
+ one start and end (the edge table's key is its start and end
640
+ columns), so a plan may rely on it (one-plan.md 2.4, as for a
641
+ node mapping); ``'check'`` (not built yet, relies on nothing);
642
+ None relies on it only where the database enforces it.
643
+ id_column: The column (or columns, a list) that names one
644
+ relationship: its id, which tells two relationships of one
645
+ start and end apart (relationship uniqueness, ``count(r)``,
646
+ ``elementId(r)``). Unset, each row is one relationship, told
647
+ apart from the other rows of its start and end by its number
648
+ among them: the same answers, a little more work, and an
649
+ ``elementId`` stable only while the table is.
650
+ start_node_identity, end_node_identity: An end given by an
651
+ identity instead of a label (pass None as its label): the
652
+ node of its key in any node mapping that declares
653
+ `identity: <name>`, whatever its labels (LDBC's LIKES ends at
654
+ a Post or a Comment, message ids in one space). One key is one
655
+ node.
656
+ """
657
+ super().__init__(source_table, source_query)
658
+ for side, label, named in (("start", start_node_label, start_node_identity),
659
+ ("end", end_node_label, end_node_identity)):
660
+ if label is not None and named is not None:
661
+ raise ValueError(f"the relationship mapping {rel_type!r} gives its {side} both a label ({label!r}) "
662
+ f"and an identity ({named!r}): give one")
663
+ if label is None and named is None:
664
+ raise ValueError(f"the relationship mapping {rel_type!r} gives its {side} no label: give "
665
+ f"{side}_node_label, or {side}_node_identity for any node of one identity")
666
+ if named in ("global", "distinct"):
667
+ raise ValueError(f"the relationship mapping {rel_type!r} gives its {side} the identity {named!r}, "
668
+ f"which names no one set of nodes: give the name the node mappings share "
669
+ f"(identity: <name>)")
670
+ self.start_node_identity = start_node_identity
671
+ self.end_node_identity = end_node_identity
672
+ self.id_columns: Optional[Tuple[str, ...]] = None if id_column is None else \
673
+ (tuple(id_column) if isinstance(id_column, (list, tuple)) else (id_column,))
674
+ self.mutable = bool(mutable)
675
+ from prograph.plan.ir.keys import key_trust_name
676
+ self.keys = key_trust_name(keys, f"keys of the relationship mapping {rel_type!r}")
677
+ self.rel_type = rel_type
678
+ self.start_node_label = start_node_label
679
+ self._start_id_column = start_id_column
680
+ self.graph_iri = graph_iri
681
+ self.end_node_label = end_node_label
682
+ self._end_id_column = end_id_column
683
+ self.property_columns = _property_columns(property_columns)
684
+ self.filter_predicate = _filter_predicate(filter_predicate)
685
+ if reify:
686
+ from prograph.plan.ir.facts import NotBuilt
687
+ raise NotBuilt(
688
+ f"reify on relationship {rel_type!r}: edge properties as reified statements are not built "
689
+ "on the SPARQL graph; they return as RDF 1.2 reifiers. Remove reify (or set it false)")
690
+ self.reify = reify
691
+ self.relation_class_iri = relation_class_iri
692
+ self.referential_integrity = referential_integrity
693
+
694
+ @property
695
+ def start_id_column(self) -> str:
696
+ """Get the start ID column name.
697
+
698
+ For backward compatibility, returns the single start ID column name.
699
+ Raises ValueError if this is a composite key with multiple columns.
700
+
701
+ Returns:
702
+ The start ID column name
703
+
704
+ Raises:
705
+ ValueError: If this mapping has a composite start key with multiple columns
706
+ """
707
+ if isinstance(self._start_id_column, list):
708
+ if len(self._start_id_column) == 1:
709
+ return self._start_id_column[0]
710
+ raise ValueError(
711
+ f"Cannot use start_id_column on composite key with {len(self._start_id_column)} columns. "
712
+ f"Use start_id_columns property instead."
713
+ )
714
+ return self._start_id_column
715
+
716
+ @start_id_column.setter
717
+ def start_id_column(self, value: Union[str, List[str]]) -> None:
718
+ """Set the start ID column(s)."""
719
+ self._start_id_column = value
720
+
721
+ @property
722
+ def start_id_columns(self) -> List[str]:
723
+ """Get all start ID columns as a list.
724
+
725
+ Always returns a list, whether this is a single-column or composite key.
726
+
727
+ Returns:
728
+ List of start ID column names
729
+ """
730
+ if isinstance(self._start_id_column, list):
731
+ return self._start_id_column
732
+ return [self._start_id_column]
733
+
734
+ @property
735
+ def end_id_column(self) -> str:
736
+ """Get the end ID column name.
737
+
738
+ For backward compatibility, returns the single end ID column name.
739
+ Raises ValueError if this is a composite key with multiple columns.
740
+
741
+ Returns:
742
+ The end ID column name
743
+
744
+ Raises:
745
+ ValueError: If this mapping has a composite end key with multiple columns
746
+ """
747
+ if isinstance(self._end_id_column, list):
748
+ if len(self._end_id_column) == 1:
749
+ return self._end_id_column[0]
750
+ raise ValueError(
751
+ f"Cannot use end_id_column on composite key with {len(self._end_id_column)} columns. "
752
+ f"Use end_id_columns property instead."
753
+ )
754
+ return self._end_id_column
755
+
756
+ @end_id_column.setter
757
+ def end_id_column(self, value: Union[str, List[str]]) -> None:
758
+ """Set the end ID column(s)."""
759
+ self._end_id_column = value
760
+
761
+ @property
762
+ def end_id_columns(self) -> List[str]:
763
+ """Get all end ID columns as a list.
764
+
765
+ Always returns a list, whether this is a single-column or composite key.
766
+
767
+ Returns:
768
+ List of end ID column names
769
+ """
770
+ if isinstance(self._end_id_column, list):
771
+ return self._end_id_column
772
+ return [self._end_id_column]
773
+
774
+ @property
775
+ def has_composite_start_key(self) -> bool:
776
+ """Check if the start endpoint uses a composite key."""
777
+ return isinstance(self._start_id_column, list) and len(self._start_id_column) > 1
778
+
779
+ @property
780
+ def has_composite_end_key(self) -> bool:
781
+ """Check if the end endpoint uses a composite key."""
782
+ return isinstance(self._end_id_column, list) and len(self._end_id_column) > 1
783
+
784
+
785
+ def filters_disjoint(a: Any, b: Any) -> bool:
786
+ """Whether no row satisfies both mappings' filter_predicates: they name
787
+ a column in common with different values (Person `kind='person'`,
788
+ Robot `kind='robot'`). A mapping with no filter, or filters on
789
+ different columns, can both hold for one row, so they are not
790
+ disjoint. A None is a value of its own (the column has none): it
791
+ differs from every other value and equals only another None, and a
792
+ mapping with no filter has every row, so it overlaps. The schema-level reading of the rule
793
+ `prograph.schema.rows.owned_rows` applies to a table's rows."""
794
+ fa = getattr(a, 'filter_predicate', None) or {}
795
+ fb = getattr(b, 'filter_predicate', None) or {}
796
+ return any(col in fb and fb[col] != value for col, value in fa.items())
797
+
798
+
799
+ def _mappings_share_rows(a: Any, b: Any) -> bool:
800
+ """Whether two node mappings can hold one row: the same table and key,
801
+ and row filters that can both hold (Person and Robot filtered out of one
802
+ table by `kind` share the table and never a row). The test of
803
+ `GraphSchema.labels_share_rows`."""
804
+ return (a is not None and b is not None
805
+ and a.qualified_source_table == b.qualified_source_table
806
+ and a.id_columns == b.id_columns
807
+ and not filters_disjoint(a, b))
808
+
809
+
810
+ def rows_within(a: Any, b: Any) -> bool:
811
+ """Whether every node of mapping a is a node of mapping b: one table
812
+ read by one key into one IRI, and b's filter_predicate asks nothing
813
+ a's does not (Bearing `type='Bearing'` within Component, which has no
814
+ filter; a mapping within itself). Two labels on one table by different
815
+ keys (an Order and a Customer read from one sales table) are different
816
+ things and share no node, as `GraphSchema.labels_share_rows` has it;
817
+ so are two that write their IRIs differently. The other reading of the
818
+ rule `filters_disjoint` reads: two labels on one table share nodes,
819
+ are apart, or one holds the other's."""
820
+ if (getattr(a, 'qualified_source_table', None) != getattr(b, 'qualified_source_table', None)
821
+ or getattr(a, 'id_columns', None) != getattr(b, 'id_columns', None)
822
+ or getattr(a, 'iri_template', None) != getattr(b, 'iri_template', None)):
823
+ return False
824
+ fa = getattr(a, 'filter_predicate', None) or {}
825
+ fb = getattr(b, 'filter_predicate', None) or {}
826
+ return all(col in fa and fa[col] == value for col, value in fb.items())
827
+
828
+
829
+ @dataclass(frozen=True)
830
+ class Candidate:
831
+ """One way a relationship pattern can match (GraphSchema.candidates).
832
+
833
+ Attributes:
834
+ mapping: The relationship mapping.
835
+ forward: True when the pattern's near node is the mapping's start
836
+ node, False when it is its end node.
837
+ near_label: The mapping's label on the pattern's near side.
838
+ far_label: The mapping's label on the pattern's far side.
839
+ """
840
+ mapping: 'RelationshipMapping'
841
+ forward: bool
842
+ near_label: str
843
+ far_label: str
844
+
845
+
846
+
847
+
848
+
849
+ # Cypher's policy for a key the data breaks (`on_duplicate`): accepted and checked so a
850
+ # mapping that states it still loads, but no 1.0 plan reads it. SPARQL's graph is a set of triples, so a
851
+ # repeated key is no error there; what a SPARQL plan may rely on is `keys: trusted` or `keys: check`
852
+ # (`prograph.plan.ir.keys`). Cypher's use returns with Cypher after 1.0 (pre-1.0.0's node_keys.py).
853
+ ON_DUPLICATE_POLICIES = ("refuse", "trust")
854
+
855
+
856
+ class OnDuplicateIgnoredWarning(UserWarning):
857
+ """A mapping states `on_duplicate`, which no 1.0 query reads."""
858
+
859
+
860
+ @home("on-duplicate-keys", "What a key the data breaks does in Cypher (on_duplicate)",
861
+ terms=("on_duplicate", "duplicate key", "repeated key value", "refuse", "trust"))
862
+ def policy_name(value: Any, what: str = "on_duplicate") -> Optional[str]:
863
+ """`value` as an `on_duplicate` policy's name, None for no setting; any other value raises
864
+ ValueError naming the policies there are. A policy set warns that 1.0 does not apply it."""
865
+ if value is None:
866
+ return None
867
+ if isinstance(value, str) and value in ON_DUPLICATE_POLICIES:
868
+ import warnings
869
+ warnings.warn(f"{what}={value!r} has no effect in ProGraph 1.0 (Cypher's policy; SPARQL reads "
870
+ f"keys: trusted or keys: check)", OnDuplicateIgnoredWarning, stacklevel=3)
871
+ return value
872
+ names = ", ".join(repr(n) for n in ON_DUPLICATE_POLICIES)
873
+ raise ValueError(f"{what} is one of {names}; got {value!r}")
874
+
875
+
876
+ class GraphSchema:
877
+ """Complete schema mapping for a virtual graph.
878
+
879
+ Combines node and relationship mappings to define how external
880
+ data sources map to a complete graph structure.
881
+
882
+ For SPARQL support, also includes predicate mappings that map
883
+ RDF predicate IRIs to LPG node properties or relationships.
884
+
885
+ Args:
886
+ default_catalog: Optional Unity Catalog name for qualifying unqualified
887
+ table names in SQL generation. If set, tables like 'persons' become
888
+ 'catalog.schema.persons' in generated SQL.
889
+ default_schema: Optional database schema name, used with default_catalog.
890
+ table_qualifications: Optional explicit mapping of short table names to
891
+ fully qualified names. Takes precedence over default_catalog/default_schema.
892
+ Example: {"accounts": "bg.demo.my_accounts", "payments": "bg.prod.payments_v2"}
893
+ name: Optional name of the graph.
894
+ base_iri: Namespace of synthesized instance IRIs,
895
+ ``{base_iri}{source_table}/{key}``. Defaults to
896
+ ``http://example.org/data/``.
897
+ decimal_text: How a DECIMAL column's value is written in a term, a
898
+ literal's text and an IRI's alike: ``"canonical"`` (the default),
899
+ XML Schema 1.1's canonical form (``1``, ``1.5``; R2RML 10.2); or
900
+ ``"database"``, the database's own text (``1.0``, ``1.50``), as
901
+ Ontop writes it. Under ``"database"`` a DECIMAL key and an INTEGER
902
+ foreign key write different IRIs (``part/1.0``, ``part/1``) and do
903
+ not meet, and a DECIMAL column is read as its text, compared and
904
+ ordered by value (sparql-choices.md D3).
905
+ """
906
+
907
+ def __init__(
908
+ self,
909
+ default_catalog: Optional[str] = None,
910
+ default_schema: Optional[str] = None,
911
+ table_qualifications: Optional[Dict[str, str]] = None,
912
+ name: Optional[str] = None,
913
+ base_iri: Optional[str] = None,
914
+ decimal_text: Optional[str] = None,
915
+ ):
916
+ from prograph.schema.source_map import decimal_text_setting
917
+ self.decimal_text: str = decimal_text_setting(decimal_text)
918
+ self.name = name
919
+ # The namespace of synthesized instance IRIs, `{base_iri}{table}/{key}`.
920
+ # Its one home: every builder and parser of an IRI reads it here
921
+ # (prograph.schema.iri.base_iri_of). Changing it changes every
922
+ # such identity.
923
+ from prograph.schema.iri import DEFAULT_BASE_IRI
924
+ self.base_iri: str = base_iri or DEFAULT_BASE_IRI
925
+ self.node_mappings: List[NodeMapping] = []
926
+ self.relationship_mappings: List[RelationshipMapping] = []
927
+ # One mapping per IRI, for callers that need only a representative. An
928
+ # RDF predicate is global, foaf:name applies to a Person and an
929
+ # Organization alike, so this cannot be the whole story; see
930
+ # _predicate_mappings_by_iri.
931
+ self.predicate_mappings: Dict[str, PredicateMapping] = {} # IRI -> mapping
932
+ # Every mapping declared for an IRI, in declaration order. Resolution
933
+ # picks among them by the subject's label.
934
+ self._predicate_mappings_by_iri: Dict[str, List[PredicateMapping]] = {}
935
+ # The same relation the other way round, LPG element -> declared IRI,
936
+ # so serialization can honor a declaration instead of inventing one.
937
+ self._property_predicate_iris: Dict[Tuple[Optional[str], str], str] = {}
938
+ self._relationship_predicate_iris: Dict[str, str] = {}
939
+ self._prefix_map: Dict[str, str] = {} # prefix -> namespace IRI
940
+ self.default_catalog = default_catalog
941
+ self.default_schema = default_schema
942
+ self.table_qualifications: Dict[str, str] = table_qualifications or {}
943
+ # A YAML source's declared table by the source's name (`sources.<name>.table`), where the
944
+ # mappings name the source: an engine reads it there unless it was given a frame of that name
945
+ # (`apply_declared_tables`).
946
+ self.declared_tables: Dict[str, str] = {}
947
+ # The owned store's MERGE keys, by label (`set_store_keys`; YAML `store: labels: <L>: {key: [...]}`).
948
+ self.store_keys: Dict[str, Tuple[str, ...]] = {}
949
+ self.table_stats: Dict[str, TableStats] = {}
950
+ # Column value types by source table, as the data source reports
951
+ # them (prograph.schema.types). Set by the engine; the SQL
952
+ # translator reads them to get Cypher's type rules right.
953
+ self.column_types: Dict[str, Dict[str, Any]] = {}
954
+ # Degree statistics per relationship mapping (prograph.schema.statistics),
955
+ # for the cost estimate; filled by engine.collect_statistics().
956
+ self.degree_stats: Dict[str, Any] = {}
957
+
958
+ # The attributes a schema's source maps are compiled from: setting one
959
+ # is a new version (`source_maps`). Statistics and column types are not
960
+ # among them.
961
+ _SOURCE_MAP_ATTRIBUTES = frozenset({
962
+ 'name', 'base_iri', 'decimal_text', 'default_catalog', 'default_schema', 'table_qualifications',
963
+ 'node_mappings', 'relationship_mappings', 'predicate_mappings',
964
+ '_predicate_mappings_by_iri', '_property_predicate_iris',
965
+ '_relationship_predicate_iris', '_prefix_map',
966
+ })
967
+
968
+ def __setattr__(self, name: str, value: Any) -> None:
969
+ object.__setattr__(self, name, value)
970
+ if name in GraphSchema._SOURCE_MAP_ATTRIBUTES:
971
+ self._schema_changed()
972
+
973
+ def _schema_changed(self) -> None:
974
+ """A new version of the schema: every mutator calls it, and so does
975
+ setting a mapping's or the schema's attribute the source maps are
976
+ compiled from (invariant I13)."""
977
+ self.__dict__['_version'] = self.__dict__.get('_version', 0) + 1
978
+
979
+ @property
980
+ def version(self) -> int:
981
+ """The schema's version: it changes whenever anything its source
982
+ maps are compiled from does."""
983
+ return self.__dict__.get('_version', 0)
984
+
985
+ def _source_maps_key(self) -> Tuple[Any, ...]:
986
+ """What the cached maps were compiled at: the version, the mappings
987
+ the lists hold (a list changed in place, `node_mappings[:] = ...`,
988
+ sets no attribute) and each one's own version (`_MAPPING_VERSIONS`:
989
+ a mapping this schema shares with another, changed while its
990
+ `_schema` is the other, bumps only the other's version), and the
991
+ table qualifications (changed in place by the engine,
992
+ `table_qualifications.update`)."""
993
+ versions = _MAPPING_VERSIONS
994
+ return (self.version,
995
+ tuple((id(m), versions.get(m, 0)) for m in self.node_mappings),
996
+ tuple((id(m), versions.get(m, 0)) for m in self.relationship_mappings),
997
+ tuple(self.table_qualifications.items()), _store_version(self))
998
+
999
+ def set_store_keys(self, keys: Dict[str, Any]) -> None:
1000
+ """The owned store's MERGE keys (YAML `store: labels: <Label>: {key: [properties]}`): each label's
1001
+ key, a property or a list of properties, whose values give the IRI of a node Cypher's MERGE creates.
1002
+ Every writer must read the same keys, or two engines make two nodes of one key: declare them in the
1003
+ one mapping. A label a node mapping defines is refused (MERGE only matches it)."""
1004
+ out: Dict[str, Tuple[str, ...]] = {}
1005
+ mapped = {m.label for m in self.node_mappings}
1006
+ for label, key in (keys or {}).items():
1007
+ key = [key] if isinstance(key, str) else list(key or ())
1008
+ if not key or not all(isinstance(k, str) and k for k in key):
1009
+ raise ValueError(f"store: labels: {label}: needs key: [properties], the properties MERGE creates "
1010
+ f"a {label} by (set_store_keys({{'{label}': [...]}}) from Python)")
1011
+ if label in mapped:
1012
+ raise ValueError(f"store: labels: {label} is a label a mapping defines: MERGE only matches it, so "
1013
+ f"it needs no store key; remove it from store: labels")
1014
+ out[str(label)] = tuple(key)
1015
+ self.store_keys = out
1016
+
1017
+ def source_maps(self) -> 'SourceMaps':
1018
+ """The schema's source maps (`prograph.schema.compile_schema`),
1019
+ compiled once per version and kept until the schema changes: on
1020
+ NPD's 1,588 node mappings a compile takes about 100 ms, on TPC-H's
1021
+ and LDBC's about 1 ms.
1022
+
1023
+ A version is every mutator, and any attribute set on the schema or
1024
+ on one of its mappings that the maps are compiled from. A dict of a
1025
+ mapping changed in place (`property_columns[name] = column`) is not
1026
+ seen: the mappings are replaced or their attributes set.
1027
+
1028
+ The SPARQL compiler reads node identity and the
1029
+ subjects two maps may share from them."""
1030
+ key = self._source_maps_key()
1031
+ cached = self.__dict__.get('_source_maps')
1032
+ if cached is not None and cached[0] == key:
1033
+ maps = cached[1]
1034
+ else:
1035
+ from prograph.schema.compile_schema import compile_schema
1036
+ from prograph.r2rml.schema import with_included
1037
+ maps = with_included(self, compile_schema(self))
1038
+ self.__dict__['_source_maps'] = (key, maps)
1039
+ return maps
1040
+
1041
+ def _map_positions(self, maps: 'SourceMaps') -> Tuple[Dict[int, int], Dict[int, int]]:
1042
+ """Each node and relationship mapping's position, by its id(), at
1043
+ the version `maps` were compiled from."""
1044
+ positions = self.__dict__.get('_map_positions_at')
1045
+ if positions is None or positions[0] is not maps:
1046
+ positions = (maps, {id(m): i for i, m in enumerate(self.node_mappings)},
1047
+ {id(m): i for i, m in enumerate(self.relationship_mappings)})
1048
+ self.__dict__['_map_positions_at'] = positions
1049
+ return positions[1], positions[2]
1050
+
1051
+ def node_map(self, mapping: NodeMapping) -> Optional['NodeMap']:
1052
+ """The node map `source_maps` compiled from `mapping`, one of this
1053
+ schema's node mappings (by its position, so a second mapping of one
1054
+ label is its own map); None for a mapping the schema does not hold."""
1055
+ maps = self.source_maps()
1056
+ position = self._map_positions(maps)[0].get(id(mapping))
1057
+ if position is None or position >= len(maps.nodes) \
1058
+ or self.node_mappings[position] is not mapping:
1059
+ return None
1060
+ return maps.nodes[position]
1061
+
1062
+ def edge_map(self, mapping: RelationshipMapping) -> Optional['EdgeMap']:
1063
+ """The edge map `source_maps` compiled from `mapping`, one of this
1064
+ schema's relationship mappings; None for one it does not hold."""
1065
+ maps = self.source_maps()
1066
+ position = self._map_positions(maps)[1].get(id(mapping))
1067
+ firsts = [e for e in maps.edges if e.branch_of is None] # a mapping's first branch stands for it
1068
+ if position is None or position >= len(firsts) \
1069
+ or self.relationship_mappings[position] is not mapping:
1070
+ return None
1071
+ return firsts[position]
1072
+
1073
+ def add_node_mapping(self, mapping: NodeMapping) -> None:
1074
+ """Add a node mapping to the schema."""
1075
+ mapping._schema = self
1076
+ self.node_mappings.append(mapping)
1077
+ self._schema_changed()
1078
+
1079
+ def add_relationship_mapping(self, mapping: RelationshipMapping) -> None:
1080
+ """Add a relationship mapping to the schema."""
1081
+ mapping._schema = self
1082
+ self.relationship_mappings.append(mapping)
1083
+ self._schema_changed()
1084
+
1085
+ def get_node_mapping(self, label: str) -> Optional[NodeMapping]:
1086
+ """Get the node mapping for a given label: the first with it.
1087
+
1088
+ Through an index of label to position, kept beside the list: a hit is
1089
+ checked against the list itself (the same position holds the label),
1090
+ and the index is rebuilt when the list was replaced, grew or shrank,
1091
+ or on a miss. A scan per lookup made planning cubic in the number of
1092
+ mappings: an untyped node over the NPD benchmark's 1588 took minutes."""
1093
+ mappings = self.node_mappings
1094
+ index = self.__dict__.get("_label_positions")
1095
+ if index is not None and index[0] is mappings and index[1] == len(mappings):
1096
+ position = index[2].get(label)
1097
+ if position is not None and mappings[position].label == label:
1098
+ return mappings[position]
1099
+ positions: Dict[str, int] = {}
1100
+ for position, mapping in enumerate(mappings):
1101
+ positions.setdefault(mapping.label, position)
1102
+ self.__dict__["_label_positions"] = (mappings, len(mappings), positions)
1103
+ position = positions.get(label)
1104
+ return mappings[position] if position is not None else None
1105
+
1106
+ def get_relationship_mappings(self, rel_type: str) -> List[RelationshipMapping]:
1107
+ """Get all relationship mappings for a given type.
1108
+
1109
+ Use this when a relationship type can connect different node types.
1110
+ For example, KNOWS might connect Person-Person and Person-Organization.
1111
+
1112
+ Args:
1113
+ rel_type: The relationship type to look up
1114
+
1115
+ Returns:
1116
+ List of all RelationshipMappings with this rel_type (may be empty)
1117
+ """
1118
+ return [m for m in self.relationship_mappings if m.rel_type == rel_type]
1119
+
1120
+ def labels_share_rows(self, label: Optional[str], other: Optional[str]) -> bool:
1121
+ """Whether a node found under `label` can be a node of `other`'s
1122
+ mapping: the same label, or the same table and key (a discriminated
1123
+ subclass, Bearing within Component). A relationship mapped from
1124
+ `other` then applies to it, as it does on the Python path."""
1125
+ if label is None or other is None or label == other:
1126
+ return True
1127
+ return _mappings_share_rows(self.get_node_mapping(label), self.get_node_mapping(other))
1128
+
1129
+ @home("first-mapping", "Relationship mappings that fit a pattern",
1130
+ terms=("candidates", "relationship mapping", "direction", "labels_share_rows", "rows_within", "pattern"))
1131
+ def candidates(self, rel_types, direction, near: Optional[str] = None,
1132
+ far: Optional[str] = None) -> List[Candidate]:
1133
+ """Every way a relationship pattern can match: each mapping of the
1134
+ pattern's types, in each orientation its direction allows, whose
1135
+ two labels fit the pattern's.
1136
+
1137
+ The one rule for which mappings answer `(near)-[:T]->(far)`. A
1138
+ caller joins one candidate, unions several, and takes none to mean
1139
+ the pattern matches nothing; it never picks the first of several
1140
+ (docs/architecture/rules.md, "Relationship mappings that fit a
1141
+ pattern").
1142
+
1143
+ Args:
1144
+ rel_types: The pattern's relationship types. Empty or None:
1145
+ any type.
1146
+ direction: 'outgoing', 'incoming' or 'undirected', as the
1147
+ pattern is written from its near node (a
1148
+ RelationshipDirection is taken by its name).
1149
+ near: The near node's label, or None when it has none.
1150
+ far: The far node's label, or None when it has none.
1151
+
1152
+ A pattern label fits a mapping's when `labels_share_rows` says so:
1153
+ the same label, or the same table and key with row filters that
1154
+ can both hold.
1155
+
1156
+ An undirected pattern over a mapping whose two labels both fit both
1157
+ ends (Person KNOWS Person) yields that mapping twice, forward and
1158
+ reversed. An edge from a node to itself then matches both, so a
1159
+ caller that unions the two must count it once; a pattern test
1160
+ (EXISTS) needs no such care.
1161
+
1162
+ Candidates come in declaration order, forward before reversed. The
1163
+ order carries no meaning.
1164
+ """
1165
+ name = str(getattr(direction, 'name', direction)).lower()
1166
+ if name in ('outgoing', 'right'):
1167
+ orientations = (True,)
1168
+ elif name in ('incoming', 'left'):
1169
+ orientations = (False,)
1170
+ elif name in ('undirected', 'both'):
1171
+ orientations = (True, False)
1172
+ else:
1173
+ raise ValueError(
1174
+ f"direction must be 'outgoing', 'incoming' or 'undirected'; got {direction!r}")
1175
+ types = set(rel_types or ())
1176
+ found: List[Candidate] = []
1177
+ for position, mapping in enumerate(self.relationship_mappings):
1178
+ if types and mapping.rel_type not in types:
1179
+ continue
1180
+ fits = []
1181
+ for forward in orientations:
1182
+ near_label = mapping.start_node_label if forward else mapping.end_node_label
1183
+ far_label = mapping.end_node_label if forward else mapping.start_node_label
1184
+ if self.labels_share_rows(near, near_label) and self.labels_share_rows(far, far_label):
1185
+ fits.append(Candidate(mapping, forward, near_label, far_label))
1186
+ if not fits:
1187
+ continue
1188
+ found.extend(fits)
1189
+ return found
1190
+
1191
+ def describe(self) -> "SchemaDescriptor":
1192
+ """Return a frozen, serializable description of this schema.
1193
+
1194
+ The returned ``SchemaDescriptor`` is safe to share with LLMs, MCP
1195
+ tools, or any consumer that needs a JSON-compatible view of the
1196
+ schema without live DataFrame references.
1197
+ """
1198
+ from prograph.schema.context import describe_schema
1199
+ return describe_schema(self)
1200
+
1201
+ # ========== Table Stats ==========
1202
+
1203
+ def set_table_stats(
1204
+ self,
1205
+ table: str,
1206
+ row_count: Optional[int] = None,
1207
+ size_bytes: Optional[int] = None,
1208
+ ) -> None:
1209
+ """Set statistics for a source table.
1210
+
1211
+ Args:
1212
+ table: Table name (short or fully qualified)
1213
+ row_count: Number of rows in the table
1214
+ size_bytes: Size of the table in bytes
1215
+ """
1216
+ self.table_stats[table] = TableStats(
1217
+ row_count=row_count,
1218
+ size_bytes=size_bytes,
1219
+ )
1220
+
1221
+ def get_table_stats(self, table: str) -> Optional[TableStats]:
1222
+ """Get statistics for a source table.
1223
+
1224
+ Tries exact match first, then checks if the short table name
1225
+ (last segment after dots) matches any stored entry.
1226
+
1227
+ Args:
1228
+ table: Table name to look up
1229
+
1230
+ Returns:
1231
+ TableStats if found, None otherwise
1232
+ """
1233
+ if table in self.table_stats:
1234
+ return self.table_stats[table]
1235
+ # Try matching by short name (last segment after dots)
1236
+ short_name = table.split('.')[-1]
1237
+ for key, stats in self.table_stats.items():
1238
+ if key.split('.')[-1] == short_name:
1239
+ return stats
1240
+ return None
1241
+
1242
+ # ========== Named Graph Support ==========
1243
+
1244
+ def get_node_mappings_for_graph(self, graph_iri: str) -> List[NodeMapping]:
1245
+ """Get node mappings that belong to a named graph.
1246
+
1247
+ A mapping matches if its ``graph_iri`` equals the given IRI.
1248
+ Mappings without a ``graph_iri`` are not included (they belong
1249
+ to the default graph).
1250
+
1251
+ Args:
1252
+ graph_iri: The named graph IRI to filter by
1253
+
1254
+ Returns:
1255
+ List of matching NodeMappings
1256
+ """
1257
+ return [
1258
+ m for m in self.node_mappings
1259
+ if m.graph_iri == graph_iri
1260
+ ]
1261
+
1262
+ def get_relationship_mappings_for_graph(
1263
+ self, graph_iri: str
1264
+ ) -> List[RelationshipMapping]:
1265
+ """Get relationship mappings that belong to a named graph.
1266
+
1267
+ Args:
1268
+ graph_iri: The named graph IRI to filter by
1269
+
1270
+ Returns:
1271
+ List of matching RelationshipMappings
1272
+ """
1273
+ return [
1274
+ m for m in self.relationship_mappings
1275
+ if m.graph_iri == graph_iri
1276
+ ]
1277
+
1278
+ def get_default_graph_node_mappings(self) -> List[NodeMapping]:
1279
+ """Get node mappings in the default graph (no named graph assigned).
1280
+
1281
+ In SPARQL semantics, the default graph is the union of all
1282
+ triples not in a named graph, plus all named graphs if no
1283
+ FROM clause restricts the dataset.
1284
+
1285
+ Returns:
1286
+ All node mappings (default graph = union of all)
1287
+ """
1288
+ return list(self.node_mappings)
1289
+
1290
+ # ========== SPARQL/RDF Predicate Support ==========
1291
+
1292
+ def add_prefix(self, prefix: str, namespace: str) -> None:
1293
+ """Register a namespace prefix for IRI resolution.
1294
+
1295
+ Args:
1296
+ prefix: The prefix (e.g., "ex", "foaf")
1297
+ namespace: The full namespace IRI (e.g., "http://example.org/")
1298
+ """
1299
+ self._prefix_map[prefix] = namespace
1300
+ self._schema_changed()
1301
+
1302
+ @property
1303
+ def prefixes(self) -> Dict[str, str]:
1304
+ """The registered prefixes, prefix to namespace IRI (a copy)."""
1305
+ return dict(self._prefix_map)
1306
+
1307
+ @property
1308
+ def source_queries(self) -> Dict[str, str]:
1309
+ """Source name to SQL query, for each mapping whose source is a
1310
+ query (`TableMapping.source_query`, an R2RML view): the frames a
1311
+ DataFrame backend computes for its Python executor."""
1312
+ return {m.source_table: m.source_query
1313
+ for m in list(self.node_mappings) + list(self.relationship_mappings)
1314
+ if getattr(m, 'source_query', None)}
1315
+
1316
+ def add_predicate_mapping(self, mapping: PredicateMapping) -> None:
1317
+ """Add a predicate mapping for SPARQL support.
1318
+
1319
+ Args:
1320
+ mapping: The PredicateMapping to add
1321
+ """
1322
+ declared = self._predicate_mappings_by_iri.setdefault(mapping.predicate_iri, [])
1323
+ if mapping.kind == PredicateKind.OBJECT:
1324
+ # An object predicate is one relationship type; a pair of classes
1325
+ # it also connects is a mapping of that type (LIKES from a Person
1326
+ # to a Post, and to a Comment), which every reader handles.
1327
+ other = next((d.relationship_type for d in declared
1328
+ if d.kind == PredicateKind.OBJECT
1329
+ and d.relationship_type != mapping.relationship_type), None)
1330
+ if other is not None:
1331
+ raise ValueError(
1332
+ f"Predicate <{mapping.predicate_iri}> already maps to relationship type "
1333
+ f"{other}; it cannot also map to {mapping.relationship_type}. Map it to "
1334
+ f"one type and give that type a RelationshipMapping per pair of classes.")
1335
+ if not any(_same_predicate_target(mapping, existing) for existing in declared):
1336
+ declared.append(mapping)
1337
+ # First declaration is the representative; a later one for a different
1338
+ # label is an addition, not a replacement. It used to overwrite, so
1339
+ # declaring foaf:name for Person and then Organization silently lost
1340
+ # Person.
1341
+ self.predicate_mappings.setdefault(mapping.predicate_iri, mapping)
1342
+ self._index_predicate_mapping(mapping)
1343
+ self._schema_changed()
1344
+
1345
+ def _index_predicate_mapping(self, mapping: PredicateMapping) -> None:
1346
+ """Record the LPG -> IRI direction of a predicate mapping.
1347
+
1348
+ `predicate_mappings` answers "given this IRI, what do I match?", which is what
1349
+ a SPARQL query needs. Serializing to RDF needs the opposite: "given this
1350
+ column, what predicate do I emit?" Both directions are the same
1351
+ relation, so they are maintained together rather than left to be
1352
+ reinvented by whoever needs the reverse (which is how the bridge came to
1353
+ synthesize its own predicate IRIs, ignoring declarations entirely).
1354
+
1355
+ First declaration wins: re-registering an equivalent mapping is
1356
+ idempotent, and a genuinely different one does not silently displace the
1357
+ binding an ontology already established.
1358
+ """
1359
+ if mapping.kind == PredicateKind.DATATYPE:
1360
+ key = (mapping.node_label, mapping.property_name)
1361
+ self._property_predicate_iris.setdefault(key, mapping.predicate_iri)
1362
+ elif mapping.kind == PredicateKind.OBJECT:
1363
+ self._relationship_predicate_iris.setdefault(
1364
+ mapping.relationship_type, mapping.predicate_iri
1365
+ )
1366
+
1367
+ def find_predicate_iri_for_property(
1368
+ self, label: Optional[str], property_name: str
1369
+ ) -> Optional[str]:
1370
+ """The declared predicate IRI for a datatype property, if any.
1371
+
1372
+ Looks for a mapping declared against this label first, then one declared
1373
+ without a label, a predicate registered generically still names the
1374
+ property, and preferring the labelled one keeps the more specific
1375
+ declaration authoritative. Between the two, a declaration for a label
1376
+ whose nodes hold every node of this one and read the property from
1377
+ the same column (Person within Resource, Bearing within Component,
1378
+ `rows_within`): the value is that label's triple, not a second one
1379
+ under another IRI. A label of other rows (Car beside a declaration
1380
+ for Person) has none, and keeps its own IRI.
1381
+ """
1382
+ iri = self._property_predicate_iris.get((label, property_name))
1383
+ if iri:
1384
+ return iri
1385
+ own = self.get_node_mapping(label) if label is not None else None
1386
+ if own is not None and property_name in own.property_columns:
1387
+ for (declared_for, prop), declared in self._property_predicate_iris.items():
1388
+ other = self.get_node_mapping(declared_for) if declared_for else None
1389
+ if (prop == property_name and other is not None and other is not own
1390
+ and other.property_columns.get(prop) == own.property_columns[prop]
1391
+ and rows_within(own, other)):
1392
+ return declared
1393
+ return self._property_predicate_iris.get((None, property_name))
1394
+
1395
+ def find_predicate_iri_for_relationship(self, rel_type: str) -> Optional[str]:
1396
+ """The declared predicate IRI for a relationship type, if any."""
1397
+ return self._relationship_predicate_iris.get(rel_type)
1398
+
1399
+ def find_predicate_mapping_for_property(
1400
+ self, label: Optional[str], property_name: str
1401
+ ) -> Optional[PredicateMapping]:
1402
+ """The declared mapping for a datatype property, if any.
1403
+
1404
+ The mapping carries more than its IRI, the literal's datatype or
1405
+ language tag come from it too, so serialization needs the object, not
1406
+ just the name.
1407
+ """
1408
+ iri = self.find_predicate_iri_for_property(label, property_name)
1409
+ return self.predicate_mappings.get(iri) if iri else None
1410
+
1411
+ @staticmethod
1412
+ def _names_of_mapping(mapping: Any) -> Set[str]:
1413
+ """The names a row of `mapping` answers: its
1414
+ properties and key columns; for a node also the columns of its IRI
1415
+ template and `id`."""
1416
+ names = set(mapping.property_columns or {})
1417
+ if isinstance(mapping, NodeMapping):
1418
+ names |= set(mapping.id_columns) | {'id'}
1419
+ if mapping.iri_template:
1420
+ from prograph.schema.iri import template_columns
1421
+ names |= set(template_columns(mapping.iri_template))
1422
+ else:
1423
+ names |= set(mapping.start_id_columns) | set(mapping.end_id_columns)
1424
+ return names
1425
+
1426
+ def declared_names(self, kind: str, among: Optional[Sequence[str]] = None,
1427
+ write: bool = False,
1428
+ resolve: Optional[Callable[[str, List[str]], Set[str]]] = None,
1429
+ alternatives: bool = False) -> Set[str]:
1430
+ """The names the schema declares: the one home
1431
+ of the sets `require_name` and the query's name check ask about.
1432
+
1433
+ kind 'label' and 'relationship_type': every mapped one. kind
1434
+ 'property': what a node of the labels `among` can have, with
1435
+ `write` what every node of them can hold. kind
1436
+ 'relationship_property': what a relationship of the types `among`
1437
+ can have. `among` empty or None is every mapping. `resolve(kind,
1438
+ names)` gives the mapped labels or types an ontology resolves names
1439
+ to (a class to its mapped subclasses, a property to its mapped
1440
+ sub-properties); the schema itself knows no ontology.
1441
+
1442
+ A read takes the mappings of the labels, of what they resolve to, and
1443
+ of every label sharing their rows. A write takes, for each label, its
1444
+ own mapping, or what every mapping it resolves to declares; with no
1445
+ label, what every node mapping declares, since the node can be any.
1446
+ With `alternatives` the labels are a node's possible labels, not all
1447
+ of its labels (`WHERE n:A OR n:B`, which ontology expansion writes
1448
+ for a class): a read takes them all the same, a write what each of
1449
+ them can hold."""
1450
+ def resolved(k, names):
1451
+ out = set(names)
1452
+ if resolve is not None and names:
1453
+ out |= set(resolve(k, list(names)))
1454
+ return out
1455
+ if kind == 'label':
1456
+ return {m.label for m in self.node_mappings if m.label is not None}
1457
+ if kind == 'relationship_type':
1458
+ return {m.rel_type for m in self.relationship_mappings}
1459
+ if kind == 'relationship_property':
1460
+ types = resolved('relationship_type', among or [])
1461
+ mappings = [m for m in self.relationship_mappings if not types or m.rel_type in types]
1462
+ return set().union(*(self._names_of_mapping(m) for m in mappings))
1463
+ if kind != 'property':
1464
+ raise ValueError(f"unknown name kind {kind!r}")
1465
+ labels = list(among or [])
1466
+ if write and alternatives and len(labels) > 1:
1467
+ return set.intersection(*(self.declared_names(kind, [label], write=True, resolve=resolve)
1468
+ for label in labels))
1469
+ if write:
1470
+ def common(mappings):
1471
+ sets = [self._names_of_mapping(m) for m in mappings]
1472
+ return set.intersection(*sets) if sets else set()
1473
+ if not labels:
1474
+ return common(self.node_mappings)
1475
+ names: Set[str] = set()
1476
+ for label in labels:
1477
+ mapping = self.get_node_mapping(label)
1478
+ if mapping is not None:
1479
+ names |= self._names_of_mapping(mapping)
1480
+ else:
1481
+ names |= common([m for m in self.node_mappings
1482
+ if m.label in resolved('label', [label]) - {label}])
1483
+ return names
1484
+ if not labels:
1485
+ mappings = list(self.node_mappings)
1486
+ else:
1487
+ wanted = resolved('label', labels)
1488
+ mappings = [m for m in self.node_mappings
1489
+ if any(m.label == w or self.labels_share_rows(w, m.label) for w in wanted)]
1490
+ return set().union(*(self._names_of_mapping(m) for m in mappings))
1491
+
1492
+ def require_name(self, kind: str, name: str, label: Optional[str] = None, *,
1493
+ among: Optional[Sequence[str]] = None, write: bool = False,
1494
+ resolve: Optional[Callable[[str, List[str]], Set[str]]] = None,
1495
+ alternatives: bool = False) -> str:
1496
+ """`name` if the schema declares it, else UnknownNameError: the one check for a name a caller or a query puts in
1497
+ front of the schema, since labels, relationship types and property
1498
+ names cannot be query parameters (prograph.parameters). kind is
1499
+ 'label', 'relationship_type', 'property' (of the labels `among`, or
1500
+ of `label`, or of any label) or 'relationship_property' (of the
1501
+ types `among`); `write`, `resolve` and `alternatives` as in
1502
+ `declared_names`. A
1503
+ label or type that `resolve` takes to a mapped one is declared."""
1504
+ import difflib
1505
+ from prograph.utils.exceptions import UnknownNameError
1506
+ labels = list(among) if among is not None else ([label] if label else [])
1507
+ known = self.declared_names(kind, labels, write=write, resolve=resolve,
1508
+ alternatives=alternatives)
1509
+ if isinstance(name, str) and name in known:
1510
+ return name
1511
+ if kind in ('label', 'relationship_type') and resolve is not None and isinstance(name, str):
1512
+ if set(resolve(kind, [name])) & known:
1513
+ return name
1514
+ nearest = difflib.get_close_matches(str(name), sorted(known), n=3, cutoff=0.6)
1515
+ declared_by: List[str] = []
1516
+ if kind in ('property', 'relationship_property'):
1517
+ owners = (self.node_mappings if kind == 'property' else self.relationship_mappings)
1518
+ declared_by = sorted({getattr(m, 'label', None) or m.rel_type for m in owners
1519
+ if name in self._names_of_mapping(m)} - set(labels))
1520
+ raise UnknownNameError(str(name), 'property' if kind == 'relationship_property' else kind,
1521
+ nearest=nearest, labels=labels, declared_by=declared_by)
1522
+
1523
+ def column_names(self) -> Set[str]:
1524
+ """Every column name a mapped table has, in lower case: those the
1525
+ data source recorded (`column_types`, every column of the table,
1526
+ mapped or not) and those the mappings name (keys, ends,
1527
+ properties). A database that folds case reads a bare name equal to
1528
+ any of them, in a SELECT that holds the table, as that column too
1529
+ (`names_kept_apart`)."""
1530
+ names = {str(c).lower() for columns in self.column_types.values() for c in columns}
1531
+ for m in self.node_mappings:
1532
+ names.update(str(c).lower() for c in m.id_columns)
1533
+ names.update(str(c).lower() for c in m.property_columns.values())
1534
+ for m in self.relationship_mappings:
1535
+ names.update(str(c).lower() for c in m.start_id_columns + m.end_id_columns)
1536
+ names.update(str(c).lower() for c in m.property_columns.values())
1537
+ return names
1538
+
1539
+ @home("column-type", "A mapped column's recorded type",
1540
+ terms=("column type", "column_types", "table_column_type", "recorded type"))
1541
+ def column_type(self, mapping: Any, column: str) -> Optional[Any]:
1542
+ """The recorded type of a mapping's column (`column_types`, a
1543
+ prograph.schema.types.CypherType), or None when the data source
1544
+ gave none. Oracle keeps an unquoted column's name in upper case
1545
+ (PID for a mapping's pid), so a name that differs only in case is
1546
+ the column when exactly one does."""
1547
+ return self.table_column_type(mapping.source_table, column)
1548
+
1549
+ def table_column_type(self, table: str, column: str) -> Optional[Any]:
1550
+ """`column_type` by the table's authored name (`source_table`, a
1551
+ source map's `Source.table`)."""
1552
+ types = self.column_types.get(table, {})
1553
+ if column in types:
1554
+ return types[column]
1555
+ folded = [t for name, t in types.items() if name.lower() == str(column).lower()]
1556
+ return folded[0] if len(folded) == 1 else None
1557
+
1558
+ def check_language_columns(self) -> None:
1559
+ """Refuse a PredicateMapping whose `language_column` its node's
1560
+ table does not have, by name, once the table's columns are recorded
1561
+ (`column_types`; a table whose columns were not read is not
1562
+ checked). Unchecked, every literal of the predicate lost its tag
1563
+ without a word."""
1564
+ for mapping in self.node_mappings:
1565
+ types = self.column_types.get(mapping.source_table)
1566
+ if not types:
1567
+ continue
1568
+ held = {str(name).lower() for name in types}
1569
+ for column in mapping.language_columns.values():
1570
+ if str(column).lower() not in held:
1571
+ predicates = sorted(
1572
+ pm.predicate_iri for declared in self._predicate_mappings_by_iri.values()
1573
+ for pm in declared if pm.language_column == column)
1574
+ raise ValueError(
1575
+ f"PredicateMapping <{predicates[0]}> names language_column "
1576
+ f"{column!r}, which table {mapping.source_table!r} of label "
1577
+ f"{mapping.label!r} does not have; its columns are "
1578
+ f"{sorted(types)}.")
1579
+ # And the source maps' own language columns: a generated mapping (no authoring objects) is
1580
+ # checked alike.
1581
+ from prograph.plan.ir.entry import source_maps
1582
+ try:
1583
+ maps = source_maps(self)
1584
+ except Exception: # noqa: BLE001 - a schema the one plan does not read is checked elsewhere
1585
+ return
1586
+ for node in maps.nodes:
1587
+ types = self.column_types.get(node.source.table)
1588
+ if not types:
1589
+ continue
1590
+ held = {str(name).lower() for name in types}
1591
+ for po in node.predicate_objects:
1592
+ column = po.object.language_column
1593
+ if column is not None and str(column).lower() not in held:
1594
+ raise ValueError(
1595
+ f"PredicateMapping <{po.predicate}> names language_column "
1596
+ f"{column!r}, which table {node.source.table!r} of label "
1597
+ f"{node.label or node.id!r} does not have; its columns are "
1598
+ f"{sorted(types)}.")
1599
+
1600
+ def resolve_prefixed_name(self, prefixed_name: str) -> Optional[str]:
1601
+ """Resolve a prefixed name (e.g., 'ex:name') to a full IRI.
1602
+
1603
+ Args:
1604
+ prefixed_name: A prefixed name like 'ex:name' or ':name'
1605
+
1606
+ Returns:
1607
+ The full IRI, or None if prefix not found
1608
+ """
1609
+ if ':' not in prefixed_name:
1610
+ return None
1611
+
1612
+ prefix, local = prefixed_name.split(':', 1)
1613
+ namespace = self._prefix_map.get(prefix)
1614
+ if namespace:
1615
+ return namespace + local
1616
+ return None
1617
+
1618
+ def predicate_declarations(self, predicate_iri: str) -> List[PredicateMapping]:
1619
+ """Every declaration of a predicate IRI, one per class it is declared
1620
+ for (foaf:name for a Person and an Organization), in order."""
1621
+ return list(self._predicate_mappings_by_iri.get(predicate_iri, []))
1622
+
1623
+ # ========== Schema Mutation ==========
1624
+
1625
+ def remove_node_mapping(self, label: str) -> Optional[NodeMapping]:
1626
+ """Remove node mapping by label.
1627
+
1628
+ Raises ValueError if any relationship mapping references this label
1629
+ as a start or end node.
1630
+
1631
+ Args:
1632
+ label: The node label to remove
1633
+
1634
+ Returns:
1635
+ The removed NodeMapping, or None if not found
1636
+
1637
+ Raises:
1638
+ ValueError: If a relationship mapping depends on this label
1639
+ """
1640
+ # Check for dependent relationships
1641
+ dependents = [
1642
+ m for m in self.relationship_mappings
1643
+ if m.start_node_label == label or m.end_node_label == label
1644
+ ]
1645
+ if dependents:
1646
+ rel_types = [m.rel_type for m in dependents]
1647
+ raise ValueError(
1648
+ f"Cannot remove node label '{label}': referenced by "
1649
+ f"relationship mapping(s): {rel_types}"
1650
+ )
1651
+
1652
+ for i, m in enumerate(self.node_mappings):
1653
+ if m.label == label:
1654
+ removed = self.node_mappings.pop(i)
1655
+ self._schema_changed()
1656
+ # Clean up table stats for the removed table
1657
+ if removed.source_table in self.table_stats:
1658
+ del self.table_stats[removed.source_table]
1659
+ return removed
1660
+ return None
1661
+
1662
+ def remove_relationship_mapping(
1663
+ self,
1664
+ rel_type: str,
1665
+ start_label: Optional[str] = None,
1666
+ end_label: Optional[str] = None,
1667
+ ) -> List[RelationshipMapping]:
1668
+ """Remove relationship mapping(s) by type, optionally filtered by endpoints.
1669
+
1670
+ Args:
1671
+ rel_type: The relationship type to remove
1672
+ start_label: If given, only remove mappings with this start label
1673
+ end_label: If given, only remove mappings with this end label
1674
+
1675
+ Returns:
1676
+ List of removed RelationshipMappings (may be empty)
1677
+ """
1678
+ removed = []
1679
+ remaining = []
1680
+ for m in self.relationship_mappings:
1681
+ if m.rel_type == rel_type:
1682
+ if start_label and m.start_node_label != start_label:
1683
+ remaining.append(m)
1684
+ continue
1685
+ if end_label and m.end_node_label != end_label:
1686
+ remaining.append(m)
1687
+ continue
1688
+ removed.append(m)
1689
+ else:
1690
+ remaining.append(m)
1691
+ self.relationship_mappings = remaining
1692
+ return removed
1693
+
1694
+ def replace_node_mapping(self, mapping: NodeMapping) -> Optional[NodeMapping]:
1695
+ """Replace existing node mapping for the same label.
1696
+
1697
+ If no mapping exists for the label, adds it as new.
1698
+
1699
+ Args:
1700
+ mapping: The new NodeMapping (matched by label)
1701
+
1702
+ Returns:
1703
+ The old NodeMapping that was replaced, or None if added as new
1704
+ """
1705
+ mapping._schema = self
1706
+ for i, m in enumerate(self.node_mappings):
1707
+ if m.label == mapping.label:
1708
+ old = self.node_mappings[i]
1709
+ self.node_mappings[i] = mapping
1710
+ self._schema_changed()
1711
+ return old
1712
+ # No existing mapping, add as new
1713
+ self.node_mappings.append(mapping)
1714
+ self._schema_changed()
1715
+ return None
1716
+
1717
+ def auto_generate_predicate_mappings(
1718
+ self, namespace: str = DEFAULT_VOCAB_IRI, ontology=None
1719
+ ) -> None:
1720
+ """Auto-generate predicate mappings from node/relationship mappings.
1721
+
1722
+ Creates PredicateMappings so SPARQL predicates resolve to the schema:
1723
+ - Each node property → DATATYPE predicate (``{namespace}{property}``)
1724
+ - Each relationship type → OBJECT predicate
1725
+ (``{namespace}{camelCasedRelType}``, ``WORKS_AT`` → ``worksAt``)
1726
+
1727
+ The spellings come from :mod:`prograph.schema.iri`, the same convention
1728
+ the SPARQL graph falls back to, so generated predicates and serialized
1729
+ ones are the same IRIs rather than two conventions that happen to look
1730
+ alike. Point ``namespace`` at your ontology and the generated object
1731
+ predicates *are* the ontology's, which is what the ``ontology``
1732
+ argument below used to be needed for.
1733
+
1734
+ Args:
1735
+ namespace: IRI namespace for generated predicates. Pass your
1736
+ ontology's namespace so SPARQL predicates like
1737
+ ``aw:name`` resolve. The default is the default vocabulary,
1738
+ :data:`prograph.schema.iri.DEFAULT_VOCAB_IRI`, the namespace
1739
+ of the default class IRIs, so a schema built with defaults
1740
+ publishes ``ont:name`` beside ``ont:Person`` (rules.md, "Node and class IRIs").
1741
+ ontology: Optional :class:`~prograph.ontology.OntologyLayer`. When
1742
+ given, each object property's *actual* IRI is also mapped to
1743
+ its relationship type, so a SPARQL query can traverse with the
1744
+ natural ontology predicate (e.g. ``aw:productInSubcategory``)
1745
+ rather than the lowercased rel-type spelling.
1746
+ """
1747
+ from prograph.schema.iri import (
1748
+ default_property_iri,
1749
+ default_relationship_iri,
1750
+ )
1751
+
1752
+ # Generate datatype predicates from node properties. A property
1753
+ # several labels have names no one label: `ex:name` is the name of
1754
+ # whatever has one, so its mapping carries no node_label (stamping
1755
+ # the first label made an untyped ?p ex:name ?n return only that
1756
+ # label's values).
1757
+ labels_with: Dict[str, set] = {}
1758
+ for node_mapping in self.node_mappings:
1759
+ for prop_name in node_mapping.property_columns:
1760
+ labels_with.setdefault(prop_name, set()).add(node_mapping.label)
1761
+ for node_mapping in self.node_mappings:
1762
+ for prop_name in node_mapping.property_columns.keys():
1763
+ iri = default_property_iri(prop_name, namespace)
1764
+ if iri not in self.predicate_mappings:
1765
+ self.add_predicate_mapping(PredicateMapping(
1766
+ predicate_iri=iri,
1767
+ kind=PredicateKind.DATATYPE,
1768
+ node_label=(node_mapping.label if len(labels_with[prop_name]) == 1
1769
+ else None),
1770
+ property_name=prop_name
1771
+ ))
1772
+
1773
+ # Generate object predicates from relationships
1774
+ for rel_mapping in self.relationship_mappings:
1775
+ iri = default_relationship_iri(rel_mapping.rel_type, namespace)
1776
+ if iri not in self.predicate_mappings:
1777
+ self.add_predicate_mapping(PredicateMapping(
1778
+ predicate_iri=iri,
1779
+ kind=PredicateKind.OBJECT,
1780
+ relationship_type=rel_mapping.rel_type
1781
+ ))
1782
+
1783
+ # Map each ontology object property's own IRI to its relationship type,
1784
+ # so SPARQL can traverse with the natural ontology predicate.
1785
+ if ontology is not None:
1786
+ from prograph.schema.naming import resolve_rel_type
1787
+ for prop in getattr(ontology, "properties", {}).values():
1788
+ rel = resolve_rel_type(prop.name, (m.rel_type for m in self.relationship_mappings))
1789
+ if rel is None:
1790
+ continue
1791
+ iri = getattr(prop, "uri", None)
1792
+ if iri and iri not in self.predicate_mappings:
1793
+ self.add_predicate_mapping(PredicateMapping(
1794
+ predicate_iri=iri,
1795
+ kind=PredicateKind.OBJECT,
1796
+ relationship_type=rel,
1797
+ ))
1798
+
1799
+
1800
+ def _store_version(schema: GraphSchema) -> Any:
1801
+ """The attached owned store's version (`prograph.r2rml.schema.store_version`)."""
1802
+ from prograph.r2rml.schema import store_version
1803
+ return store_version(schema)