TABLE_SEMANTICS
注意
TABLE_SEMANTICS 视图目前处于实验阶段，未来版本可能会发生变化。
TABLE_SEMANTICS 提供 GreptimeDB 表语义的查询入口。一张表设置了至少一个 greptime.semantic.* 选项，或者内置约定为它派生出实体声明时，会出现在该视图中；其余的表不会出现。
语义选项标识一张表所代表的可观测性概念，使下游工具（LLM agent、告警与仪表盘生成器、ETL）无需依赖列名推断即可识别表的用途。语义选项有两种设置方式：
- 摄入时自动设置。 OTLP、Prometheus remote write 等路径在自动建表时写入相应的 key。
- 建表时手动设置。 在
CREATE TABLE ... WITH (...)中指定。仅接受白名单内、取值合法的 key；未知 key 或超出取值范围的值会被拒绝。
CREATE TABLE my_metrics (
ts TIMESTAMP TIME INDEX,
val DOUBLE
) WITH (
'greptime.semantic.signal_type' = 'metric',
'greptime.semantic.source' = 'opentelemetry',
'greptime.semantic.metric.type' = 'counter'
);
signal_type、source、source_version、pipeline、metadata_quality 被提升为独立列，可直接用于过滤。其余选项合并到 semantic_options JSON 字符串中，并去掉各自的 greptime.semantic. 前缀。
DESC TABLE information_schema.table_semantics;
输出如下：
+---------------------+--------+-----+------+---------+---------------+
| Column | Type | Key | Null | Default | Semantic Type |
+---------------------+--------+-----+------+---------+---------------+
| table_catalog | String | | NO | | FIELD |
| table_schema | String | | NO | | FIELD |
| table_name | String | | NO | | FIELD |
| table_id | UInt32 | | NO | | FIELD |
| signal_type | String | | YES | | FIELD |
| source | String | | YES | | FIELD |
| source_version | String | | YES | | FIELD |
| pipeline | String | | YES | | FIELD |
| metadata_quality | String | | YES | | FIELD |
| semantic_options | String | | YES | | FIELD |
| entity_declarations | String | | YES | | FIELD |
+---------------------+--------+-----+------+---------+---------------+
列说明
table_catalog：表所在的 catalog 名称。table_schema：表所在的 schema 名称。table_name：表名。table_id：内部表 ID。signal_type：表所属的遥测信号类型，取值为以下之一：metric—— 指标。trace—— 链路（span）。log—— 日志。event—— 离散事件。预留值：取值合法、可手动设置，但当前没有摄入路径会自动设置该值；自动设置的取值仅为metric、log、trace。unknown—— 设置时无法确定。
source：写入数据的来源生态，取值为opentelemetry、prometheus、influxdb、opentsdb、elasticsearch、loki、custom、mixed、unknown之一。mixed表示同一张表接收了多个来源的数据，unknown表示无法确定。source_version：来源协议的版本 。Prometheus remote write 路径会写入1.0或2.0，其他路径为空。pipeline：内部摄入数据模型的标识，自由格式字符串。当前仅 OTLP trace 路径会自动设置，根据所选 pipeline 取值为greptime_trace_v1或greptime_trace_v2；其他取值需手动设置。它是table_data_model的后继选项，不依赖具体信号类型。metadata_quality：metric.type标注的来源，即其可信程度，取值为以下之一：declared—— 摄入协议显式提供了 instrument 类型（如 OTLP 指标自带类型），可信。inferred—— 类型由指标名推断得到（如 Prometheus 的_total后缀被识别为 counter），对命名不规范的指标可能不准确。unknown—— 无法确定。
semantic_options：JSON 字符串，包含未被提升为列的其余语义选项，各 key 去掉greptime.semantic.前缀。key 按字典序排列，因此多次查询的输出保持稳定。具体 key 见下文 semantic_options 的 key。entity_declarations：JSON 数组，是该表向语义图贡献的实体身份，由它的greptime.semantic.entity.*选项和内置约定解析而来。没有任何贡献时为NULL。见下文实体声明。
semantic_options 的 key
以下 key 可能出现在 semantic_options 中。它们仅对特定信号有意义，因此保留在 JSON 中，未提升为独立列。表上原始的 entity.<type>.{id|descriptive|scope} 选项也出现在这里，entity_declarations 是它们解析后的形式。
metric.type：instrument 类型，取值为counter、gauge、histogram、summary、updown_counter、gauge_histogram、info、stateset、mixed、unknown之一。mixed表示同一张表中包含多种 instrument 类型。metric.unit：UCUM 格式的单位，如s、By、{request}。单位在行编码阶段被丢弃，数据写入后无法从中恢复。metric.temporality：聚合时间性（temporality，仅 OTLP），取值为cumulative、delta、mixed、unknown之一。该信息不体现在指标名中，仅凭表本身无法恢复。metric.original_name：翻译前的 OpenTelemetry 指标名，在表名被转换为 Prometheus 风格时记录。下游可据此在 OpenTelemetry 语义约定中反查该指标。trace.conventions：行数据所遵循的语义约定版本，通常为 OpenTelemetry schema URL，如https://opentelemetry.io/schemas/1.27.0，也可能为unknown/mixed。
unknown 与 mixed 是两个通用的哨兵值：unknown 表示设置时无法确定取值；mixed 表示一个本应单值的 key 在表的生命周期内出现了相互冲突的多个取值。
实体声明
entity_declarations 报告一张表向语义图贡献的实体，无论来自表选项还是内置约定。数组的每个元素包含以下字段：
entity_type：声明的实体类型，例如service、k8s.pod。origin：declared表示来自greptime.semantic.entity.*表选项，convention表示来自内置规则。id：标识列，按声明顺序排列。顺序是实体身份的一部分。id_qualifier：限定第一个标识分量的列，由把命名空间折进 id 的约定使用。未使用时不出现。superseded_by：更具体实体类型的标识列；行上带齐这些列时由该类型接管。未使用时不出现。descriptive：作为非标识属性快照的列。为空时不出现。scope：作为实体命名空间或环境暴露的列。为空时不出现。
声明的设置方式和约定的生效规则见声明实体与关系。
示例
查询语义元数据：
SELECT table_schema, table_name, signal_type, source, source_version, pipeline, metadata_quality, semantic_options
FROM information_schema.table_semantics
ORDER BY table_name;
输出示例：
+--------------+----------------+-------------+---------------+----------------+--------------------+------------------+-----------------------------------------------------------------+
| table_schema | table_name | signal_type | source | source_version | pipeline | metadata_quality | semantic_options |
+--------------+----------------+-------------+---------------+----------------+--------------------+------------------+-----------------------------------------------------------------+
| public | metrics_tagged | metric | opentelemetry | 2.0 | greptime_metric_v1 | declared | {"metric.type":"counter","metric.unit":"By"} |
| public | traces_tagged | trace | opentelemetry | | | | {"trace.conventions":"https://opentelemetry.io/schemas/1.27.0"} |
+--------------+----------------+-------------+---------------+----------------+--------------------+------------------+-----------------------------------------------------------------+
列出向语义图贡献声明的表：
SELECT table_name, entity_declarations
FROM information_schema.table_semantics
WHERE entity_declarations IS NOT NULL;
对一张 OTLP trace 表，service 由接入路径写入，其余来自内置约定：
[
{"entity_type": "container", "origin": "convention", "id": ["resource_attributes.container.id"]},
{"entity_type": "service", "origin": "declared", "id": ["service_name"]},
{"entity_type": "service.instance", "origin": "convention",
"id": ["service_name", "resource_attributes.service.instance.id"],
"id_qualifier": "resource_attributes.service.namespace"}
]
直接对提升的列进行过滤：
SELECT table_name, signal_type
FROM information_schema.table_semantics
WHERE signal_type = 'metric'
ORDER BY table_name;
+----------------+-------------+
| table_name | signal_type |
+----------------+-------------+
| metrics_tagged | metric |
+----------------+-------------+