Space Management & Migration

Skill: databricks-genie

What You Can Build

You can manage Genie Spaces programmatically — creating curated data Q&A environments from table schemas, exporting and importing spaces across workspaces, and migrating from dev to production with catalog remapping. This matters when you’re onboarding new datasets at scale, keeping spaces in sync with schema changes, or promoting spaces through deployment environments.

In Action

“Write Python code that inspects table schemas and creates a Genie Space with curated descriptions and sample questions.”

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

# Step 2: Create the space with business context
create_or_update_genie(
    display_name="Sales Analytics",
    table_identifiers=["my_catalog.sales.customers", "my_catalog.sales.orders"],
    description="""Explore retail sales data with two related tables:
- customers: demographics, region, segment
- orders: transaction history with amounts and dates
Tables join on customer_id.""",
    sample_questions=[
        "What were total sales last month?",
        "Who are our top 10 customers by total_amount?",
        "How many orders were placed in Q4 by region?"
    ]
)

Key decisions:

• Always inspect table schemas first — get_table_details reveals column names, types, and cardinality that inform the description and sample questions
• The description teaches Genie how the tables relate and what the columns mean. Be explicit about join keys and business definitions
• sample_questions demonstrate correct question patterns that Genie can reference when generating SQL
• Point to Silver (cleaned) or Gold (aggregated) tables, not Bronze (raw data with quality issues)

More Patterns

Export and clone a space within the same workspace

“Write Python code that exports a Genie Space and creates a clone of it in the same workspace.”

# Export the source space
source = migrate_genie(type="export", space_id="01abc123...")

# Import as a clone
migrate_genie(
    type="import",
    warehouse_id=source["warehouse_id"],
    serialized_space=source["serialized_space"],
    title=source["title"],
    description=source["description"]
)

Export returns a serialized representation of the space configuration — tables, descriptions, instructions, certified queries, and sample questions. Importing creates a new space from that serialized data. Use this to create variations of an existing space for different teams or use cases.

Migrate a space across workspaces with catalog remapping

“Write Python code that moves a Genie Space from a dev workspace to production, remapping the catalog name.”

# Step 1: Export from source workspace
exported = migrate_genie(type="export", space_id="01abc123...")

# Step 2: Remap catalog name from dev to prod
modified = exported["serialized_space"].replace("dev_catalog", "prod_catalog")

# Step 3: Import to target workspace
migrate_genie(
    type="import",
    warehouse_id="<target_warehouse_id>",
    serialized_space=modified,
    title=exported["title"],
    description=exported["description"]
)

The serialized_space string contains fully qualified table references. A string replace on the catalog name remaps all table references from one environment to another. Make sure the target catalog has the same schema and table structure.

Update an existing space with new tables or instructions

“Write Python code that updates a Genie Space after the underlying schema changes.”

create_or_update_genie(
    space_id="01abc123...",
    display_name="Sales Analytics",
    table_identifiers=[
        "my_catalog.sales.customers",
        "my_catalog.sales.orders",
        "my_catalog.sales.returns"  # New table added
    ],
    description="""Explore retail sales data with three related tables:
- customers: demographics, region, segment
- orders: transaction history with amounts and dates
- returns: return requests with reason codes
Tables join on customer_id. Returns join to orders on order_id.""",
    sample_questions=[
        "What were total sales last month?",
        "What is the return rate by product category?",
        "Which regions have the highest return rates?"
    ]
)

When schemas evolve, update the space description to reflect new tables, columns, and join paths. Add sample questions that exercise the new data so Genie learns the correct query patterns.

Watch Out For

• Pointing Genie at Bronze tables — raw data often has quality issues, inconsistent schemas, and cryptic column names. Use Silver (cleaned) or Gold (aggregated) tables for reliable answers.
• Writing vague space descriptions — Genie uses the description to understand table relationships and business definitions. “Sales data” is not enough. Spell out join keys, column meanings, and business rules.
• Migrating without verifying target schema compatibility — catalog remapping changes the catalog prefix but assumes identical schema and table structures. Mismatched schemas produce SQL errors in the target workspace.
• Forgetting permissions after import — exporting requires CAN EDIT on the source space. Importing requires create privileges in the target folder. Users who need to query the imported space need separate access grants.