Table Descriptions Page

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
Table descriptions & keywords

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.

Bad descriptionGood description
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.
Sufficient context is important, but your descriptions should still be below 3 sentences.

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.

Bad keywordsGood keywords
items, goods, inventory, products list, offerings, productsitems, goods, inventory, products, model trains, toys, toy cars, model cars, model planes
Each table needs to have at least 5 keywords.

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.

Column descriptions

How to write good column descriptions

  1. Describe what the column is.

    Bad descriptionGood 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 descriptionGood 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 descriptionGood 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.