Skip to content

Clarify group()-step callouts for non-productive key vs value projection#3572

Open
spmallette wants to merge 1 commit into
apache:masterfrom
spmallette:tp-docs-group-step-callout-asymmetry
Open

Clarify group()-step callouts for non-productive key vs value projection#3572
spmallette wants to merge 1 commit into
apache:masterfrom
spmallette:tp-docs-group-step-callout-asymmetry

Conversation

@spmallette

Copy link
Copy Markdown
Contributor

The two group()-step examples in reference/the-traversal.asciidoc that project age first as a key and then as a value were annotated with symmetric callouts, both saying the non-productive entries are "filtered". Their runtime behavior is actually asymmetric:

  • A non-productive key-projection (by('age').by('name')) drops the vertex from the result map entirely — no key is produced for vertices lacking an age value.
  • A non-productive value-projection (by('name').by('age')) keeps the key (since name is productive for every vertex) but leaves its value list empty, e.g. ripple=[], lop=[].

The old symmetric wording made the {ripple:[], lop:[]} output surprising. This change rewrites callout <2> to explain that keys are retained with empty value lists, and updates callout <1> to state the entry is dropped entirely, drawing an explicit contrast between the two cases. The productive cross-reference is preserved.

Only the two callouts changed; the example code lines are untouched and still render their live output at build time, which confirms the reworded prose matches what the reader sees.

The two group()-step examples that project 'age' as a key and then as a
value were annotated with symmetric callouts, but their runtime behavior
is asymmetric. A non-productive key-projection excludes the vertex from
the result map entirely (no key is produced), while a non-productive
value-projection retains the key with an empty value list. Reword the
two callouts to describe each case accurately and contrast them.

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.50%. Comparing base (a28cd1f) to head (89a62a9).
⚠️ Report is 373 commits behind head on master.

Additional details and impacted files
@@             Coverage Diff              @@
##             master    #3572      +/-   ##
============================================
+ Coverage     76.35%   76.50%   +0.14%     
- Complexity    13424    14300     +876     
============================================
  Files          1012     1036      +24     
  Lines         60341    64608    +4267     
  Branches       7075     7661     +586     
============================================
+ Hits          46076    49431    +3355     
- Misses        11548    12088     +540     
- Partials       2717     3089     +372     

☔ 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