Skip to main content

Add a Genie space resource to a Databricks app

Add AI/BI Genie spaces as Databricks Apps resources to enable natural language querying in your applications. Genie spaces provide a conversational interface for data exploration, allowing users to ask business questions in plain English and receive SQL-based insights from your curated datasets.

When you add a Genie space as a resource, your app can:

  • Convert natural language queries from users into SQL
  • Access pre-configured business context and metadata
  • Use curated sample queries and data definitions
  • Generate responses based on your organization's datasets

Add a Genie space resource​

Before you add a Genie space as an app resource, review the resource prerequisites.

  1. In the App resources section when you create or edit an app, click + Add resource.
  2. Select Genie space as the resource type.
  3. Choose a Genie space from the list of available spaces in your workspace.
  4. Select the permission level for your app:
    • Can view: Grants the app permission to read the Genie space configuration and metadata.
    • Can run: Grants the app permission to submit queries to the Genie space and receive responses.
    • Can edit: Grants the app permission to modify the Genie space configuration.
    • Can manage: Grants the app full administrative access to the Genie space.
  5. (Optional) Specify a custom resource key, which is how you reference the Genie space in your app configuration. The default key is genie-space.

When you add a Genie space resource:

  • Databricks grants your app's service principal the specified permissions on the selected Genie space.
  • The app can submit natural language queries to the space and receive structured responses with SQL queries and results.
  • The app accesses the space's curated business context, including metadata, sample queries, and data definitions.
  • Access is scoped to the selected space only. Your app can't access other Genie spaces unless you add them as separate resources.
note

The app's service principal also needs appropriate permissions on the underlying data sources that the Genie space queries. This typically includes USE CATALOG, USE SCHEMA, and SELECT permissions on the relevant Unity Catalog tables and views.

Environment variables​

When you deploy an app with a Genie space resource, Databricks exposes the space ID through environment variables that you can reference using the valueFrom field in your app.yaml configuration.

Example configuration:

YAML
env:
  - name: GENIE_SPACE_ID
    valueFrom:
      resourceKey: genie-space # Use your custom resource key if different

Using the space ID in your application:

Python
import os
from databricks.genie import GenieClient

# Access the Genie space using the injected environment variable
space_id = os.getenv("GENIE_SPACE_ID")
genie_client = GenieClient()

# Submit a natural language query
response = genie_client.query(
    space_id=space_id,
    query="What were our top-selling products last quarter?"
)

For more information, see Access environment variables from resources.

Remove a Genie space resource​

When you remove a Genie space resource from an app, the app's service principal loses access to the space. The Genie space itself remains unchanged and continues to be available for other users and applications that have appropriate permissions.

Combine Genie spaces with other app resources​

Combine Genie spaces with other Databricks Apps resources to create more sophisticated data applications. Common integration patterns include:

Natural language analytics dashboard​

Use the following resources together to run interactive analytics:

  • Genie space: Converts user questions into SQL queries
  • SQL warehouse: Runs the queries and returns results for visualization
  • Secrets: Stores API keys for external visualization tools

Example configuration:

YAML
env:
  - name: GENIE_SPACE_ID
    valueFrom:
      resourceKey: genie-space
  - name: SQL_WAREHOUSE_ID
    valueFrom:
      resourceKey: sql-warehouse
  - name: EXTERNAL_API_KEY
    valueFrom:
      resourceKey: viz-secret

AI-enhanced business intelligence​

Use the following resources to integrate with AI models:

  • Genie space: Generates the initial query and data context
  • Model serving endpoint: Returns AI-generated summaries and recommendations
  • SQL warehouse: Runs complex analytical queries

Service principal permissions​

Grant your app's service principal the following permissions when integrating with other app resources:

  • CAN RUN on the Genie space
  • CAN USE on the SQL warehouse (if using a separate one from the Genie space)
  • CAN QUERY on model serving endpoints
  • USE CATALOG and USE SCHEMA on relevant Unity Catalog objects
  • SELECT on tables the app queries directly

Best practices​

Follow these best practices when you work with Genie space resources:

  • Grant minimal permissions. Only provide access to the specific Genie spaces your app needs to function.
  • Ensure the Genie space contains well-curated datasets and metadata to improve the quality of natural language query responses.
  • Test your app's queries against the Genie space to validate that it can generate accurate results for expected user questions.
  • Monitor query performance and adjust your app's interaction patterns with the Genie space to optimize response times.
  • Implement error handling for cases where the Genie space can't interpret or respond to user queries effectively.
Last updated on