Work with an AI/BI Genie space

Preview

This feature is in Public Preview. See Enable Genie spaces in your workspace.

Overview

Domain experts, such as data analysts, configure Genie spaces with datasets, sample queries, and text guidelines to help Genie translate business questions into analytical queries. After set up, business users can ask questions and generate visualizations to understand operational data. You can continuously update Genie’s semantic knowledge as your data changes and users pose new questions. For additional information about DatabricksIQ, see DatabricksIQ-powered features.

AI/BI Genie uses the names and descriptions from annotated tables and columns to convert natural language questions to an equivalent SQL query. Then, it responds with the generated query and results table, if possible. If Genie can’t generate an answer, it can ask follow-up questions to clarify as it attempts to provide a response.

Example use cases

You can create different Genie spaces to serve various non-technical audiences. The following scenarios describe two possible use cases.

Example 1: Visualize opportunity status

A sales manager wants to get the current status of open and closed opportunities by stage in their sales pipeline. They can interact with the Genie space using natural language and automatically generate a visualization.

The following gif shows this interaction:

Example 2: Tracking logistics

A logistics company wants to use Genie spaces to help business users from different departments track operational and financial details. They set up a Genie space for their shipment facility managers to track shipments and another for their financial executives to understand their financial health.

Technical requirements

Genie spaces must meet the following requirements:

• Use data registered to Unity Catalog.

• Use a pro or serverless SQL warehouse.

Required permissions

The following permissions are required to create, edit, and use Genie spaces:

• Compute permissions: Genie space creators, editors, and users require CAN USE access to the default SQL warehouse designated for the space. Creators select the default SQL warehouse when they create a space. They can select any SQL warehouse for which they have CAN RUN permissions.

• Data access permissions: Any user who interacts with the space needs at least SELECT privileges on the data used in a space.

• Genie space permissions: Users need CAN RUN permissions on the Genie space to interact with Genie and the data used in the space. See Genie space ACLs for a complete mapping of privileges and abilities for a Genie space.

Note

Configuring data and compute access requires elevated permissions generally restricted to an administrator. See Create a SQL warehouse and Manage privileges in Unity Catalog.

Enable Genie spaces in your workspace

Genie uses Partner-Powered AI features that must be enabled at the account level and in the workspace where Genie spaces are created. To enable Genie spaces, verify each of the following settings.

• Partner-powered AI features are enabled at the account level. An account admin can enable this feature by completing the following steps:

  1. In the account console sidebar, click Settings.

  2. Click the Feature enablement tab.

  3. Turn on the Enable partner-powered AI features option.

  Partner-powered AI features must be enabled at the account level before it can be enabled at the workspace level.

• Partner-powered AI assistive features must be enabled for the workspace. A workspace admin can enable this feature using the following steps:

  1. Login to your workspace.

  2. Click your username in the top bar of the Databricks workspace and select Settings.

  3. Click the Advanced tab and scroll down to the Other section.

  4. Turn on the Partner-powered AI assistive features option.

• Genie must be enabled from the Previews page. A workspace admin can enable this preview. See Manage Databricks Previews.

Setup and usage limits

Capacity:

• A workspace can have up to 1,000 Genie spaces.

Text processing:

Each Genie space has a token limit of approximately 14,000 tokens per question. Tokens are the basic units of text that Genie uses to process and understand language. For example, text included as instructions and in metadata is converted into tokens. The token limit includes table metadata (including column names, descriptions, table names, and key definitions), instructions, sample SQL statements, trusted assets, and previous chat conversations. If your Genie space approaches or exceeds this limit, the product notifies you with warnings or errors.

For help with troubleshooting errors like this, see Request not processed due to a token limit.

Create a new Genie space

When Genie spaces are enabled in a workspace data analysts can create a domain-specific Genie space experience for business users by taking the following steps:

1. Click Genie in the sidebar.

2. Click New in the upper-right corner of the screen.

   

3. In the New dialog, choose your initial settings. The options are described as follows:

