greptimedb/operator/statement/semantic_graph/relationships/index.html

<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="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."><title>operator::statement::semantic_graph::relationships - Rust</title><script>if(window.location.protocol!=="file:")document.head.insertAdjacentHTML("beforeend","SourceSerif4-Regular-6b053e98.ttf.woff2,FiraSans-Italic-81dc35de.woff2,FiraSans-Regular-0fe48ade.woff2,FiraSans-MediumItalic-ccf7e434.woff2,FiraSans-Medium-e1aa3f0a.woff2,SourceCodePro-Regular-8badfe75.ttf.woff2,SourceCodePro-Semibold-aa29a496.ttf.woff2".split(",").map(f=>`<link rel="preload" as="font" type="font/woff2"href="../../../../static.files/${f}">`).join(""))</script><link rel="stylesheet" href="../../../../static.files/normalize-9960930a.css"><link rel="stylesheet" href="../../../../static.files/rustdoc-1ed95124.css"><meta name="rustdoc-vars" data-root-path="../../../../" data-static-root-path="../../../../static.files/" data-current-crate="operator" data-themes="" data-resource-suffix="" data-rustdoc-version="1.98.1 (48a229cea 2026-09-01)" data-channel="1.98.1" data-search-js="search-9944d736.js" data-stringdex-js="stringdex-2da4960a.js" data-settings-js="settings-170eb4bf.js" ><script src="../../../../static.files/storage-41dd4d93.js"></script><script defer src="../sidebar-items.js"></script><script defer src="../../../../static.files/main-417ebf0a.js"></script><noscript><link rel="stylesheet" href="../../../../static.files/noscript-f7c3ffd8.css"></noscript><link rel="alternate icon" type="image/png" href="../../../../static.files/favicon-32x32-eab170b8.png"><link rel="icon" type="image/svg+xml" href="../../../../static.files/favicon-044be391.svg"></head><body class="rustdoc mod"><a class="skip-main-content" href="#main-content">Skip to main content</a><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><rustdoc-topbar><h2><a href="#">Module relationships</a></h2></rustdoc-topbar><nav class="sidebar"><div class="sidebar-crate"><h2><a href="../../../../operator/index.html">operator</a><span class="version">1.4.0-alpha.0</span></h2></div><div class="sidebar-elems"><section id="rustdoc-toc"><h2 class="location"><a href="#">Module relationships</a></h2><h3><a href="#structs">Module Items</a></h3><ul class="block"><li><a href="#structs" title="Structs">Structs</a></li><li><a href="#constants" title="Constants">Constants</a></li><li><a href="#functions" title="Functions">Functions</a></li></ul></section><div id="rustdoc-modnav"><h2><a href="../index.html">In operator::<wbr>statement::<wbr>semantic_<wbr>graph</a></h2></div></div></nav><div class="sidebar-resizer" title="Drag to resize sidebar"></div><main><div class="width-limiter"><section id="main-content" class="content" tabindex="-1"><div class="main-heading"><div class="rustdoc-breadcrumbs"><a href="../../../index.html">operator</a>::<wbr><a href="../../index.html">statement</a>::<wbr><a href="../index.html">semantic_graph</a></div><h1>Module <span>relationships</span>&nbsp;<button id="copy-path" title="Copy item path to clipboard">Copy item path</button></h1><rustdoc-toolbar></rustdoc-toolbar><span class="sub-heading"><a class="src" href="../../../../src/operator/statement/semantic_graph/relationships.rs.html#15-2008">Source</a> </span></div><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>The <code>semantic_relationships</code> derivation: the plan builders for every edge
branch behind the computed table — trace-derived service <code>calls</code> (with
virtual-node edges for unmatched clients), agent <code>calls</code> 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.</p>
</div></details><h2 id="structs" class="section-header">Structs<a href="#structs" class="anchor">§</a></h2><dl class="item-table"><dt><a class="struct" href="struct.CallsSource.html" title="struct operator::statement::semantic_graph::relationships::CallsSource">Calls<wbr>Source</a></dt><dd>A trace table’s scan paired with the entity declarations its derivations
key on — a unit of <code>build_relationships_plan</code>. The <code>service</code> declaration
feeds service calls, the <code>agent</code> declaration agent calls; the two are
independent, so a table whose service declaration is unusable still
derives agent edges (and vice versa).</dd><dt><a class="struct" href="struct.CoDeclaredSource.html" title="struct operator::statement::semantic_graph::relationships::CoDeclaredSource">CoDeclared<wbr>Source</a></dt><dd>A declaring table’s scan paired with its entity declarations, from which
the same-row co-declaration rules derive edges. <code>is_trace</code> gates the
agent-edge vocabulary, which the RFC ties to span structure.</dd><dt><a class="struct" href="struct.DeclaredSource.html" title="struct operator::statement::semantic_graph::relationships::DeclaredSource">Declared<wbr>Source</a></dt><dd>The declared-edge table’s scan (<code>semantic_relationships_declared</code>), whose
rows <code>build_relationships_plan</code> unions into the edge set.</dd><dt><a class="struct" href="struct.RelationshipSources.html" title="struct operator::statement::semantic_graph::relationships::RelationshipSources">Relationship<wbr>Sources</a></dt><dd>Everything <code>build_relationships_plan</code> derives edges from.</dd></dl><h2 id="constants" class="section-header">Constants<a href="#constants" class="anchor">§</a></h2><dl class="item-table"><dt><a class="constant" href="constant.CHILD_SPAN_EARLY_NANOS.html" title="constant operator::statement::semantic_graph::relationships::CHILD_SPAN_EARLY_NANOS">CHILD_<wbr>SPAN_<wbr>EARLY_<wbr>NANOS</a><span title="Restricted Visibility">&nbsp;🔒</span> </dt><dd>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.</dd><dt><a class="constant" href="constant.CHILD_SPAN_LATE_NANOS.html" title="constant operator::statement::semantic_graph::relationships::CHILD_SPAN_LATE_NANOS">CHILD_<wbr>SPAN_<wbr>LATE_<wbr>NANOS</a><span title="Restricted Visibility">&nbsp;🔒</span> </dt><dt><a class="constant" href="constant.CO_DECLARED_VALID_COLUMN.html" title="constant operator::statement::semantic_graph::relationships::CO_DECLARED_VALID_COLUMN">CO_<wbr>DECLARED_<wbr>VALID_<wbr>COLUMN</a><span title="Restricted Visibility">&nbsp;🔒</span> </dt><dt><a class="constant" href="constant.DECLARED_REVISION_COLUMN.html" title="constant operator::statement::semantic_graph::relationships::DECLARED_REVISION_COLUMN">DECLARED_<wbr>REVISION_<wbr>COLUMN</a><span title="Restricted Visibility">&nbsp;🔒</span> </dt><dd>Ranking column used to pick the latest declared-edge revision per edge key.</dd><dt><a class="constant" href="constant.RELATIONSHIP_COLUMNS.html" title="constant operator::statement::semantic_graph::relationships::RELATIONSHIP_COLUMNS">RELATIONSHIP_<wbr>COLUMNS</a><span title="Restricted Visibility">&nbsp;🔒</span> </dt><dd>The projected columns of <code>semantic_relationships</code>, in order. Every derived
branch and the declared-edge branch must project exactly these so the
top-level <code>UNION ALL</code> type-aligns; <code>build_relationships_plan</code> re-selects
them over the union to enforce the contract. (The physical declared table
additionally stores <code>valid_from</code>/<code>valid_until</code>, which feed the validity
filter and the projected window columns.)</dd><dt><a class="constant" href="constant.VIRTUAL_NODE_CONFIDENCE.html" title="constant operator::statement::semantic_graph::relationships::VIRTUAL_NODE_CONFIDENCE">VIRTUAL_<wbr>NODE_<wbr>CONFIDENCE</a><span title="Restricted Visibility">&nbsp;🔒</span> </dt><dd>Confidence of a virtual-node edge: the peer was named by a client-side
attribute, not witnessed by a server span (the RFC requires <code>&lt; 1.0</code>).</dd></dl><h2 id="functions" class="section-header">Functions<a href="#functions" class="anchor">§</a></h2><dl class="item-table"><dt><a class="fn" href="fn.agent_calls_branch.html" title="fn operator::statement::semantic_graph::relationships::agent_calls_branch">agent_<wbr>calls_<wbr>branch</a><span title="Restricted Visibility">&nbsp;🔒</span> </dt><dd>The <code>parent_agent calls agent</code> derivation over trace tables declaring an
<code>agent</code> 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 <code>observed_at</code>, the child side
widens by the time-proximity allowance and supplies status/duration.</dd><dt><a class="fn" href="fn.build_relationships_plan.html" title="fn operator::statement::semantic_graph::relationships::build_relationships_plan">build_<wbr>relationships_<wbr>plan</a></dt><dd>Builds the <code>semantic_relationships</code> plan: the service-calls, agent-calls,
co-declared, and declared-edge branches unioned and re-projected to the
18-column contract. Returns <code>None</code> when no source can contribute edges, so
the computed table streams empty.</dd><dt><a class="fn" href="fn.builtin.html" title="fn operator::statement::semantic_graph::relationships::builtin">builtin</a><span title="Restricted Visibility">&nbsp;🔒</span> </dt><dd>The embedded conventions, with a broken file surfaced as a plan error.</dd><dt><a class="fn" href="fn.calls_branch.html" title="fn operator::statement::semantic_graph::relationships::calls_branch">calls_<wbr>branch</a><span title="Restricted Visibility">&nbsp;🔒</span> </dt><dd>The <code>calls</code> derivation: union the client spans and the server spans of all
trace tables (each projected to a normalized shape with its own table’s
<code>service</code> identity), left-join clients to their child server spans on
<code>trace_id</code> + <code>parent_span_id</code>, 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 <em>different</em> trace table
(<code>x-greptime-trace-table-name</code> routing); with a single table it degenerates
to the previous self-join. Returns <code>None</code> when no trace table has a
usable <code>service</code> declaration.</dd><dt><a class="fn" href="fn.client_spans.html" title="fn operator::statement::semantic_graph::relationships::client_spans">client_<wbr>spans</a><span title="Restricted Visibility">&nbsp;🔒</span> </dt><dd><code>(timestamp, trace_id, span_id, src_id, status_code, duration_nano, virtual_dst, virtual_conn)</code>. <code>src_id</code> is built from the table’s <code>service</code>
declaration, so edges land on exactly the entity ids the registry emits (a
composite identity renders the same sorted <code>k=v</code> form); the per-table
projection is what lets tables with different declarations union.</dd><dt><a class="fn" href="fn.co_declared_branch.html" title="fn operator::statement::semantic_graph::relationships::co_declared_branch">co_<wbr>declared_<wbr>branch</a><span title="Restricted Visibility">&nbsp;🔒</span> </dt><dd>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 <code>unnest_rows</code> (the registry idiom). Attribute
edges carry <code>provenance = 'attribute'</code>; agent edges are span-structure
observations and carry <code>provenance = 'trace'</code>.</dd><dt><a class="fn" href="fn.declared_edges.html" title="fn operator::statement::semantic_graph::relationships::declared_edges">declared_<wbr>edges</a><span title="Restricted Visibility">&nbsp;🔒</span> </dt><dd>The declared-edge branch: the latest revision per edge key <em>as of the
queried window</em> (mito dedups on primary key + <code>observed_at</code>, so re-asserting
an edge stores a new revision), filtered by business-validity overlap.</dd><dt><a class="fn" href="fn.duration_nano_expr.html" title="fn operator::statement::semantic_graph::relationships::duration_nano_expr">duration_<wbr>nano_<wbr>expr</a><span title="Restricted Visibility">&nbsp;🔒</span> </dt><dd>One trace table’s client spans, normalized to
A trace table’s <code>duration_nano</code> 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.</dd><dt><a class="fn" href="fn.real_wins.html" title="fn operator::statement::semantic_graph::relationships::real_wins">real_<wbr>wins</a><span title="Restricted Visibility">&nbsp;🔒</span> </dt><dd><code>CASE WHEN has_pair THEN real ELSE virtual END</code> — the real-wins projection
over the mixed aggregate.</dd><dt><a class="fn" href="fn.server_spans.html" title="fn operator::statement::semantic_graph::relationships::server_spans">server_<wbr>spans</a><span title="Restricted Visibility">&nbsp;🔒</span> </dt><dd>One trace table’s server spans, normalized to
<code>(timestamp, trace_id, parent_span_id, dst_id, status_code, duration_nano)</code>.</dd><dt><a class="fn" href="fn.span_predicate.html" title="fn operator::statement::semantic_graph::relationships::span_predicate">span_<wbr>predicate</a><span title="Restricted Visibility">&nbsp;🔒</span> </dt><dd>The window + span-kind + identity predicate shared by both join sides.
<code>strict</code> 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).</dd><dt><a class="fn" href="fn.virtual_attrs_expr.html" title="fn operator::statement::semantic_graph::relationships::virtual_attrs_expr">virtual_<wbr>attrs_<wbr>expr</a><span title="Restricted Visibility">&nbsp;🔒</span> </dt><dd>The <code>attributes</code> JSON of a virtual edge, from the aggregated
<code>connection_type</code>.</dd></dl></section></div></main></body></html>