10.2 Curation via Instructions, Descriptions & Sample Questions
Key Takeaways
- Space instructions provide domain-specific context, defining business logic, metric formulas, default filters, and acronym definitions for the Genie space.
- Unity Catalog table and column comments are automatically ingested by Genie as first-class metadata signals during SQL translation.
- Curating 10 to 15 representative sample questions with verified SQL queries improves LLM translation accuracy by providing few-shot context.
- Ambiguous metric definitions (such as Active Customer or Gross Revenue) should be explicitly defined in Space Instructions using standard SQL filtering conditions.
10.2 Curation via Instructions, Descriptions & Sample Questions
While Databricks AI/BI Genie uses advanced LLMs to convert natural language into SQL, raw schema metadata alone is rarely sufficient to handle enterprise business nuances. Business terminology is frequently ambiguous: "revenue" might refer to gross, net, or recognized revenue; "active user" could mean logged in within 30 days or completing a transaction within 7 days. To bridge the semantic gap between end-user questions and database structures, analysts curate Genie spaces using Space Instructions, Unity Catalog Descriptions, and Sample Questions.
The Role of Curation in Conversational Analytics
Curation transforms a raw relational schema into a domain-aware semantic model. Without curation, Genie must guess business logic, which increases the likelihood of hallucinated joins, incorrect aggregation logic, or misaligned filtering criteria.
+--------------------------+ +--------------------------+ +--------------------------+
| Space Instructions | | Unity Catalog Metadata | | Sample Questions |
| - Metric Definitions | + | - Table Comments | + | - Verified SQL Queries |
| - Default Date Filters | | - Column Descriptions | | - Few-Shot Context |
| - Acronym Mappings | | - PK / FK Constraints | | - Pattern Matching |
+--------------------------+ +--------------------------+ +--------------------------+
|
v
+-------------------------------+
| High-Precision Genie Space |
| - Accurate SQL Translation |
| - Zero Metric Ambiguity |
+-------------------------------+
Proper curation ensures that every user query is interpreted using uniform corporate rules, delivering consistent results across self-service analytics teams.
Authoring Space-Level Instructions
Space Instructions provide global guidance for the entire Genie space. They serve as system-level prompts that dictate how Genie should interpret queries, construct SQL logic, handle edge cases, and default to specific timeframes or filters.
Key Components of Effective Space Instructions
- Metric Definitions: Explicit mathematical formulas and SQL logic for calculating KPIs.
- Business Acronyms: Translation of organization-specific jargon (e.g., "ARR", "CAC", "Churn").
- Default Behavior Rules: Rules governing date ranges, soft-delete filtering, and currency conversion.
- Table Routing Rules: Directives specifying which table to query for specific domains (e.g., "For quarterly financial metrics, query
main.finance.gold_quarterly_financials").
### Example Space Instruction Block
- **Active Customer Definition**: Always filter `is_active = TRUE` and `last_login_date >= CURRENT_DATE() - INTERVAL 30 DAYS` when users ask for active customers.
- **Revenue Calculation**: Default to `net_revenue` (which subtracts discounts and refunds) unless the user explicitly asks for `gross_revenue`.
- **Fiscal Calendar**: Our fiscal year starts on February 1st. Q1 is Feb-Apr, Q2 is May-Jul, Q3 is Aug-Oct, Q4 is Nov-Jan. Use `CASE` statements or `fiscal_quarter` columns in `dim_date`.
- **Currency Standard**: All monetary values are stored in USD. Do not apply currency conversion unless requested.
- **Default Timeframe**: If no date range or period is specified in the question, default to the current calendar year (`order_date >= DATE_TRUNC('year', CURRENT_DATE())`).
Instructing Genie with clear bulleted points avoids ambiguous conversational prose and ensures deterministic application of business logic during SQL generation.
Enhancing Metadata with Unity Catalog Descriptions
Genie dynamically reads table and column comments directly from Unity Catalog. Comprehensive catalog-level documentation provides localized context at the exact moment Genie maps user terminology to database attributes.
Analysts should use COMMENT ON statements in Databricks SQL to document tables, views, and individual columns:
-- Adding clear business descriptions to Unity Catalog tables and columns
COMMENT ON TABLE main.sales_gold.fact_orders IS
'Primary transactional table recording all online and retail customer orders. Contains line-item revenue, tax, and discount details.';
COMMENT ON COLUMN main.sales_gold.fact_orders.net_amount IS
'Net order revenue in USD, calculated as gross_amount - discount_amount + tax_amount. Use this column for standard revenue reporting.';
COMMENT ON COLUMN main.sales_gold.fact_orders.order_status IS
'Lifecycle status of order. Allowed values: PENDING, SHIPPED, COMPLETED, CANCELLED, REFUNDED. Filter by COMPLETED for realized revenue.';
When writing descriptions:
- Specify valid enumerated values for categorical columns (e.g.,
'COMPLETED','REFUNDED'). - Clarify measurement units (e.g.,
milliseconds,USD,kilograms). - Call out special handling rules (e.g., "Contains NULL for guest checkout accounts").
Curating Effective Sample Questions
Sample Questions are paired natural language queries and verified SQL statements saved directly within the Genie space. They serve two vital functions:
- User Guidance: They appear in the Genie user interface to show business users what questions the space can answer.
- Few-Shot Prompting: They act as high-priority exemplars for the underlying LLM. When a user submits a prompt, Genie searches sample questions for structural and semantic similarities, using verified SQL patterns as templates for new query generation.
-- Sample Question 1: "Show top 5 customers by revenue in 2025"
-- Verified SQL Expression:
SELECT
c.customer_name,
SUM(o.net_amount) AS total_revenue
FROM main.sales_gold.fact_orders o
JOIN main.sales_gold.dim_customers c ON o.customer_id = c.customer_id
WHERE o.order_date >= '2025-01-01' AND o.order_date < '2026-01-01'
AND o.order_status = 'COMPLETED'
GROUP BY c.customer_name
ORDER BY total_revenue DESC
LIMIT 5;
To maximize sample question effectiveness:
- Cover Diverse Query Patterns: Include examples covering aggregations, multi-table joins, subqueries, window functions, and date arithmetic.
- Keep SQL Clean and ANSI-Compliant: Ensure sample queries use standard Databricks SQL syntax and explicit alias naming.
- Maintain 10-15 Core Questions: Focus on high-frequency, complex analytical queries rather than trivial single-table selects.
Resolving Terminology Ambiguity & Edge Cases
When users ask questions with competing or overlapping business meanings, space instructions must establish clear precedence:
| User Term | Potential Ambiguity | Curated Instruction Solution |
|---|---|---|
| "Sales" | Booking revenue vs. Cash collection vs. Shipped orders | "Interpret 'Sales' as completed net order revenue from fact_orders where status = 'COMPLETED'." |
| "Churn Rate" | Logo churn (customers) vs. Revenue churn (ARR) | "Default 'Churn Rate' to customer logo churn. If ARR loss is mentioned, calculate revenue churn." |
| "New Customers" | First purchase ever vs. First purchase in current fiscal year | "Filter first_order_date within the specified window to identify new customers." |
Where should an analyst document business acronyms, default date ranges, and soft-delete filtering rules for an entire Genie space?
How do sample questions with verified SQL statements assist the AI/BI Genie translation engine?
What is the primary benefit of adding explicit COMMENT ON descriptions to Unity Catalog table columns for a Genie space?