QnA on databases admin guide

This guide describes how admins can set up databases for users to ask questions in the QnA UI against those databases. To set up QnA on documents instead of databases, see QnA on documents admin guide.

Prerequisites

• You must have an API token to configure hila to use external LLMs.
• You must have a connection string to your database so hila can connect to the database for conversational analytics.
• You must have a list of commonly asked questions to the data by business user of the application so you can build SQL into the system.

Procedure

1. Configure hila to use external LLMs as described in LLM configuration.

2. Open the hila example AdventureWorks notebook as a reference for your own use:

   1. Open edahub. See Open edahub.

   2. This image shows the file path in edahub to the directory that contains the AdventureWorks notebook.

      

3. In the AdventureWorks notebook, go to the third cell and find the line that assigns conn_string. Replace the value with your connection string.

4. In the Prepare Metadata cell, review and modify the variables as needed:
   • adventureworks_md_name is the name of the metadata you are creating. You can go back to where this variable is assigned and create your own variable with a different name. Throughout this notebook, you can replace adventureworks_md_name with your own variable name.
   • db_uri is the connection string to your database. You changed this assignment in the previous step, so you can leave it as-is.
   • conn_name is the name of the connection to your database. You can leave this as-is or go back to the variable assignment and change it to a name that makes sense to you.
   • schema is the schema of the database you are connecting to. Change this to whatever schema you want to use.
   • md_tables is a list of tables and views in your schema that you want to ask questions against.

   This cell creates the metadata object you need to ask questions against your database. You can also build the metadata object manually. The easiest way to do this is to run the automatic metadata generation once, and from the output you can see what the object looks like and how to modify it by hand.

5. In the cell with the leading comment “# Add example queries”, add the queries based on the list of commonly asked questions mentioned in the prerequisites. The format is:

   {
    "natural_language_query": "<the natural language question to match the SQL",
    "sql_query": "<some SQL query>",
    "text_query": "<some text query>",
    "description": "description of the question (None is a valid value)"
   }
   

6. At the end of the same cell, you can add any rules for data connection.

7. The notebook now has all the information it needs to build the complete metadata for your data connection. Run the notebook through all the cells to post the metadata. Notice that in the second-to-last cell (# Post metadata to Metadata table), the notebook posts the metadata to the metadata table in hila.

8. Test the application by checking the responses to the last cell. If you get poor results, consider adding more queries to the list of queries, changing the LLM model, or adding your own custom model (see Integrate your own LLMs).

9. Set up users and access rights to the applications. To make sure your user has permissions for the full user functionality of hila, assign the user the role of Explorer and modify as needed, or create a new role based on Explorer. See Users, roles, and permissions.

10. Get users from your user base to do acceptance testing and fine tuning the application. Have them follow the steps in QnA on databases user guide.

11. Release for production.