[pull] master from cube-js:master

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.
+
+<Note>
+
+`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**.
+
+</Note>
+
+Use `ai_context` on [views][ref-view-meta] to provide high-level guidance,
+and on individual members for member-specific instructions:
 
 <CodeGroup>
 
 ```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`
+      ]
+    }
+  ]
+})
+```
+
+</CodeGroup>
+
+For member-level context, define `ai_context` directly on the measure or
+dimension:
+
+<CodeGroup>
+
+```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`, {
 
 </CodeGroup>
 
-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:
 
 <CodeGroup>
 
 ```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