greptimedb/operator/statement/semantic_graph/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="Typed DataFusion plan builders for the read-time derivation behind the computed `semantic_entities` / `semantic_relationships` tables."><title>operator::statement::semantic_graph - 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-17e0aaed.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.96.0-nightly (ac7f9ec7d 2026-03-20)" data-channel="nightly" data-search-js="search-63369b7b.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-5013f961.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 semantic_graph</a></h2></rustdoc-topbar><nav class="sidebar"><div class="sidebar-crate"><h2><a href="../../../operator/index.html">operator</a><span class="version">1.3.0</span></h2></div><div class="sidebar-elems"><section id="rustdoc-toc"><h2 class="location"><a href="#">Module semantic_<wbr>graph</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="#statics" title="Statics">Statics</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</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></div><h1>Module <span>semantic_<wbr>graph</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.rs.html#15-1090">Source</a> </span></div><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>Typed DataFusion plan builders for the read-time derivation behind the
computed <code>semantic_entities</code> / <code>semantic_relationships</code> tables.</p>
<p>The derivation is built as typed [<code>Expr</code>]s over [<code>DataFrame</code>]s (never as SQL
text), so user-controlled identifiers are plain values — no quoting or SQL
injection surface — and the plans compose with DataFusion’s optimizer,
including filter pushdown into the source table scans. See
<code>docs/rfcs/2026-06-25-entity-relationships-and-graph-query.md</code>.</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::CallsSource">Calls<wbr>Source</a></dt><dd>A trace table’s scan paired with the <code>service</code> declaration it derives
<code>calls</code> edges for — the unit <code>build_calls_plan</code> consumes.</dd><dt><a class="struct" href="struct.EntityDeclaration.html" title="struct operator::statement::semantic_graph::EntityDeclaration">Entity<wbr>Declaration</a></dt><dd>A single table’s entity-identity declaration, projected from
<code>information_schema.table_semantics</code> (<code>greptime.semantic.entity.&lt;type&gt;.*</code>).</dd><dt><a class="struct" href="struct.GraphWindow.html" title="struct operator::statement::semantic_graph::GraphWindow">Graph<wbr>Window</a></dt><dd>The read-time query window as scalar [<code>Expr</code>]s. Kept as expressions so the
provider can fill them from a scan’s time predicate or the product default.</dd><dt><a class="struct" href="struct.RegistrySource.html" title="struct operator::statement::semantic_graph::RegistrySource">Registry<wbr>Source</a></dt><dd>A declaring table’s scan paired with the entity declarations it carries —
the unit <code>build_registry_plan</code> derives registry rows 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.BIN_NANOS.html" title="constant operator::statement::semantic_graph::BIN_NANOS">BIN_<wbr>NANOS</a><span title="Restricted Visibility">&nbsp;🔒</span> </dt><dd>Bin width for the temporal window of derived rows: 60s buckets, matching the
service-graph convention.</dd><dt><a class="constant" href="constant.CHILD_SPAN_EARLY_NANOS.html" title="constant operator::statement::semantic_graph::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::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.REGISTRY_COLUMNS.html" title="constant operator::statement::semantic_graph::REGISTRY_COLUMNS">REGISTRY_<wbr>COLUMNS</a><span title="Restricted Visibility">&nbsp;🔒</span> </dt><dt><a class="constant" href="constant.REGISTRY_VALID_COLUMN.html" title="constant operator::statement::semantic_graph::REGISTRY_VALID_COLUMN">REGISTRY_<wbr>VALID_<wbr>COLUMN</a><span title="Restricted Visibility">&nbsp;🔒</span> </dt></dl><h2 id="statics" class="section-header">Statics<a href="#statics" class="anchor">§</a></h2><dl class="item-table"><dt><a class="static" href="static.PARSE_JSON_UDF.html" title="static operator::statement::semantic_graph::PARSE_JSON_UDF">PARSE_<wbr>JSON_<wbr>UDF</a><span title="Restricted Visibility">&nbsp;🔒</span> </dt><dd>The <code>parse_json</code> UDF, shared by all derivation plans. Resolved from the
global registry once: the UDF is stateless (its <code>FunctionContext</code> is unused).</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.bin_interval.html" title="fn operator::statement::semantic_graph::bin_interval">bin_<wbr>interval</a><span title="Restricted Visibility">&nbsp;🔒</span> </dt><dt><a class="fn" href="fn.bin_ms.html" title="fn operator::statement::semantic_graph::bin_ms">bin_ms</a><span title="Restricted Visibility">&nbsp;🔒</span> </dt><dd><code>date_bin(60s, ts)</code> cast to millisecond precision, so the output schema is
deterministic regardless of the source column’s precision (trace tables are
nanosecond, metric tables millisecond).</dd><dt><a class="fn" href="fn.build_calls_plan.html" title="fn operator::statement::semantic_graph::build_calls_plan">build_<wbr>calls_<wbr>plan</a></dt><dd>Builds the <code>calls</code> derivation (RFC §3a) over <code>traces</code>: pair each client span
with its child server span on <code>trace_id</code> + <code>parent_span_id</code>, project to
<code>service</code>, union the pairs of all trace tables, and aggregate to RED metrics
per 60s window in one pass — so an edge observed across several trace tables
yields one row, not per-table fragments. This is the plan form of the Tempo
servicegraph connector. Virtual-node edges (uninstrumented peers) are a
separate branch, added on top of this. Column names are the fixed
<code>greptime_trace_v1</code> schema (the reason <code>table_data_model = greptime_trace_v1</code>
is required); <code>span_status_code</code> is a string column (<code>STATUS_CODE_ERROR</code>),
verified against the trace ingest path. Returns <code>None</code> when there is no
trace table.</dd><dt><a class="fn" href="fn.build_registry_plan.html" title="fn operator::statement::semantic_graph::build_registry_plan">build_<wbr>registry_<wbr>plan</a></dt><dd>Builds the <code>semantic_entities</code> registry plan: one branch and source scan per
declaring table, filtered to <code>window</code>, then <code>UNION ALL</code> across source tables.
Returns <code>None</code> when nothing declared an entity, so the computed table streams
empty.</dd><dt><a class="fn" href="fn.calls_pairs.html" title="fn operator::statement::semantic_graph::calls_pairs">calls_<wbr>pairs</a><span title="Restricted Visibility">&nbsp;🔒</span> </dt><dd>One trace table’s client/server span pairs, projected to the aggregation
inputs <code>(observed_at, src_id, dst_id, status_code, duration_nano)</code>.
Endpoint ids are built from the table’s <code>service</code> entity declaration, so
edges land on exactly the entity ids the registry emits (a composite
service identity renders the same sorted <code>k=v</code> form on both sides).</dd><dt><a class="fn" href="fn.cast_string_or_empty.html" title="fn operator::statement::semantic_graph::cast_string_or_empty">cast_<wbr>string_<wbr>or_<wbr>empty</a><span title="Restricted Visibility">&nbsp;🔒</span> </dt><dd><code>coalesce(CAST(column AS STRING), '')</code>: renders a nullable column for string
concatenation without collapsing the result to NULL.</dd><dt><a class="fn" href="fn.concat_expr.html" title="fn operator::statement::semantic_graph::concat_expr">concat_<wbr>expr</a><span title="Restricted Visibility">&nbsp;🔒</span> </dt><dt><a class="fn" href="fn.entity_id_expr.html" title="fn operator::statement::semantic_graph::entity_id_expr">entity_<wbr>id_<wbr>expr</a><span title="Restricted Visibility">&nbsp;🔒</span> </dt><dd>The canonical entity-id expression for <code>id_columns</code>: the value verbatim for
a single column, the sorted <code>k=v,k=v</code> rendering for a composite. <code>col</code>
constructs the column reference (unqualified for registry branches,
join-side-qualified for the calls derivation).</dd><dt><a class="fn" href="fn.interval.html" title="fn operator::statement::semantic_graph::interval">interval</a><span title="Restricted Visibility">&nbsp;🔒</span> </dt><dd>An <code>INTERVAL</code> literal of <code>nanos</code> nanoseconds.</dd><dt><a class="fn" href="fn.json_escaped_value_expr.html" title="fn operator::statement::semantic_graph::json_escaped_value_expr">json_<wbr>escaped_<wbr>value_<wbr>expr</a><span title="Restricted Visibility">&nbsp;🔒</span> </dt><dd>Wraps a column reference in <code>replace</code> calls so its runtime value is
JSON-escaped (<code>\</code> then <code>"</code>); NULL becomes <code>''</code> so one NULL column does not
invalidate the whole JSON text (descriptive columns are nullable).</dd><dt><a class="fn" href="fn.json_object_expr.html" title="fn operator::statement::semantic_graph::json_object_expr">json_<wbr>object_<wbr>expr</a><span title="Restricted Visibility">&nbsp;🔒</span> </dt><dd>Builds a JSONB object from <code>columns</code> by concatenating a JSON text and parsing
it — GreptimeDB has no struct→json function. Keys are JSON-escaped in Rust;
values are JSON-escaped at runtime via <a href="fn.json_escaped_value_expr.html" title="fn operator::statement::semantic_graph::json_escaped_value_expr"><code>json_escaped_value_expr</code></a>.</dd><dt><a class="fn" href="fn.json_quote.html" title="fn operator::statement::semantic_graph::json_quote">json_<wbr>quote</a><span title="Restricted Visibility">&nbsp;🔒</span> </dt><dd>Renders a compile-time-known string as JSON text (quoted, fully escaped —
including control characters, unlike the runtime value escaping).</dd><dt><a class="fn" href="fn.null_json.html" title="fn operator::statement::semantic_graph::null_json">null_<wbr>json</a><span title="Restricted Visibility">&nbsp;🔒</span> </dt><dd>A NULL literal typed as JSONB storage (<code>Binary</code>), so branches without a JSON
value union-align with branches that produce one.</dd><dt><a class="fn" href="fn.parse_json_expr.html" title="fn operator::statement::semantic_graph::parse_json_expr">parse_<wbr>json_<wbr>expr</a><span title="Restricted Visibility">&nbsp;🔒</span> </dt><dd>Parses a JSON text expression into a JSONB value, cast from the UDF’s
<code>BinaryView</code> output to <code>Binary</code> — the storage type the computed tables’
declared <code>json</code> columns map to in Arrow.</dd><dt><a class="fn" href="fn.qcol.html" title="fn operator::statement::semantic_graph::qcol">qcol</a><span title="Restricted Visibility">&nbsp;🔒</span> </dt><dd>A column reference qualified by a join-side alias, built without string
parsing (so column names containing <code>.</code> or <code>"</code> stay verbatim).</dd><dt><a class="fn" href="fn.registry_source.html" title="fn operator::statement::semantic_graph::registry_source">registry_<wbr>source</a><span title="Restricted Visibility">&nbsp;🔒</span> </dt><dd>Projects all entity declarations of one source table with one source scan.</dd><dt><a class="fn" href="fn.sorted_kv_expr_with.html" title="fn operator::statement::semantic_graph::sorted_kv_expr_with">sorted_<wbr>kv_<wbr>expr_<wbr>with</a><span title="Restricted Visibility">&nbsp;🔒</span> </dt><dd>Renders pre-sorted columns as a <code>k=v,k=v</code> concatenation. <code>nullable</code>
coalesces each value to <code>''</code> (id columns are tags and non-null; scope
columns carry no such guarantee).</dd><dt><a class="fn" href="fn.union_all.html" title="fn operator::statement::semantic_graph::union_all">union_<wbr>all</a><span title="Restricted Visibility">&nbsp;🔒</span> </dt><dd>Folds union branches without requiring a non-empty input.</dd></dl></section></div></main></body></html>