版本：1.3

semantic_relationships

semantic_relationships 是语义图的边集合：实体之间带类型、有时间范围的关系。

这张表是计算出来的，不是存储的。扫描它时，会配对 trace span、根据声明表同一行中的实体身份派生关系，并把结果与 semantic_relationships_declared 的行 union 起来。它是只读的：INSERT、CREATE、ALTER、TRUNCATE、DROP 都会被拒绝。

SELECT src_id, dst_id, rel_type, provenance, request_count, error_count
FROM greptime_private.semantic_relationships
WHERE observed_at >= now() - INTERVAL '15' MINUTE
ORDER BY dst_id;

四个时间列对派生边和声明边含义不同：

列	派生边	声明边
`observed_at`	观测到该边的 60 秒时间桶	边的生效起点与查询窗口下界中较晚的那个
`window_start`	该时间桶的起点	`valid_from`，为 `NULL` 时取声明时间
`window_end`	`window_start` + 60 秒	`valid_until`，为 `NULL` 时取查询窗口的上界
`fresh_until`	等于 `window_end`	等于 `window_end`

也就是说，声明边覆盖的是它的整个有效期，而不是一个 60 秒时间桶，其 window_start、window_end、fresh_until 在读取时计算。semantic_relationships_declared 里这三列写入的值不会被使用。

列	类型	说明
`observed_at`	`TimestampMillisecond`	时间索引，含义见上表。
`window_start`	`TimestampMillisecond`	该行覆盖窗口的起点。
`window_end`	`TimestampMillisecond`	该窗口的终点。
`fresh_until`	`TimestampMillisecond`	该边被视为有效的截止时间。
`src_type`	`String`	源端类型。
`src_id`	`String`	源端的规范化 id。
`dst_type`	`String`	目标端类型。
`dst_id`	`String`	目标端的规范化 id。
`rel_type`	`String`	关系类型：`calls`、`runs_on`、`contains`、`part_of`、`uses`、`invokes`、`depends_on`、`owns`，或声明边上的自定义值。方向为 `src` → `dst`。
`provenance`	`String`	边的来源方式：`trace`（配对的 span）、`attribute`（同一行上的两个身份）、`declared`（人工断言）、`agent`（agent 推断）。
`confidence`	`Float64`	派生的确定程度。配对成功的边为 `1.0`，虚拟节点边为 `0.5`；声明边原样保留插入的值，包括 `NULL`。预期取值范围是 `[0, 1]`，对声明边不做强制校验。它不修正 trace 采样带来的偏差。
`request_count`	`Int64`	窗口内的请求数，仅 `calls` 边。
`unmatched_count`	`Int64`	该边上没有匹配到 server span 的 client span 数量。声明边恒为 `NULL`。
`error_count`	`Int64`	窗口内的错误请求数。
`duration_sum`	`Float64`	请求耗时之和，单位为秒。
`duration_count`	`Int64`	参与求和的耗时个数。
`duration_max`	`Float64`	与 `duration_sum` 同一批样本中最长的单次请求耗时，单位为秒。声明边恒为 `NULL`。
`attributes`	`Json`	边的属性，例如 `{"connection_type":"database"}`。

provenance 是边身份的一部分，因此同一对端点上人工声明的边和派生出的边作为两行共存。

observed_at 谓词决定派生范围。没有谓词时使用最近一小时；没有下界的谓词会报错。见查询窗口。

派生以发起查询的用户身份执行。调用者读不到的源表会被排除，由 join 派生的边要求对参与 join 的每张表都有读权限。

semantic_relationships_declared

semantic_relationships_declared 是一张物理表，存放你自己断言的边，它的行会 union 进 semantic_relationships。GreptimeDB 在首次 INSERT 时按规范 schema 创建它，并拒绝用户的 CREATE 和 ALTER；INSERT、DELETE、DROP 允许。TTL 为 90 天。

它的列与 semantic_relationships 相同，去掉 unmatched_count 和 duration_max，并增加：

列	类型	说明
`valid_from`	`TimestampMillisecond`	业务有效期起点。`NULL` 表示自声明起有效。
`valid_until`	`TimestampMillisecond`	业务有效期终点。`NULL` 表示只要行存在就有效。
`scope`	`String`	边所属的命名空间或环境。属于主键，计算表不暴露该列。
`generation_id`	`String`	自由格式的代次标记。属于主键，计算表不暴露该列。

主键为 (src_type, src_id, rel_type, dst_type, dst_id, provenance, scope, generation_id)，时间索引为 observed_at。用相同主键再次插入会存入新版本，读取时保留截至查询窗口上界的最新版本。

window_start、window_end、fresh_until 存在于这张表只是为了与计算表保持 schema 对称。读取时会根据 valid_from 和 valid_until 重新计算，写入这三列不产生任何效果。confidence 和 RED 各列则原样透传。

用法见人工声明边。

semantic_relationships

semantic_relationships_declared​

semantic_relationships_declared