Skip to content

Clarify subgraph-step TinkerVertex caveat as implementation-dependent#3571

Open
spmallette wants to merge 1 commit into
apache:masterfrom
spmallette:tp-docs-subgraph-tinkervertex-caveat
Open

Clarify subgraph-step TinkerVertex caveat as implementation-dependent#3571
spmallette wants to merge 1 commit into
apache:masterfrom
spmallette:tp-docs-subgraph-tinkervertex-caveat

Conversation

@spmallette

Copy link
Copy Markdown
Contributor

The subgraph()-step section cautions that a TinkerGraph subgraph's elements (TinkerVertex/TinkerEdge) can not be used directly in Gremlin running against the original graph, and presents this example as one that "would likely return an error":

Vertex v = sg.V().has('name','marko').next();
List<Vertex> vertices = g.V(v).out().toList();

For the example as shown, though, the original graph is also a TinkerGraph. In that case TinkerGraph looks vertices up by their identifier, so the reference resolves and g.V(v).out() returns the expected result rather than erroring. The warning is accurate only when the original graph is a different implementation that may not recognize a foreign TinkerVertex.

This reduces the caveat paragraph and its callout to implementation-dependent framing:

  • When the original graph is also a TinkerGraph (as in the modern graph example shown), the reference resolves by identifier and the traversal succeeds.
  • When the original graph is a different implementation, it may reject a foreign TinkerVertex and could return an error.

Scope is limited to the caveat paragraph and its second callout. The edge-induced subgraph examples above and the ReferenceVertex/id() portable-recommendation block below are unchanged, and the illustrative snippet remains non-executed text. The reference book was rendered locally to confirm it builds and reads coherently.

The subgraph-step section warned that a TinkerGraph subgraph's elements
could not be used directly against the original graph and gave an example
it said would likely return an error. That is misleading for the example
shown, where the original graph is also a TinkerGraph: TinkerGraph looks
vertices up by their identifier, so the reference resolves and the
traversal succeeds. Reword the caveat and its callout to frame the
behavior as implementation-dependent. It resolves for a TinkerGraph
original and may fail against a different implementation that does not
recognize a foreign TinkerVertex. The ReferenceVertex/id() block remains
the portable recommendation.

Assisted-by: Kiro:claude-opus-4.8
@codecov-commenter

codecov-commenter commented Jul 25, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 76.52%. Comparing base (a28cd1f) to head (46f0a0e).
⚠️ Report is 373 commits behind head on master.

Additional details and impacted files
@@             Coverage Diff              @@
##             master    #3571      +/-   ##
============================================
+ Coverage     76.35%   76.52%   +0.16%     
- Complexity    13424    14309     +885     
============================================
  Files          1012     1036      +24     
  Lines         60341    64608    +4267     
  Branches       7075     7661     +586     
============================================
+ Hits          46076    49442    +3366     
- Misses        11548    12078     +530     
- Partials       2717     3088     +371     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants