Entrada

A Databricks semantic layer is the difference between an AI agent that reasons about your business correctly and one that guesses at machine speed. The Navy has a saying: a collision at sea can ruin your entire day. It is usually attributed to Thucydides, and it is usually delivered with a straight face, because everyone on the bridge knows the joke is not a joke. The sea does not care how good your intentions were. Neither does an AI agent generating SQL against your data estate.

Across our delivery practice at Entrada, the practice that earned us the 2026 Databricks Genie Partner of the Year award, we have built semantic layers, ontologies, and Unity Catalog glossaries for six major customer engagements and more than a dozen internal workspace implementations: a global retail chain putting natural-language analytics in front of store managers, a major telecommunications and media company classifying every one of its field markets weekly, a global consumer packaged goods company modernizing procurement analytics, a life sciences organization accelerating clinical cohort discovery, a multinational consumer goods manufacturer whose supply chains do not talk to each other, and our own internal governance and FinOps estate.

The finding is consistent everywhere we have sailed: accuracy failures in natural-language analytics are overwhelmingly semantic failures, not model failures. On one engagement, benchmark accuracy moved from roughly 50% to more than 90% across a fixed set of predefined questions, and every point of that gain was attributable to metadata work: synonyms, table aliases, business-term-to-column mappings, and curated SQL exemplars. Not the model. The metadata.

Here is the core thesis, and it deserves to be stated bluntly:

Semantic ambiguity is not a documentation problem that AI will paper over. It is a correctness problem that AI amplifies, because agents apply an ambiguous definition thousands of times per day, silently, at machine speed.

A helmsman making a one-degree steering error corrects it in seconds. An autopilot making the same one-degree error, unattended, puts you on the rocks. Your semantic layer is the chart, the compass, and the standing orders combined. What follows are the practices we now treat as non-negotiable, in roughly the order a new engagement should tackle them.

TL;DR: Databricks Semantic Layer Best Practices

Define every governed measure once, in a Unity Catalog metric view. Never in a prompt.
Teach the agent with SQL first: expressions, then example queries. Text instructions are the last resort.
Comment every column down to units, grain, null semantics, and enumerated values. Ninety percent coverage is the AI-Ready line.
Write the benchmark suite before you build the space. Accuracy is a number that moves, not an opinion.
Version everything in Git, deploy through bundles, log every answer, and put a named owner on every term and every space.

No officer of the deck navigates a strait from memory. They navigate from the chart, because the chart is surveyed, versioned, and shared by every watch stander on the ship.

Every business measure should live in a Unity Catalog metric view. Zero measures should live in instruction text, prompt templates, or agent system messages. Prompt-embedded logic has no lineage, no permissions, no version history, and no test coverage. When Finance changes the revenue recognition rule, a catalog-defined measure changes in one place; a prompt-defined measure changes in however many prompts someone remembers to edit.

Two details here matter more than they look, and both are why the catalog wins over the prompt:

The filter clause encodes the population rule. Test orders and incomplete orders are excluded once, for everyone, forever. No agent can forget it, because it is not the agent’s job to remember it.
NULLIF in the ratio denominator prevents division errors that surface as “0% margin” instead of the real problem. Defensive math belongs in the definition, not in a thousand generated queries.

2. SQL first, text last: the instruction hierarchy Databricks now makes official

This one comes straight from the current Databricks guidance on curating Genie Agents, and it matches what we learned the hard way in the field: prioritize SQL expressions and example SQL over text instructions.

SQL expressions define business semantics: metrics, filters, dimensions. revenue, active_customers, gross_margin belong here.
Example SQL queries teach the agent how to handle common ambiguous prompts and multi-step patterns.
Text instructions are the last resort, reserved for guidance that genuinely requires natural language, such as clarification triggers and formatting rules.

This does not contradict practice 1; it completes it. Governed enterprise measures, the ones Finance signs off on and every dashboard shares, live in metric views. SQL expressions in the agent’s knowledge store are for agent-scoped definitions that only that space needs: a persona-specific recency window, a default filter for one team’s view of the world. The two layers have different owners and different blast radii. What they have in common is that neither lives in prose.

The same business rule, expressed three ways, in descending order of reliability:

Structured definitions through SQL are more reliable and maintainable than plain text guidance. The reason is simple: models pattern-match. Given no exemplars, they pattern-match against generic internet SQL. Given ten certified queries showing how your organization joins, filters, and grains its data, they pattern-match against your conventions. Ten good examples reliably beat a thousand tables of documentation. A practical way to bootstrap the exemplar library:

Two caveats. First, GROUP BY on the exact statement text will not collapse near-duplicates: the same query with a different date literal or a trailing comment counts as a new row, so expect to dedupe by hand or normalize literals before grouping. Second, the service principal filters above are placeholders; substitute whatever naming convention your workspace uses, and if you use dashboards you may also want to exclude their refresh queries by warehouse. 

