What you will be able to do
- Rank candidate fixes for a Genie Agent: dataset metadata, SQL expressions, example SQL, then text instructions
- Account for the instruction and knowledge-store limits and for conflicting guidance when picking a change
- Verify a fix through the generated SQL, and recognise which mechanisms don't change agent behaviour
1.Ranking fixes: metadata and SQL before text
Exam scenarios often offer several plausible fixes and ask which will have the highest impact. Databricks gives a clear ranking. First come concise, well-documented datasets. That means quality descriptions, resolving column ambiguities, and pre-joining or de-normalising tables with views or metric views. Metric views work especially well because they predefine metrics, dimensions and aggregations. Next, define business semantics as SQL expressions, and use example SQL to teach Genie how to handle ambiguous or complex prompts. Text instructions come last. Structured SQL definitions are more reliable and easier to maintain than plain-text guidance, so the docs warn against using text to define metrics, filters or query patterns that SQL can express.
| Need | Configuration element | Documented example |
|---|---|---|
| Genie misreads what a column means | Column description and synonyms | Precise contextual information, free of ambiguous detail |
| A frequently used metric, filter or dimension | SQL expression in the knowledge store | revenue, active_customers, gross_margin, recent_sales |
| A hard-to-interpret, multi-part or complex question | Complete example SQL query | "breakdown my team's performance" |
| Guidance that needs a natural-language explanation and applies globally | Text instruction | "Always round percentages to two decimal places in summaries." |
The tune-quality guide adds a rule for telling global guidance from local guidance. General text instructions apply to every prompt. If a piece of guidance matters only for some prompts, it belongs in an example query, a function, or the relevant table's comments. A company fiscal calendar, such as FY26 running from February 1, 2026 to January 31, 2027, is a reasonable global instruction. A note that only affects how one table's status column is read belongs in that column's description.
Checkpoint 1 of 5· Match them up
Match each accuracy problem to the configuration element Databricks recommends for it
Tap a term, then the definition that fits it.
Business terms go into SQL expressions and complex question patterns into example SQL. Only guidance that applies globally goes into text, and guidance for a subset of prompts lives with the table.
“it should be included as an example query or function, or documented in the relevant table as comments or metadata”Source: docs.databricks.com
Checkpoint 2 of 5· Exam question
A Genie space joins an `orders` table to an `order_line_items` table. When users ask for total revenue, Genie's generated SQL joins the two tables and sums the `amount` column from `orders`, producing a total several times larger than the true value because each order has multiple line items. Which configuration change addresses this?
Correct answer: A — Define the join between `orders` and `order_line_items` with explicit One-to-Many cardinality.
- A. Correct. The inflated total is a classic fan-out from joining a one-side table to a many-side table without declared cardinality. Explicitly defining the relationship as One-to-Many lets Genie generate SQL that avoids double-counting `orders.amount`.
- B. Incorrect. Genie is already correctly locating the `amount` column when generating SQL; the failure is a join fan-out issue, not a term-to-column mapping issue that a synonym would fix.
- C. Incorrect. A single example query patches one scenario but does not teach Genie the general join behavior; every new revenue-related question would still risk the same fan-out unless the underlying relationship is fixed.
- D. Incorrect. Forbidding the join entirely would break legitimate questions that genuinely need line-item detail from `order_line_items`, rather than fixing the aggregation logic.
- E. Incorrect. Clarifying what `amount` means does not address why joining to `order_line_items` multiplies the row count before the sum is applied.
2.Limits and conflicts that shape the choice
Each Genie Agent has two separate limits, and they affect which fix is cheapest. The instruction limit is 100 per agent. Each example SQL query counts as one, each SQL function counts as one, and the whole General instructions block counts as one. The knowledge-store limit is 200 snippets, shared by table descriptions, join relationships and SQL expressions (measures, filters and dimensions). Several high-value fixes count against neither limit: column descriptions, prompt matching settings, and the text instructions, example queries and functions that are already counted as instructions. So enabling Example values or tightening column descriptions never uses up the snippet budget.
Checkpoint 3 of 5· Check yourself
A curator is close to the 200-snippet knowledge-store limit. Which change can they still make without using a snippet?
Column descriptions are explicitly excluded from the snippet limit. Table descriptions, join relationships and SQL expressions all count toward it.
“Text instructions, example SQL queries, SQL functions, column descriptions, and prompt matching settings do not count toward this limit.”Source: docs.databricks.com
More guidance isn't automatically better. Too many instructions can reduce effectiveness, because Genie may struggle to prioritise what matters most, especially in long conversations. Conflicts are worse than volume. Genie is nondeterministic, so contradictory guidance shows up as answers that change from run to run, and resolving inconsistencies is a core setup task. A typical conflict: the text instructions say to round to two decimals, but an example query doesn't. When an agent answers inconsistently, check for conflicting guidance before adding anything new. Example queries also have a quality factor of their own. Title each one with the most typical phrasing of the user's question so Genie can match prompts to it, and add usage guidance that says when the example applies.
Checkpoint 4 of 5· Exam question
A Unity Catalog table has columns `created_at` and `updated_at` with no descriptions. When users ask "how many customers signed up last month," Genie sometimes filters on `updated_at` instead of `created_at`, producing incorrect counts. What is the highest-impact fix?
Correct answer: A — Add column descriptions noting `created_at` is signup time, `updated_at` is last-modified time.
- A. Correct. The ambiguity is purely semantic: two similarly named timestamp columns with no documentation of what each represents. Column descriptions give Genie the business meaning it needs to pick the right column for "signed up".
- B. Incorrect. Sample date values do not clarify which column represents signup versus modification; the values in both columns look the same (dates), so a value dictionary does not resolve the ambiguity.
- C. Incorrect. Enumerating every possible phrasing does not scale and does not address the root cause, which is that the columns themselves are undocumented.
- D. Incorrect. Renaming columns is a schema change outside typical metadata configuration and is unnecessary when a column description can resolve the ambiguity without touching the underlying table.
- E. Incorrect. `created_at` and `updated_at` are two attributes of the same row, not two separate tables needing a join relationship; cardinality configuration is not applicable here.
Look at the example SQL queries. If any of them round differently, they conflict with the text instruction. Instruction types have to agree with each other, so align the examples with the text instead of adding yet another instruction.
3.Confirming the change worked
A configuration change is only a hypothesis until you test it. Databricks tells curators to be their agent's first user. Ask realistic questions, read the generated SQL carefully, and correct it where Genie misreads the data or the jargon. Check that the specific clause you diagnosed (the WHERE literal, the JOIN, the column choice) now comes out right. Because Genie can give different outputs for the same prompt, run the question more than once. Example SQL queries that Genie can learn from help make it more consistent.
Two mechanisms look like fixes but aren't. User feedback (Yes, Fix it, Request review) shows you where to improve, but it doesn't change how the agent behaves on its own. A curator has to act on it. Benchmarks score accuracy at scale, but they are for evaluation only and never become context. Adding the failing question to the benchmarks measures the gap without closing it.
Checkpoint 5 of 5· Check yourself
Over a week, users clicked Fix it on dozens of wrong revenue answers. The curator changed nothing. What is true about the agent now?
Feedback is a signal for the curator. Behaviour changes only when someone updates metadata, SQL expressions, examples or instructions.
“Your Genie Agent's behavior does not change based on user feedback alone.”Source: docs.databricks.com
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.The quickest high-impact fix for an inconsistently computed metric is a general text instruction that defines it.Why is that wrong?
Metrics, filters and query patterns that SQL can express should be SQL expressions or example SQL. Text instructions are the last resort.
Covered in Ranking fixes: metadata and SQL before text
2.Adding a failing question and its correct SQL to the benchmarks teaches Genie the right answer.Why is that wrong?
Benchmarks only measure accuracy. Genie never uses them as context, so to fix the gap you need an example query or a metadata change.
Covered in Confirming the change worked
3.When accuracy is inconsistent, adding more instructions will make Genie more reliable.Why is that wrong?
Too many instructions can reduce effectiveness, and conflicting guidance causes inconsistency. Resolve conflicts before adding guidance.
Covered in Limits and conflicts that shape the choice
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“Resolve column ambiguities and pre-join or de-normalize tables using views or metric views.”
↩︎ Ranking fixes: metadata and SQL before text“Metric views are particularly effective for Genie Agents because they pre-define metrics, dimensions, and aggregations.”
↩︎ Ranking fixes: metadata and SQL before text“When addressing hard-to-interpret, multi-part, or complex questions, provide complete example SQL queries.”
↩︎ Ranking fixes: metadata and SQL before text“if text instructions specify rounding decimals to two digits, then example SQL queries must also round to two digits.”
↩︎ Limits and conflicts that shape the choice“Carefully examine the SQL generated in response to your questions.”
↩︎ Confirming the change worked“Avoid using text instructions to define metrics, filters, or query patterns that can be expressed through SQL.”
↩︎ Exam trap 1“Too many instructions can reduce effectiveness, especially in longer conversations”
↩︎ Exam trap 3“For example, use SQL expressions to define revenue, active_customers, gross_margin, or recent_sales.”
↩︎ Prediction - 2.
“Text instructions are only for context that should be applied globally and do not fit into the other formats.”
↩︎ Ranking fixes: metadata and SQL before text“Each example SQL query, each SQL function, and the entire General instructions text block each count as one instruction.”
↩︎ Limits and conflicts that shape the choice“When setting up the agent, a key task is to review and resolve any inconsistencies.”
↩︎ Limits and conflicts that shape the choice“it should be included as an example query or function, or documented in the relevant table as comments or metadata”
↩︎ Checkpoint“Text instructions, example SQL queries, SQL functions, column descriptions, and prompt matching settings do not count toward this limit.”
↩︎ Checkpoint - 3.
“Providing example SQL queries that Genie can learn from can help make Genie more consistent.”
↩︎ Confirming the change worked“Your Genie Agent's behavior does not change based on user feedback alone.”
↩︎ Checkpoint
Also cited
“Unlike instructions, benchmarks are for evaluation only. Genie does not use benchmark questions or SQL to improve its context.”
↩︎ Exam trap 2