Module semantic_graph 

The entity-relationship graph: the physical declared-edge table DDL and the typed DataFusion plan builders for the read-time derivation behind the computed semantic_entities / semantic_relationships tables.

In OSS the graph is derived at read time, so the only stored part is the declared-edge table: edges a user asserts by hand (provenance = 'declared').

The derivation is built as typed [Expr]s over [DataFrame]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 docs/rfcs/2026-06-25-entity-relationships-and-graph-query.md.

Modules

conventions 🔒

The built-in derivation conventions of the entity graph, embedded as conventions.yaml: the co-declared edge vocabulary, the virtual-destination candidates, and the implicit declarations of well-known Prometheus entity-descriptor metrics. The file is data shipped with the binary, not an operator-editable configuration surface; explicit greptime.semantic.entity.* declarations always override it.

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.

Conventions

The parsed, validated conventions file.

DeclaredSource

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

EntityDeclaration

A single table’s entity-identity declaration, projected from information_schema.table_semantics (greptime.semantic.entity.<type>.*).

GraphQueryWindow

The read-time query window, resolved from the scan’s observed_at predicate (or the product default). Two half-open [start, end) millisecond ranges:

ImplicitEntity

One implicit entity declaration: of a whitelisted Prometheus or OTel info metric, or of a trace-v1 table’s flattened resource attributes.

RegistrySource

A declaring table’s scan paired with the entity declarations it carries — the unit build_registry_plan derives registry rows from.

RelationshipSources

Everything build_relationships_plan derives edges from.

Constants

BIN_NANOS 🔒

Bin width for the temporal window of derived rows, matching the service-graph convention. Shared so ingestion-synthesized observations land in the same buckets.

DECLARED_EDGE_IDENTITY_COLUMNS 🔒

The externally visible edge identity: the primary key minus scope and generation_id, which the computed table does not expose. Revision ranking uses this identity, or assertions differing only in those two columns would surface as indistinguishable duplicate rows.

DECLARED_PRIMARY_KEY_COLUMNS

The primary-key (tag) columns, in key order. Starting with the source endpoint makes out-edge lookup (WHERE src_type=? AND src_id=?) a key-prefix scan; provenance and generation_id are in the key so a declared edge and a (future) derived edge for the same pair coexist without clobbering.

DECLARED_RELATIONSHIPS_TTL_ENV 🔒

Environment variable overriding the declared-edge table’s TTL at creation time (e.g. 180d, forever).

DEFAULT_DECLARED_RELATIONSHIPS_TTL 🔒

Default retention for the declared-edge table; expiry slides the topology window.

ENTITY_TYPE_GEN_AI_AGENT

ENTITY_TYPE_GEN_AI_MODEL

ENTITY_TYPE_GEN_AI_TOOL

ENTITY_TYPE_HOST

ENTITY_TYPE_K8S_CONTAINER

ENTITY_TYPE_K8S_NODE

ENTITY_TYPE_K8S_POD

ENTITY_TYPE_K8S_WORKLOAD

ENTITY_TYPE_PROCESS

ENTITY_TYPE_SERVICE

The built-in entity-type vocabulary. User-declared types are open-ended; the embedded conventions file must stay inside this set.

ENTITY_TYPE_SERVICE_INSTANCE

ID_ESCAPE 🔒

ID_QUALIFIER_SEPARATOR 🔒

Left unescaped: <namespace>/<name> is how Prometheus renders job.

ID_SEPARATOR 🔒

PROVENANCE_AGENT

PROVENANCE_ATTRIBUTE

PROVENANCE_DECLARED

PROVENANCE_TRACE

REGISTRY_COLUMNS 🔒

REGISTRY_VALID_COLUMN 🔒

REL_TYPE_CALLS

The relationship vocabulary (the RFC’s rel_type table) and the edge provenances.

REL_TYPE_CONTAINS

REL_TYPE_DEPENDS_ON

REL_TYPE_INVOKES

REL_TYPE_OWNS

REL_TYPE_PART_OF

REL_TYPE_RUNS_ON

REL_TYPE_USES

Statics

JSON_OBJECT_UDF 🔒

