table/requests/
semantic.rs

1// Copyright 2023 Greptime Team
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! Table semantic layer vocabulary.
16//!
17//! A thin layer of semantic metadata attached to a table via `table_options`, so
18//! machine consumers (LLM agents, alert/dashboard builders, MCP servers, ETL) can
19//! align a table with the observability concept it stands for without guessing
20//! from column names. See `docs/rfcs/2026-05-28-table-semantic-layer.md`.
21//!
22//! The vocabulary is intentionally small: a key earns its place only when it
23//! records something a consumer cannot cheaply and reliably recover from the
24//! schema/data itself. Keys whose value is already in the metric name by
25//! convention, is a constant, or duplicates an existing column are deliberately
26//! omitted rather than stamped for completeness.
27//!
28//! All public keys share the [`SEMANTIC_PREFIX`] namespace and are string-valued.
29//! [`is_semantic_option_key`] gates them through
30//! [`crate::requests::validate_table_option`], so they are accepted both on the
31//! ingestion auto-create path and on explicit `CREATE TABLE ... WITH (...)` DDL.
32
33/// Reserved prefix for every public semantic table-option key.
34pub const SEMANTIC_PREFIX: &str = "greptime.semantic.";
35
36/// Internal `QueryContext` extension key carrying the per-table semantic index
37/// (a `{table_name -> {semantic_key: value}}` JSON blob) from the ingestion
38/// encode path to the auto-create site. Deliberately OUTSIDE [`SEMANTIC_PREFIX`]
39/// so it is not a valid table option and never leaks into a table's options.
40pub const SEMANTIC_PER_TABLE_INDEX_KEY: &str = "greptime.internal.semantic.per_table_index";
41
42// ---- Common keys (all signals) ----
43
44/// Signal kind: one of [`SIGNAL_TYPE_TRACE`] / [`SIGNAL_TYPE_LOG`] /
45/// [`SIGNAL_TYPE_METRIC`] / [`SIGNAL_TYPE_EVENT`].
46pub const SEMANTIC_SIGNAL_TYPE: &str = "greptime.semantic.signal_type";
47/// Ingestion ecosystem, e.g. [`SOURCE_OPENTELEMETRY`] / [`SOURCE_PROMETHEUS`].
48pub const SEMANTIC_SOURCE: &str = "greptime.semantic.source";
49/// Internal ingestion pipeline / data model, e.g. `greptime_trace_v1`. The
50/// signal-agnostic successor to the engine-specific `table_data_model` option.
51pub const SEMANTIC_PIPELINE: &str = "greptime.semantic.pipeline";
52
53// ---- Trace keys ----
54
55/// Semantic-conventions version the rows conform to (e.g. the OTel schema URL),
56/// or [`SEMANTIC_VALUE_UNKNOWN`] / [`SEMANTIC_VALUE_MIXED`] when not single-valued.
57pub const SEMANTIC_TRACE_CONVENTIONS: &str = "greptime.semantic.trace.conventions";
58
59// ---- Metric keys ----
60
61/// Instrument kind: `counter` / `gauge` / `histogram` / `summary` /
62/// `updown_counter` / `gauge_histogram` / `info` / `stateset`.
63pub const SEMANTIC_METRIC_TYPE: &str = "greptime.semantic.metric.type";
64/// UCUM unit, e.g. `s`, `By`, `{request}`. Discarded by the row encoders, so it
65/// is unrecoverable once ingested.
66pub const SEMANTIC_METRIC_UNIT: &str = "greptime.semantic.metric.unit";
67/// `cumulative` / `delta` (OTel only). Invisible in the metric name, so it is
68/// unrecoverable from the table alone.
69pub const SEMANTIC_METRIC_TEMPORALITY: &str = "greptime.semantic.metric.temporality";
70/// [`METADATA_QUALITY_DECLARED`] when the protocol stated the type, or
71/// [`METADATA_QUALITY_INFERRED`] when guessed from a name suffix.
72pub const SEMANTIC_METRIC_METADATA_QUALITY: &str = "greptime.semantic.metric.metadata_quality";
73/// Pre-translation OTel name when the table name was Prometheus-ised; the key a
74/// consumer uses to look the metric up in the OTel semantic conventions.
75pub const SEMANTIC_METRIC_ORIGINAL_NAME: &str = "greptime.semantic.metric.original_name";
76
77// ---- Value constants ----
78
79pub const SIGNAL_TYPE_TRACE: &str = "trace";
80pub const SIGNAL_TYPE_LOG: &str = "log";
81pub const SIGNAL_TYPE_METRIC: &str = "metric";
82pub const SIGNAL_TYPE_EVENT: &str = "event";
83
84pub const SOURCE_OPENTELEMETRY: &str = "opentelemetry";
85pub const SOURCE_PROMETHEUS: &str = "prometheus";
86pub const SOURCE_INFLUXDB: &str = "influxdb";
87pub const SOURCE_OPENTSDB: &str = "opentsdb";
88pub const SOURCE_LOKI: &str = "loki";
89pub const SOURCE_ELASTICSEARCH: &str = "elasticsearch";
90
91pub const METADATA_QUALITY_DECLARED: &str = "declared";
92pub const METADATA_QUALITY_INFERRED: &str = "inferred";
93
94/// Sentinel for a key that cannot be determined at stamp time.
95pub const SEMANTIC_VALUE_UNKNOWN: &str = "unknown";
96/// Sentinel for a single-valued key that saw conflicting sources.
97pub const SEMANTIC_VALUE_MIXED: &str = "mixed";
98
99/// Every recognised public semantic table-option key. The set is a closed
100/// whitelist: keys under [`SEMANTIC_PREFIX`] that are not listed here are rejected,
101/// so an unknown key like `greptime.semantic.unknown_key` does not silently land
102/// in a table's options. Adding a key to the vocabulary means adding it here.
103pub const SEMANTIC_OPTION_KEYS: &[&str] = &[
104    SEMANTIC_SIGNAL_TYPE,
105    SEMANTIC_SOURCE,
106    SEMANTIC_PIPELINE,
107    SEMANTIC_TRACE_CONVENTIONS,
108    SEMANTIC_METRIC_TYPE,
109    SEMANTIC_METRIC_UNIT,
110    SEMANTIC_METRIC_TEMPORALITY,
111    SEMANTIC_METRIC_METADATA_QUALITY,
112    SEMANTIC_METRIC_ORIGINAL_NAME,
113];
114
115/// Returns true if `key` is a recognised semantic table-option key (whitelist).
116///
117/// Note this is membership, not a prefix test: unknown keys under
118/// [`SEMANTIC_PREFIX`] are rejected, and the internal
119/// [`SEMANTIC_PER_TABLE_INDEX_KEY`] (outside the prefix) never matches.
120pub fn is_semantic_option_key(key: &str) -> bool {
121    SEMANTIC_OPTION_KEYS.contains(&key)
122}
123
124/// Validates a `greptime.semantic.*` option's `value` against its allowed domain.
125///
126/// Open-value keys (unit, original_name, pipeline, conventions) accept any
127/// non-empty string. Closed-domain keys accept a fixed set, plus the `unknown`
128/// sentinel, plus `mixed` for the keys where one long-lived table can
129/// legitimately see multiple values. Keys not in [`SEMANTIC_OPTION_KEYS`] are
130/// rejected.
131pub fn validate_semantic_option(key: &str, value: &str) -> bool {
132    match key {
133        SEMANTIC_PIPELINE
134        | SEMANTIC_METRIC_UNIT
135        | SEMANTIC_METRIC_ORIGINAL_NAME
136        | SEMANTIC_TRACE_CONVENTIONS => !value.is_empty(),
137
138        SEMANTIC_SIGNAL_TYPE => matches!(value, "trace" | "log" | "metric" | "event" | "unknown"),
139        SEMANTIC_SOURCE => matches!(
140            value,
141            "opentelemetry"
142                | "prometheus"
143                | "influxdb"
144                | "opentsdb"
145                | "elasticsearch"
146                | "loki"
147                | "custom"
148                | "mixed"
149                | "unknown"
150        ),
151        SEMANTIC_METRIC_TYPE => matches!(
152            value,
153            "counter"
154                | "gauge"
155                | "histogram"
156                | "summary"
157                | "updown_counter"
158                | "gauge_histogram"
159                | "info"
160                | "stateset"
161                | "mixed"
162                | "unknown"
163        ),
164        SEMANTIC_METRIC_TEMPORALITY => {
165            matches!(value, "cumulative" | "delta" | "mixed" | "unknown")
166        }
167        SEMANTIC_METRIC_METADATA_QUALITY => matches!(value, "declared" | "inferred" | "unknown"),
168
169        _ => false,
170    }
171}
172
173#[cfg(test)]
174mod tests {
175    use super::*;
176
177    #[test]
178    fn test_is_semantic_option_key() {
179        assert!(is_semantic_option_key(SEMANTIC_SIGNAL_TYPE));
180        assert!(is_semantic_option_key(SEMANTIC_METRIC_TYPE));
181        assert!(is_semantic_option_key(SEMANTIC_PIPELINE));
182
183        // Unknown keys under the prefix are not whitelisted.
184        assert!(!is_semantic_option_key("greptime.semantic.future.key"));
185        assert!(!is_semantic_option_key("greptime.semantic.unknown_key"));
186        // Keys cut from the vocabulary are no longer accepted.
187        assert!(!is_semantic_option_key(
188            "greptime.semantic.metric.monotonic"
189        ));
190        assert!(!is_semantic_option_key(
191            "greptime.semantic.resource.attributes_dropped"
192        ));
193        // Near-misses must not match.
194        assert!(!is_semantic_option_key("greptime.semanticx"));
195        assert!(!is_semantic_option_key("semantic.signal_type"));
196        assert!(!is_semantic_option_key("table_data_model"));
197        // The internal transport key must never be treated as a table option.
198        assert!(!is_semantic_option_key(SEMANTIC_PER_TABLE_INDEX_KEY));
199    }
200
201    #[test]
202    fn test_validate_semantic_option() {
203        // Enum keys reject out-of-domain values.
204        assert!(validate_semantic_option(SEMANTIC_SIGNAL_TYPE, "metric"));
205        assert!(!validate_semantic_option(SEMANTIC_SIGNAL_TYPE, "spans"));
206        assert!(validate_semantic_option(SEMANTIC_METRIC_TYPE, "counter"));
207        assert!(validate_semantic_option(SEMANTIC_METRIC_TYPE, "mixed"));
208        assert!(!validate_semantic_option(SEMANTIC_METRIC_TYPE, "bogus"));
209
210        // Sentinels and open values.
211        assert!(validate_semantic_option(
212            SEMANTIC_METRIC_TEMPORALITY,
213            "unknown"
214        ));
215        assert!(validate_semantic_option(SEMANTIC_METRIC_UNIT, "By"));
216        assert!(!validate_semantic_option(SEMANTIC_METRIC_UNIT, ""));
217        assert!(validate_semantic_option(
218            SEMANTIC_PIPELINE,
219            "greptime_trace_v1"
220        ));
221
222        // A cut key validates to false regardless of value.
223        assert!(!validate_semantic_option(
224            "greptime.semantic.metric.monotonic",
225            "true"
226        ));
227        // Unknown key is rejected regardless of value.
228        assert!(!validate_semantic_option(
229            "greptime.semantic.future.key",
230            "x"
231        ));
232
233        // Drift guard: every value stamped by the ingestion path must validate.
234        assert!(validate_semantic_option(
235            SEMANTIC_SIGNAL_TYPE,
236            SIGNAL_TYPE_TRACE
237        ));
238        assert!(validate_semantic_option(
239            SEMANTIC_SIGNAL_TYPE,
240            SIGNAL_TYPE_METRIC
241        ));
242        assert!(validate_semantic_option(
243            SEMANTIC_SIGNAL_TYPE,
244            SIGNAL_TYPE_LOG
245        ));
246        assert!(validate_semantic_option(
247            SEMANTIC_SOURCE,
248            SOURCE_OPENTELEMETRY
249        ));
250        assert!(validate_semantic_option(SEMANTIC_SOURCE, SOURCE_PROMETHEUS));
251        assert!(validate_semantic_option(
252            SEMANTIC_METRIC_METADATA_QUALITY,
253            METADATA_QUALITY_INFERRED
254        ));
255        assert!(validate_semantic_option(
256            SEMANTIC_METRIC_METADATA_QUALITY,
257            METADATA_QUALITY_DECLARED
258        ));
259        assert!(validate_semantic_option(
260            SEMANTIC_TRACE_CONVENTIONS,
261            SEMANTIC_VALUE_UNKNOWN
262        ));
263        // An empty value never validates, for any whitelisted key.
264        for key in SEMANTIC_OPTION_KEYS {
265            assert!(
266                !validate_semantic_option(key, ""),
267                "empty value should never validate for {key}"
268            );
269        }
270    }
271}
table/requests/semantic.rs

table/requests/
semantic.rs
