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, not revenue.

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:

IndexSkip
Names and titles: products, customers, programsNumeric fields: amounts, counts, IDs
Categorical values: statuses, types, categoriesTimestamps 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.

Next Steps

On this page