The json_object UDF, resolved like PARSE_JSON_UDF. It assembles the JSONB binary directly from the value columns, so runtime values need no JSON text escaping.

PARSE_JSON_UDF 🔒

The parse_json UDF, shared by all derivation plans. Resolved from the global registry once: the UDF is stateless (its FunctionContext is unused).

Functions

bin_interval 🔒

bin_ms 🔒

date_bin(60s, ts) cast to millisecond precision, so the output schema is deterministic regardless of the source column’s precision (trace tables are nanosecond, metric tables millisecond).

build_declared_relationships_expr

Builds the CREATE TABLE request for the declared-edge table. Columns mirror the computed semantic_relationships shape (temporal window + endpoints + provenance/confidence + RED metrics) plus the declared-only business validity window (valid_from / valid_until), which — unlike TTL (physical retention) — expresses whether a hand-declared edge is still in effect.

build_registry_plan

Builds the semantic_entities registry plan: one branch and source scan per declaring table, filtered to window, then UNION ALL across source tables. Returns None when nothing declared an entity, so the computed table streams empty.

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.

cast_string_or_empty 🔒

coalesce(CAST(column AS STRING), ''): renders a nullable column for string concatenation without collapsing the result to NULL.

column 🔒

concat_expr 🔒

conventions

The embedded conventions. Err means the embedded file is broken — pinned by unit test, and propagated by the derivation paths rather than panicking.

declaration_predicate 🔒

The row-level guard a declaration carries: every identity component present, and the superseding type’s identity not complete. Every branch that turns a declaration into rows applies this, so the guard cannot drift between them.

declared_relationships_schema_matches

Whether an existing declared-edge table still matches the canonical definition (build_declared_relationships_expr): columns, time index, primary key, engine, and merge behaviour — the union branch’s revision and dedup semantics lean on all of these. A mismatch (upgrade skew) must be surfaced, not silently derived wrong; DROP resets the table.

declared_relationships_ttl 🔒

entity_id_expr 🔒

The identity values in declared order (broad to narrow), escaped and joined.

escaped_id_value 🔒

Escapes so a composite id decodes back to its components. The escape character goes first, or it would double the escapes the separator pass introduces.

field 🔒

identifies 🔒

A row identifies an entity only when every identity component is present and non-empty: kube-state-metrics descriptors emit empty-string labels (an unscheduled pod’s node, an owner-less pod’s owner_*), and an empty string is never a meaningful entity id. The qualifier is optional by construction and so is not guarded.

interval 🔒

An INTERVAL literal of nanos nanoseconds.

json_field 🔒

json_object_expr 🔒

Builds a JSONB object with one entry per column: key = the column name, value = the column rendered as a string, NULL coalesced to "" so one NULL column does not null the entry (descriptive columns are nullable). Keys come out sorted — JSONB objects are key-ordered regardless of input order.

json_quote 🔒

Renders a compile-time-known string as JSON text (quoted, fully escaped).

null_json 🔒

A NULL literal typed as JSONB storage (Binary), so branches without a JSON value union-align with branches that produce one.

parse_json_expr 🔒

Parses a JSON text expression into a JSONB value, cast from the UDF’s BinaryView output to Binary — the storage type the computed tables’ declared json columns map to in Arrow.

qcol 🔒

A column reference qualified by a join-side alias, built without string parsing (so column names containing . or " stay verbatim).

qualified_id_expr 🔒

<qualifier>/<value>, or bare value when the qualifier is empty on this row — the spec’s rule composing job from service.namespace and service.name.

registry_source 🔒

Projects all entity declarations of one source table with one source scan via unnest_rows.

sorted_kv_expr_with 🔒

Renders pre-sorted columns as a k=v,k=v concatenation. nullable coalesces each value to '' (id columns are tags and non-null; scope columns carry no such guarantee).

tag 🔒

ts_ms_lit 🔒

union_all 🔒

Folds union branches without requiring a non-empty input.

unnest_rows 🔒

Expands one source row into one output row per entry of rows with a single source scan: each output field is first built as an array whose entries correspond to the rows, then unnested. Every row is [valid, values...] aligned with columns; rows whose valid expression is false are dropped, and the distinct output columns are columns.