Table & column descriptions
Manage context and documentation around your schema.
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
.
Bad description | Good 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. |
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 keywords | Good keywords |
---|---|
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.
Was this page helpful?