docs: clarify trace operator return behavior and expand documentation

[shubham-signoz]

Addresses SigNoz/signoz#10025

trace operators now explicitly document that results return left-hand side spans. Added operator reference list, expression syntax details, and examples for OR, NOT, and nested expressions.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
signoz-web	Ready	Preview, Comment	Mar 25, 2026 4:52am

[shubham-signoz]

@claude /review

[github-actions]

Claude finished @shubham-signoz's task in 2m 13s —— View job

---

Review: PR #2955 — Trace operator docs (re-review)

• Gather context and read changed files
• Run docs verification checks
• Review with docs skill and post inline findings
• Post summary

---

Changes since last review

The "address reviews" commit (ee5b5ac) addressed the P1 naming inconsistency from the first review:

• Renamed "Direct Descendant" → "Has Direct Child" and "Indirect Descendant" → "Has Descendant"
• Added a concrete precedence example (A => B && C → A => (B && C))
• Updated figcaptions to match new names

These are good improvements. The core content — the Admonition about left-hand-side return behavior, the operator reference list, expression syntax, and new OR/NOT/Nested examples — continues to directly address the linked issue (signoz#10025).

---

Findings

P2 — Description/name perspective mismatch (inline 1, inline 2)
The operators were renamed to "Has Direct Child" and "Has Descendant" (B is A's child/descendant), but the descriptions still say "direct parents" and "ancestors" (A is B's parent/ancestor). Both are technically correct but mixing perspectives is confusing. Suggest aligning descriptions to the operator name's perspective. Fix this →

P3 — Operator precedence: || higher than && is unconventional (inline)
The stated precedence has OR binding tighter than AND, which is the opposite of standard Boolean precedence. If correct, a brief note would help prevent user confusion. If incorrect, it should be fixed before merge.

P3 — Pre-existing typo in asset filenames (carried over, no action needed this PR)
direct-descedant-operator.mp4 and indirect-descedant-operator.webp — missing 'n' in "descendant."

---

Personas and JTBD Fit

Check	Status
Primary persona	SigNoz user writing trace queries (developer, SRE)
Primary job	"When analyzing distributed traces, I want to understand trace operators and what spans they return, so I can write correct multi-query expressions"
Primary job clarity	✅ Clear — Admonition + per-operator "Returns" callouts
Happy path focus	✅ Examples are well-structured, progressive
Step clarity	✅ Improved — perspective mismatch is minor (P2)
Recommended defaults	✅ Parentheses recommendation is practical
Beginner unblockers	⚠️ Precedence order should be verified (P3)
Success signal	N/A (explanation doc, not task flow)

Docs PR Checklist

Item	Status
Frontmatter (date, id, title, description, doc_type)	✅ All present, doc_type: explanation correct
Content matches doc_type	✅ Conceptual explanation with examples
SEO keywords	✅ "Query Builder", "trace operators" present
Links validated	✅ No new external links
Images/media	✅ Existing visuals retained; new sections (OR, NOT, Nested) have no visuals per author decision
Sidebar / redirects	N/A — no URL change
yarn check:docs-metadata / yarn check:doc-redirects	⚠️ Could not run due to CI environment permissions — please verify in CI or locally

Open Questions

1. Is the || > && precedence order verified against the SigNoz parser? This is the most important item to confirm before merge.

---

No add-to-onboarding label needed — edit to existing doc, not a new file.