Module semantic 

Table semantic layer vocabulary.

A thin layer of semantic metadata attached to a table via table_options, so machine consumers (LLM agents, alert/dashboard builders, MCP servers, ETL) can align a table with the observability concept it stands for without guessing from column names. See docs/rfcs/2026-05-28-table-semantic-layer.md.

The vocabulary is intentionally small: a key earns its place only when it records something a consumer cannot cheaply and reliably recover from the schema/data itself. Keys whose value is already in the metric name by convention, is a constant, or duplicates an existing column are deliberately omitted rather than stamped for completeness.

All public keys share the SEMANTIC_PREFIX namespace and are string-valued. is_semantic_option_key gates them through crate::requests::validate_table_option, so they are accepted both on the ingestion auto-create path and on explicit CREATE TABLE ... WITH (...) DDL.

Constants

METADATA_QUALITY_DECLARED

METADATA_QUALITY_INFERRED

SEMANTIC_METRIC_METADATA_QUALITY

METADATA_QUALITY_DECLARED when the protocol stated the type, or METADATA_QUALITY_INFERRED when guessed from a name suffix.

SEMANTIC_METRIC_ORIGINAL_NAME

Pre-translation OTel name when the table name was Prometheus-ised; the key a consumer uses to look the metric up in the OTel semantic conventions.

SEMANTIC_METRIC_TEMPORALITY

cumulative / delta (OTel only). Invisible in the metric name, so it is unrecoverable from the table alone.

SEMANTIC_METRIC_TYPE

Instrument kind: counter / gauge / histogram / summary / updown_counter / gauge_histogram / info / stateset.

SEMANTIC_METRIC_UNIT

UCUM unit, e.g. s, By, {request}. Discarded by the row encoders, so it is unrecoverable once ingested.

SEMANTIC_OPTION_KEYS

Every recognised public semantic table-option key. The set is a closed whitelist: keys under SEMANTIC_PREFIX that are not listed here are rejected, so an unknown key like greptime.semantic.unknown_key does not silently land in a table’s options. Adding a key to the vocabulary means adding it here.

SEMANTIC_PER_TABLE_INDEX_KEY

Internal QueryContext extension key carrying the per-table semantic index (a {table_name -> {semantic_key: value}} JSON blob) from the ingestion encode path to the auto-create site. Deliberately OUTSIDE SEMANTIC_PREFIX so it is not a valid table option and never leaks into a table’s options.

SEMANTIC_PIPELINE

Internal ingestion pipeline / data model, e.g. greptime_trace_v1. The signal-agnostic successor to the engine-specific table_data_model option.

SEMANTIC_PREFIX

Reserved prefix for every public semantic table-option key.

SEMANTIC_SIGNAL_TYPE

Signal kind: one of SIGNAL_TYPE_TRACE / SIGNAL_TYPE_LOG / SIGNAL_TYPE_METRIC / SIGNAL_TYPE_EVENT.

SEMANTIC_SOURCE

Ingestion ecosystem, e.g. SOURCE_OPENTELEMETRY / SOURCE_PROMETHEUS.

SEMANTIC_TRACE_CONVENTIONS

Semantic-conventions version the rows conform to (e.g. the OTel schema URL), or SEMANTIC_VALUE_UNKNOWN / SEMANTIC_VALUE_MIXED when not single-valued.

SEMANTIC_VALUE_MIXED

Sentinel for a single-valued key that saw conflicting sources.

SEMANTIC_VALUE_UNKNOWN

Sentinel for a key that cannot be determined at stamp time.

SIGNAL_TYPE_EVENT

SIGNAL_TYPE_LOG

SIGNAL_TYPE_METRIC

SIGNAL_TYPE_TRACE

SOURCE_ELASTICSEARCH

SOURCE_INFLUXDB

SOURCE_LOKI

SOURCE_OPENTELEMETRY

SOURCE_OPENTSDB

SOURCE_PROMETHEUS

Functions

is_semantic_option_key

Returns true if key is a recognised semantic table-option key (whitelist).

validate_semantic_option

Validates a greptime.semantic.* option’s value against its allowed domain.