What you will be able to do
- List the context components Genie assembles when it answers a question, and name the details it leaves out by default
- Decide which data sources belong inside a Genie Agent's boundary for a described task, and recognise tasks that Chat mode cannot serve
- Match each piece of business knowledge to the right context element: SQL expression, example SQL query, SQL function or text instruction
- Tell real context apart from configuration that only looks like context, such as benchmarks
Key concept
The attached-source boundary — A Genie Agent can only reason over and query the data objects you explicitly attach to it. Anything outside that set is out of scope for the agent, even when instructions or metadata mention it. Scoping a task therefore starts with choosing which sources to attach.
1.The context a Genie Agent actually reads
Many agent tasks come down to answering natural-language questions about governed tables. Databricks serves those tasks with a Genie Agent. Genie Agents were formerly called Genie Spaces, and an exam question may use either name. Before you decide what to add to one, you need to know what Genie actually puts together when a question arrives. Each context element you might select corresponds to one of these components. If a piece of knowledge does not land in any of them, Genie never sees it.
| Component | What it contributes |
|---|---|
| Unity Catalog table metadata | Table names, descriptions, and defined primary key (PK) and foreign key (FK) relationships |
| Column names and descriptions | Genie filters for the column names and descriptions relevant to the question |
| Knowledge store context | Agent-specific metadata the author adds locally, including column values relevant to query generation; Unity Catalog metadata is unchanged |
| Example SQL queries | Genie selects the relevant examples from the agent's SQL queries |
| SQL functions | All SQL functions that have been added to the agent |
| Instructions | Plain-text notes provided as General instructions |
| Prompt and response history | Prompts and responses from the current chat, with the oldest parts dropped when token limits require it |
Genie does not send all of this with every request. It filters example SQL queries, table and column metadata, and chat history, and keeps the context most relevant to the current question. That is why the scope of what you attach matters so much: a large, unfocused set of tables gives the filter more chances to pick the wrong thing. Some details are left out entirely. A table's owner and size are not included by default, so a task that needs them must query the information schema views that every Unity Catalog catalog provides.
Checkpoint 1 of 6· Check yourself
A user asks a Genie Agent, "Who owns the orders table and how large is it?" Which statement describes the default context?
Genie's default table metadata covers names, descriptions and PK/FK relationships. Owner and table size are left out unless you expose them through information schema views.
“Some table details, such as the owner and table size, are not included by default.”Source: docs.databricks.com
Sources1
2.Drawing the boundary: attached sources and data type
The first scoping decision is which data objects to attach, because that set is the agent's whole world. The boundary is strict. If you build a joined view for the agent, but your existing Databricks SQL queries run against the original source table, Genie will not return those queries, because it does not suggest queries on tables that are not added. Attaching a source does not bypass governance either: each user's access to attached sources is still checked against their own Unity Catalog permissions.
The second decision is whether the task fits the data type at all. In Chat mode, Genie works only with structured data. A task that needs PDFs or Word documents cannot be served by attaching more tables. To query unstructured files in Unity Catalog volumes (Beta), use Agent mode. For external documents, use Chat in Genie, which can connect to sources such as Google Drive and SharePoint.
The third decision is how narrow to go. Databricks says to include only the tables needed for the questions you want answered, aiming for five or fewer, and to limit columns as well. An agent should serve one topic and one audience. You can prejoin tables, remove unnecessary columns, and hide columns that might confuse Genie.
Checkpoint 2 of 6· Check yourself
A team wants a Genie Agent in Chat mode to answer questions about the clauses in supplier contract PDFs, alongside a structured spend table. What is the correct scoping judgement?
Chat mode cannot answer questions about unstructured files. Agent mode is the documented route for files stored in Unity Catalog volumes.
“To query unstructured files stored in Unity Catalog volumes (Beta), use Agent mode.”Source: docs.databricks.com
Checkpoint 3 of 6· Exam question
An HR analytics agent must answer natural-language questions against a Unity Catalog table of employee headcount data, where each manager should only see rows for their own department. Which combination of context elements is required for the agent to correctly scope and execute this task?
Correct answer: A — Register the table in a Genie space, add a Unity Catalog row-level security policy filtering by department, and provide a pro or serverless SQL warehouse.
3.Choosing the right element for each piece of knowledge
After the data boundary is set, look at each piece of business knowledge the task depends on and choose the element that should carry it. Databricks sets an order of preference. Use structured SQL definitions first, then example queries, and use text instructions only as a last resort. Its reason is that SQL definitions are more reliable and easier to maintain than plain-text guidance. The scope of the knowledge also matters. General text instructions apply to every prompt, so knowledge that applies only to some prompts belongs elsewhere.
| Knowledge the task needs | Context element to select |
|---|---|
| A standard business term reused across questions, such as revenue, active_customers or gross_margin | SQL expression (measure, filter or dimension) in the knowledge store |
| How to answer a hard-to-interpret, multi-part question such as "breakdown my team's performance" | Complete example SQL query, titled with the user's typical phrasing |
| Complex logic that a static or parameterized query cannot capture, or that should stay hidden | SQL function registered in Unity Catalog and added to the agent |
| Accurate JOIN statements between attached tables | Join relationships in the knowledge store |
| Global guidance that needs natural language, such as a February fiscal-year start or rounding rules | General text instructions |
Two elements need a closer look. SQL functions are a deliberate scoping choice. Genie can call them with user-supplied parameters, but it cannot view or modify the SQL inside them. That makes them the right place for logic that should not be surfaced or changed. Text instructions, by contrast, are easy to overuse. If an instruction applies only to some prompts, move it into an example query, a function, or a table's comments or metadata.
Checkpoint 4 of 6· Match them up
Match each requirement to the context element Databricks recommends for it
Tap a term, then the definition that fits it.
Business terms go into SQL expressions, complex question patterns into example queries, and hidden or complex logic into functions. Text instructions are kept for global guidance that none of those formats can express.
“Text instructions are only for context that should be applied globally and do not fit into the other formats.”Source: docs.databricks.com
Checkpoint 5 of 6· Exam question
A customer-support agent needs to perform semantic search over product manuals that have been chunked into a Delta table, with results scoped to the correct product line. Which context elements must be configured for the agent to correctly scope and execute this retrieval task? (Select all that apply.)(Select 3)
Correct answers: A, B, D — A source Delta table with Change Data Feed enabled containing the chunked manual text.; An embedding model to compute vector representations of the chunks for the AI Search index.; A metadata column on product line so results can be filtered to the correct manual set.
4.What looks like context but is not
Some configuration looks like context but never reaches the model when it answers. Benchmarks are the clearest case. They test the agent's accuracy, so a correct query you want Genie to learn from belongs in example SQL, not in a benchmark.
Each element also has a limited reach. Summary customization is a good example: only text instructions affect how Genie writes its natural-language summaries, and example SQL and SQL expressions have no influence on them. More context is not always better, either. Too many instructions reduce effectiveness, especially in longer conversations, because Genie may struggle to work out which guidance matters most.
Checkpoint 6 of 6· Check yourself
A task requires every Genie summary to cite the tables and columns used. Where must this requirement go?
Summary behaviour is controlled only by text instructions. SQL examples and expressions do not affect summaries, and benchmarks are not context at all.
“Only text instructions affect summary generation. SQL examples and SQL expressions don't influence how Genie creates summaries.”Source: docs.databricks.com
Sources3
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.If the agent's instructions or table metadata name a table, Genie can query it even though it was not attached.Why is that wrong?
Only explicitly attached sources are in scope. References in instructions or metadata do not extend the boundary.
Covered in Drawing the boundary: attached sources and data type
2.Adding benchmark questions with verified SQL improves the context Genie answers from.Why is that wrong?
Benchmarks are for evaluation only. To teach Genie a query pattern, add it as example SQL.
Covered in What looks like context but is not
3.A business metric such as revenue is best defined in the general text instructions so Genie always sees it.Why is that wrong?
Metrics, filters and query patterns that SQL can express should be SQL expressions or example queries. Text instructions are a last resort.
Covered in Choosing the right element for each piece of knowledge
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“Genie intelligently filters example SQL queries, table and column metadata, and chat history to select the most relevant context for answering the request.”
↩︎ The context a Genie Agent actually reads“If necessary, because of set token limits, the oldest parts of the chat record are excluded.”
↩︎ The context a Genie Agent actually reads“In Chat mode, Genie works with structured data only.”
↩︎ Drawing the boundary: attached sources and data type“Genie does not use benchmark questions or SQL to improve its context.”
↩︎ Exam trap 2“Some table details, such as the owner and table size, are not included by default.”
↩︎ Checkpoint“To query unstructured files stored in Unity Catalog volumes (Beta), use Agent mode.”
↩︎ Checkpoint“Unlike instructions, benchmarks are for evaluation only. Genie does not use benchmark questions or SQL to improve its context.”
↩︎ Prediction - 2.
“Genie does not suggest queries on tables that are not added to the agent.”
↩︎ Drawing the boundary: attached sources and data type“A Genie Agent uses only the data sources explicitly attached under its Sources.”
↩︎ Key concept“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 1“Genie does not query tables or Unity Catalog functions that are not attached, even if the agent's instructions or metadata reference them.”
↩︎ Prediction - 3.
“Include only the tables necessary to answer the questions you want the agent to handle. Aim for five or fewer tables.”
↩︎ Drawing the boundary: attached sources and data type“An agent should answer questions for a particular topic and audience, not general questions across various domains.”
↩︎ Drawing the boundary: attached sources and data type“When addressing hard-to-interpret, multi-part, or complex questions, provide complete example SQL queries.”
↩︎ Choosing the right element for each piece of knowledge“Too many instructions can reduce effectiveness, especially in longer conversations, because Genie might struggle to prioritize the most important guidance.”
↩︎ What looks like context but is not“Avoid using text instructions to define metrics, filters, or query patterns that can be expressed through SQL.”
↩︎ Exam trap 3“Only text instructions affect summary generation. SQL examples and SQL expressions don't influence how Genie creates summaries.”
↩︎ Checkpoint - 4.
“Genie cannot view or modify the SQL used in the function, making this approach well-suited for logic that should not be surfaced or changed.”
↩︎ Choosing the right element for each piece of knowledge“If an instruction is relevant only to a subset of prompts, it should be included as an example query or function”
↩︎ Choosing the right element for each piece of knowledge“Text instructions are only for context that should be applied globally and do not fit into the other formats.”
↩︎ Checkpoint