§ 2.3Connecting Data
Column Comments & AI Context
When you connect a source and select a table, Dashport lets you add a comment to each column. These comments are passed directly to the AI — the clearer and more descriptive they are, the better and more accurate the answers you'll get from Dashport Chat.
Where to add comments#
After selecting your table in the connection wizard, Dashport displays a column preview panel. Each column row has a Comment field on the right-hand side — click it to type your description. Comments are saved with the connection and used every time Chat queries that source.
Examples: vague vs. clear#
| Column name | Poor comment | Clear comment |
|---|---|---|
order_date | Date | The date the customer placed the order (UTC, YYYY-MM-DD). Use this as the primary time axis for all revenue trends. |
amt | Amount | Total order value in USD, after discounts, before tax. This is the main revenue figure used in financial reports. |
cust_id | Customer ID | Unique identifier for the customer. Join to the customers table on this column to get name, region, and plan tier. |
status | Status | Order lifecycle status. Values: pending, processing, completed, refunded, cancelled. Only 'completed' counts as recognised revenue. |
mrr | MRR | Monthly Recurring Revenue for this subscription in USD. Excludes one-time charges and trial accounts (trial = 1). |
product_sku | SKU | Internal product code. Maps to the products table. Use the product_name column from that table for user-facing labels. |
Tips for writing good comments#
- State the unit. Always say whether a value is in USD, GBP, minutes, percentage points, etc. — never assume it's obvious.
- List possible values for status/flag columns. Enumerated fields like
statusorplan_tiershould have all valid values listed so Chat can filter them correctly. - Explain joins. If the AI needs to combine this column with another table to get a human-readable label, say so in the comment.
- Clarify business rules. If only certain rows count toward a metric (e.g. only
status = 'completed'is revenue), document it here so Chat applies the right filter automatically. - Note the time zone. For date and timestamp columns, specify whether values are UTC, local, or something else — this prevents off-by-one errors in daily and hourly charts.
- Keep it concise but complete. Two or three sentences is ideal. You don't need an essay — just enough that someone unfamiliar with your schema would understand the column immediately.