SQL annotations are not a semantic layer—and verified queries are not either

A database can be richly annotated and still leave an analytics agent guessing how two business entities join. It can declare every join and still fail on a question whose intended calculation is company-specific. It can also store a library of trusted question-and-SQL pairs without giving the model a complete vocabulary for unfamiliar requests.

That is because annotations, semantic relationships and verified queries solve different failures. Recent first-party documentation from Oracle, Databricks and Snowflake makes the separation unusually clear.

Annotations describe objects

Oracle SQLcl 26.3 introduced commands and MCP tools for generating annotations on tables and columns. Its November 26.3.1 maintenance release then added the less glamorous lifecycle work: updating existing annotations, supporting multiple JSON tags and avoiding conflicts with database-level annotations.

This layer is about object-level context. It can tell an agent what a column means or attach structured tags to a database object. The maintenance fixes matter because stale or conflicting descriptions are worse than missing descriptions: they make incorrect context look authoritative.

But an annotation does not, by itself, define how a revenue fact should join to a customer dimension or encode the accepted calculation for “profit last month.”

Relationships describe legal join paths

Databricks’ beta relationships between Unity Catalog metric views add a different kind of context: a named, directed connection with declared cardinality and a join condition. AI assistants and BI tools can read that metadata instead of inferring joins from column names.

The important caveat is in the contract. Databricks says these relationships are metadata only. The platform validates whether the join expression resolves, but it does not enforce the relationship, check the data against the declared cardinality or use the relationship for query optimization. A MANY TO ONE declaration is therefore guidance for query construction, not proof that the target key is unique.

That distinction creates an operational requirement: teams still need data-quality checks for the cardinalities they publish to agents.

Verified queries describe accepted answer patterns

Snowflake’s Cortex Analyst Verified Query Repository addresses a third problem. It stores natural-language questions alongside reviewed SQL, and Cortex Analyst can reuse relevant examples when answering similar questions. The SQL must reference logical tables and columns from the semantic model rather than underlying physical names.

Snowflake’s documented workflow is explicitly human-in-the-loop: inspect the generated query and its results, edit and rerun it when necessary, then save it as verified. Optional verified_by and verified_at fields record provenance. Snowflake also warns that invalid or inaccurate entries can reduce performance and accuracy.

A verified query is therefore an approved example, not a universal rule. It helps with recurring business questions, but it cannot replace broader object descriptions or join metadata for requests that do not resemble the stored examples.

The practical stack

For an enterprise NL2SQL system, the mechanisms should be layered rather than compared as competing “semantic context” features:

1. Annotations establish vocabulary and object meaning.
2. Relationships constrain plausible join paths and declare intended cardinality.
3. Verified queries preserve reviewed calculations and recurring answer patterns.
4. Runtime permissions and data-quality tests remain separate controls; none of the three context layers proves that a user may access the data or that declared relationships hold.

The purchasing question is not whether a product has a semantic layer. It is which failure modes its context model covers—and which ones your team must still govern outside the prompt.