Skip to content

Graph-Native Infrastructure for Context and Accountable AI Systems

fix(export): keep backend endpoint names in LPG relationship export (#2058)

Tymur0747f53d7e57
diff --git a/semantica/export/endpoint_names.py b/semantica/export/endpoint_names.py
index 95c0b17b..e6274ff2 100644
--- a/semantica/export/endpoint_names.py
+++ b/semantica/export/endpoint_names.py
@@ -49,6 +49,15 @@ ENDPOINT_ALIASES: Dict[str, Tuple[str, ...]] = {
}
+def is_unset_id(value: Any) -> bool:
+ """Whether an id value counts as missing: ``None`` or ``""`` (#2018).
+
+ A reader then tries the next accepted name. Anything else, ``0`` included,
+ is a real id.
+ """
+ return value is None or value == ""
+
+
def has_endpoints(sample: Dict[str, Any]) -> bool:
"""Whether a record carries both ends of a relationship, under any name."""
return any(k in sample for k in SOURCE_ENDPOINT_NAMES) and any(
@@ -60,8 +69,11 @@ def canonical_endpoints(records: Any) -> Any:
"""Return ``records`` with relationship endpoints under their canonical keys.
Records that already carry ``source_id``/``target_id`` are returned
- untouched, as are non-dict records. The original list is returned when
- nothing needed adding, so callers that pass a canonical graph pay nothing.
+ untouched, as are non-dict records. An unset canonical value (see
+ ``is_unset_id``) takes the first set alias, so ``source_id=""`` next to
+ ``start_node_id="alice"`` becomes ``source_id="alice"``. The original list
+ is returned when nothing needed adding, so callers that pass a canonical
+ graph pay nothing.
"""
if not isinstance(records, list):
return records
@@ -75,10 +87,10 @@ def canonical_endpoints(records: Any) -> Any:
resolved: Dict[str, Any] = {}
for canonical, aliases in ENDPOINT_ALIASES.items():
- if record.get(canonical) is not None:
+ if not is_unset_id(record.get(canonical)):
continue
for alias in aliases:
- if record.get(alias) is not None:
+ if not is_unset_id(record.get(alias)):
resolved[canonical] = record[alias]
break
diff --git a/semantica/export/lpg_exporter.py b/semantica/export/lpg_exporter.py
index 06ac4554..3ec9ac19 100644
--- a/semantica/export/lpg_exporter.py
+++ b/semantica/export/lpg_exporter.py
@@ -27,6 +27,7 @@ from ..utils.exceptions import ProcessingError, ValidationError
from ..utils.helpers import _require_mapping, ensure_directory, normalize_graph_payload
from ..utils.logging import get_logger
from ..utils.progress_tracker import get_progress_tracker
+from .endpoint_names import SOURCE_ENDPOINT_NAMES, TARGET_ENDPOINT_NAMES, is_unset_id
class LPGExporter:
@@ -233,7 +234,14 @@ class LPGExporter:
lines = []
for idx, node in enumerate(nodes):
- node_id = node.get("id") or node.get("entity_id", f"node_{idx}")
+ node_id = next(
+ (
+ node[key]
+ for key in ("id", "entity_id")
+ if not is_unset_id(node.get(key))
+ ),
+ f"node_{idx}",
+ )
node_type = node.get("type") or node.get("entity_type", "Entity")
label = node.get("label") or node.get("name") or node.get("text", "")
@@ -285,11 +293,25 @@ class LPGExporter:
lines = []
for idx, edge in enumerate(edges):
- source_id = edge.get("source") or edge.get("source_id")
- target_id = edge.get("target") or edge.get("target_id")
+ source_id = next(
+ (
+ edge[key]
+ for key in SOURCE_ENDPOINT_NAMES
+ if not is_unset_id(edge.get(key))
+ ),
+ None,
+ )
+ target_id = next(
+ (
+ edge[key]
+ for key in TARGET_ENDPOINT_NAMES
+ if not is_unset_id(edge.get(key))
+ ),
+ None,
+ )
rel_type = edge.get("type") or edge.get("relationship_type", "RELATED_TO")
- if not source_id or not target_id:
+ if source_id is None or target_id is None:
continue
# Escape special characters
@@ -301,10 +323,8 @@ class LPGExporter:
properties = {}
for key, value in edge.items():
if key not in [
- "source",
- "source_id",
- "target",
- "target_id",
+ *SOURCE_ENDPOINT_NAMES,
+ *TARGET_ENDPOINT_NAMES,
"type",
"relationship_type",
]:
diff --git a/tests/export/test_endpoint_names_empty_values.py b/tests/export/test_endpoint_names_empty_values.py
new file mode 100644
index 00000000..01049a21
--- /dev/null
+++ b/tests/export/test_endpoint_names_empty_values.py
@@ -0,0 +1,105 @@
+"""``None`` and ``""`` endpoint values count as unset in ``endpoint_names`` (#2018).
+
+An empty ``source_id`` next to a backend name such as ``start_node_id`` used to
+stay empty, so ``export_knowledge_graph`` wrote blank endpoints to JSON, a
+``None`` subject and object to Turtle, and raised for Parquet.
+"""
+
+import json
+
+import pytest
+
+from semantica.export.endpoint_names import canonical_endpoints, is_unset_id
+from semantica.export.methods import export_knowledge_graph
+
+BACKEND_EDGE = {
+ "id": "r1",
+ "source_id": "",
+ "target_id": "",
+ "start_node_id": "alice",
+ "end_node_id": "acme",
+ "type": "WORKS_AT",
+}
+
+
+def _graph():
+ return {
+ "entities": [
+ {"id": "alice", "type": "Person", "text": "Alice"},
+ {"id": "acme", "type": "Org", "text": "Acme"},
+ ],
+ "relationships": [dict(BACKEND_EDGE)],
+ }
+
+
+ "value, unset",
+ [(None, True), ("", True), (0, False), ("0", False), ("alice", False)],
+)
+def test_is_unset_id(value, unset):
+ assert is_unset_id(value) is unset
+
+
[email protected]("empty", [None, ""])
+def test_unset_canonical_endpoint_takes_the_backend_name(empty):
+ edge = {**BACKEND_EDGE, "source_id": empty, "target_id": empty}
+
+ [out] = canonical_endpoints([edge])
+
+ assert (out["source_id"], out["target_id"]) == ("alice", "acme")
+
+
+def test_empty_alias_defers_to_the_next_alias():
+ edge = {"source": "", "start_node_id": "alice", "target": "", "end_id": "acme"}
+
+ [out] = canonical_endpoints([edge])
+
+ assert (out["source_id"], out["target_id"]) == ("alice", "acme")
+
+
+ "edge",
+ [
+ {"source_id": 0, "start_node_id": "x", "target_id": "acme"},
+ {"source_id": "", "target_id": ""},
+ ],
+)
+def test_records_without_a_set_alias_are_returned_as_given(edge):
+ records = [edge]
+
+ assert canonical_endpoints(records) is records
+
+
+def test_json_export_writes_the_backend_endpoints(tmp_path):
+ target = tmp_path / "kg.json"
+
+ export_knowledge_graph(_graph(), str(target), format="json")
+
+ [rel] = json.loads(target.read_text(encoding="utf-8"))["relationships"]
+ assert (rel["source_id"], rel["target_id"]) == ("alice", "acme")
+
+
+def test_turtle_export_links_the_two_entities(tmp_path):
+ pytest.importorskip("rdflib", reason="the RDF writer needs rdflib")
+ target = tmp_path / "kg.ttl"
+
+ export_knowledge_graph(_graph(), str(target))
+
+ body = target.read_text(encoding="utf-8")
+ assert "ns#None" not in body
+ assert (
+ "ns#alice> <https://semantica.dev/ns#WORKS_AT> <https://semantica.dev/ns#acme>"
+ in body
+ )
+
+
+def test_parquet_export_keeps_the_relationship(tmp_path):
+ pytest.importorskip("pyarrow", reason="the parquet writer needs pyarrow")
+ import pyarrow.parquet as pq
+
+ export_knowledge_graph(_graph(), str(tmp_path / "kg.parquet"))
+
+ table = pq.read_table(tmp_path / "kg_relationships.parquet")
+ assert table.select(["source_id", "target_id"]).to_pylist() == [
+ {"source_id": "alice", "target_id": "acme"}
+ ]
diff --git a/tests/export/test_lpg_exporter_endpoint_names.py b/tests/export/test_lpg_exporter_endpoint_names.py
new file mode 100644
index 00000000..05e097ad
--- /dev/null
+++ b/tests/export/test_lpg_exporter_endpoint_names.py
@@ -0,0 +1,131 @@
+"""LPG exports must retain relationships whose endpoints use backend names."""
+
+from copy import deepcopy
+
+import pytest
+
+from semantica.export import LPGExporter
+
+
+def _export(tmp_path, records, vocabulary=("entities", "relationships")):
+ path = tmp_path / "graph.cypher"
+ graph = {
+ vocabulary[0]: [{"id": "alice"}, {"id": "acme"}],
+ vocabulary[1]: records,
+ }
+ LPGExporter(include_indexes=False).export(graph, path)
+ return path.read_text(encoding="utf-8")
+
+
+ "vocabulary", [("entities", "relationships"), ("nodes", "edges")]
+)
+ "source_key, target_key",
+ [
+ ("source_id", "target_id"),
+ ("source", "target"),
+ ("start_node_id", "end_node_id"),
+ ("start_id", "end_id"),
+ ],
+)
+def test_export_retains_relationship_for_each_endpoint_spelling(
+ tmp_path, vocabulary, source_key, target_key
+):
+ record = {
+ "id": "r1",
+ source_key: "alice",
+ target_key: "acme",
+ "type": "WORKS_AT",
+ "weight": 0.5,
+ }
+ original = deepcopy(record)
+
+ text = _export(tmp_path, [record], vocabulary)
+
+ assert text.count("CREATE (a)-[") == 1
+ assert (
+ "MATCH (a {id: 'alice'}), (b {id: 'acme'}) "
+ "CREATE (a)-[r:WORKS_AT {id: 'r1', weight: 0.5}]->(b);"
+ ) in text
+ assert record == original
+
+
+def test_export_retains_mixed_endpoint_spellings(tmp_path):
+ text = _export(
+ tmp_path,
+ [
+ {"source": "alice", "target_id": "acme", "type": "FIRST"},
+ {"start_node_id": "acme", "end_id": "alice", "type": "SECOND"},
+ ],
+ )
+
+ assert text.count("CREATE (a)-[") == 2
+ assert "CREATE (a)-[r:FIRST]->(b);" in text
+ assert "CREATE (a)-[r:SECOND]->(b);" in text
+
+
[email protected]("source, target", [(0, 1), (1, 0)])
+def test_export_retains_zero_endpoint_ids(tmp_path, source, target):
+ path = tmp_path / "numeric.cypher"
+ LPGExporter(include_indexes=False).export(
+ {
+ "nodes": [{"id": source}, {"id": target}],
+ "edges": [{"start_node_id": source, "end_node_id": target}],
+ },
+ path,
+ )
+
+ text = path.read_text(encoding="utf-8")
+ assert (
+ f"MATCH (a {{id: '{source}'}}), (b {{id: '{target}'}}) "
+ "CREATE (a)-[r:RELATED_TO]->(b);"
+ ) in text
+ # A node with id 0 keeps its id instead of a generated node_<n> placeholder.
+ assert "node_" not in text
+
+
[email protected]("empty", [None, ""])
+def test_empty_earlier_names_fall_back_to_backend_names(tmp_path, empty):
+ text = _export(
+ tmp_path,
+ [
+ {
+ "source_id": empty,
+ "source": empty,
+ "target_id": empty,
+ "target": empty,
+ "start_node_id": "alice",
+ "end_node_id": "acme",
+ }
+ ],
+ )
+
+ assert "MATCH (a {id: 'alice'}), (b {id: 'acme'})" in text
+
+
+def test_canonical_endpoints_take_precedence(tmp_path):
+ text = _export(
+ tmp_path,
+ [
+ {
+ "source_id": "alice",
+ "target_id": "acme",
+ "source": "ignored",
+ "target": "ignored",
+ "start_node_id": "ignored",
+ "end_node_id": "ignored",
+ }
+ ],
+ )
+
+ assert "MATCH (a {id: 'alice'}), (b {id: 'acme'})" in text
+ assert "ignored" not in text
+
+
+ "record",
+ [{}, {"start_node_id": "alice"}, {"end_node_id": "acme"}],
+)
+def test_missing_endpoints_still_skip_the_relationship(tmp_path, record):
+ assert "CREATE (a)-[" not in _export(tmp_path, [record])