What you will be able to do
- List the metadata inputs a Genie Agent uses to turn a question into SQL
- Trace a wrong answer (bad filter value, bad join, wrong column) to the specific metadata element that is missing or vague
- Decide whether a metadata fix belongs in Unity Catalog or in the agent's knowledge store, and know the privileges each one requires
Key concept
Metadata-driven accuracy — A Genie Agent writes SQL from the names, descriptions, key relationships and sample values attached to its data, so most accuracy gaps come from a missing or vague metadata element. To fix one, find the element the failed SQL shows was missing and supply it.
1.What a Genie Agent actually reads
When a Databricks Genie Agent (formerly called a Genie Space; exam items may use either name) returns wrong answers, the cause usually comes before the model ever runs. It is the metadata the agent was given. Genie turns a natural-language question into SQL by picking relevant names and descriptions from annotated tables and columns. Unity Catalog comments, metadata and sample values from selected columns let it infer both business and technical logic. So diagnosis starts with a list of everything Genie reads for each question, because any one of those inputs could be the gap.
| Component | What Genie takes from it |
|---|---|
| Unity Catalog table metadata | Table names, descriptions, and defined primary key (PK) and foreign key (FK) relationships |
| Column names and descriptions | Filtered for relevance to the question |
| Knowledge store context | Agent-specific metadata added locally, including column values relevant to query generation |
| Example SQL queries | Relevant examples selected from the agent's SQL queries |
| SQL functions | All SQL functions added to the agent |
| Instructions | Plain-text General instructions |
| Prompt and response history | The current chat, with the oldest parts dropped if token limits require it |
Three parts of this list matter most for diagnosis. First, Genie filters column names and descriptions for relevance. A column with a vague or missing description can lose out to a better-described neighbour, even when it is the right one. Second, Genie learns joins from defined PK and FK relationships. If those constraints were never declared, nothing in the table metadata tells Genie how the tables connect. Third, the scope is fixed. Genie uses only the sources attached to the agent and won't query a table that isn't attached, even when an instruction or description names it. Some details, such as a table's owner and size, aren't included by default. To answer questions about them, Genie needs views from the information schema.
Checkpoint 1 of 5· Check yourself
Users ask a Genie Agent who owns the orders table and get a wrong answer. Table and column descriptions are complete. Which explanation fits the documentation?
Ownership isn't part of the table metadata Genie receives by default. The documented route is to add views from the information schema.
“Some table details, such as the owner and table size, are not included by default.”Source: docs.databricks.com
2.Mapping a symptom to the missing element
The natural reflex is to write another instruction. The troubleshooting guidance points somewhere else: each common failure traces back to a specific missing metadata element, and the fix is to supply that element. Read the generated SQL and find the clause that went wrong. A wrong literal in a WHERE clause means Genie couldn't see the data values. Prompt matching, which includes format assistance and entity matching, lets Genie match values relevant to the question and correct spelling in prompts. When new data arrives in those tables, refresh the values. A missing or wrong JOIN usually means foreign keys were never declared. If Genie picks the wrong one of several similar columns, the agent probably holds overlapping tables or columns.
| Symptom in generated SQL | Missing or weak element | Configuration change |
|---|---|---|
| WHERE clause matches 'California' when the table uses 'CA' | Genie has no visibility into data values | Enable Example values and Value dictionaries on the relevant columns; refresh values after new data is added |
| Tables joined wrongly or not at all | Foreign key references not defined in Unity Catalog | Define foreign keys in Unity Catalog; otherwise define join relationships in the knowledge store; add example queries with standard joins |
| Joins still fail after those fixes | Data model too complex for the agent | Pre-join the tables into a view and use that as input instead |
| Genie uses the wrong one of several similar columns | Overlapping tables, columns or concepts | Remove unnecessary or overlapping tables or columns, or hide columns from the agent |
The join options come in a deliberate order. A foreign key declared in Unity Catalog is the most durable fix. The knowledge-store join relationship is the alternative for complex cases such as self-joins, or when you can't modify the underlying tables. A pre-joined view is the fallback if neither works. Column ambiguity has a matching fix on the description side. Column descriptions should give precise context and leave out ambiguous or unnecessary detail. Synonyms help Genie pick the column for relevant questions and write more accurate SQL.
Checkpoint 2 of 5· Exam question
A Genie space is registered against a Unity Catalog table containing a `country` column that stores values like "AUS", "USA", and "GBR". Users frequently type full country names such as "Australia" in natural-language questions, and Genie fails to apply the correct filter, returning empty or incorrect results. Which configuration change will most directly fix this?
Correct answer: A — Add an example-value mapping tying "Australia" to the stored code "AUS" for the country column.
- A. Correct. Genie matches user-typed business terms against column values using configured example values (a value dictionary). Mapping "Australia" to the stored code "AUS" directly resolves the mismatch between natural-language input and the actual stored data.
- B. Incorrect. The problem is not that Genie fails to find the `country` column itself — it already targets that column. A synonym for the column name does not help Genie translate the typed value "Australia" into the stored code "AUS".
- C. Incorrect. Uppercasing input would not solve a semantic mismatch between a country name ("Australia") and an unrelated ISO-style code ("AUS"); there is no textual transformation that bridges the two without an explicit mapping.
- D. Incorrect. Warehouse size affects query execution speed, not whether Genie can correctly translate a business term into the right stored value. This is a metadata/semantic problem, not a compute problem.
- E. Incorrect. A single hard-coded example query only teaches Genie one specific filter value; it does not generalize to other country names users might type, and it does not document the mapping as reusable metadata the way an example-value dictionary does.
Checkpoint 3 of 5· Check yourself
Genie keeps producing wrong joins between orders and customers. No foreign keys are declared in Unity Catalog, and the curator has CAN EDIT on the agent but no permission to modify the underlying tables. Which change has the highest impact?
Without permission to modify the tables, the curator can't declare the foreign key. The documentation names knowledge-store join relationships for exactly this case.
“This strategy is helpful for more complex join scenarios like self-joins, or if you don't have sufficient permission to modify the underlying tables.”Source: docs.databricks.com
3.Fixing metadata in Unity Catalog or in the agent
Once you know which element is missing, decide where to add it. Unity Catalog comments are a metadata field on any securable object (catalogs, schemas, tables and more) and on table columns. Anyone with BROWSE can read them. To comment on a table or column you must own it or hold MODIFY and SELECT on the table, plus USE CATALOG and USE SCHEMA on its parents. Views and materialized views are stricter: only the owner can comment, and MANAGE isn't enough. Saving a comment runs an ALTER command, which can disrupt pipelines and jobs.
The other place is the agent's knowledge store. There you can add custom table and column descriptions and synonyms that are scoped to the agent. The default table description shows the Unity Catalog comment. You can edit it to add directions that help Genie write SQL, and Reset restores the catalog text. These edits never write back to Unity Catalog. Use them when you can't change the catalog, or when the guidance only makes sense for this one agent.
AI-generated comments are a quick way to fill empty descriptions. You request them per object in Catalog Explorer, and an LLM drafts the text from object metadata such as the schema and column names. That input is also their limit: the model sees structure, not your business meaning. Databricks strongly recommends human review, and its Genie guidance says to keep an AI-generated description only if it matches what you would have written yourself. The model shouldn't be used to classify data, for example to detect PII.
Checkpoint 4 of 5· Put it in order
Put the steps for adding an AI-generated comment to a Unity Catalog object in order
- 1.Click Accept to keep the comment as-is, or Edit to change it before saving
- 2.In the About this object panel, click AI generate
- 3.In your Databricks workspace, click Catalog
- 4.Search or browse for the object and select it
You request the comment from the object's panel in Catalog Explorer, then review it. You either accept it or edit it before saving.
“Click Accept to accept the comment as-is, or Edit to modify it before you save it.”Source: docs.databricks.com
Checkpoint 5 of 5· Check yourself
A Genie Agent is built on a view with no comment. The curator has MANAGE on the view but doesn't own it. What happens when they try to add a Unity Catalog comment?
Views and materialized views need ownership for comment edits. MANAGE isn't enough, so the curator should fall back to an agent-level description.
“Having the MANAGE privilege is insufficient.”Source: docs.databricks.com
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.Editing a column description in the Genie Agent's knowledge store also updates the Unity Catalog comment.Why is that wrong?
Knowledge-store metadata is scoped to the agent and never overwrites Unity Catalog. Other consumers of the catalog won't see the change.
2.Bulk-accepting AI-generated comments is a safe way to close a metadata gap.Why is that wrong?
AI-generated comments are drafted from schema and column names and can be inaccurate. Databricks strongly recommends reviewing them before saving.
3.If an instruction or description names a table, Genie will query that table even when it isn't attached to the agent.Why is that wrong?
Genie only queries sources attached to the agent. If the right data isn't attached, no metadata change will fix the answer.
Covered in What a Genie Agent actually reads
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“Table names, descriptions, and defined primary key (PK) and foreign key (FK) relationships.”
↩︎ What a Genie Agent actually reads“combined with relevant Unity Catalog comments, metadata, and sample values from selected columns, allow Genie to infer both business and technical logic”
↩︎ What a Genie Agent actually reads“Some table details, such as the owner and table size, are not included by default.”
↩︎ Checkpoint - 2.
“Genie Agents were formerly known as Genie Spaces.”
↩︎ What a Genie Agent actually reads“Quality column descriptions and synonyms help Genie understand the column better, choose it for relevant questions, and write more accurate SQL.”
↩︎ Mapping a symptom to the missing element“Inspect any AI-generated descriptions for accuracy and clarity, and use them only if they align with what you would manually provide.”
↩︎ Fixing metadata in Unity Catalog or in the agent“Quality table and column descriptions in Unity Catalog are critical for Genie accuracy.”
↩︎ Key concept“This metadata is scoped to your Genie Agent and does not overwrite metadata stored in Unity Catalog.”
↩︎ Exam trap 1 - 3.
“When Genie doesn't have visibility into the data values, it might set the WHERE clause to filter for the wrong value.”
↩︎ Mapping a symptom to the missing element“If foreign key references are not defined in Unity Catalog, your agent might not know how to join different tables together.”
↩︎ Mapping a symptom to the missing element“If none of these resolve the problem, pre-join the table into a view and use that as input for the agent instead.”
↩︎ Mapping a symptom to the missing element“verify that relevant columns have Example values and Value dictionaries enabled”
↩︎ Prediction“This strategy is helpful for more complex join scenarios like self-joins, or if you don't have sufficient permission to modify the underlying tables.”
↩︎ Checkpoint - 4.https://docs.databricks.com/aws/en/commentsOfficial docs
“you must be the owner or have the following privileges: MODIFY and SELECT on the table.”
↩︎ Fixing metadata in Unity Catalog or in the agent“Having the MANAGE privilege is insufficient.”
↩︎ Checkpoint - 5.
“Edit this description to add specific directions that help Genie author SQL for your agent.”
↩︎ Fixing metadata in Unity Catalog or in the agent - 6.
“Comments are powered by a large language model (LLM) that takes into account object metadata, such as the table schema and column names.”
↩︎ Fixing metadata in Unity Catalog or in the agent“Databricks strongly recommends human review of AI-generated comments to check for inaccuracies.”
↩︎ Exam trap 2“Click Accept to accept the comment as-is, or Edit to modify it before you save it.”
↩︎ Checkpoint
Also cited
“Genie does not query tables or Unity Catalog functions that are not attached, even if the agent's instructions or metadata reference them.”
↩︎ Exam trap 3