• Title: The title appears in the workspace browser with other workspace objects. Choose a title that will help end users discover your Genie space.

• Description: Users see the description when they open the Genie space. Use this text area to describe the spaces’s purpose.

• Default warehouse: This compute resource powers the SQL statements generated in the Genie spaces. End users need access to this warehouse to interact with the space. A Genie space can use a pro or serverless SQL warehouse. For optimal performance, Databricks recommends using a serverless SQL warehouse.

• Tables: Genie spaces can be based on one or more tables. The Add tables button opens a new dialog where you can select the Unity Catalog tables you want to include.

• Sample questions: Sample questions are optional. They appear in chats to provide examples of the types of questions users can ask. They can be added during creation or later from the space’s Settings.

What data should I use?

You can create new Genie spaces based on one or more Unity Catalog managed tables. AI/BI Genie uses the metadata attached to Unity Catalog objects to generate responses. Well-annotated datasets, paired with specific instructions that you provide, are key to creating a positive experience for end users.

Databricks recommends the following:

• Curate data for analytical consumption: Layer views to reduce the number of columns and add use-case-specific information to increase response quality.

• Minimize the number of tables and columns in a Genie space: Bring in only the tables and columns needed to answer questions for a given domain. Unnecessary tables or columns can cause Genie to provide confusing or incorrect answers, or display an error message.

Provide instructions

Instructions help to guide Genie’s responses so that it can process the unique jargon, logic, and concepts in a given domain. Comprehensive instructions are critical to a seamless, intuitive Genie space experience. To enter instructions, click Instructions in the Genie space sidebar to open the instructions pane. Use this pane to add General instructions, Example SQL Queries, and SQL Functions.

General instructions

Provide plain text instructions that clearly convey your business or response preferences for Genie to follow. You can format the instructions as a single comprehensive note or categorize them by topics for better organization.

The following shows an example of information you could include in general instructions:

• Company-specific business information:

  • “Our fiscal year starts in February”

• Values, aliases, or common filters:

  • “Always convert to lowercase and use a like operator when applying filters.”

  • “Use abbreviations for states in filter values.”

• Specify functions to answer questions and provide instructions for return values:

  • “For quarters use the adventureworks.oneb.get_quarter(date) UDF. The output of get_quarter() is the quarter and is either 1,2,3, or 4. Use this to filter the data as needed.

Example SQL queries

Example SQL queries are SQL queries that you prepare to help train Genie. When you add example queries, you are effectively showing Genie how to use your data to answer questions. You can also add example questions to teach Genie about the kinds of questions you would expect the example query to answer. If Genie recieves a matching question, it can use the example query directly to provide an answer. If it gets a similar question, it can use clues from the example query to help stucture the SQL provided in the response. Focus on providing samples that highlight logic that is unique to your organization and data, as in the following example:

  -- Return our current total open pipeline by region.
  -- Opportunities are only considered pipelines if they are tagged as such.
  SELECT
    a.region__c AS `Region`,
    sum(o.amount) AS `Open Pipeline`
  FROM
    sales.crm.opportunity o
    JOIN sales.crm.accounts a ON o.accountid = a.id
  WHERE
    o.forecastcategory = 'Pipeline' AND
    o.stagename NOT ILIKE '%closed%'
  GROUP BY ALL;

Add parameters in SQL queries

Parameters let you write example queries that include placeholders for specific values to be substituted in at runtime. With parameters, Genie can take specific inputs from user questions and reuse the structure of an example query to provide verified answers as trusted assets. For example, you could adjust the previous SQL query to include a parameter that filters by the o.forecastcategory value, enabling the query to address questions about opportunities tagged in different forecast categories. For more information about how to use parameterized queries to generate reponses labeled as trusted assets, see Use trusted assets in AI/BI Genie spaces.

The following code snippet shows the previous example, modified by adding a parameter for the o.forecastcategory value. Parameters use the same syntax as named parameter markers. See Named parameter markers.

