greptimedb/table/requests/semantic/index.html

<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="Table semantic layer vocabulary."><title>table::requests::semantic - Rust</title><script>if(window.location.protocol!=="file:")document.head.insertAdjacentHTML("beforeend","SourceSerif4-Regular-6b053e98.ttf.woff2,FiraSans-Italic-81dc35de.woff2,FiraSans-Regular-0fe48ade.woff2,FiraSans-MediumItalic-ccf7e434.woff2,FiraSans-Medium-e1aa3f0a.woff2,SourceCodePro-Regular-8badfe75.ttf.woff2,SourceCodePro-Semibold-aa29a496.ttf.woff2".split(",").map(f=>`<link rel="preload" as="font" type="font/woff2"href="../../../static.files/${f}">`).join(""))</script><link rel="stylesheet" href="../../../static.files/normalize-9960930a.css"><link rel="stylesheet" href="../../../static.files/rustdoc-1ed95124.css"><meta name="rustdoc-vars" data-root-path="../../../" data-static-root-path="../../../static.files/" data-current-crate="table" data-themes="" data-resource-suffix="" data-rustdoc-version="1.98.1 (48a229cea 2026-09-01)" data-channel="1.98.1" data-search-js="search-9944d736.js" data-stringdex-js="stringdex-2da4960a.js" data-settings-js="settings-170eb4bf.js" ><script src="../../../static.files/storage-41dd4d93.js"></script><script defer src="../sidebar-items.js"></script><script defer src="../../../static.files/main-417ebf0a.js"></script><noscript><link rel="stylesheet" href="../../../static.files/noscript-f7c3ffd8.css"></noscript><link rel="alternate icon" type="image/png" href="../../../static.files/favicon-32x32-eab170b8.png"><link rel="icon" type="image/svg+xml" href="../../../static.files/favicon-044be391.svg"></head><body class="rustdoc mod"><a class="skip-main-content" href="#main-content">Skip to main content</a><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><rustdoc-topbar><h2><a href="#">Module semantic</a></h2></rustdoc-topbar><nav class="sidebar"><div class="sidebar-crate"><h2><a href="../../../table/index.html">table</a><span class="version">1.4.0-alpha.0</span></h2></div><div class="sidebar-elems"><section id="rustdoc-toc"><h2 class="location"><a href="#">Module semantic</a></h2><h3><a href="#enums">Module Items</a></h3><ul class="block"><li><a href="#enums" title="Enums">Enums</a></li><li><a href="#constants" title="Constants">Constants</a></li><li><a href="#functions" title="Functions">Functions</a></li></ul></section><div id="rustdoc-modnav"><h2><a href="../index.html">In table::<wbr>requests</a></h2></div></div></nav><div class="sidebar-resizer" title="Drag to resize sidebar"></div><main><div class="width-limiter"><section id="main-content" class="content" tabindex="-1"><div class="main-heading"><div class="rustdoc-breadcrumbs"><a href="../../index.html">table</a>::<wbr><a href="../index.html">requests</a></div><h1>Module <span>semantic</span>&nbsp;<button id="copy-path" title="Copy item path to clipboard">Copy item path</button></h1><rustdoc-toolbar></rustdoc-toolbar><span class="sub-heading"><a class="src" href="../../../src/table/requests/semantic.rs.html#15-550">Source</a> </span></div><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>Table semantic layer vocabulary.</p>
<p>A thin layer of semantic metadata attached to a table via <code>table_options</code>, 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 <code>docs/rfcs/2026-05-28-table-semantic-layer.md</code>.</p>
<p>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.</p>
<p>All public keys share the <a href="../constant.SEMANTIC_PREFIX.html" title="constant table::requests::SEMANTIC_PREFIX"><code>SEMANTIC_PREFIX</code></a> namespace and are string-valued.
<a href="../fn.is_semantic_option_key.html" title="fn table::requests::is_semantic_option_key"><code>is_semantic_option_key</code></a> gates them through
<a href="../fn.validate_table_option.html" title="fn table::requests::validate_table_option"><code>crate::requests::validate_table_option</code></a>, so they are accepted both on the
ingestion auto-create path and on explicit <code>CREATE TABLE ... WITH (...)</code> DDL.</p>
</div></details><h2 id="enums" class="section-header">Enums<a href="#enums" class="anchor">§</a></h2><dl class="item-table"><dt><a class="enum" href="enum.EntityRole.html" title="enum table::requests::semantic::EntityRole">Entity<wbr>Role</a></dt><dd>The role a set of columns plays for an entity: <code>id</code> (identifying
attributes), <code>descriptive</code>, or <code>scope</code>. Columns may be tags or fields; DDL
validation only requires that they exist and render as stable strings
(<a href="../fn.has_stable_string_form.html" title="fn table::requests::has_stable_string_form"><code>has_stable_string_form</code></a>).</dd></dl><h2 id="constants" class="section-header">Constants<a href="#constants" class="anchor">§</a></h2><dl class="item-table"><dt><a class="constant" href="constant.METADATA_QUALITY_DECLARED.html" title="constant table::requests::semantic::METADATA_QUALITY_DECLARED">METADATA_<wbr>QUALITY_<wbr>DECLARED</a></dt><dt><a class="constant" href="constant.METADATA_QUALITY_INFERRED.html" title="constant table::requests::semantic::METADATA_QUALITY_INFERRED">METADATA_<wbr>QUALITY_<wbr>INFERRED</a></dt><dt><a class="constant" href="constant.METRIC_TEMPORALITY_CUMULATIVE.html" title="constant table::requests::semantic::METRIC_TEMPORALITY_CUMULATIVE">METRIC_<wbr>TEMPORALITY_<wbr>CUMULATIVE</a></dt><dt><a class="constant" href="constant.METRIC_TEMPORALITY_DELTA.html" title="constant table::requests::semantic::METRIC_TEMPORALITY_DELTA">METRIC_<wbr>TEMPORALITY_<wbr>DELTA</a></dt><dt><a class="constant" href="constant.SEMANTIC_ENTITY_PREFIX.html" title="constant table::requests::semantic::SEMANTIC_ENTITY_PREFIX">SEMANTIC_<wbr>ENTITY_<wbr>PREFIX</a></dt><dd>Reserved prefix for the entity-identity sub-namespace:
<code>greptime.semantic.entity.&lt;type&gt;.{id|descriptive|scope}</code>. Unlike the rest of
the vocabulary (a closed whitelist), entity types are open-ended (<code>service</code>,
<code>host</code>, <code>k8s.pod</code>, <code>process</code>, <code>agent</code>, custom, …), so keys here are validated
by prefix + shape rather than membership. See
<code>docs/rfcs/2026-06-25-entity-relationships-and-graph-query.md</code>.</dd><dt><a class="constant" href="constant.SEMANTIC_ENTITY_SERVICE_ID.html" title="constant table::requests::semantic::SEMANTIC_ENTITY_SERVICE_ID">SEMANTIC_<wbr>ENTITY_<wbr>SERVICE_<wbr>ID</a></dt><dd>The well-known entity-identity key auto-stamped on OTLP trace tables; its value
is the <code>service_name</code> tag column, declaring the logical <code>service</code> entity.</dd><dt><a class="constant" href="constant.SEMANTIC_METRIC_METADATA_QUALITY.html" title="constant table::requests::semantic::SEMANTIC_METRIC_METADATA_QUALITY">SEMANTIC_<wbr>METRIC_<wbr>METADATA_<wbr>QUALITY</a></dt><dd><a href="../constant.METADATA_QUALITY_DECLARED.html" title="constant table::requests::METADATA_QUALITY_DECLARED"><code>METADATA_QUALITY_DECLARED</code></a> when the protocol stated the type, or
<a href="../constant.METADATA_QUALITY_INFERRED.html" title="constant table::requests::METADATA_QUALITY_INFERRED"><code>METADATA_QUALITY_INFERRED</code></a> when guessed from a name suffix.</dd><dt><a class="constant" href="constant.SEMANTIC_METRIC_ORIGINAL_NAME.html" title="constant table::requests::semantic::SEMANTIC_METRIC_ORIGINAL_NAME">SEMANTIC_<wbr>METRIC_<wbr>ORIGINAL_<wbr>NAME</a></dt><dd>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.</dd><dt><a class="constant" href="constant.SEMANTIC_METRIC_TEMPORALITY.html" title="constant table::requests::semantic::SEMANTIC_METRIC_TEMPORALITY">SEMANTIC_<wbr>METRIC_<wbr>TEMPORALITY</a></dt><dd>Catalog-level <code>cumulative</code> / <code>delta</code> / <code>mixed</code> description for OTLP metrics.
Per-series query behavior is determined from stored row identity instead.</dd><dt><a class="constant" href="constant.SEMANTIC_METRIC_TYPE.html" title="constant table::requests::semantic::SEMANTIC_METRIC_TYPE">SEMANTIC_<wbr>METRIC_<wbr>TYPE</a></dt><dd>Instrument kind: <code>counter</code> / <code>gauge</code> / <code>histogram</code> / <code>summary</code> /
<code>updown_counter</code> / <code>gauge_histogram</code> / <code>info</code> / <code>stateset</code>.</dd><dt><a class="constant" href="constant.SEMANTIC_METRIC_UNIT.html" title="constant table::requests::semantic::SEMANTIC_METRIC_UNIT">SEMANTIC_<wbr>METRIC_<wbr>UNIT</a></dt><dd>UCUM unit, e.g. <code>s</code>, <code>By</code>, <code>{request}</code>. Discarded by the row encoders, so it
is unrecoverable once ingested.</dd><dt><a class="constant" href="constant.SEMANTIC_OPTION_KEYS.html" title="constant table::requests::semantic::SEMANTIC_OPTION_KEYS">SEMANTIC_<wbr>OPTION_<wbr>KEYS</a></dt><dd>Every recognised public semantic table-option key. The set is a closed
whitelist: keys under <a href="../constant.SEMANTIC_PREFIX.html" title="constant table::requests::SEMANTIC_PREFIX"><code>SEMANTIC_PREFIX</code></a> that are not listed here are rejected,
so an unknown key like <code>greptime.semantic.unknown_key</code> does not silently land
in a table’s options. Adding a key to the vocabulary means adding it here.</dd><dt><a class="constant" href="constant.SEMANTIC_PER_TABLE_INDEX_KEY.html" title="constant table::requests::semantic::SEMANTIC_PER_TABLE_INDEX_KEY">SEMANTIC_<wbr>PER_<wbr>TABLE_<wbr>INDEX_<wbr>KEY</a></dt><dd>Internal <code>QueryContext</code> extension key carrying the per-table semantic index
(a <code>{table_name -&gt; {semantic_key: value}}</code> JSON blob) from the ingestion
encode path to the auto-create site. Deliberately OUTSIDE <a href="../constant.SEMANTIC_PREFIX.html" title="constant table::requests::SEMANTIC_PREFIX"><code>SEMANTIC_PREFIX</code></a>
so it is not a valid table option and never leaks into a table’s options.</dd><dt><a class="constant" href="constant.SEMANTIC_PIPELINE.html" title="constant table::requests::semantic::SEMANTIC_PIPELINE">SEMANTIC_<wbr>PIPELINE</a></dt><dd>Internal ingestion pipeline / data model, e.g. <code>greptime_trace_v1</code>. The
signal-agnostic successor to the engine-specific <code>table_data_model</code> option.</dd><dt><a class="constant" href="constant.SEMANTIC_PREFIX.html" title="constant table::requests::semantic::SEMANTIC_PREFIX">SEMANTIC_<wbr>PREFIX</a></dt><dd>Reserved prefix for every public semantic table-option key.</dd><dt><a class="constant" href="constant.SEMANTIC_SIGNAL_TYPE.html" title="constant table::requests::semantic::SEMANTIC_SIGNAL_TYPE">SEMANTIC_<wbr>SIGNAL_<wbr>TYPE</a></dt><dd>Signal kind: one of <a href="../constant.SIGNAL_TYPE_TRACE.html" title="constant table::requests::SIGNAL_TYPE_TRACE"><code>SIGNAL_TYPE_TRACE</code></a> / <a href="../constant.SIGNAL_TYPE_LOG.html" title="constant table::requests::SIGNAL_TYPE_LOG"><code>SIGNAL_TYPE_LOG</code></a> /
<a href="../constant.SIGNAL_TYPE_METRIC.html" title="constant table::requests::SIGNAL_TYPE_METRIC"><code>SIGNAL_TYPE_METRIC</code></a> / <a href="../constant.SIGNAL_TYPE_EVENT.html" title="constant table::requests::SIGNAL_TYPE_EVENT"><code>SIGNAL_TYPE_EVENT</code></a>.</dd><dt><a class="constant" href="constant.SEMANTIC_SOURCE.html" title="constant table::requests::semantic::SEMANTIC_SOURCE">SEMANTIC_<wbr>SOURCE</a></dt><dd>Ingestion ecosystem, e.g. <a href="../constant.SOURCE_OPENTELEMETRY.html" title="constant table::requests::SOURCE_OPENTELEMETRY"><code>SOURCE_OPENTELEMETRY</code></a> / <a href="../constant.SOURCE_PROMETHEUS.html" title="constant table::requests::SOURCE_PROMETHEUS"><code>SOURCE_PROMETHEUS</code></a>.</dd><dt><a class="constant" href="constant.SEMANTIC_SOURCE_VERSION.html" title="constant table::requests::semantic::SEMANTIC_SOURCE_VERSION">SEMANTIC_<wbr>SOURCE_<wbr>VERSION</a></dt><dd>Source protocol version, e.g. Prometheus remote write <code>1.0</code> / <code>2.0</code>.</dd><dt><a class="constant" href="constant.SEMANTIC_TABLE_SCOPE.html" title="constant table::requests::semantic::SEMANTIC_TABLE_SCOPE">SEMANTIC_<wbr>TABLE_<wbr>SCOPE</a></dt><dd>Information-schema visibility: <code>catalog</code> for providers that filter rows to
their catalog, or <code>global</code> for catalog-independent data. Only registered
system-table metadata is trusted for authorization.</dd><dt><a class="constant" href="constant.SEMANTIC_TRACE_CONVENTIONS.html" title="constant table::requests::semantic::SEMANTIC_TRACE_CONVENTIONS">SEMANTIC_<wbr>TRACE_<wbr>CONVENTIONS</a></dt><dd>Semantic-conventions version the rows conform to (e.g. the OTel schema URL),
or <a href="../constant.SEMANTIC_VALUE_UNKNOWN.html" title="constant table::requests::SEMANTIC_VALUE_UNKNOWN"><code>SEMANTIC_VALUE_UNKNOWN</code></a> / <a href="../constant.SEMANTIC_VALUE_MIXED.html" title="constant table::requests::SEMANTIC_VALUE_MIXED"><code>SEMANTIC_VALUE_MIXED</code></a> when not single-valued.</dd><dt><a class="constant" href="constant.SEMANTIC_VALUE_MIXED.html" title="constant table::requests::semantic::SEMANTIC_VALUE_MIXED">SEMANTIC_<wbr>VALUE_<wbr>MIXED</a></dt><dd>Sentinel for a single-valued key that saw conflicting sources.</dd><dt><a class="constant" href="constant.SEMANTIC_VALUE_UNKNOWN.html" title="constant table::requests::semantic::SEMANTIC_VALUE_UNKNOWN">SEMANTIC_<wbr>VALUE_<wbr>UNKNOWN</a></dt><dd>Sentinel for a key that cannot be determined at stamp time.</dd><dt><a class="constant" href="constant.SIGNAL_TYPE_EVENT.html" title="constant table::requests::semantic::SIGNAL_TYPE_EVENT">SIGNAL_<wbr>TYPE_<wbr>EVENT</a></dt><dt><a class="constant" href="constant.SIGNAL_TYPE_LOG.html" title="constant table::requests::semantic::SIGNAL_TYPE_LOG">SIGNAL_<wbr>TYPE_<wbr>LOG</a></dt><dt><a class="constant" href="constant.SIGNAL_TYPE_METRIC.html" title="constant table::requests::semantic::SIGNAL_TYPE_METRIC">SIGNAL_<wbr>TYPE_<wbr>METRIC</a></dt><dt><a class="constant" href="constant.SIGNAL_TYPE_TRACE.html" title="constant table::requests::semantic::SIGNAL_TYPE_TRACE">SIGNAL_<wbr>TYPE_<wbr>TRACE</a></dt><dt><a class="constant" href="constant.SOURCE_ELASTICSEARCH.html" title="constant table::requests::semantic::SOURCE_ELASTICSEARCH">SOURCE_<wbr>ELASTICSEARCH</a></dt><dt><a class="constant" href="constant.SOURCE_INFLUXDB.html" title="constant table::requests::semantic::SOURCE_INFLUXDB">SOURCE_<wbr>INFLUXDB</a></dt><dt><a class="constant" href="constant.SOURCE_LOKI.html" title="constant table::requests::semantic::SOURCE_LOKI">SOURCE_<wbr>LOKI</a></dt><dt><a class="constant" href="constant.SOURCE_OPENTELEMETRY.html" title="constant table::requests::semantic::SOURCE_OPENTELEMETRY">SOURCE_<wbr>OPENTELEMETRY</a></dt><dt><a class="constant" href="constant.SOURCE_OPENTSDB.html" title="constant table::requests::semantic::SOURCE_OPENTSDB">SOURCE_<wbr>OPENTSDB</a></dt><dt><a class="constant" href="constant.SOURCE_PROMETHEUS.html" title="constant table::requests::semantic::SOURCE_PROMETHEUS">SOURCE_<wbr>PROMETHEUS</a></dt></dl><h2 id="functions" class="section-header">Functions<a href="#functions" class="anchor">§</a></h2><dl class="item-table"><dt><a class="fn" href="fn.has_stable_string_form.html" title="fn table::requests::semantic::has_stable_string_form">has_<wbr>stable_<wbr>string_<wbr>form</a></dt><dd>Returns true if a column of <code>data_type</code> 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.</dd><dt><a class="fn" href="fn.is_entity_option_key.html" title="fn table::requests::semantic::is_entity_option_key">is_<wbr>entity_<wbr>option_<wbr>key</a></dt><dd>Returns true if <code>key</code> is a well-formed entity-identity option key.</dd><dt><a class="fn" href="fn.is_semantic_option_key.html" title="fn table::requests::semantic::is_semantic_option_key">is_<wbr>semantic_<wbr>option_<wbr>key</a></dt><dd>Returns true if <code>key</code> is a recognised semantic table-option key.</dd><dt><a class="fn" href="fn.is_v2_attribute_column.html" title="fn table::requests::semantic::is_v2_attribute_column">is_<wbr>v2_<wbr>attribute_<wbr>column</a><span title="Restricted Visibility">&nbsp;🔒</span> </dt><dt><a class="fn" href="fn.is_valid_entity_type.html" title="fn table::requests::semantic::is_valid_entity_type">is_<wbr>valid_<wbr>entity_<wbr>type</a><span title="Restricted Visibility">&nbsp;🔒</span> </dt><dd>Returns true if <code>ty</code> is a syntactically valid entity type, e.g. <code>service</code>,
<code>host</code>, <code>k8s.pod</code>, <code>service.instance</code>. An entity type is one or more
dot-separated segments, each a non-empty <code>[a-z0-9_]+</code> token. The dotted form
carries the two-entity-layer convention (<code>service</code> vs <code>service.instance</code>).</dd><dt><a class="fn" href="fn.parse_entity_columns.html" title="fn table::requests::semantic::parse_entity_columns">parse_<wbr>entity_<wbr>columns</a></dt><dd>Tokenizes an entity option’s comma-separated column list (trimmed, empty
tokens dropped). <a href="../fn.validate_semantic_option.html" title="fn table::requests::validate_semantic_option"><code>validate_semantic_option</code></a> rejects empty tokens at DDL
time, so readers only ever drop what validation already refused.</dd><dt><a class="fn" href="fn.parse_entity_option_key.html" title="fn table::requests::semantic::parse_entity_option_key">parse_<wbr>entity_<wbr>option_<wbr>key</a></dt><dd>Parses a well-formed entity-identity option key of the shape
<code>greptime.semantic.entity.&lt;type&gt;.{id|descriptive|scope}</code> into
<code>(entity_type, role)</code>. The <code>&lt;type&gt;</code> 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.</dd><dt><a class="fn" href="fn.trace_v2_attribute.html" title="fn table::requests::semantic::trace_v2_attribute">trace_<wbr>v2_<wbr>attribute</a></dt><dd>Resolves a Trace V2 entity reference to a JSON2 root and a literal attribute key.
Everything after the first dot belongs to the key, matching Trace V1’s
flattened column names. Existing physical columns take precedence.</dd><dt><a class="fn" href="fn.validate_semantic_option.html" title="fn table::requests::semantic::validate_semantic_option">validate_<wbr>semantic_<wbr>option</a></dt><dd>Validates a <code>greptime.semantic.*</code> option’s <code>value</code> against its allowed domain.</dd></dl></section></div></main></body></html>