Iterating Your Genie Space’s Quality: Best Practices Checklist

As a starter, here I my bullets after tackling a few Genie Space quality iteration requests from real user cases.

Priority Origin: Consider adopt an industry data model fitting your user case from this repo, 

• Combining robust data modeling with Metric Views (see below) removes unnecessary token overhead, allowing Genie to prioritize natural language comprehension over complex schema exploration.

Priority 0: Build Benchmark dataset 

• With at least 10 most representative question-answers (100% correct ones)

• then iterate below items one small change/step at a time, verify improvement/regression

• backup frequently structured output json of Genie room for your own version controls (by using either the ai-dev-kit genie export skills or write a notebook calling Genie export API yourself) 

Priority 1: Unity Catalog Metadata (most effective)

• Table and column comments/descriptions

• Clear, descriptive naming conventions

• Primary keys and foreign key relationships

Priority 2: Reduce Excessive # of tables per Genie space and # of columns per table 

• tables better under 20 per space

• columns better under 50 per table

• If you have excessive tables, consider either split into muliple spaces (if your have multiple domains), or if have to keep one space, use metric views/regular views to group tables into less (replacing original tables)

• If you have excessive columns per table, either hide unused columns, or use metric views/regular views to group columns to less (replacing original tables)

Priority 3: Prompt Matching

• Enable entity matching for categorical columns

• Curate value lists for important dimensions

• This will map user terms to data values (e.g., “Florida” → “FL”)

Priority 4: SQL Expressions (if sharable among multiple Genie rooms, prefer put in Metric Views)

• Define measures for KPIs and metrics

• Create filters for common conditions

• Set up dimensions for grouping

Priority 5: SQL Examples

• Cover common query patterns

• Include diverse examples

• Use parameterized queries for reusable patterns

Priority 6: Join Definitions (if sharable among multiple Genie rooms, prefer put in Metric Views)

• Explicitly define table relationships

• Specify relationship cardinality

• Prevent incorrect joins

Priority 7: General Instructions (least effective)

• Keep concise (under 2000 characters), see below proven template

• Focus on business context

• Convert complex instructions to Metrics View, SQL Expressions, Joins Defeinitions and SQL examples instead

One caution

Avoid encoding the same business logic in multiple places (including Metric Views) with slight differences. Databricks guidance is to avoid conflicting instructions across context types, because inconsistency hurts reliability.

-----below is an proven template structure for General Text Instruction----

# [SPACE METADATA] (100-200 chars)

Purpose: [One-line business capability]

Scope: [3-5 core data entities]

Users: [Specific target audience]

Domain: [Business area]

# [DATA FOUNDATION] (200-400 chars)

- Core tables with business descriptions

- Key relationships and join logic

- Value dictionaries for categorical data

# [BUSINESS TERMINOLOGY] (200-400 chars)

- Primary Terms: "synonym1", "synonym2"

- Metrics: "metric1", "metric2"

- Abbreviations: "HC"="headcount", "TL"="Technical Leader"

# [RESPONSE STANDARDS] (300-500 chars)

1. Required Fields: Always include [key identifiers]

2. Format Rules: [Date/number formatting]

3. Current Data: Use latest [time dimension] when "current" requested

# [ERROR HANDLING] (100-200 chars)

- No results: "No data found matching criteria..."

- Multiple matches: "Multiple records found, shown by [identifier]..."

What we have seen working well with customers is when Genie spaces have a specific owner with a monthly review with business users.

Another important aspect is context. If a business user asks for "Win Rate," there is no foundation model that can guess how your company defines that calculation mathematically. This is a nice guide on how to proactively ground text-to-SQL logic: https://docs.databricks.com/aws/en/genie/tune-quality

I just came across this awesome Genie Code agent skill, which allows Genie Code (or any other agent) to build a Genie space following best practices.https://github.com/sean-zhang-dbx/prompt-to-genie

Instead of manually configuring Genie spaces through the UI or writing raw API calls, simply describe what you want in plain English and let the Assistant handle the rest.

Besides the fact that good data prep is what makes or breaks a Genie space. What I recently realised is that you can also add synonyms on column level. This is a big improvement for me.

Also, start small, and expand.