Relationship search: span(...), log(...), and THEN
Load this file when a search-sessions question depends on how events relate to each other: "did A happen and then B?", "did A happen but never B?", "which sessions had both A and B?", "either A or B?".
Plain filters such as visited-url=*/pricing* visited-url=*/checkout* only check that a session matched each filter, in any order and not necessarily on the same event. Relationship search wraps each event in its own block and joins the blocks with AND, OR, or THEN. Never tell the user that event order or absence cannot be checked; use this syntax instead.
Blocks
| Block | Matches |
|---|---|
span(A) |
at least one span matching A in the session |
no_span(A) |
no span in the session matches A |
log(A) |
at least one log matching A, recorded during the session |
no_log(A) |
no log matches A during the session |
This file covers relationship search in search-sessions. search-traces takes a smaller form within one trace: span(A) THEN span(B), span(A) THEN no_span(B), and the top-level any_span(...), child_span(...), parent_span(...) and root_span(...); see traces.md. The log(...) blocks are sessions only.
In Session Replay search, every page view, click, network request, track call, and flag evaluation is stored as a span, so span(...) covers frontend events as well as backend spans. Log blocks only join logs recorded with the session's secure_session_id. Frontend console logs carry it. Backend logs carry it only when the SDK propagated the session to that request.
Operators between blocks
All three operators join blocks. Pick the one that matches the question:
| Query | Meaning |
|---|---|
span(A) span(B) or span(A) AND span(B) |
Both happened, in any order. The two blocks may match the same event. |
span(A) OR span(B) |
Either happened. |
span(A) THEN span(B) |
A happened, and strictly later B happened. Chains can be longer: span(A) THEN span(B) THEN span(C). |
span(A) THEN no_span(B) |
Drop-off: A happened and B never happened after the first A. |
span(A) no_span(B) |
A happened and B never happened anywhere, before or after. |
Span and log blocks are interchangeable, so they mix freely: span(A) THEN log(B), span(A) OR log(B), log(A) THEN no_log(B).
Precedence, tightest first: THEN, then AND / whitespace, then OR. country=US span(A) THEN span(B) has_rage_clicks=true parses as country=US AND (span(A) THEN span(B)) AND has_rage_clicks=true. Use parentheses to group OR alternatives.
Where to put OR
Prefer OR inside a single block when the alternatives are the same kind of event. It scans once instead of joining twice:
span(span_name="click" event.text=("Pay Now" OR "Complete Order")) THEN span(has_errors=true OR http.status_code>=500)Use OR between blocks when the alternatives are different kinds of events, such as a span versus a log, or two different sequences:
span(http.url=*/api/pay* http.status_code>=500) OR log(level=error message=*payment*)
(span(view_name="/signup") THEN span(has_errors=true)) OR (span(view_name="/login") THEN span(has_errors=true))Two scopes: session keys vs. span keys
Everything outside a block filters the whole session. Everything inside a block filters one event. The keys are different. A session key written inside span(...) still parses, but it silently matches nothing, so convert it first:
| Session key (outside blocks only) | Inside span(...) |
|---|---|
visited-url=*/checkout* |
view_name="/checkout" (web path or mobile screen name) or url.full=*/checkout* |
clickTextContent="Pay Now" |
span_name="click" event.text="Pay Now" |
clickSelector=... |
span_name="click" with event.id, event.classname, or event.xpath |
clickTarget=BUTTON |
span_name="click" event.tag="BUTTON" |
event="order_completed" (custom track event) |
span_name="track" key="order_completed" |
has_errors=true |
has_errors=true (an error on that event) |
Session keys with no span equivalent (country, browser_name, os_name, identifier, email, length, active_length, has_rage_clicks, first_time, viewed_by_me, environment, ...) stay outside the blocks: country=US span(A) THEN span(B).
Canonical span recipes
- Page or screen view:
span(view_name="/checkout").view_nameholds the path only; to match a host or query string, usespan(span_name="page_view" url.full=*...*). - Click:
span(span_name="click" event.text="Pay Now"). Addurl.full=*/checkout*inside the same block to pin the page. - Network request:
span(http.method=POST http.url=*/api/checkout* http.status_code>=500).duration>3salso works. - Custom
trackevent:span(span_name="track" key="order_completed"). Don't useevent.name, which is the mobile screen name. - Error:
span(has_errors=true)orspan(service_name="payment-service" has_errors=true). - Flag evaluation:
span(feature_flag.key="new-checkout" feature_flag.result.value="true"). Values are JSON-encoded, so match a string variation with an unquoted wildcard:feature_flag.result.value=*treatment*.
Inside log(...), use log keys: level, message, source, service_name, or any log attribute. A bare word searches the message: log(timeout).
The normal filter grammar applies inside a block: =, !=, <, >, EXISTS, value groups like (500 OR 502), and unquoted wildcards. A * inside quotes is a literal asterisk. Duration suffixes need whole integers (1500ms, not 1.5s).
Examples
# Visited /pricing, then /checkout
span(view_name="/pricing") THEN span(view_name="/checkout")
# Clicked "Pay Now", then the app logged a payment error
span(span_name="click" event.text="Pay Now") THEN log(level=error message=*payment*)
# Checkout funnel drop-off: clicked "Pay Now" and never completed the order
span(view_name="/checkout") THEN span(span_name="click" event.text="Pay Now") THEN no_span(span_name="track" key="order_completed")
# Visited /pricing and never clicked "Contact Sales" anywhere in the session
span(view_name="/pricing") no_span(span_name="click" event.text="Contact Sales")
# Both happened, in any order
span(feature_flag.key="new-editor" feature_flag.result.value="true") span(service_name="document-service" duration>5s)
# US mobile users who either cancelled or hit a failing delete-account request
os_name=(iOS OR Android) country=US (span(span_name="click" event.text="Cancel Subscription") OR span(http.method=DELETE http.url=*/api/account*))
# Clicked "Save" twice (THEN guarantees two distinct events)
span(span_name="click" event.text="Save") THEN span(span_name="click" event.text="Save")Rules the parser enforces
THENonly joins blocks, never plain filters. Writecountry=US span(A), notcountry=US THEN span(A).- A
THENchain must start withspan(...)orlog(...). For "B never happened, and A did", writespan(A) no_span(B). THEN no_span(...)/THEN no_log(...)may only be the last step. "A, then C, with no B in between" is not expressible.NOTcannot precede a block or a chain. Useno_span(...)/no_log(...)instead.span(NOT x)means "some event that isn't x", which almost every session has.- Blocks cannot be nested, and a parenthesized group cannot follow
THEN. Expandspan(A) THEN (span(B) OR span(C))into(span(A) THEN span(B)) OR (span(A) THEN span(C)), or mergeBandCinto one block with a value group. ORbetween a block and a plain session filter is rejected.country=US span(A) OR span(B)is also rejected, because it parses as(country=US AND span(A)) OR span(B). Wrap the alternatives:country=US (span(A) OR span(B)).
Not supported
Don't invent syntax for these. Rewrite to the closest supported form and tell the user what was dropped:
- Time bounds ("B within 10 seconds of A"): there is no
WITHIN.THENmeans "later, with no upper bound". - Counts ("clicked Retry at least 3 times"): there is no count operator. Chain
THENonce per occurrence for small numbers. - Ordering across sessions: every block is scoped to one session.
Interpreting results
THENanchors on the earliest match of each step. A session that didA, thenB, thenAagain with noBafterwards is not aspan(A) THEN no_span(B)drop-off, becauseBfollowed the firstA.THENneeds strictly increasing timestamps. Two events written with the same timestamp, such as a page view and a flag evaluation that fires on load, never satisfyTHENin either order.- Every block is limited to the query's time range. A
Bthat happened just outside the window is invisible, so near-the-edge drop-offs can be false positives. - Exact matches are case- and whitespace-sensitive. When the user's wording is approximate, use a case-insensitive regex:
event.text=/pay now/i. - Span-based blocks need the SDK's tracing instrumentation. If a project has session keys like
clickTextContentbutspan(span_name="click" ...)returns nothing, the project may be on an older SDK or have tracing off. Say so rather than reporting zero matches as a finding.