-- Return our current pipeline at a stage by region.
-- Opportunities are only considered pipelines if they are tagged as such.
  SELECT
    a.region__c AS `Region`,
    sum(o.amount) AS `Open Pipeline`
  FROM
    sales.crm.opportunity o
    JOIN sales.crm.accounts a ON o.accountid = a.id
  WHERE
    o.forecastcategory = :forecast_category AND
    o.stagename NOT ILIKE '%closed%'
  GROUP BY ALL;

To add a parameter to a query:

1. Place your cursor where you want to place the parameter in your query.

2. Click Add parameter to insert a new parameter.

   This creates a new parameter with the default name parameter. To change the default name, replace it in the query editor. You can also add parameters by typing a colon followed by a parameter name (:parameter_name) into the editor.

Edit a query parameter

To edit a parameter do the following:

1. Click next to the parameter name. A Parameter details dialog appears and includes the following configuration options:

   • Keyword: The keyword that represents the parameter in the query. This can only be changed by directly updating the text in the query.

   • Display name: The human-readable name that Genie uses in the chat experience. When Genie uses a parameterized query to generate a response, it includes the display name and associated value in the response.

   • Type: Supported types include String, Date, Date and Time, and Numeric.

     • The default type is String.

     • The Numeric datatype allows you to specify between Decimal and Integer. The default numeric type is Decimal.

     Note

     If the actual input value does not match the selected parameter type, Genie treats the input value as the incorrect type, which can lead to inaccurate results.

2. Click another part of the UI to close the dialog.

SQL functions

SQL functions are custom functions that are stored in Unity Catalog and used by Genie to answer specific questions. Genie can call these functions and insert any user specified parameters, but it cannot access the underlying SQL content. That means that SQL functions are ideal for answering common specific questions that include complex arguments or calculations that Genie should not be able to access or edit. For guidance on registering a function in Unity Catalog, see Create a SQL table function and User-defined functions (UDFs) in Unity Catalog.

Trusted assets

When the exact text of a parameterized example query or SQL function is used to generate a response, Genie marks the response as a Trusted asset. Trusted assets are meant to convey an extra layer of assurance in the accuracy of a result to an space user. See Use trusted assets in AI/BI Genie spaces.

Chat in the Genie space

Most Genie space interactions take place in a chat window.

A new chat window includes a curated set of sample questions. These sample questions help users understand what questions they can ask their Genie space. The text field, where users input questions, is near the bottom of the screen.

Responses appear above the text field. After a user enters a question, it is saved to a chat history thread in the left pane.

Chat history

Chat history threads are saved for each user so that they can refer to past questions and answers. Users can also resubmit or revise questions from a chat thread. The New chat button in the left pane starts a new thread.

Each chat thread maintains context about previous questions it has been asked. This allows users to ask follow-up questions to further explore or refocus a result set.

Response structure

The precise response structure varies based on the question. Often, responses include a natural language explanation and a table showing the relevant result set. All responses include the SQL query that was generated to answer the question. Click Show generated code to view the generated query.

The lower-right side of the response includes optional actions. You can copy the response CSV to your clipboard, download it as a CSV file, add it as an instruction for the Genie space, and upvote or downvote the answer.

A set of Quick actions tiles follow responses that include tabular data. You can use them to generate visualizations.

You can also generate a visualization by describing it in words after getting a query result.

Provide response feedback

Each AI/BI Genie response includes a thumbs-up or thumbs-down feedback button. Databricks recommends encouraging users to provide feedback on the space using this mechanism.

For a response that includes query results, users can request that it be reviewed by a Genie space editor by clicking the . If a user has questions about the quality or accuracy of a generated response, they can mark it for review and, optionally, add their comment or question.

Business users can view updates to the questions they’ve marked for review on their History page. Users with at least CAN MANAGE permission on the Genie space can review the specific exchange, comment on the request, and confirm or correct the response. They can access feedback and review requests on the monitoring page. Then you can use that feedback to tune responses and iterate on your space. See Review history and feedback.

Review history and feedback

