From af31ac919dd8da0bd9c5d7fbca98348093cbfa67 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 21 Apr 2026 14:54:56 -0700 Subject: [PATCH] docs: clarify that cube-level ai_context does not propagate to views (#10715) * Clarify that cube-level ai_context does not propagate to views Generated-By: mintlify-agent * docs: clarify ai_context is only consumed on views and members Made-with: Cursor --------- Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> Co-authored-by: Artyom Keydunov --- .../docs/data-modeling/ai-context.mdx | 211 ++++++++++++------ 1 file changed, 137 insertions(+), 74 deletions(-) diff --git a/docs-mintlify/docs/data-modeling/ai-context.mdx b/docs-mintlify/docs/data-modeling/ai-context.mdx index aed182a8a95c0..416983e16c9bc 100644 --- a/docs-mintlify/docs/data-modeling/ai-context.mdx +++ b/docs-mintlify/docs/data-modeling/ai-context.mdx @@ -81,31 +81,95 @@ query generation. If you want to provide context to the AI agent **without exposing it in the user interface**, use the `ai_context` key inside the [`meta`][ref-cube-meta] parameter. The `meta` parameter accepts custom -metadata on cubes, views, measures, and dimensions. +metadata on views, measures, and dimensions. + + + +`ai_context` must be defined on **views** or on **individual members** +(measures, dimensions). `ai_context` defined at the cube level is **not +consumed by the AI agent**. + + + +Use `ai_context` on [views][ref-view-meta] to provide high-level guidance, +and on individual members for member-specific instructions: ```yaml title="YAML" -cubes: - - name: orders - sql_table: orders - description: All orders +views: + - name: revenue_overview + description: Revenue metrics and breakdowns meta: ai_context: > - This cube contains all e-commerce orders. When users ask about - revenue, prefer the total_revenue measure which filters for - completed orders only. The amount column includes tax. + This is the primary view for revenue analysis. It combines + order, product, and user data. Use this view when users ask + about sales, revenue, or product performance. + + cubes: + - join_path: order_items + includes: + - total_sale_price + - count + - status + - created_at + - join_path: order_items.products + includes: + - brand + - category +``` + +```javascript title="JavaScript" +view(`revenue_overview`, { + description: `Revenue metrics and breakdowns`, + meta: { + ai_context: `This is the primary view for revenue analysis. It combines + order, product, and user data. Use this view when users ask about + sales, revenue, or product performance.` + }, + + cubes: [ + { + join_path: order_items, + includes: [ + `total_sale_price`, + `count`, + `status`, + `created_at` + ] + }, + { + join_path: order_items.products, + includes: [ + `brand`, + `category` + ] + } + ] +}) +``` + + + +For member-level context, define `ai_context` directly on the measure or +dimension: + + + +```yaml title="YAML" +cubes: + - name: order_items + sql_table: ECOMMERCE.ORDER_ITEMS measures: - - name: total_revenue - sql: amount + - name: total_sale_price + sql: sale_price type: sum - filters: - - sql: "{CUBE}.status = 'completed'" + format: currency meta: ai_context: > Use this measure for any revenue-related questions. - This excludes pending and cancelled orders. + It includes all line items regardless of order status. dimensions: - name: created_at @@ -114,28 +178,21 @@ cubes: meta: ai_context: > This is the order creation timestamp in UTC. - For fiscal year reporting, use the completed_at - dimension instead. + For delivery analysis, use delivered_at instead. ``` ```javascript title="JavaScript" -cube(`orders`, { - sql_table: `orders`, - description: `All orders`, - meta: { - ai_context: `This cube contains all e-commerce orders. When users ask - about revenue, prefer the total_revenue measure which filters for - completed orders only. The amount column includes tax.` - }, +cube(`order_items`, { + sql_table: `ECOMMERCE.ORDER_ITEMS`, measures: { - total_revenue: { - sql: `amount`, + total_sale_price: { + sql: `sale_price`, type: `sum`, - filters: [{ sql: `${CUBE}.status = 'completed'` }], + format: `currency`, meta: { ai_context: `Use this measure for any revenue-related questions. - This excludes pending and cancelled orders.` + It includes all line items regardless of order status.` } } }, @@ -146,8 +203,7 @@ cube(`orders`, { type: `time`, meta: { ai_context: `This is the order creation timestamp in UTC. - For fiscal year reporting, use the completed_at - dimension instead.` + For delivery analysis, use delivered_at instead.` } } } @@ -156,44 +212,55 @@ cube(`orders`, { -You can also use `ai_context` on [views][ref-view-meta]: +You can also override member-level `ai_context` when including members in +a view — for example, to define synonyms or acronyms that only apply in the +context of that view: ```yaml title="YAML" views: - - name: revenue_overview - description: Revenue metrics and breakdowns + - name: sales_overview + description: Sales metrics and breakdowns meta: ai_context: > - This is the primary view for revenue analysis. It combines - order and product data. Use this view when users ask about - sales, revenue, or product performance. + This view is for sales performance analysis across brands. cubes: - - join_path: orders + - join_path: order_items includes: - - total_revenue - - created_at - - status + - total_sale_price + - join_path: order_items.products + includes: + - name: brand + meta: + ai_context: > + Common acronyms: LC = Lucky Charms, + HNC = Honey Nut Cheerios. ``` ```javascript title="JavaScript" -view(`revenue_overview`, { - description: `Revenue metrics and breakdowns`, +view(`sales_overview`, { + description: `Sales metrics and breakdowns`, meta: { - ai_context: `This is the primary view for revenue analysis. It combines - order and product data. Use this view when users ask about - sales, revenue, or product performance.` + ai_context: `This view is for sales performance analysis across brands.` }, cubes: [ { - join_path: orders, + join_path: order_items, + includes: [`total_sale_price`] + }, + { + join_path: order_items.products, includes: [ - `total_revenue`, - `created_at`, - `status` + { + name: `brand`, + meta: { + ai_context: `Common acronyms: LC = Lucky Charms, + HNC = Honey Nut Cheerios.` + } + } ] } ] @@ -208,7 +275,7 @@ view(`revenue_overview`, { | --- | --- | --- | | Visible in the UI | Yes | No | | Used by the AI agent | Yes | Yes | -| Supported on | Cubes, views, measures, dimensions, segments | Cubes, views, measures, dimensions | +| Supported on | Cubes, views, measures, dimensions, segments | Views, measures, dimensions | Use `description` when the context is useful to both end users and the AI agent. Use `ai_context` when you want to provide additional instructions or @@ -223,45 +290,38 @@ You can use both together. The AI agent reads both the `description` and ```yaml title="YAML" cubes: - - name: orders - sql_table: orders - description: All customer orders - meta: - ai_context: > - When users ask about "sales", they usually mean completed - orders only. Prefer total_revenue over raw amount sums. + - name: order_items + sql_table: ECOMMERCE.ORDER_ITEMS + description: Line items for all orders measures: - - name: total_revenue - sql: amount + - name: total_sale_price + sql: sale_price type: sum - description: Total revenue from completed orders - filters: - - sql: "{CUBE}.status = 'completed'" + format: currency + description: Total revenue across all line items meta: ai_context: > This is the primary revenue metric. Always use this - instead of summing the amount dimension directly. + instead of summing the sale_price column directly. + When users ask about "sales", they mean this measure. ``` ```javascript title="JavaScript" -cube(`orders`, { - sql_table: `orders`, - description: `All customer orders`, - meta: { - ai_context: `When users ask about "sales", they usually mean completed - orders only. Prefer total_revenue over raw amount sums.` - }, +cube(`order_items`, { + sql_table: `ECOMMERCE.ORDER_ITEMS`, + description: `Line items for all orders`, measures: { - total_revenue: { - sql: `amount`, + total_sale_price: { + sql: `sale_price`, type: `sum`, - description: `Total revenue from completed orders`, - filters: [{ sql: `${CUBE}.status = 'completed'` }], + format: `currency`, + description: `Total revenue across all line items`, meta: { ai_context: `This is the primary revenue metric. Always use this - instead of summing the amount dimension directly.` + instead of summing the sale_price column directly. + When users ask about "sales", they mean this measure.` } } } @@ -277,6 +337,9 @@ cube(`orders`, { - **Use AI context for agent-specific guidance.** If you need to tell the AI agent which measure to prefer or how to interpret ambiguous terms, use `ai_context`. +- **Define context on views or individual members.** `ai_context` defined + at the cube level is not consumed by the AI agent. Place it on the view + itself or on individual measures and dimensions. - **Be specific.** Vague context like "important metric" is less helpful than "use this measure when users ask about monthly recurring revenue." - **Document relationships.** Use AI context to explain how cubes relate to each