query_semantic_graph
Explore entities and relationships in a semantic graph over a time window. Use summary to discover types, then query entities or relationships by type or id.
Instructions
Query the semantic graph: which entities exist and which are related.
Use view=summary when the entity and relationship types in this graph are
not known yet; it reports them with the endpoint type pairs each
relationship connects. With a type or an id already in hand, query
entities or relationships directly.
The window is required and half-open, [start_time, end_time), over
observed_at -- the 60-second bucket an observation was recorded in. Rows
are aggregated across the buckets in the window, and the result echoes the
window and the limit it used.
relationships returns one row per edge per confidence. The database reports
confidence 1.0 for a bucket whose client and server spans paired and 0.5
for one where only the client was seen, and it switches request_count,
error_count and the durations to whichever population that bucket
describes: paired requests timed by the server span, or unmatched clients
timed by their own. An edge observed both ways therefore comes back as two
rows. unmatched_count reports client spans with no paired server span.
Durations are in seconds.
entities returns one row per distinct set of attributes, so an entity whose
descriptive attributes changed inside the window appears more than once;
item_count counts rows, not entities. first_seen and last_seen bound where
the row was observed inside this window, not when the entity first existed.
Ordering is by type and endpoint. Only `calls` edges carry request, error
and duration counts, so pass rel_type=calls to order by error and request
count instead. When complete is false, more rows matched than the limit and
later types may be absent entirely rather than merely cut short.
A missing edge is not evidence that two entities are unrelated: it can also
mean the call was not instrumented, was sampled out, or fell outside this
window. Entities are not deduplicated across identity schemes, so one
process can appear under two ids if two sources named it differently.
entity_id_attrs names the attributes an id was assembled from and
source_tables names the telemetry tables that witnessed it. Identifiers
from alerts and other tools are not graph ids unless a query here returned
that exact string.
When masking is on, a returned field is hidden if its own name matches a
sensitive pattern, and an attribute map is also masked by the names inside
it. entities additionally hides entity_id when a masked attribute helped
build it; relationships cannot do the same, because its view does not carry
attribute names, so such a value can still appear there as src_id or
dst_id.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| view | Yes | summary: which entity and relationship types exist and what they connect. entities: the nodes. relationships: the edges. | |
| limit | No | Maximum rows to return. | |
| scope | No | entities only: the namespace or environment an id is scoped to. | |
| dst_id | No | relationships only: a canonical destination id this graph returned. | |
| src_id | No | relationships only: a canonical source id this graph returned. | |
| dst_type | No | relationships only: destination endpoint type. | |
| end_time | Yes | Exclusive end of the window, RFC3339. | |
| rel_type | No | relationships only: calls, runs_on, contains, part_of, uses, invokes, depends_on, owns, or a custom declared value. | |
| src_type | No | relationships only: source endpoint type. | |
| entity_id | No | entities only: a canonical id this graph returned. | |
| provenance | No | relationships only: how the edge was obtained -- trace (paired spans), attribute (identities on one row), declared, or agent. | |
| start_time | Yes | Inclusive start of the window, RFC3339, e.g. 2026-09-05T07:00:00Z. Without an offset it is read as UTC. | |
| entity_type | No | entities only: service, k8s.pod, host, ... |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |