hs-sql-agent
2.0.2
Docs 2.0.2
Documentation version
2.0.2 Latest
2.0.2 Latest
Docs Administration

Semantic Metadata

Enrich database discovery with table and column semantics, relationships, and metric metadata in hs-sql-agent 2.0.1.

Entities Display names, descriptions, and synonyms for tables and columns.
Relationships Named source-to-target column relationships with cardinality and direction.
Metrics Scoped metric metadata with formula, aggregation, grain, filters, and synonyms.

Semantic metadata belongs to a Database Management entry. It enriches how schema discovery describes the physical database without changing the physical schema itself.

Entity metadata

An entity record can target either a table or one column inside a table.

FieldMeaning
DbManagementIdDatabase Management entry that owns the semantic record
SchemaNameOptional schema
TableNameRequired physical table name
ColumnNameOptional; omit it for table-level metadata
DisplayNameHuman-readable name
DescriptionBusiness or operational description
SynonymsAlternate terms used to describe the table/column

Synonyms are normalized by trimming empty values, deduplicating case-insensitively, and retaining at most 100 values per record.

Relationships

Relationship metadata describes how two physical columns are related.

FieldMeaning
NameStable relationship name
SourceSchema / SourceTable / SourceColumnSource side
TargetSchema / TargetTable / TargetColumnTarget side
CardinalityDefaults to many-to-one
DirectionDefaults to source-to-target
DescriptionOptional operator/business explanation

Schema discovery only surfaces relationship descriptions when both participating tables are allowed by the authenticated MCP key’s table whitelist.

Metrics

Metric metadata is scoped to a table and can describe a business measure:

FieldMeaning
NameStable metric identifier
DisplayNameHuman-readable name
DescriptionBusiness explanation
FormulaFormula metadata
AggregationDefaults to custom; can describe the intended aggregation
GrainOptional grain metadata
FilterOptional filter metadata
SynonymsAlternate terms for the metric
Executablefalse in the 2.0.1 model

How MCP schema discovery consumes semantics

The formal MCP schema tools remain get_schemas, get_tables, and get_columns.

When semantic metadata exists for the key’s bound Database Management entry:

  • get_tables can append table display name, description, synonyms, and scoped metric descriptions;
  • get_columns can append column display name, description, synonyms, and related relationship descriptions;
  • table whitelist rules continue to filter physical table visibility and relationship context.

Semantic metadata therefore enriches discovery; it does not widen what a key can access.

Admin API surface

The 2.0.1 Admin API exposes semantic management under api/DbSemantic:

OperationPermission
get entity records for a database/runtime/db-management/semantic → view
get the combined entity/relationship/metric model/runtime/db-management/semantic → view
upsert entity metadata/runtime/db-management/semantic → edit
delete entity metadata/runtime/db-management/semantic → edit
upsert/delete relationship/runtime/db-management/semantic → edit
upsert/delete metric/runtime/db-management/semantic → edit

Modeling guidance

Use semantic metadata for terminology that is stable enough to help multiple agents and operators:

  • business names that differ from physical table/column names;
  • abbreviations and domain synonyms;
  • relationships that are important to query generation;
  • metric definitions that clarify intended formulas and grain.

Do not use it to smuggle credentials, runtime instructions, or authorization decisions into schema descriptions. Access control remains a separate enforced layer.