Skip to content

Show optimization strategies firing in the Unnecessary Steps recipe - #3613

Merged
spmallette merged 1 commit into
apache:masterfrom
spmallette:tp-docs-antipatterns-explain
Aug 5, 2026
Merged

Show optimization strategies firing in the Unnecessary Steps recipe#3613
spmallette merged 1 commit into
apache:masterfrom
spmallette:tp-docs-antipatterns-explain

Conversation

@spmallette

Copy link
Copy Markdown
Contributor

The "Unnecessary Steps" section of the anti-patterns recipe correctly teaches the manual rewrites (outE().inV() to out(), and folding a counted adjacency onto its incident edges), and states that TinkerPop performs these rewrites automatically through optimization strategies. However the section gave a reader no way to confirm that claim, never named the strategies involved, and offered no pointer to further reading.

This change addresses that gap:

  • Adds a runnable explain() example on the two original (unoptimized) queries so the optimizations are visible in the compiled traversal rather than taken on faith. The block is executed at doc-build time against the modern graph, so the transcript is real output.
  • Names the two strategies responsible: IncidentToAdjacentStrategy (which folds outE("created").inV() into a single out("created") step) and AdjacentToIncidentStrategy (which rewrites the counted adjacency back onto the incident edges), and explains how to read the strategy/category columns and the Final Traversal line.
  • Cross-references the explain() and profile() steps and the traversal strategies section of the reference documentation.

The change is scoped to docs/src/recipes/anti-patterns.asciidoc (+26 lines). The rendered recipes book was previewed locally to confirm the live explain() transcript renders and the new prose displays cleanly.

The Unnecessary Steps anti-patterns recipe stated that TinkerPop rewrites these
traversals automatically but offered no way to confirm it, never named the
strategies involved, and gave no pointer to further reading. Add a runnable
explain() example on the original queries so the rewrites are visible, name the
IncidentToAdjacentStrategy and AdjacentToIncidentStrategy strategies that
perform them, and cross-reference the explain() and profile() steps and the
traversal strategies section of the reference documentation.

Assisted-by: Kiro:claude-opus-4.8
@spmallette
spmallette merged commit 0e83640 into apache:master Aug 5, 2026
7 checks passed
@spmallette
spmallette deleted the tp-docs-antipatterns-explain branch August 5, 2026 17:56
@codecov-commenter

codecov-commenter commented Aug 5, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 76.46%. Comparing base (a28cd1f) to head (74193b5).
⚠️ Report is 430 commits behind head on master.

Additional details and impacted files
@@             Coverage Diff              @@
##             master    #3613      +/-   ##
============================================
+ Coverage     76.35%   76.46%   +0.10%     
- Complexity    13424    14294     +870     
============================================
  Files          1012     1036      +24     
  Lines         60341    64620    +4279     
  Branches       7075     7664     +589     
============================================
+ Hits          46076    49409    +3333     
- Misses        11548    12120     +572     
- Partials       2717     3091     +374     

☔ 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