docs: KG construction research findings

[DecisionNerd]

Closes #449

Summary

• Validated all 11 code snippets from docs/use-cases/knowledge-graph-construction.md against current main (9 pass, 2 fail)
• Ran full 8-entity-type / 26-relationship pipeline test — 31/31 checks pass, including all four export methods
• Documented 6 friction points with runnable problem code, workarounds, and competitive context
• Investigated ontology-constrained KG construction via three approaches (Pydantic-only, GF ontology-as-graph, hybrid) — all validated against main
• Filed 7 follow-on issues from the findings

Issues filed

Issue	Title
#468	shortestPath() causes SyntaxError — parser does not recognise the function
#469	Schema introspection — labels(), relationship_types(), node_count(), relationship_count()
#470	to_json() / from_json()
#471	merge_node() — safe label injection
#472	add_graph_documents() — LangChain-compatible batch ingestion
#473	Docs: warn about CREATE vs MERGE idempotency
#474	EXISTS {} subquery fails in planner with outer variable binding

Test plan

• Research doc is readable and all code snippets are correctly formatted
• All issue references (fix: shortestPath() causes SyntaxError — parser does not recognise the function #468–fix: EXISTS {} subquery fails in planner when outer variable used in inner MATCH property #474) resolve correctly
• No library code changed — docs only

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith with what you need.}

• Let Codesmith autofix CI failures and bot reviews

[coderabbitai]

Important

Review skipped

Review was skipped due to path filters

⛔ Files ignored due to path filters (1)

• docs/research/kg-construction.md is excluded by !**/*.md, !**/docs/**

CodeRabbit blocks several paths by default. You can override this behavior by explicitly including those paths in the path filters. For example, including **/dist/** will override the default block on the dist directory, by removing the pattern from both the lists.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 5d37121b-61e2-4a55-b9c7-e531ca15d615

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/449-kg-construction-research

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 88.01%. Comparing base (f566052) to head (6d004da).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #475   +/-   ##
=======================================
  Coverage   88.01%   88.01%           
=======================================
  Files          40       40           
  Lines       14449    14449           
  Branches     3430     3430           
=======================================
  Hits        12718    12718           
  Misses       1141     1141           
  Partials      590      590           

Flag	Coverage Δ
full-coverage	88.01% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Components	Coverage Δ
parser	95.67% <ø> (ø)
planner	82.94% <ø> (ø)
executor	83.63% <ø> (ø)
storage	91.25% <ø> (ø)
ast	98.20% <ø> (ø)
types	94.75% <ø> (ø)

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update f566052...6d004da. Read the comment docs.