Module relationships 

The semantic_relationships derivation: the plan builders for every edge branch behind the computed table — trace-derived service calls (with virtual-node edges for unmatched clients), agent calls from span structure, same-row co-declared edges, and the declared-edge union. Shared expression helpers and the entity registry live in the parent module.

Structs

CallsSource

A trace table’s scan paired with the entity declarations its derivations key on — a unit of build_relationships_plan. The service declaration feeds service calls, the agent declaration agent calls; the two are independent, so a table whose service declaration is unusable still derives agent edges (and vice versa).

CoDeclaredSource

A declaring table’s scan paired with its entity declarations, from which the same-row co-declaration rules derive edges. is_trace gates the agent-edge vocabulary, which the RFC ties to span structure.

DeclaredSource

The declared-edge table’s scan (semantic_relationships_declared), whose rows build_relationships_plan unions into the edge set.

RelationshipSources

Everything build_relationships_plan derives edges from.

Constants

CHILD_SPAN_EARLY_NANOS 🔒

A child server span starts no earlier than 5 minutes before its client span (clock-skew allowance) and no later than 1 hour after it; the bounds keep the join windowed instead of pairing arbitrarily distant spans of a long-lived trace.

CHILD_SPAN_LATE_NANOS 🔒

CO_DECLARED_VALID_COLUMN 🔒

DECLARED_REVISION_COLUMN 🔒

Ranking column used to pick the latest declared-edge revision per edge key.

RELATIONSHIP_COLUMNS 🔒

The projected columns of semantic_relationships, in order. Every derived branch and the declared-edge branch must project exactly these so the top-level UNION ALL type-aligns; build_relationships_plan re-selects them over the union to enforce the contract. (The physical declared table additionally stores valid_from/valid_until, which feed the validity filter and the projected window columns.)

VIRTUAL_NODE_CONFIDENCE 🔒

Confidence of a virtual-node edge: the peer was named by a client-side attribute, not witnessed by a server span (the RFC requires < 1.0).

Functions

agent_calls_branch 🔒

The parent_agent calls agent derivation over trace tables declaring an agent entity: pair each span with its child span (no span-kind filter — agent spans are typically INTERNAL) across all agent-declaring tables, keep pairs whose agent identities differ, and aggregate RED metrics per 60s window. Anchored like the service derivation on the caller: the parent side is bounded to the source window and stamps observed_at, the child side widens by the time-proximity allowance and supplies status/duration.

build_relationships_plan

Builds the semantic_relationships plan: the service-calls, agent-calls, co-declared, and declared-edge branches unioned and re-projected to the 18-column contract. Returns None when no source can contribute edges, so the computed table streams empty.

builtin 🔒

The embedded conventions, with a broken file surfaced as a plan error.

calls_branch 🔒

The calls derivation: union the client spans and the server spans of all trace tables (each projected to a normalized shape with its own table’s service identity), left-join clients to their child server spans on trace_id + parent_span_id, and aggregate RED metrics per 60s window — the plan form of the Tempo servicegraph connector. Unioning spans before the join pairs a client with a server stored in a different trace table (x-greptime-trace-table-name routing); with a single table it degenerates to the previous self-join. Returns None when no trace table has a usable service declaration.

client_spans 🔒

(timestamp, trace_id, span_id, src_id, status_code, duration_nano, virtual_dst, virtual_conn). src_id is built from the table’s service declaration, so edges land on exactly the entity ids the registry emits (a composite identity renders the same sorted k=v form); the per-table projection is what lets tables with different declarations union.

co_declared_branch 🔒

The same-row co-declared branch: for each source table, every vocabulary pair whose two entity types the table declares yields an edge projection, expanded from one scan via unnest_rows (the registry idiom). Attribute edges carry provenance = 'attribute'; agent edges are span-structure observations and carry provenance = 'trace'.

declared_edges 🔒

The declared-edge branch: the latest revision per edge key as of the queried window (mito dedups on primary key + observed_at, so re-asserting an edge stores a new revision), filtered by business-validity overlap.

duration_nano_expr 🔒

One trace table’s client spans, normalized to A trace table’s duration_nano is UInt64 on tables created before the signed-integer ingest change and Int64 after it. The per-table selects are unioned, and those two have no common integer type.

real_wins 🔒

CASE WHEN has_pair THEN real ELSE virtual END — the real-wins projection over the mixed aggregate.

server_spans 🔒

One trace table’s server spans, normalized to (timestamp, trace_id, parent_span_id, dst_id, status_code, duration_nano).

span_predicate 🔒

The window + span-kind + identity predicate shared by both join sides. strict bounds the scan to the source window; the non-strict side widens by the join’s time-proximity allowance (the join bounds reference the other side’s timestamp and cannot prune this side’s scan on their own).

virtual_attrs_expr 🔒

The attributes JSON of a virtual edge, from the aggregated connection_type.