Then discard the wrong ones (there will be wrong ones), and register the survivors as trusted assets.

3. Write comments a sailor could stand watch on: units, grain, nullability, enumerations

In the Navy, “brilliant on the basics” is not a compliment for beginners; it is the standard for professionals. Column comments are the basics, and most estates fail them.

A comment that says temperature is unusable. A comment that says temperature, degrees Fahrenheit, null when sensor offline is queryable. The difference between those two strings is the difference between an agent that guesses and an agent that knows.

Every column comment should capture, at minimum: units (Fahrenheit or Celsius, dollars or thousands of dollars), grain (what one row represents), nullability semantics (what a null means, not just whether it occurs), and enumerated values with exact casing:

That last comment is doing two jobs. Enumerating valid values with casing prevents the agent from applying defensive normalization like UPPER(TRIM(status)) = ‘HOT’, which bloats queries and occasionally introduces bugs. Stating the non-null guarantee prevents IS NOT NULL guards that signal uncertainty and can change results. If you do not tell the agent the data is clean, it will assume the data is dirty, and it will write SQL like it.

The field evidence is stark: tables with 90%+ column comment coverage consistently produce 30 to 40% higher Genie accuracy than tables with no coverage. We now treat 90% coverage as the “AI-Ready” line in every readiness assessment; below 30% we route the domain back to data engineering before any AI surface gets built.

4. One signal, many flags: encode synonym relationships explicitly

Ships of different navies can operate together because signal flags mean the same thing on every mast. Your tables were not built by one navy. One system calls it subscriber_id; another calls it subscription_guid; the business calls it “the account.”

Encode these synonym relationships explicitly, and do it as comments and agent-scoped synonym metadata rather than renaming columns. Renames break lineage, downstream pipelines, and every dashboard nobody remembers exists. A comment costs nothing and travels with the object:

Genie Agents also support column synonyms scoped to the agent itself, without overwriting Unity Catalog metadata. Users say “confidence” but the column is stage1_confidence; users say “status” but mean predicted_status. Add a synonym for every user-facing term. And enable entity matching (value indexing) only where it helps:

Enable on low-cardinality categorical columns whose values users reference by name: statuses, regions, product tiers.
Never enable on high-cardinality identifiers, numeric measures, or timestamps. Indexing a million distinct IDs buys you nothing and costs you retrieval quality.

5. Watertight compartments: scope narrow, then widen

Warships survive damage because they are built in watertight compartments. Flooding in one space does not sink the ship. Genie Agents should be built the same way.

Accuracy is inversely proportional to semantic surface area. A space covering three well-modeled subject areas outperforms one pointed at an entire catalog, every time, because ambiguity compounds: two domains sharing the word “unit” with different meanings will degrade both. Databricks now recommends five or fewer tables to start and enforces a hard limit of 30 tables or views per agent. Our field practice on one program for a major telecommunications and media company split the estate into purpose-specific spaces, each curated to a bounded asset set; that program deployed 19 executive-sponsored Genie spaces across multiple business units in ten weeks, and once the pattern was established, new spaces shipped at roughly two per week.

Pick your first compartment where a wrong answer has a visible business consequence, the gold layer is already clean, and there is a named executive sponsor with a budget. On one engagement with a global consumer packaged goods company, that domain was procurement: bounded question space, contractual vocabulary (supplier, vendor, and counterparty mean the same thing, and there is a document that says so), and gold tables already curated for Finance. Excitement is not a success factor; curated conformed dimensions are.

6. Standing orders: maintain an instructions file per space, and write your Rules of the Road

Every commanding officer publishes standing orders: what the watch does without asking, what requires waking the captain, and what is never done under any circumstances. Every Genie Agent needs the same document.

Maintain a version-controlled instructions file per space, structured so both the agent and the next engineer can scan it:

The prohibitions section is where hard-won lessons go so they are never learned twice. The pattern is always WHAT to do, WHAT NOT to do, and WHY. Naming the failure mode matters as much as stating the rule; “doing so silently skips the most recent week” gives the agent, and the next engineer, the reason that makes the rule stick.

The single most expensive prohibition we ever wrote down is the wrong-denominator bug, so it earns its own snippet:

Both queries run. Both return a number. Only one of them is true. That is precisely the class of error a semantic layer exists to prevent, because no error is thrown and no human reads the SQL.

And keep the total instruction set small and well organized; too many instructions dilute each other, which is exactly why the SQL-first hierarchy in practice #2 exists.

7. The shakedown cruise: build the benchmark suite before you build the space

No ship joins the fleet without a shakedown cruise, and no ship deploys without one. Yet teams routinely ship natural-language analytics with no agreed definition of “working.”

Write 40 to 60 representative questions with known-correct answers, authored by the business, before implementation begins. Without a benchmark, “is it working?” is a matter of opinion and UAT never closes. With one, accuracy is a number that moves, and every metadata curation round can be measured against the same fixed question set, which is precisely how you prove the gains came from your work rather than luck or a model upgrade.