A Genie space is meant to be a continuous collaboration tool for data teams and business users to accumulate knowledge, not a one-time deployment. Understanding the new questions that business users need answers to is essential for knowledge building. On the history page, you can view individual questions and responses, thumbs-up or thumbs-down feedback provided by users, and questions marked for review. To open the history page, click History in the Genie space sidebar.

The history page shows all of the questions and answers that have been asked in the space. You can filter questions by time, rating, user, or status. By monitoring the space, Genie space editors can proactively understand the queries raised by business users and how the Genie space responded.

By identifying the questions that Genie struggles with, you can update the Genie space with specific instructions to improve its responses. Click a question to open the question and response text. You can also access the complete chat thread from this view.

Edit generated SQL

You can review and edit the generated SQL in any response. Genie space authors typically know the domain and data that allows them to recognize when Genie is generating an incorrect answer. Often, errors can be fixed with a small amount of manual tuning to the generated SQL query. To view the generated SQL for any response, click Show generated code to inspect the query.

You can edit the generated SQL statement to correct it if you have CAN EDIT or greater privileges on the Genie space. After you’ve made your corrections, run the query. Then, you can save it as an instruction to teach Genie how to answer in the future. To save your edited query, click Save as instruction.

Evaluate responses with benchmarks

Benchmarks allow you to scale up testing and evaluation of individual responses in a Genie space. Unlike instructions, benchmarks are meant to evaluate, not inform, your Genie space. Genie does not use benchmark questions or example SQL to improve Genie’s context.

Using benchmarks, you can run a collection of test questions and use the responses to measure Genie’s accuracy. Optionally, you can include a SQL answer returns the expected results. When the benchmark question runs, Genie’s reponse is compared to the results provided SQL statement and scored for accuracy. If no SQL answer has been provided, the question is marked for review.

See Use benchmarks in a Genie space.

Share a Genie space

Important

Genie space users must use their own credentials to access data. Any question about data they can’t access generates an empty response.

Genie space users must have CAN USE permissions on the warehouse attached to a Genie space and access permissions on the Unity Catalog objects surfaced in the space. See What data should I use?.

New Genie spaces are saved to your user folder by default. Like other workspace objects, they inherit permissions from their enclosing folder. You can use your workspace folder structure to share them with other users. See Organize workspace objects into folders.

You can also specify certain users or groups to share with at a given permission level: CAN MANAGE, CAN EDIT, CAN RUN, and CAN VIEW.

To share with specific users or groups:

1. Click Share.

2. Enter users or groups you want to share the space with. Then, click Add and set appropriate permission levels.

3. Use the Copy link button at the bottom of the Share dialog to get a shareable link to the Genie space. Privileged users can click the link to open the Genie space in a new tab and ask questions.

Clone a Genie space

Cloning a Genie space creates a copy, including all setup context and instructions. This is helpful if you have a well-developed space and want to create a new space for additional testing or reuse the context from the original space. After a space is cloned, the new space is independent of the original, allowing you to make edits and adjustments without impacting the original.

The following elements are copied to a cloned Genie space:

• Tables and settings

• General instructions

• Example SQL queries

• SQL functions

Existing chat threads and History data are not copied to the new space.

To clone a Genie space, do the following:

1. Open the Genie space you want to clone.

2. Click the kebab menu in the upper-right corner of the space.

3. Click Clone.

4. (Optional) In the Clone dialog, specify a new name and workspace folder location for the cloned Genie space.

5. Click Clone to create the new space.

How are Genie space responses generated?

Genie spaces generate responses to natural language questions using table and column names and descriptions. The actual data in the tables remains hidden from Genie.

Best practices for space preparation

• Before you build, establish a set of well-defined questions that you want space users to be able to answer.

• Test your Genie space to check response quality. Try the following to see if the model provides the expected response:

  • Rephrase the provided questions.

  • Ask other questions related to the datasets.

• Add and refine Genie space instructions until questions provide the expected response.

For more guidance on best practices and help with troubleshooting issues, see Curate an effective Genie space.