Table & column descriptions

​

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 xyz?”

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 deals.

​

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.

​

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

1. 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.

2. 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.

3. 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’.]

4. If the column contains a JSON object, we recommend putting the keys and values within the description.

   Good description of a JSON object

   settings: these are the settings associated with a user. The JSON structure is as follows:

   {
       notifications: boolean, //representing if the user has notifications turned on
       dark_mode: boolean, // representing if the user has dark mode turned on
       profile_info: {
           img_url: string // "string of the url that relates back to the user"
       }
   }