Module requests 

Table and TableEngine requests

Modules

semantic 🔒

Table semantic layer vocabulary.

Structs

AddColumnRequest

Add column request

AlterTableRequest

Alter table request

AnnotationContext

Table shape an annotation option is validated against.

BuildIndexTableRequest

CompactTableRequest

CopyDatabaseRequest

CopyQueryToRequest

CopyTableRequest

Copy table request

DeleteRequest

Delete (by primary key) request

FlushTableRequest

InsertRequest

ModifyColumnTypeRequest

Change column datatype request

SetDefaultRequest

TableOptions

TruncateTableRequest

Truncate table request

Enums

AlterKind

AnnotationFamily

A family of annotation table options: pure metadata markers that no region consumes. Setting or unsetting them only rewrites the table’s extra_options, so the alter skips region dispatch entirely.

AnnotationValidationError

Why an annotation option was rejected. Typed so each DDL entry point maps rules onto its existing error variants and status codes: ALTER keeps missing columns as TableColumnNotFound (4002), CREATE keeps its InvalidArguments family — the rules converge, the contracts do not.

CopyDirection

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).

SetIndexOption

UnsetIndexOption

Constants

AUTO_CREATE_TABLE_KEY

COMMENT_KEY

DDL_TIMEOUT

DDL_WAIT

FILE_TABLE_FORMAT_KEY

FILE_TABLE_LOCATION_KEY

FILE_TABLE_META_KEY

FILE_TABLE_PATTERN_KEY

METADATA_QUALITY_DECLARED

METADATA_QUALITY_INFERRED

OTLP_METRIC_COMPAT_KEY

OTLP_METRIC_COMPAT_PROM

REPARTITION_COLUMN_HINT_KEY

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

SKIP_WAL_KEY

SOURCE_ELASTICSEARCH

SOURCE_INFLUXDB

SOURCE_LOKI

SOURCE_OPENTELEMETRY

SOURCE_OPENTSDB

SOURCE_PROMETHEUS

STORAGE_KEY

TABLE_DATA_MODEL

TABLE_DATA_MODEL_TRACE_V1

TRACE_TABLE_PARTITIONS_HINT_KEY

TTL_KEY

VALID_DDL_OPTION_KEYS

VALID_TABLE_OPTION_KEYS

WRITE_BUFFER_SIZE_KEY

Statics

VALID_DB_OPT_KEYS 🔒

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_trace_v1_table

Returns true if the table stores spans in the greptime_trace_v1 data model (fixed span columns), the shape the Jaeger query path and the entity-graph derivation rely on.

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_and_normalize_annotation 🔒

Validates one annotation option and returns the value to store — the repartition hint is trimmed to the bare column name, semantic values pass through unchanged.

validate_and_normalize_annotation_options

CREATE-side entry: validates every annotation option present in options and writes normalized values back in place.

validate_database_option

Returns true if the key is a valid key for database.

validate_semantic_option

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

validate_table_option

Returns true if the key is a valid key for any engine or storage.