semantic_entities

semantic_entities is the node set of the semantic graph: the entities that the stored telemetry describes.

The table is computed, not stored. Scanning it derives rows at read time, within the queried time window, from every table that contributes an entity declaration — set through greptime.semantic.entity.* options or resolved from a built-in convention. Built-in conventions let OTLP trace tables, target_info, and kube-state-metrics descriptors contribute convention-defined entities without carrying an explicit greptime.semantic.entity.* option for those entities. It is read-only: INSERT, CREATE, ALTER, TRUNCATE, and DROP are rejected.

SELECT entity_type, entity_id, scope, source_tables
FROM greptime_private.semantic_entities
WHERE observed_at >= now() - INTERVAL '15' MINUTE
ORDER BY entity_type, entity_id;

Column	Type	Description
observed_at	TimestampMillisecond	Time index. The 60-second bucket the entity was observed in.
window_start	TimestampMillisecond	Start of the observation window.
window_end	TimestampMillisecond	End of the window (window_start + 60 seconds).
fresh_until	TimestampMillisecond	Time up to which the entity counts as present. Equals window_end for derived rows.
entity_type	String	The entity's type, for example service, service.instance, host, k8s.pod, gen_ai.agent.
entity_id	String	Canonical identifier: the identifying column values in declared order, escaped and joined with ,.
entity_id_attrs	Json	The identifying attributes as an object, keyed by the columns they came from.
scope	String	Namespace or environment the id is scoped to. Empty when the declaration names no scope column.
descriptive	Json	Snapshot of the declared non-identifying attributes. NULL when none were declared.
source_tables	Json	Array of the telemetry tables that contributed this observation, as schema.table.

A row is one entity observation from one contributing table in one window, so an entity declared by several tables produces several rows per window. Deduplicate with SELECT DISTINCT entity_type, entity_id.

The observed_at predicate bounds the derivation. Without one, the last hour is used; a predicate with no lower bound is an error. See The query window.

Derivation runs with the querying user's permissions. Source tables the caller cannot read are excluded.