Genie Spaces

Skill: databricks-genie

What You Can Build

You can stand up a natural language data exploration interface backed by Unity Catalog tables. Business users ask questions in plain English, Genie translates them to SQL, runs them on a warehouse, and returns results conversationally. Ask your AI coding assistant to create a Genie Space and it will inspect your tables, wire up the space with sample questions, and configure the description so Genie produces accurate SQL from day one.

In Action

“Create a Genie Space for the sales team using our orders and customers tables in Unity Catalog. Add sample questions so they know what to ask.”

# Step 1: Inspect the tables first
get_table_details(
    catalog="my_catalog",
    schema="sales",
    table_stat_level="SIMPLE"
)

# Step 2: Create the space with guided sample questions
create_or_update_genie(
    display_name="Sales Analytics",
    table_identifiers=[
        "my_catalog.sales.customers",
        "my_catalog.sales.orders"
    ],
    description="Explore sales data with natural language. "
                "Tables include customer demographics and order history "
                "with amounts, dates, and product categories.",
    sample_questions=[
        "What were total sales last month?",
        "Who are our top 10 customers by revenue?",
        "Show month-over-month revenue trend for Q4"
    ]
)

Key decisions:

• Inspect tables before creating — get_table_details reveals column names, types, and basic stats. This context drives better descriptions and sample questions, which directly affect Genie’s SQL accuracy.
• Descriptive description field — Genie uses this to understand what the tables contain and how they relate. Vague descriptions produce vague SQL.
• Sample questions as guidance rails — these show up in the Genie UI as suggested queries. They train users on what the space can answer and give Genie concrete examples of expected question patterns.
• Unity Catalog three-level names — always use catalog.schema.table format. Genie resolves table identifiers through Unity Catalog, so partial names will fail.

More Patterns

Query a Genie Space programmatically

“Ask our Sales Analytics Genie space what the revenue was last quarter, then get the raw data back.”

result = ask_genie(
    space_id="your_space_id",
    question="What was total revenue last quarter?"
)
# result contains: SQL query, column metadata, data rows, row_count

The Conversation API returns the generated SQL alongside the result data. Use conversation_id from the response to ask follow-up questions in the same context — Genie will remember the prior query and refine from there.

Export and clone a Genie Space

“Export our production Genie Space and create an identical copy for the QA team.”

# Export preserves tables, instructions, SQL examples, and layout
exported = migrate_genie(type="export", space_id="prod_space_id")

# Import as a new space (same catalog)
migrate_genie(
    type="import",
    warehouse_id=exported["warehouse_id"],
    serialized_space=exported["serialized_space"],
    title="Sales Analytics - QA",
    description=exported["description"]
)

The serialized payload captures the full space configuration. For cross-workspace migration, use separate MCP server profiles — one per workspace — and export from the source, then import via the target. Catalog names can be remapped during import if they differ across environments.

Update an existing space with new tables

“Add the returns table to our existing Sales Analytics Genie Space.”

create_or_update_genie(
    space_id="existing_space_id",
    display_name="Sales Analytics",
    table_identifiers=[
        "my_catalog.sales.customers",
        "my_catalog.sales.orders",
        "my_catalog.sales.returns"
    ],
    description="Explore sales data including customer demographics, "
                "order history, and return records.",
    sample_questions=[
        "What were total sales last month?",
        "What is our return rate by product category?",
        "Which customers have the highest return frequency?"
    ]
)

Pass the space_id to update rather than create. Update the description and sample questions to reflect the new table — Genie’s SQL accuracy depends on knowing what data is available.

Watch Out For

• Skipping get_table_details before creation — if you do not understand the column names and types, the description you write will be too vague for Genie to generate correct SQL. Always inspect first.
• Cross-workspace migration with different schema names — Genie migration only supports catalog remapping. If schema or table names differ between environments, you will need to manually edit the serialized payload after export.
• Missing SQL warehouse — Genie executes queries on a SQL warehouse. If none is specified, it auto-detects one, but that can fail in workspaces with restricted warehouse access. Specify the warehouse ID explicitly in production setups.
• Stale sample questions after table changes — when you add or remove tables, update the sample questions and description. Old questions referencing removed columns cause Genie to generate failing SQL.