Automate it. A regression harness that runs nightly keeps accuracy from silently decaying:

Three disciplines make benchmarks earn their keep:

Score by category, not just overall. An 85% aggregate that hides 40% accuracy on time-series comparisons tells you exactly which dimension needs work. That is why category is a first-class column in the harness above.
Expected SQL should be canonical, not merely correct. The benchmark enforces function routing and style, not just result equality.
Run the full suite after every instruction change. Instruction edits cascade. Treat them like schema changes, because they have the same blast radius.

Then practice benchmark-driven development the way you would test-driven development: write the failing benchmark first, prove the gap exists, add the minimal instruction to close it, and verify nothing else regressed. Damage control teams drill before the fire, not during it.

8. Keep the ship’s log: version everything in Git, deploy through bundles

A ship’s log is a legal record. Every course change, every watch relief, every casualty is written down, because “we think we turned north around midnight” does not survive a board of inquiry. In regulated environments, “the AI said so” is not an acceptable provenance chain either.

Two practices here.

Version metric views, column comments, and Genie instructions in Git, and deploy through bundles. A Genie Agent built by clicking through the UI is a snowflake: you cannot diff it, review it, promote it between environments, or rebuild it if the workspace is lost. Define spaces as YAML config-as-code, put every change through pull-request review, and promote through Databricks Asset Bundles, which Databricks now ships as Declarative Automation Bundles with first-class Genie Agent resource support:

On our largest programs, every threshold is code-generated from a single constants.py; nothing is hand-typed into YAML or SQL. That is the why behind config-as-code: it is not tidiness, it is drift prevention with a test that fails when the generator and the source disagree.

Stamp every answer. Log the question, generated SQL, result fingerprint, user, and semantic/instruction/metric-view versions to a Delta table:

A stamped log lets you reconstruct exactly which definition produced which number on which date. That is what an auditor, and your own incident review, will ask for.

9. The watch bill: every term and every space has a named owner

The Navy does not post “someone” to the helm. The watch bill names a person, and that person is accountable for the watch. Semantic layers fail the same way unmanned watches do: quietly, and then all at once.

Run the glossary as a decision log with three columns per term: the business definition in plain English, the physical expression in SQL, and an accountable owner who is a named human being. Terms without an owner do not enter the semantic layer. If “active customer” means 90-day recency to Marketing and 12-month recency to Finance, no amount of instruction tuning resolves it; the model will oscillate between definitions depending on question phrasing, and both departments will call the agent wrong.

At the space level, the same rule scales up: each Genie Agent gets a named business owner accountable for its benchmark question set. On our largest program, that meant executive sponsorship as a technical control, not a courtesy: each space had a named senior business owner accountable for whether the answers were right. Genie spaces do not fail from bad models. They fail from unowned semantics.

10. Eternal vigilance is the price of a clean chart: monitor in production

Charts go stale. Sandbars move, wrecks accumulate, and the prudent mariner checks Notices to Mariners before getting underway. Semantic drift works the same way: new columns land, ETL grain changes, a joined dimension picks up duplicate rows, and the space degrades without a single error being thrown.

Monitor accuracy, latency, and failure modes continuously. Track thumbs-up rate weekly (we target above 80%), mine conversations for user corrections (“no, I meant Hot, not Watch”; every correction is a candidate instruction), and promote every thumbs-down into a benchmark question so the regression suite grows from real traffic. Most importantly: route the failure log into the glossary backlog. The questions users ask that the system cannot answer are a ranked list of the measures you should define next. The failure log is your roadmap.

One more standing order belongs here, and it may be the most valuable instruction you will ever write. Teach the agent to refuse:

A system that reliably says “I can’t answer that” is worth more than a system that is right 90% of the time and confident 100% of the time. Any sailor who has trusted a confident but wrong position report understands why.

The anti-patterns: how ships run aground

Bringing it alongside

Calm seas never made a skilled sailor, and easy datasets never made a good semantic layer. The organizations getting real value from AI/BI on Databricks are not the ones with better models. They are the ones that did the unglamorous work first: agreed on what “revenue” means, encoded it once in the catalog as SQL rather than prose, commented every column down to units and null semantics, wrote their standing orders and their prohibitions, benchmarked before they launched, put a name on every watch, logged every answer, and kept the chart corrected in production.

The surface, the chat window where a store manager or a field technician asks a question in plain language, is the last mile. The ontology stack underneath it is the investment. Ships are safe in harbor, but that is not what ships are for; the same is true of your data. Do the work on your Databricks semantic layer, and you can take it to sea.

Entrada AI, Inc., the 2026 Databricks Genie Partner of the Year, is a Databricks-pureplay consulting and systems integration firm. The practices above draw on engagements across retail, telecommunications and media, consumer packaged goods, life sciences, and manufacturing, and on the current Databricks guidance for curating Genie Agents. Customer engagements are described anonymously except where the customer or Databricks has published the work.