Relationship Search

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

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:

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:

Use OR between blocks when the alternatives are different kinds of events, such as a span versus a log, or two different sequences:

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 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_name holds the path only; to match a host or query string, use span(span_name="page_view" url.full=*...*).
• Click: span(span_name="click" event.text="Pay Now"). Add url.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>3s also works.
• Custom track event: span(span_name="track" key="order_completed"). Don’t use event.name, which is the mobile screen name.
• Error: span(has_errors=true) or span(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

Rules the parser enforces

• THEN only joins blocks, never plain filters. Write country=US span(A), not country=US THEN span(A).
• A THEN chain must start with span(...) or log(...). For “B never happened, and A did”, write span(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.
• NOT cannot precede a block or a chain. Use no_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. Expand span(A) THEN (span(B) OR span(C)) into (span(A) THEN span(B)) OR (span(A) THEN span(C)), or merge B and C into one block with a value group.
• OR between 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. THEN means “later, with no upper bound”.
• Counts (“clicked Retry at least 3 times”): there is no count operator. Chain THEN once per occurrence for small numbers.
• Ordering across sessions: every block is scoped to one session.

Interpreting results

• THEN anchors on the earliest match of each step. A session that did A, then B, then A again with no B afterwards is not a span(A) THEN no_span(B) drop-off, because B followed the first A.
• THEN needs strictly increasing timestamps. Two events written with the same timestamp, such as a page view and a flag evaluation that fires on load, never satisfy THEN in either order.
• Every block is limited to the query’s time range. A B that 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 clickTextContent but span(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.