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.

Enums

EntityRole

The role a set of columns plays for an entity: id (identifying attributes), descriptive, or scope. Columns may be tags or fields; DDL validation only requires that they exist and render as stable strings (has_stable_string_form).

Constants

METADATA_QUALITY_DECLARED

METADATA_QUALITY_INFERRED

SEMANTIC_ENTITY_PREFIX

Reserved prefix for the entity-identity sub-namespace: greptime.semantic.entity.<type>.{id|descriptive|scope}. Unlike the rest of the vocabulary (a closed whitelist), entity types are open-ended (service, host, k8s.pod, process, agent, custom, …), so keys here are validated by prefix + shape rather than membership. See docs/rfcs/2026-06-25-entity-relationships-and-graph-query.md.

SEMANTIC_ENTITY_SERVICE_ID

The well-known entity-identity key auto-stamped on OTLP trace tables; its value is the service_name tag column, declaring the logical service entity.

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_SOURCE_VERSION

Source protocol version, e.g. Prometheus remote write 1.0 / 2.0.

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

has_stable_string_form

Returns true if a column of data_type renders as a stable string — the requirement for entity id/descriptive/scope columns. The read-time derivation casts them to strings, so a type without a stable string form would fail only when the graph is scanned; DDL validation rejects it up front instead.

is_entity_option_key

Returns true if key is a well-formed entity-identity option key.

is_semantic_option_key

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

is_valid_entity_type 🔒

Returns true if ty is a syntactically valid entity type, e.g. service, host, k8s.pod, service.instance. An entity type is one or more dot-separated segments, each a non-empty [a-z0-9_]+ token. The dotted form carries the two-entity-layer convention (service vs service.instance).

parse_entity_columns

Tokenizes an entity option’s comma-separated column list (trimmed, empty tokens dropped). validate_semantic_option rejects empty tokens at DDL time, so readers only ever drop what validation already refused.

parse_entity_option_key

Parses a well-formed entity-identity option key of the shape greptime.semantic.entity.<type>.{id|descriptive|scope} into (entity_type, role). The <type> may itself contain dots; the role is the final dot-separated segment. This is the single parser of the key format — DDL validation and the read-time derivation both go through it.

validate_semantic_option

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