Descriptions and Value Search
How to describe what each field means with
Two annotations tell people and agents what a model's fields mean and what values they hold: #(doc) describes a field, and #(index) makes a dimension's values searchable. When you publish, the engine compresses the descriptions and indexed values into the concept index, which people and agents search by meaning.
The agent adds #(doc) to every field it defines, and #(index) where it helps discovery, as part of the modeling workflow, and can document an existing model the same way. Which sources and fields callers see at all is set separately; see Exports and Field Visibility. For how indexes are built, kept fresh and paid for, see Materialization and Performance.
Descriptions
Put #(doc) on the line before a field to describe what it means:
source: orders is warehouse.table('sales.orders') extend {
dimension:
#(doc) Customer segment based on lifetime value: High (>$10k), Medium (>$1k), Low
customer_segment is case
when lifetime_value > 10000 then 'High'
when lifetime_value > 1000 then 'Medium'
else 'Low'
end
measure:
#(doc) Revenue at order placement. Recognized revenue lives in finance.recognized_revenue.
booked_revenue is sum(amount)
}Write descriptions that add what the code can't say:
- Include units, thresholds, business rules, caveats, what depends on the definition, and where related numbers live.
- Don't restate the field name or logic the model already expresses.
- Name the distinction, too. Agents take field names at face value, so call booked revenue
booked_revenue, notrevenue.
Value Indexing
Put #(index) on a dimension to index its distinct values, so agents can find the field by searching for a value, not only by a field name or description:
source: products is warehouse.table('catalog.products') extend {
dimension:
#(index)
#(doc) The product category (e.g., Electronics, Clothing, Home & Garden)
category is product_category
#(index)
#(doc) The brand name
brand is brand_name
}For example, if product_category holds values like "Running Shoes" and "Athletic Apparel", a question about "sports gear" matches nothing by name. With #(index), the engine matches the question to those values and helps the agent filter on them.
Index the dimensions people ask about by value:
| Index | Skip |
|---|---|
| Names and titles: products, customers, programs | Numeric fields: amounts, counts, IDs |
| Categorical values: statuses, types, categories | Timestamps and dates |
| Lookup values: regions, departments, brands |
Only exported sources are indexed on their own; see Exports and Field Visibility.
Value search is limited on access-controlled sources, because one index serves every caller. See Value Search and Materialization for which sources keep it.