Context around your database
To assist Buster, we auto-generate documentation around your tables and columns. These include table and column descriptions that enable Buster to answer user questions more accurately. You will need to validate and correct the descriptions that we generate.
A good way to think about this is to ask yourself the question: “If I was starting my job here today, would I know that
column_1 is used to accomplish
If the answer to the above is ‘no’, then you probably need to change the column’s description to give Buster the context needed to correctly answer users’ questions.
You will be able to edit these descriptions after onboarding.
You must validate the following:
- Table Descriptions
- Table Keywords
- Column Descriptions
1. Table Descriptions
Table descriptions should be about how the table can be used to answer user questions. Essentially, you should mention all the topics that can be answered using the associated table. Here are some examples of good and bad descriptions for a table named
|This table can be used to answer questions about deals.
|This table can be used to answer questions related to information about deals. Information includes pricing info, start dates, end dates, status, company involved in the deal, etc.
2. Table Keywords
Your user questions are unlikely to refer to tables as they are actually named in your database. For example you may have a table called
orders . In reference to this table, your users will likely ask questions about purchases, sales, transactions, etc. Buster uses these keywords to more accurately relate user questions back to the associated tables.
You should check the keywords that we generated and validate that they are relevant. You should also add any additional keywords that your users will use to reference the associated tables. Also note that a single keyword can be more than one word (i.e. ‘product sales’)
Here are some examples of good and bad keywords for a table named
products, containing toy products.
|items, goods, inventory, products list, offerings, products
|items, goods, inventory, products, model trains, toys, toy cars, model cars, model planes
3. Column Descriptions
Buster will attempt to generate descriptions about what your column is. If your column name is human-readable (meaning it accurately represents the data within the column), Buster will do a good job of generating these.
For production-ready performance, you must validate the description for each column.
How to write good column descriptions
Describe what the column is.
Bad description Good description
close_date: this is the close date.
close_date: this is the date assigned by a sales rep for when they expect the deal to be closed.
Specify any transformations or calculations that are necessary for a column.
Bad description Good description
price: the price of the product.
price: the buying price that the product was purchased at as a whole number. Divide this number by 100 to get the currency amount.
If the column contains less than 10 values (enums, categories, etc.), we recommend putting those into the column description. If the enums or values aren’t representative of what they actually mean, we recommend defining those.
Bad description Good descriptions
status: the stage of the deal.
status: the stage the deal is currently in. Stages are: [‘lost’, ‘won’, and ‘in progress’.]
status: the stage the deal is currently in. Stages are: [0=‘lost’, 1=‘won’, and 2=‘in progress’.]
If the column contains a JSON object, we recommend putting the keys and values within the description.